B Oracle JET v7.2.0 Tooling Migration

If you used Oracle JET tooling to scaffold your application with Oracle JET v5.x.0, v6.x.0, or v7.x.0 you can migrate your application manually to v7.2.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 v5.0.0.

Migrating a v5.x.0, v6.x.0 Application to v7.2.0

To migrate your Oracle JET application from v5.x.0 or v6.x.0. you must upgrade npm packages, update theme and library reference paths, and the replace path_mapping.json file.

Beginning with 5.0.0, you no longer need to edit multiple files when adding new libraries, and you no longer need to update paths manually in src/js/main.js or scripts/config/oraclejet-build.js.
  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 command in a terminal window:

    [sudo] npm install -g @oracle/ojet-cli@~7.2.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@~7.2.0 @oracle/oraclejet-tooling@~7.2.0 --save
  3. Review the Theming section in the release notes for SCSS variable or other changes, and update your theming files manually, if needed.
  4. 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 the v7.2.0 version.

      <link rel="stylesheet" href="css/libs/oj/v7.2.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.

  5. Update the Oracle JET library configuration paths to reference the v7.2.0 version of Oracle libraries.
    1. At a terminal prompt, create a temporary application to obtain the files that you will copy as needed to your migrating application:

      ojet create tempApp
    2. Rename your migrating application’s src/js/path_mapping.json as migrating-path_mapping.json.

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

    4. 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. Verify that the paths property of the requirejs.config in the src/js/main.js file includes the opening and closing //injector and //endinjector comments. When you build or serve the application, the tooling relies on the presence of these comments to inject release-specific library paths in the generated web/js/main.js file. 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.
    requirejs.config(
     {
       baseUrl: 'js',
       // Path mappings for the logical module names
       // Update the main-release-paths.json for release mode when updating the mappings
       paths:
       //injector:mainReleasePaths
        {
         ...no need to revise...
        }
       //endinjector 
     }
    );
  7. Copy any new script template files from the tempApp/scripts/hooks directory to your migrating application’s scripts/hooks directory.
  8. To test the migration, 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
  9. Optional: When you are satisfied that your application has migrated successfully, remove the temporary application and delete the renamed migrating-path_mapping.json file from your migrated application.

Migrating a v7.x.0 Application to v7.2.0

When upgrading to a minor release version of Oracle JET, within the same major version, such as from 7.0.0 or 7.1.0 to 7.2.0, features changes do not introduce backward incompatibility from the previous release. In this case, you need only update the Oracle JET command-line interface (CLI), and you can leave npm unchanged. In the migrating application, you will update the CDN paths in the path_mappings.json file. Finally, you can ensure that you have the latest version of Oracle JET installed files by running the ojet strip and ojet restore commands on the application root.

  1. Update the Oracle JET CLI, by using this command.

    npm update -g @oracle/ojet-cli
  2. Migrate your application to use Oracle JET 7.2.0 tooling, by running these commands on your application root.

    npm uninstall @oracle/oraclejet @oracle/oraclejet-tooling
    npm install @oracle/oraclejet@~7.2.0 @oracle/oraclejet-tooling@~7.2.0 --save
  3. Edit the migrating application's src/js/path_mapping.json file to use the current release version number in these CDN paths near the top of the file.

    {
      "baseUrl": "js",
      "use": "local",
    
      "cdns": {
        "jet": {
          "prefix": "http://.../job/CDN_v7.x/lastSuccessfulBuild/artifact/cdn/v7.2.0/default/js",
          "config": "bundles-config.js"
        },
        "3rdparty": "http://.../job/CDN_v7.x/lastSuccessfulBuild/artifact/cdn/v7.2.0/3rdparty"
      },
    ...
  4. On the application root of the migrating application, run the following command to remove non-source files (dependencies, plugins, libraries, and so on) installed from the previous version.

    ojet strip
  5. Also on the application root, run the following command to reinstall all required non-source files that are specific to the current version.

    ojet restore