B Oracle JET Application Migration for Release 11.0.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 11.0.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 Redwood-themed Apps from Releases 9.x.0 to Release 11.0.0

To migrate your Oracle JET app source from version 9.x.0 to the latest version 11.0.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 11.0.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 commands to audit your app.

    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 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.

  • 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 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: 4.2.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@~11.0.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@~11.0.0 @oracle/oraclejet-tooling@~11.0.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 v11.0.0.

      <link rel="stylesheet" href="css/libs/oj/v11.0.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. 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 application 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. Update the Oracle JET library configuration paths to reference the 11.0.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": ""
            }
          },
      ...
  7. 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.

  8. 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 application bootstrap file. This function was included previously to detect whether an application 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(
           {
            ...
           }
         );
      }());
  9. Open the oraclejetconfig.json file in your app root folder and ensure it contains the following properties and settings for sassVer, defaultTheme, and generatorVersion. 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",
      "generatorVersion": "11.0.0"
    }
  10. 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 (11.0.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
  11. 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 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 11.0.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 11.0.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": "5.0.0",
       "defaultTheme": "redwood",
       "architecture": "mvvm",
       "generatorVersion": "11.0.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 Alta-themed Applications from Releases Prior to 8.3.0 to Release 11.0.0

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

  • 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.2.4.

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@~11.0.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@~11.0.0 @oracle/oraclejet-tooling@~11.0.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 v11.0.0.

      <link rel="stylesheet" href="css/libs/oj/v11.0.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. 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 application 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 application with the navdrawer template specified to obtain the files that you will copy to your migrating application.
    ojet create tempApp --template=navdrawer
  6. Update the Oracle JET library configuration paths to reference the 11.0.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": ""
            }
          },
      ...
  7. 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.

  8. In your application, open the main.js application 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 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.

    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 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.

    3. Remove the private function _ojIsIE11, if it appears in the main.js application bootstrap file. This function was included previously to detect whether an application 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(
           {
            ...
           }
         );
      }());
  9. Open the oraclejetconfig.json file in your application root folder and ensure it contains the following properties and settings for sassVer, defaultTheme, and generatorVersion. 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",
      "generatorVersion": "11.0.0"
    }

    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",

  10. 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
  11. 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.