Use ojet serve to run your web app in a local web server for testing and debugging.

The following table describes the available ojet serve options and provides examples for their use.

Oracle JET tooling uses Express, a Node.js web app framework, to set up and host the web app when you run ojet serve. If the ready-to-use ojet serve options do not meet your requirements, you can add Express configuration options or write Express middleware functions in Oracle JET’s before_serve.js hook point. For an example that demonstrates how to add Express configuration options, see Serve a Web App to a HTTPS Server Using a Self-signed Certificate.

The before_serve hook point provides options to determine whether to replace the existing middleware or instead prepend and append a middleware function to the existing middleware. Typically, you’ll prepend a middleware function (preMiddleware) that you write if you want live reload to continue to work after you serve your web app. Live reload is the first middleware that Oracle JET tooling uses. You must use the next function as an argument to any middleware function that you write if you want subsequent middleware functions, such as live reload, to be invoked by the Express instance. In summary, use one of the following arguments to determine when your Express middleware function executes:

• preMiddleware: Execute before the default Oracle JET tooling middleware. The default Oracle JET tooling middleware consists of connect-livereload, serve-static, and serve-index, and executes in that order.
• postMiddleware: Execute after the default Oracle JET tooling middleware.
• middleware: Replaces the default Oracle JET tooling middleware. Use if you need strict control of the order in which middleware runs. Note that you will need to redefine all the default middleware that was previously added by Oracle JET tooling.

You can customize the JET CLI tooling to serve your web app to a HTTPS server instead of the default HTTP server that the Oracle JET ojet serve command uses.

Do this if, for example, you want to approximate your development environment more closely to a production environment where your web app will eventually be deployed. Requests to your web app when it is deployed to a production environment will be served from an SSL-enabled HTTP server (HTTPS).

To implement this behavior, you’ll need to install a certificate in your web app directory. You’ll also need to configure the before_serve.js hook to do the following:

• Create an instance of Express to host the served web app.

• Set up HTTPS on the Express instance that you’ve created. You specify the HTTPS protocol, identify the location of the self-signed certificate that you placed in the app directory, and specify a password.
• Pass the modified Express instance and the SSL-enabled server to the JET tooling so that ojet serve uses your middleware configuration rather than the ready-to-use middleware configuration provided by the Oracle JET tooling.
• To ensure that live reloads works when your web app is served to the HTTPS server, you’ll also create an instance of the live reload server and configure it to use SSL.

If you can’t use a certificate issued by a certificate authority, you can create your own certificate (a self-signed certificate). Tools such as OpenSSL, Keychain Access on Mac, and the Java Development Kit’s keytool utility can be used to perform this task for you. For example, using the Git Bash shell that comes with Git for Windows, you can run the following command to create a self-signed certificate with the OpenSSL tool:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Once you've obtained the self-signed certificate that you want to use, install it in your app's directory. For example, place the two files generated by the previous command in your app’s root directory:

...
.gitignore
cert.pem
key.pem
node_modules
...

Once you have installed the self-signed certificates in your app, you configure the script for the before_serve hook point. To do this, open the AppRootDir/scripts/hooks/before_serve.js with your editor and configure it as described by the comments in the following example configuration.

'use strict';

module.exports = function (configObj) {
  return new Promise((resolve, reject) => {
    console.log("Running before_serve hook.");

    // Create an instance of Express, the Node.js web app framework that Oracle 
    // JET tooling uses to host the web apps that you serve using ojet serve
    const express = require("express");

    // Set up HTTPS 
    const fs = require("fs");
    const https = require("https");
    
    // Specify the self-signed certificates. In our example, these files exist 
    // in the root directory of our project.
    const key = fs.readFileSync("./key.pem");
    const cert = fs.readFileSync("./cert.pem");
    // If the self-signed certificate that you created or use requires a 
    // password, specify it here:
    const passphrase = "1234";

    const app = express();

    // Pass the modified Express instance and the SSL-enabled server to the Oracle JET tooling
    configObj['express'] = app;
    configObj['urlPrefix'] = 'https';
    configObj['server'] = https.createServer({
      key: key,
      cert: cert,
      passphrase: passphrase
    }, app);

    // Enable the Oracle JET live reload option using its default port number so that
    // any changes you make to app code are immediately reflected in the browser after you
    // serve it
    const tinylr = require("tiny-lr");
    const lrPort = "35729";

    // Configure the live reload server to also use SSL
    configObj["liveReloadServer"] = tinylr({ lrPort, key, cert, passphrase });

    resolve(configObj);
  });
};

