B Oracle JET App Migration for Release 15.1.0

If you used Oracle JET tooling to scaffold your app with Oracle JET version 5.x.0 or later, you can migrate your app manually to version 15.1.0.

Before you migrate your app, be sure to check the Oracle JET Release Notes for any component, framework, or other change that could impact your app.

Important:

This process is not supported for Oracle JET releases prior to version 5.0.0.

Note:

The Alta theme was deprecated in release 10.0.0 and will be supported through the 12.x releases. In release 13.0.0 and later, Oracle JET will provide "best effort" support for Alta. No bug fixes or new features will be provided for Alta-only issues. For more information about Oracle JET's release schedule, see What is the release schedule for Oracle JET?

The content that described how to use the Alta theme in an Oracle JET app has been removed from the documentation and it has been removed from the Oracle JET Cookbook. If you want to refer to the documentation, consult release 11.1.0 of the documentation that last published Alta Theme in Oracle JET v9.0.0 and Later.

Migrate Redwood-themed Apps from Releases 9.x.0 or Later to Release 15.1.0

To migrate your Oracle JET app source from version 9.x.0 or later to the latest version 15.1.0, you must upgrade NPM packages, update theme and library reference paths, and replace the path_mapping.json file. Additionally, you replace references to the oj-redwood-cssvars*.css files that introduced CSS variables as a preview feature in JET release 9.0.0. CSS variables were a production feature in JET release 10.0.0. Finally, you include script injector tokens in appDirRoot/src/index.html that will automatically be replaced with the required scripts tags at build time.

Before You Begin:

• Oracle strongly recommends that you audit your app with Oracle JET Audit Framework (JAF) before any migration. The built-in audit rules provided with JAF will help you to identify and fix invalid functionality, including deprecated components and APIs. Implement the audit results with some attention to detail to ensure a successful migration to JET release 15.1.0.

  As Administrator on Windows or using sudo as needed on Macintosh and Linux systems, enter the following command in a terminal window:

  npm install -g @oracle/oraclejet-audit

  On your app root, run the following JAF command to initialize the audit of your app.

  ojaf --init

  In the generated AppRootDir/oraclejafconfig.json file, set the value of the jetVer property to the release to which you are migrating your app. For example, "jetVer": "15.1.0".

  Run the following command to audit your app and review any issues that the audit identifies.

  ojaf

  For more details about JAF, see Initialize Oracle JAF and Run an Audit in Using and Extending the Oracle JET Audit Framework.

• A maintenance or active long-term support (LTS) version of Node.js is required. Open a Command Prompt window as an administrator and check your Node.js version.

  node -v

  If your Node.js version is earlier than the versions listed as maintenance or active LTS on the Releases page of the Nodejs.org website, download a newer LTS version. Go to the Nodejs.org website. Under LTS Version (Recommended for Most Users), download the installer for your system. In the Download dialog box, choose a location for the file and click Save. Run the downloaded installer as an administrator and follow the steps in the installation wizard to install Node.js.

  One additional caveat is that if you install version 16 or higher of Node.js, change the value of sassVer in your appRootDir/oraclejetconfig.json file to a version of node-sass that is compatible with the Node.js version that you have installed. Oracle JET installs the version of node-sass specified by sassVer when you run the ojet add theming command to use custom themes in your Oracle JET app. For example, if you installed v16.17.1 of Node.js, set "sassVer": "7.0.0" in your appRootDir/oraclejetconfig.json file.

• Starting in JET release 9.0.0, apps configured for TypeScript development require a local installation of the TypeScript library to perform compilation. To ensure that your app, if configured for TypeScript development, has a local installation, run the following command from the root of your app.

  ojet add typescript

  The JET Tooling installs the latest supported version of the TypeScript language: 5.0.4.

To migrate your app:

1. Remove the existing version of the ojet-cli tooling package and install the latest version.

   As Administrator on Windows or using sudo as needed on Macintosh and Linux systems, enter the following commands in a terminal window:

   [sudo] npm uninstall -g ojet-cli
   npm install -g @oracle/ojet-cli@~15.1.0

