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

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@~17.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@~17.1.0 @oracle/oraclejet-tooling@~17.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 17.1.0 of JET does not include new or modified entries that you should make in the app that you are migrating to release 17.1.0.
   In particular, pay attention to the version numbers referenced by the various *Libraries properties in the oraclejetconfig.json file for optional features that your Oracle JET app may use. These properties (typescriptLibraries, webpackLibraries, mochaTestingLibraries, and jestTestingLibraries) reference additional packages that your Oracle JET app requires if it uses TypeScript, Webpack, or the testing libraries.
7. Update the Oracle JET library configuration paths to reference the 17.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": "8.0.0",
      "defaultTheme": "redwood",
      "typescriptLibraries": "...",
      "webpackLibraries": "...",
      "mochaTestingLibraries": "...",
      "jestTestingLibraries": "...",
      "architecture": "mvvm"
    }

    If your app uses TypeScript, Webpack or testing libraries, ensure that the *Libraries properties for these features are up-to-date by reviewing the entries in the temporary app that you created earlier (./tempApp/oraclejetconfig.json).

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

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.

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": "8.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

To migrate your Oracle JET app source from version 5.x.0 through version 8.3.0 to the latest version 17.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 17.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.

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@~17.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@~17.1.0 @oracle/oraclejet-tooling@~17.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 v17.1.0.

      <link rel="stylesheet" href="css/libs/oj/v17.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 17.1.0 of JET does not include new or modified entries that you should make in the app that you are migrating to release 17.1.0.
   In particular, pay attention to the version numbers referenced by the various *Libraries properties in the oraclejetconfig.json file for optional features that your Oracle JET app may use. These properties (typescriptLibraries, webpackLibraries, mochaTestingLibraries, and jestTestingLibraries) reference additional packages that your Oracle JET app requires if it uses TypeScript, Webpack, or the testing libraries.
7. Update the Oracle JET library configuration paths to reference the 17.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": "8.0.0",
      "defaultTheme": "alta",
      "typescriptLibraries": "...",
      "webpackLibraries": "...",
      "mochaTestingLibraries": "...",
      "jestTestingLibraries": "...",
      "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",

    If your app uses TypeScript, Webpack or testing libraries, ensure that the *Libraries properties for these features are up-to-date by reviewing the entries in the temporary app that you created earlier (./tempApp/oraclejetconfig.json).

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.