Once you have completed these configuration steps, run the series of commands (ojet build and ojet serve, for example) that you typically run to build and serve your web app. As the certificate that you are using is a self-signed certificate rather than a certificate issued by a certificate authority, the browser that you use to access the web app displays a warning the first time that you access the web app. Acknowledge the warning and click the options that allow you to access your web app. On Google Chrome, for example, you click Advanced and Proceed to localhost (unsafe) if your web app is being served to https://localhost:8000/.

Once your web app opens in the browser, you'll see that the HTTPS protocol is used and an indicator that the connection is not secure, because you are not using a certificate from a certificate authority. You can also view the certificate information to confirm that it is the self-signed certificate that you created. In Google Chrome, click Not secure and Certificate to view the certificate information.

The before_serve hook point is one of a series of script hook points that you can use to customize the tooling workflow for Oracle JET apps. See Customize the Web App Tooling Workflow.

The Oracle JET hooks system defines various script trigger points, also called hook points, that allow you to customize the create, build, serve, package, and restore workflow across the various command-line interface processes. Customization relies on script files and the script code that you want to trigger for a particular hook point.

The following table identifies the hook points and the workflow customizations they support in the Oracle JET tooling create, build, serve, and restore processes. Unless noted, hook points for the build and serve processes support both debug and release mode.

The Oracle JET hooks system defines various script trigger points, also called hook points, that allow you to customize the create, build, serve, and restore workflow across the various command-line interface processes.

The following diagram shows the script hook point flow for the create process.

The following diagram shows the script hook point flow for the build process.

The following diagram shows the script hook point flow for the serve and restore processes.

When you create an app, Oracle JET tooling generates script templates in the /scripts/hooks app subfolder. Your development effort may require you to relocate hook scripts to a common location, for example to support team development.

By default, the hooks system locates the scripts in the hooks subfolder using a generated JSON file (hooks.json) that specifies the script paths. When the tooling reaches the hook point, it executes the corresponding script which it locates using the hooks.json file. If you relocate hook script(s) to a common location, you must edit the hooks.json file to specify the new location for the hook scripts that you relocated, as illustrated by the following example.

{
    "description": "OJET-CLI hooks configuration file",
    "hooks": {
        "after_app_create": "scripts/hooks/after_app_create.js",
	...
        "after_serve": "http://example.com/cdn/common/scripts/hooks/after_serve.js "
    }
}

You can create a hook point script to define a new command-line interface process step for your web app. To create a hook script, you edit the hook script template associated with a specific hook point in the tooling build and serve workflow.

The Oracle JET hooks system defines various script trigger points, also called hook points, that allow you to customize the build and serve workflow across the various build and serve modes. Customization relies on script files and the script code that you want to trigger for a particular hook point. Note that the generated script templates that you modify with your script code are named for their corresponding hook point.

To customize the workflow for the build or serve processes, you edit the generated script template file named for a specific hook point. For example, to trigger a script at the start of the tooling's build process, you would edit the before_build.js script named for the hook point triggered before the build begins. That hook point is named before_build.

A basic example illustrates a simple customization using the before_optimize hook, which allows you to control the RequireJS properties shown in bold to modify the app's bundling configuration.