2. Enter the following commands to change to the app’s top-level directory and upgrade local NPM dependencies:

   cd appDir
   npm uninstall @oracle/oraclejet @oracle/oraclejet-tooling
   npm install @oracle/oraclejet@~15.1.0 @oracle/oraclejet-tooling@~15.1.0 --save

3. In the app’s src directory, replace any hardcoded references to a previous version.
   1. If CSS references to Redwood, similar to the following, appear in the src/index.html file:

      <!-- This is the main css file for the default theme -->
       <!-- injector:theme -->
        <link rel="stylesheet" href="css/libs/oj/v9.0.0/redwood/oj-redwood-min.css" 
              type="text/css"/>
       <!-- endinjector -->

      Remove the <link> tag so that only the injector:theme entry remains:

      <!-- This is the main css file for the default theme -->
       <!-- injector:theme -->
       <!-- endinjector -->

   2. Search for hardcoded references to a previous release version that may appear in .html and .js files and replace those with the current release version.

4. If present in the src/index.html file, replace the following script tags:

   . . . 
       <script type="text/javascript" src="js/libs/require/require.js"></script>
       <script type="text/javascript" src="js/main.js"></script>
     </body>
   </html>

   With these script tag injector tokens:

    . . .   
     <!-- This injects script tags for the main javascript files -->
   	<!-- injector:scripts -->
   	<!-- endinjector -->
     </body>
   </html>

   At build time, these tokens will automatically be replaced with the required scripts tags. During debug builds, the tokens will be replaced with script tags that load the require.js and main.js files. During release builds, the tokens will be replaced with script tags that load the require.js and bundle.js files. Because it is no longer used during release builds, the main.js file will be deleted at the end of the build. This means that if your app does not use the script tag injector tokens, it will have to include a script tag in the appRootDir/src/index.html file that loads bundle.js instead of main.js.

5. At a terminal prompt, create a temporary app with the navdrawer template specified to obtain the files that you will copy to your migrating app.

   ojet create tempApp --template=navdrawer

