Use ojet create with optional arguments to create the Oracle JET web app and scaffolding.

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

"devDependencies": {
    "@oracle/oraclejet-tooling": "https://.../ojet-dev-local/oracle-oraclejet-tooling-17.1.0.tgz"
  },

Scaffolding is the process you use in the Oracle JET command-line interface (CLI) to create an app that contains a blank template or one pre-configured with a basic layout, navigation bar, or navigation drawer. Each pre-configured template is optimized for responsive web apps. After scaffolding, you can modify the app as needed.

The following image shows the differences between the pre-configured Starter Templates. The blank template contains an index.html file but no UI features. The basic:web template is similar to the blank template but adds responsive styling that will adjust the display when the screen size changes. The navbar:web and navdrawer:web templates contain sample content and follow best practices for layout, navigation, and styling that you can also modify as needed.

Description of the illustration gs_web_templates.png

After scaffolding, you can perform the following tasks to customize your app:

• Modify Starter Template Content

• Modify the Web App’s File Structure

The Oracle JET scaffolding process creates files and folders that you modify as needed for your app.

The new app will have a directory structure similar to the one shown in the following image.

Description of the illustration gs_web_directory.jpg

The app folders contain the app and configuration files that you will modify as needed for your own app.

After scaffolding, you can perform the following tasks to customize your app:

• Modify Starter Template Content

• Modify the Web App’s File Structure

You can modify your scaffolded app’s file structure if the default structure doesn’t meet your needs.

{
  "paths": {
    "source": {
      "common": "src",
      "web": "src-web",
      "hybrid": "src-hybrid",
      "javascript": "js",
      "typescript": "ts",
      "styles": "css",
      "themes": "themes"
    },
    "staging": {
      "web": "web",
      "hybrid": "hybrid",
      "themes": "themes"
    }
  },
  "defaultBrowser": "chrome",
  "sassVer": "8.0.0",
  "defaultTheme": "redwood",
  "architecture": "mvvm",
  "generatorVersion": "17.1.0"
}

1. In your app’s top level directory, open oraclejetconfig.json for editing.
2. In oraclejetconfig.json, change the paths as needed and save the file.

   For example, if you want to change the default styles path from css to app-css, edit the following line in oraclejetconfig.json:

   "styles": "app-css"

3. Rename the directories as needed for your app, making sure to change only the paths listed in oraclejetconfig.json.
   For example, if you changed styles to app-css in oraclejetconfig.json, change the app’s css directory to app-css.
4. Update your app files as needed to reference the changed path.

   For example, if you modified the path to the CSS for your app to app-css, update the links appropriately in your app’s index.html.

   <link rel="icon" href="app-css/images/favicon.ico" type="image/x-icon" />
   
       <!-- This is the main css file for the default theme -->
       <!-- injector:theme -->
       <link rel="stylesheet" href="app-css/libs/oj/v17.1.0/redwood/oj-redwood-min.css" type="text/css"/>
       <!-- endinjector -->

5. At the command prompt, from the app root directory, build your app to use the new paths.

   ojet build

Use the ojet build command with optional arguments to build a development version of your web app before serving it to a browser.

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

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.

Oracle JET apps use parameter-based routing by default. With a couple of changes, you can use path-based routing instead.

With parameter-based routing, the URLs that appear in a user’s browser may not be descriptive or easy to remember. For example, a JET app that uses the navbar template displays the following URLs in the browser when served locally:

• http://localhost:8000/?ojr=dashboard
• http://localhost:8000/?ojr=incidents

By way of contrast, the same app configured to use path-based routing uses the following URLs when the app displays the Dashboard or Incidents page:

• http://localhost:8000/dashboard
• http://localhost:8000/incidents

To implement this behavior, you need to configure the JET app so that when it receives a request from the client for a page, it rewrites the URL before it serves the request. Specifically, you’ll need to do the following:

• Update the appController.js file so that your app uses path-based routing by creating an instance of the UrlPathAdapter class that takes the base URL from which the app is served as a parameter.
• Configure the before_serve.js hook to do the following:
  • Write an Express function to inspect the path of the requested URL. If the request is for any of the typical file extensions (.js, .ts, and so on), the Express instance handles these requests while other requests are passed to the app's index.html file for JET's CoreRouter to manage.
  • Invoke the Express middleware function that you write using the before_serve.js hook point’s configObj['preMiddleware'] option so that the new Express middleware function is invoked before the default middleware used by Oracle JET tooling, such as live reload.

To update the appController.js file so that your app uses path-based routing, open the AppRootDir/src/js/appController.js with your editor and configure it as described by the comments in the following example configuration.

// Replace the entries that the JET tooling generates for 'ojs/ojurlparamadapter' and UrlParamAdapter 
// with entries for 'ojs/ojurlpathadapter' and UrlPathAdapter
define(... 'ojs/ojurlpathadapter', 'ojs/ojarraydataprovider', 'ojs/ojknockouttemplateutils', 'ojs/ojmodule-element', 'ojs/ojknockout'],
  function(... UrlPathAdapter, ArrayDataProvider, KnockoutTemplateUtils) {   
....
let baseUrl = "/";
       let router = new CoreRouter(navData, {
        urlAdapter: new UrlPathAdapter(baseUrl)
      });
      router.sync();
....

To configure the script for the before_serve hook point, 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) {

    /* Write an Express middleware function to inspect the path of the requested 
    URL. If the request is for any of the extensions (js, ts, and so on), 
    the Express instance handles these requests while other requests are
    passed to the app’s index.html file for the JET CoreRouter to manage. 
    */
  function urlRewriteMiddleware(req, res, next) {
    const matchStaticFiles = req.url.match(/\/(js|css)\/.*/);
    req.url = matchStaticFiles ? matchStaticFiles[0] : '/index.html';
    next();
  }
  return new Promise((resolve, reject) => {
    /* Call the Express middleware function that inspects the URL to rewrite 
       and prepend it to JET’s default middleware so that other options provided 
       by JET’s default middleware, such as live reload continue to work. 
    */	    	
    configObj['preMiddleware'] = [urlRewriteMiddleware]
    resolve(configObj);
  });
};

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/js/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 and Serve a Web App Using Path-based Routing.

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();
    }
  });
};