requirejs.config(
{
  baseUrl: "web/js",
  name: "main-temp",
  paths: {
  // injector:mainReleasePaths
    "knockout":"libs/knockout/knockout-3.x.x.debug",
    "jquery":"libs/jquery/jquery-3.x.x",
    "jqueryui-amd":"libs/jquery/jqueryui-amd-1.x.x",
     ...
  }
  // endinjector
  out: "web/main.js"
}
...

A script for this hook point might add one line to the before_optimize script template, as shown below. When you build the app with this customization script file in the default location, the tooling triggers the script before calling requirejs.out() and changes the out property setting to a custom directory path. The result is that the app-generated main.js is created in the named directory instead of the default web/js/main.js location.

module.exports = function (configObj) {
  return new Promise((resolve, reject) => {
    console.log("Running before_optimize hook.");
    configObj.requirejs.out = 'myweb/js/main.js';
    resolve(configObj);
  });
};

You can retrieve more information about the definition of configObj that is passed into many script hook points as a parameter by making the following modification in one of the build-related hook points and then running ojet build. For example, the before_build.js hook point can be modified as follows:

module.exports = function (configObj) {
  return new Promise((resolve, reject) => {
  	console.log("Running before_build hook.", configObj);
  	resolve(configObj);
   });
};

The console from where you run the ojet build command then displays the available options that you can customize in configObj.

Cleaning staging path.
Running before_build hook {
  buildType: 'dev',
  opts: {
    stagingPath: 'web',
    injectPaths: {
      startTag: '// injector:mainReleasePaths',
. . . 

Elsewhere, read examples that illustrate how to use the configObj to customize a hook point to, for example, add Express configuration options or write Express middleware functions in the before_serve.js hook point if the ready-to-use ojet serve options do not meet your requirements. See Serve a Web App to a HTTPS Server Using a Self-signed Certificate.

The following example illustrates a more complex build customization using the after_build hook. This hook script adds a customize task after the build finishes.

'use strict’;

const fs = require('fs');
const archiver = require('archiver');

module.exports = function (configObj) {
  return new Promise((resolve, reject) => {
   console.log("Running after_build hook.");

    //Set up the archive
    const output = fs.createWriteStream('my-archive.war');
    const archive = archiver('zip');

    //Callbacks for the archiver
    output.on('close', () => {
      console.log('Files were successfully archived.');
      resolve();
    });
  
    archive.on('warning', (error) => {
      console.warn(error);
    });
  
    archive.on('error', (error) => {
      reject(error);
    });
  
    //Archive the web folder and close the file
    archive.pipe(output);
    archive.directory('web', false);
    archive.finalize();
  });
};

In this example, assume the script templates reside in the default folder generated when you created the app. The goal is to package the app into a ZIP file. Because packaging occurs after the app build process completes, this script is triggered for the after_build hook point. For this hook point, the modified script template after_build.js will contain the script code to ZIP the app, and because the .js file resides in the default location, no hooks system configuration changes are required.

You can pass extra values to a hook script from the command-line interface when you build or serve the web app. The hook script that you create can use these values to perform some workflow action, such as creating an archive file from the contents of the web folder.

ojet build --user-options="some string1" "some string2" "some stringx"

ojet build web --user-options="archive-file=deploy.zip"

'use strict';
const fs = require('fs');
const archiver = require('archiver');
const path = require('path');

module.exports = function (configObj) {
  return new Promise((resolve, reject) => {
    console.log("Running after_build hook.");

    //Check to see if the user set the flag 
    //In this case we're only expecting one possible user defined
    //argument so the parsing can be simple
    const options = configObj.userOptions;
    if (options){
      const userArgs = options.split('=');
      if (userArgs.length > 1 && userArgs[0] === 'archive-file'){
        const deployRoot = 'deploy';
        const outputArchive = path.join(deployRoot,userArgs[1]);

        //Ensure the output folder exists
        if (!fs.existsSync(deployRoot)) {
          fs.mkdirSync(deployRoot);
        }

        //Set up the archive
        const output = fs.createWriteStream(outputArchive);
        const archive = archiver('zip');

        //callbacks for the archiver
        output.on('close', () => {
          console.log(`Archive file ${outputArchive} successfully created.`);
          resolve();
        });

        archive.on('error', (error) => {
          console.error(`Error creating archive ${outputArchive}`);
          reject(error);
        });

        //Archive the web folder and close the file
        archive.pipe(output);
        archive.directory('web', false);
        archive.finalize();
      }
      else {
        //Unexpected input - fail with information message
        reject(`Unexpected flags in user-options: ${options}`);
      }
    }
    else {
  	//nothing to do
  	resolve();
    }
  });
};