6. Review the entries in the package.json and oraclejetconfig.json files of the temporary app to ensure that release 15.1.0 of JET does not include new or modified entries that you should make in the app that you are migrating to release 15.1.0.
7. Update the Oracle JET library configuration paths to reference the 15.1.0 versions of Oracle libraries by copying the path_mappings.json file from the temporary app.

   1. Rename your migrating app’s src/js/path_mapping.json as migrating-path_mapping.json.

   2. Copy tempApp/src/js/path_mapping.json to your migrating app’s src/js directory.

   3. If you added any third-party libraries to your app, open path_mapping.json for editing and add an entry for each library that appears in migrating-path_mapping.json, copying an existing entry and modifying as needed. The code sample below shows the addition you might make for a third-party library named my-library.

      "libs": {
      
          "my-library": {
            "cdn": "3rdparty",
            "cwd": "node_modules/my-library/build/output",
            "debug": {
              "src": "my-library.debug.js",
              "path": "libs/my-library/my-library.debug.js",
              "cdnPath": ""
            },
            "release": {
              "src": "my-library.js",
              "path": "libs/my-library/my-library.js",
              "cdnPath": ""
            }
          },
      ...

8. Update the app script templates by copying from the temporary app.

   1. Copy any new script template files from the tempApp/scripts/hooks directory to your migrating app’s scripts/hooks directory.

   2. Copy the hooks.json scripting configuration file from the tempApp/scripts/hooks directory to your migrating app’s scripts/hooks directory. The updated configuration file associates any new script template files with their corresponding build system hook point and allows the Oracle JET CLI to call your scripts.

9. In your app, open the main.js app bootstrap file and verify that it contains the following code.

   1. Verify that the paths property of the requirejs.config definition includes the opening and closing //injector and //endinjector comments. If the comments were removed, add them to your requirejs.config() definition, as shown.

         requirejs.config(
           {
             baseUrl: 'js',
      
             paths:
             /* DO NOT MODIFY
             ** All paths are dynamicaly generated from the path_mappings.json file.
             ** Add any new library dependencies in path_mappings json file.
             */
             //injector:mainReleasePaths
             {
                ...no need to revise...
             }
             //endinjector 
           }
         );

      When you build or serve the app, the tooling relies on the presence of these injector comments to inject release-specific library paths in main.js. The updated path_mapping.json file (from the previous migration step) ensures that the migrated app has the correct library configuration paths for this release.

   2. Verify that any modifications you made to app.loadModule() in your main.js file appear.

      Starting in JET release 9.0.0, app.loadModule() is deprecated and has been removed from main.js, but your bootstrap code may continue to use the function, for example to change a path. Because migrating apps created prior to release 9.x.0 rely on loadModule(), the function should remain in your migrated main.js file, and your migrated appController.js file should contain the loadModule() definition.

      In new apps that you create, starting in JET release 9.0.0, the loadModule() observable dependency is no longer used to support the deprecated ojRouter for use with the oj-module element. Starter app templates now use CoreRouter and work with oj-module though the ModuleRouterAdapter.

   3. Remove the private function _ojIsIE11, if it appears in the main.js app bootstrap file. This function was included previously to detect whether an app was running in the IE11 web browser in order to load the required polyfills and the transpiled to ES5 version of Oracle JET. Starting in JET release 11.0.0, JET removed support for IE11 and no longer distributes the polyfills and other resources to run JET apps in the IE11 web browser. As a result, the _ojIsIE11 function serves no purpose, and can be removed.

      (function () {
      
         function _ojIsIE11() {
            var nAgt = navigator.userAgent;
            return nAgt.indexOf('MSIE') !== -1 || !!nAgt.match(/Trident.*rv:11./);
         };
         var _ojNeedsES5 = _ojIsIE11();
      
         requirejs.config(
           {
            ...
           }
         );
      }());

10. Open the oraclejetconfig.json file in your app root folder and ensure it contains the following properties and settings for sassVer and defaultTheme. The following example specifies redwood so that the app uses the Redwood theme. If your app uses a custom theme, specify the name of the custom theme. For example, "defaultTheme": "myCustomTheme",

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

11. Test the migration and verify the look and feel.
    1. If your app uses a custom theme, you may encounter the following console error message if you not recompile the custom theme after you update it from the previous to the current release:

       "Your CSS file is incompatible with this version of JET (15.1.0)"

    2. To make your custom theme compatible with the new JET version, run ojet add sass to enable Sass processing.

    3. Run ojet build and ojet serve with appropriate options to build and serve the app.

       For a list of available options, enter the following command at a terminal prompt in your app’s top-level directory: ojet help.

       If your app uses a custom theme, be sure to include the --theme option to recompile the CSS:

       ojet build [options] --theme=myTheme

       To specify multiple custom themes, use:

       ojet build [options] --theme=myTheme --themes=myTheme,myTheme1,myTheme2

12. Optional: When you are satisfied that your app has migrated successfully, remove the temporary app and delete the renamed migrating-path_mapping.json and migrating-main.js files from your migrated app. Should you find issues, you can re-run the JAF audit tool for an audit report.

Migrate to the Redwood Theme CSS

Redwood theme is the Oracle JET standard for app look and feel and is available when you want to migrate your app to the Redwood theme.

If you have an existing app that you want to migrate from the Alta theme, you can migrate to JET release 15.1.0 and configure the app to run with the Redwood CSS included with Oracle JET. You obtained the Redwood CSS distribution when you completed the app source migration process.

Migrating your app's Alta theme to Redwood theme requires making a change at the app level. You edit the oraclejetconfig.json file to control whether JET Tooling builds with the Redwood or Alta CSS. With the setting configured, you can rebuild your app and all the pages will use the appropriate CSS, as specified by the stylesheet injector in your app's index.html file.

After you set the Redwood theme as the new default and run your app, you will find the look and feel of your app changes considerably. To adjust to the Redwood theme, you will need to make manual updates to app layout for new fonts, sizes, and patterns.

CSS variables, which are supported by the Redwood theme, were introduced in the oj-redwood-cssvars*.css files as a preview feature in JET release 9.0.0. In JET release 10.0.0, CSS variables became a production feature and are now included in the oj-redwood*.css files. Replace references to the oj-redwood-cssvars*.css files with references to the oj-redwood*.css files in your migrated apps. Be aware of this change if you migrated your app to use the Redwood theme and started to use CSS variables in JET releases prior to release 10.0.0.

Before You Begin:

• Complete migration of your app source files before attempting to migrate to the Redwood theme. First migrate with the Alta theme preserved and then migrate to the Redwood theme. This way you can test your app with the Redwood theme and easily revert back to the Alta theme, if desired. See Migrate Alta-themed Apps from Releases Prior to 8.3.0 to Release 15.1.0 for details.

• If you use a custom theme, review the Theme Changes section in the release notes and update your custom theme manually.

  Be aware that Sass variables that you may have overridden in an Alta theme will need to be migrated to CSS variables in the Redwood theme. For more information about migrating a custom theme, please see About CSS Variables and Custom Themes in Oracle JET.

• Review app images and consider how you will replace images that belong to the deprecated Oracle JET framework images library with public domain images, such as those found on Oracle Apex Universal Theme and on Font Awesome. The Oracle JET framework image classes are no longer shown in JET Cookbook, starting in release 9.0.0.

To migrate to the Redwood theme CSS:

1. Configure the app to load the Redwood CSS.

   Edit the <app_root>/oraclejetconfig.json file and change the property defaultTheme to redwood.

   {
     "paths": { 
          ...
        }
      },
      "defaultBrowser": "chrome",
      "sassVer": "5.0.0",
      "defaultTheme": "redwood",
      "architecture": "mvvm"
   }

   This configures JET Tooling to inject oj-redwood-min.css into the stylesheet link in your app's index.html file.

