B Oracle JET Application Migration for Release 10.1.0

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

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

Important:

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

Topics:

Migrate Alta-themed Applications from Releases Prior to 8.3.0 to Release 10.1.0

To migrate your Oracle JET application source from version 5.x.0 through version 8.3.0 to the latest version 10.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 10.1.0. Migration to the Redwood CSS theme, if desired, should be performed only after successful migration of the application source has been verified.

Before You Begin:

  • Due to potential incompatibilities with releases prior to JET version 9.0.0, Oracle strongly recommends that you audit your application 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 10.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 application root, run the following JAF commands to audit your application.

    ojaf --init
    ojaf

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

  • A minimum version of 10.0.0 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 isn't 10.0.0 or later, then 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.

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

    ojet add typescript

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

To migrate your application:

  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@~10.1.0
  2. Enter the following commands to change to the application’s top level directory and upgrade local npm dependencies:
    cd appDir
    npm uninstall @oracle/oraclejet @oracle/oraclejet-tooling
    npm install @oracle/oraclejet@~10.1.0 @oracle/oraclejet-tooling@~10.1.0 --save
  3. In the application’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 v10.1.0.

      <link rel="stylesheet" href="css/libs/oj/v10.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. At a terminal prompt, create a temporary application with the navdrawer template specified to obtain the files that you will copy to your migrating application.
    ojet create tempApp --template=navdrawer
  5. Update the Oracle JET library configuration paths to reference the 10.1.0 versions of Oracle libraries by copying the path_mappings.json file from the temporary application.
    1. Rename your migrating application’s src/js/path_mapping.json as migrating-path_mapping.json.

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

    3. If you added any third-party libraries to your application, 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": ""
            }
          },
      ...
  6. Update the application script templates by copying from the temporary application.
    1. Copy any new script template files from the tempApp/scripts/hooks directory to your migrating application’s scripts/hooks directory.

    2. Copy the hooks.json scripting configuration file from the tempApp/scripts/hooks directory to your migrating application’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.

  7. In your application, open the main.js application bootstrap file and verify that it contains the following code.
    1. Verify that the private function _ojIsIE11 appears. If the function is missing in main.js, add it above the requirejs.config definition, as shown.

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

      This function detects whether the application is running in the IE11 web browser to enable loading of required polyfills and the transpiled to ES5 version of Oracle JET. If IE11 is not detected at runtime, then Oracle JET enables the default ES6-based browser support, which does not require loading of polyfill libraries.

    2. 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 application, 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 application has the correct library configuration paths for this release.

    3. 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 applications 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 applications 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 application templates now use CoreRouter and work with oj-module though the ModuleRouterAdapter.

  8. Open the oraclejetconfig.json file in your application root folder and ensure it contains the following properties and settings for sassVer, defaultTheme, and generatorVersion.
    {
      "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": "4.13.0",
      "defaultTheme": "alta",
      "generatorVersion": "10.1.0"
    }

    The setting "defaultTheme": "alta" enables your application to migrate and remain on the Alta theme. This property supports migrating to the Redwood theme in a later migration process.

  9. Test the migration and verify the look and feel.
    1. If your application 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 application.

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

      If your application 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
  10. Optional: When you are satisfied that your application has migrated successfully, remove the temporary application and delete the renamed migrating-path_mapping.json and migrating-main.js files from your migrated application. Should you find issues, you can re-run the JAF audit tool for an audit report.

After you migrate your application 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.

Migrate to the Redwood Theme CSS

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

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

Migrating your application's Alta theme to Redwood theme requires making a change at the application 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 application and all the pages will use the appropriate CSS, as specified by the stylesheet injector in your application's index.html file.

After you set the Redwood theme as the new default and run your application, you will find the look and feel of your application changes considerably. To adjust to the Redwood theme, you will need to make manual updates to application 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 applications. Be aware of this change if you migrated your application 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 application 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 application with the Redwood theme and easily revert back to the Alta theme, if desired. See Migrate Alta-themed Applications from Releases Prior to 8.3.0 to Release 10.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 application 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 application to load the Redwood CSS.

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

    {
      "paths": { 
           ...
         }
       },
       "defaultBrowser": "chrome",
       "sassVer": "x.x.x",
       "defaultTheme": "redwood",
       "generatorVersion": "10.1.0"
    }

    This configures JET Tooling to inject oj-redwood-min.css into the stylesheet link in your application'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 application.

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

    If your application 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 Redwood-themed Applications from Releases 9.x.0 to Release 10.1.0

To migrate your Oracle JET application source from version 9.x.0 to the latest version 10.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 are a production feature in JET release 10.1.0.

Before You Begin:

  • Oracle strongly recommends that you audit your application 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 10.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 application root, run the following JAF commands to audit your application.

    ojaf --init
    ojaf

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

  • A minimum version of 10.0.0 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 isn't 10.0.0 or later, then 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.

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

    ojet add typescript

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

To migrate your application:

  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@~10.1.0
  2. Enter the following commands to change to the application’s top level directory and upgrade local npm dependencies:
    cd appDir
    npm uninstall @oracle/oraclejet @oracle/oraclejet-tooling
    npm install @oracle/oraclejet@~10.1.0 @oracle/oraclejet-tooling@~10.1.0 --save
  3. In the application’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 v10.1.0.

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

      If you are not using the JET CLI to build your app, you'll need to search for hardcoded references to the oj-redwood-cssvars-min.css file and replace with references to oj-redwood-min.css. CSS variables 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.

    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. At a terminal prompt, create a temporary application with the navdrawer template specified to obtain the files that you will copy to your migrating application.
    ojet create tempApp --template=navdrawer
  5. Update the Oracle JET library configuration paths to reference the 10.1.0 versions of Oracle libraries by copying the path_mappings.json file from the temporary application.
    1. Rename your migrating application’s src/js/path_mapping.json as migrating-path_mapping.json.

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

    3. If you added any third-party libraries to your application, 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": ""
            }
          },
      ...
  6. Update the application script templates by copying from the temporary application.
    1. Copy any new script template files from the tempApp/scripts/hooks directory to your migrating application’s scripts/hooks directory.

    2. Copy the hooks.json scripting configuration file from the tempApp/scripts/hooks directory to your migrating application’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.

  7. In your application, open the main.js application bootstrap file and verify that it contains the following code.
    1. Verify that the private function _ojIsIE11 appears. If the function is missing in main.js, add it above the requirejs.config definition, as shown.

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

      This function detects whether the application is running in the IE11 web browser to enable loading of required polyfills and the transpiled to ES5 version of Oracle JET. If IE11 is not detected at runtime, then Oracle JET enables the default ES6-based browser support, which does not require loading of polyfill libraries.

    2. 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 application, 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 application has the correct library configuration paths for this release.

    3. 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 applications 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 applications 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 application templates now use CoreRouter and work with oj-module though the ModuleRouterAdapter.

  8. Open the oraclejetconfig.json file in your application root folder and ensure it contains the following properties and settings for sassVer, defaultTheme, and generatorVersion.
    {
      "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": "4.13.0",
      "defaultTheme": "redwood",
      "generatorVersion": "10.1.0"
    }
  9. Test the migration and verify the look and feel.
    1. If your application 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 application.

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

      If your application 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
  10. Optional: When you are satisfied that your application has migrated successfully, remove the temporary application and delete the renamed migrating-path_mapping.json and migrating-main.js files from your migrated application. Should you find issues, you can re-run the JAF audit tool for an audit report.