Oracle JET v5.2.0 Tooling Migration

B Oracle JET v5.2.0 Tooling Migration

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

Migrating a v4.x.0 Application to v5.2.0

To migrate your Oracle JET application from v4.x.0 to v5.2.0, you must upgrade npm packages, update theme and library reference paths, and replace main-release-paths.json with path_mapping.json.

Beginning with 5.0.0, you no longer need to edit multiple files when adding new libraries. The src/js/path_mapping.json replaces src/js/main-release-paths.json, and you no longer need to update paths manually in src/js/main.js or scripts/config/oraclejet-build.js.

At a terminal prompt, enter the following command to clean the npm cache:
```
npm cache clean
```
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@~5.2.0
```

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@~5.2.0 @oracle/oraclejet-tooling@5.2.0 --save

Review the Theming section in the release notes for SCSS variable or other changes, and update your theming files manually, if needed.
In the application’s src directory, edit index.html and replace the existing css reference with the v5.2.0 version.
```
<link rel="stylesheet" href="css/libs/oj/v5.2.0/alta/oj-alta-min.css" id="css" />
```
Update the Oracle JET library configuration paths to reference the v5.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. 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, 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": ""
      }
    },
...
```
  Tip:
  You can get the information you need for path_mapping.json from your migrating application’s src/js/main-release-paths.json, scripts/config/oraclejet-build.js, and src/js/main.js files.
Copy the tempApp/scripts/hooks directory to your migrating application’s scripts/hooks directory.
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
```
Optional: When you are satisfied that your application has migrated successfully, remove the temporary application and your migrating application’s src/js/main-release-paths.json file.

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

When upgrading to a minor release version of Oracle JET, such as from 5.0.0 to 5.2.0, where features changes do not introduce backward incompatibility from the previous release, you can update the Oracle JET command-line interface (CLI) and leave npm unchanged.

To update the Oracle JET CLI, use this command.

npm update -g @oracle/ojet-cli

To migrate your application to use Oracle JET 5.2.0 tooling, run these commands on your application root:

npm uninstall @oracle/oraclejet @oracle/oraclejet-tooling
npm install @oracle/oraclejet@~5.2.0 @oracle/oraclejet-tooling~@5.2.0 --save