2. Test the migration and verify the look and feel.

   Run ojet build and ojet serve with appropriate options to build and serve the app.

   For a list of available options, enter the following command at a terminal prompt in your app’s top level directory: ojet help.

   If your app uses a custom theme, be sure to include the --theme option to regenerate the CSS:

   ojet build [options] --theme=myTheme

   To specify multiple custom themes, use:

   ojet build [options] --theme=myTheme --themes=myTheme,myTheme1,myTheme2

Migrate Alta-themed Apps from Releases Prior to 8.3.0 to Release 15.1.0

To migrate your Oracle JET app source from version 5.x.0 through version 8.3.0 to the latest version 15.1.0, you must upgrade npm packages, update theme and library reference paths, and replace the path_mapping.json file. Additionally, you must update the oraclejetconfig.json file to enable Alta CSS support in JET release 15.1.0. Migration to the Redwood CSS theme, if desired, should be performed only after successful migration of the app source has been verified. Finally, you include script injector tokens in appDirRoot/src/index.html that will automatically be replaced with the required scripts tags at build time.

Before You Begin:

• Due to potential incompatibilities with releases prior to JET version 9.0.0, Oracle strongly recommends that you audit your app with Oracle JET Audit Framework (JAF). The built-in audit rules provided with JAF will help you to identify and fix invalid functionality, including deprecated components and APIs. Implement the audit results with some attention to detail to ensure a successful migration to JET release 15.1.0.

  As Administrator on Windows or using sudo as needed on Macintosh and Linux systems, enter the following command in a terminal window:

  npm install -g @oracle/oraclejet-audit

  On your app root, run the following JAF command to initialize the audit of your app.

  ojaf --init

  In the generated AppRootDir/oraclejafconfig.json file, set the value of the jetVer property to the release to which you are migrating your app. For example, "jetVer": "15.1.0".

  Run the following command to audit your app and review any issues that the audit identifies.

  ojaf

  For more details about JAF, see Initialize Oracle JAF and Run an Audit in Using and Extending the Oracle JET Audit Framework.

• A maintenance or active long-term support (LTS) version of Node.js is required. Open a Command Prompt window as an administrator and check your Node.js version.

  node -v

  If your Node.js version is earlier than the versions listed as maintenance or active LTS on the Releases page of the Nodejs.org website, download a newer LTS version. Go to the Nodejs.org website. Under LTS Version (Recommended for Most Users), download the installer for your system. In the Download dialog box, choose a location for the file and click Save. Run the downloaded installer as an administrator and follow the steps in the installation wizard to install Node.js.

  One additional caveat is that if you install version 16 or higher of Node.js, change the value of sassVer in your appRootDir/oraclejetconfig.json file to a version of node-sass that is compatible with the Node.js version that you have installed. Oracle JET installs the version of node-sass specified by sassVer when you run the ojet add theming command to use custom themes in your Oracle JET app. For example, if you installed v16.17.1 of Node.js, set "sassVer": "7.0.0" in your appRootDir/oraclejetconfig.json file.

• Starting in JET release 9.0.0, apps configured for TypeScript development require a local installation of the TypeScript library to perform compilation. To ensure that your app, if configured for TypeScript development, has a local installation, run the following command from the root of your app.

  ojet add typescript

  The JET Tooling installs the latest supported version of the TypeScript language: 5.0.4.

To migrate your app:

1. Remove the existing version of the ojet-cli tooling package and install the latest version.

   As Administrator on Windows or using sudo as needed on Macintosh and Linux systems, enter the following commands in a terminal window:

   [sudo] npm uninstall -g ojet-cli
   npm install -g @oracle/ojet-cli@~15.1.0

2. Enter the following commands to change to the app’s top level directory and upgrade local npm dependencies:

   cd appDir
   npm uninstall @oracle/oraclejet @oracle/oraclejet-tooling
   npm install @oracle/oraclejet@~15.1.0 @oracle/oraclejet-tooling@~15.1.0 --save

3. In the app’s src directory, replace any hardcoded references to a previous version.

   1. Edit the src/index.html file and replace the existing CSS reference with version v15.1.0.

      <link rel="stylesheet" href="css/libs/oj/v15.1.0/alta/oj-alta-min.css" id="css" />
      

   2. Search for other hardcoded references to a previous release version that may appear in .html and .js files and replace those with the current release version.

4. If present in the src/index.html file, replace the following script tags:

   . . . 
       <script type="text/javascript" src="js/libs/require/require.js"></script>
       <script type="text/javascript" src="js/main.js"></script>
     </body>
   </html>

   With these script tag injector tokens:

    . . .   
     <!-- This injects script tags for the main javascript files -->
   	<!-- injector:scripts -->
   	<!-- endinjector -->
     </body>
   </html>

   At build time, these tokens will automatically be replaced with the required scripts tags. During debug builds, the tokens will be replaced with script tags that load the require.js and main.js files. During release builds, the tokens will be replaced with script tags that load the require.js and bundle.js files. Because it is no longer used during release builds, the main.js file will be deleted at the end of the build. This means that if your app does not use the script tag injector tokens, it will have to include a script tag in the appRootDir/src/index.html file that loads bundle.js instead of main.js.

5. At a terminal prompt, create a temporary app with the navdrawer template specified to obtain the files that you will copy to your migrating app.

   ojet create tempApp --template=navdrawer

6. Review the entries in the package.json and oraclejetconfig.json files of the temporary app to ensure that release 15.1.0 of JET does not include new or modified entries that you should make in the app that you are migrating to release 15.1.0.
7. Update the Oracle JET library configuration paths to reference the 15.1.0 versions of Oracle libraries by copying the path_mappings.json file from the temporary app.

   1. Rename your migrating app’s src/js/path_mapping.json as migrating-path_mapping.json.

   2. Copy tempApp/src/js/path_mapping.json to your migrating app’s src/js directory.

   3. If you added any third-party libraries to your app, open path_mapping.json for editing and add an entry for each library that appears in migrating-path_mapping.json, copying an existing entry and modifying as needed. The code sample below shows the addition you might make for a third-party library named my-library.

      "libs": {
      
          "my-library": {
            "cdn": "3rdparty",
            "cwd": "node_modules/my-library/build/output",
            "debug": {
              "src": "my-library.debug.js",
              "path": "libs/my-library/my-library.debug.js",
              "cdnPath": ""
            },
            "release": {
              "src": "my-library.js",
              "path": "libs/my-library/my-library.js",
              "cdnPath": ""
            }
          },
      ...

8. Update the app script templates by copying from the temporary app.

   1. Copy any new script template files from the tempApp/scripts/hooks directory to your migrating app’s scripts/hooks directory.

   2. Copy the hooks.json scripting configuration file from the tempApp/scripts/hooks directory to your migrating app’s scripts/hooks directory. The updated configuration file associates any new script template files with their corresponding build system hook point and allows the Oracle JET CLI to call your scripts.

9. In your app, open the main.js app bootstrap file and verify that it contains the following code.

   1. Verify that the paths property of the requirejs.config definition includes the opening and closing //injector and //endinjector comments. If the comments were removed, add them to your requirejs.config() definition, as shown.

         requirejs.config(
           {
             baseUrl: 'js',
      
             paths:
             /* DO NOT MODIFY
             ** All paths are dynamicaly generated from the path_mappings.json file.
             ** Add any new library dependencies in path_mappings json file.
             */
             //injector:mainReleasePaths
             {
                ...no need to revise...
             }
             //endinjector 
           }
         );

      When you build or serve the app, the tooling relies on the presence of these injector comments to inject release-specific library paths in main.js. The updated path_mapping.json file (from the previous migration step) ensures that the migrated app has the correct library configuration paths for this release.

   2. Verify that any modifications you made to app.loadModule() in your main.js file appear.

      Starting in JET release 9.0.0, app.loadModule() is deprecated and has been removed from main.js, but your bootstrap code may continue to use the function, for example to change a path. Because migrating apps rely on loadModule(), the function should remain in your migrated main.js file, and your migrated appController.js file should contain the loadModule() definition.

      In new apps that you create, starting in JET release 9.0.0, the loadModule() observable dependency is no longer used to support the deprecated ojRouter for use with the oj-module element. Starter app templates now use CoreRouter and work with oj-module though the ModuleRouterAdapter.

   3. Remove the private function _ojIsIE11, if it appears in the main.js app bootstrap file. This function was included previously to detect whether an app was running in the IE11 web browser in order to load the required polyfills and the transpiled to ES5 version of Oracle JET. Starting in JET release 11.0.0, JET removed support for IE11 and no longer distributes the polyfills and other resources to run JET apps in the IE11 web browser. As a result, the _ojIsIE11 function serves no purpose, and can be removed.

      (function () {
      
         function _ojIsIE11() {
            var nAgt = navigator.userAgent;
            return nAgt.indexOf('MSIE') !== -1 || !!nAgt.match(/Trident.*rv:11./);
         };
         var _ojNeedsES5 = _ojIsIE11();
      
         requirejs.config(
           {
            ...
           }
         );
      }());

10. Open the oraclejetconfig.json file in your app root folder and ensure it contains the following properties and settings for sassVer and defaultTheme. If your app uses a custom theme, specify the name of the custom theme instead. For example, "defaultTheme": "myCustomTheme",

    {
      "paths": {
        "source": {
    	"common": "src",
    	"web": "src-web",
    	"hybrid": "src-hybrid",
    	"javascript": "js",
    	"typescript": "ts",
    	"styles": "css",
    	"themes": "themes"
        },
        "staging": {
    	"web": "web",
    	"hybrid": "hybrid",
    	"themes": "staged-themes"
        }
      },
      "defaultBrowser": "chrome",
      "sassVer": "5.0.0",
      "defaultTheme": "alta",
      "architecture": "mvvm"
    }

    The setting "defaultTheme": "alta" enables your app to migrate and remain on the Alta theme. This property supports migrating to the Redwood theme in a later migration process. If your app uses a custom theme, specify the name of the custom theme instead. For example, "defaultTheme": "myCustomTheme",

11. Test the migration and verify the look and feel.

    1. If your app uses a custom theme, run ojet add sass to enable Sass processing.

    2. Run ojet build and ojet serve with appropriate options to build and serve the app.

       For a list of available options, enter the following command at a terminal prompt in your app’s top level directory: ojet help.

       If your app uses a custom theme, be sure to include the --theme option to regenerate the CSS:

       ojet build [options] --theme=myTheme

       To specify multiple custom themes, use:

       ojet build [options] --theme=myTheme --themes=myTheme,myTheme1,myTheme2

12. Optional: When you are satisfied that your app has migrated successfully, remove the temporary app and delete the renamed migrating-path_mapping.json and migrating-main.js files from your migrated app. Should you find issues, you can re-run the JAF audit tool for an audit report.

After you migrate your app and ensure it runs with the Alta theme, you can follow an additional, separate process to migrate to the Redwood theme, as described in Migrate to the Redwood Theme CSS.