B Oracle JET v4.1.0 Tooling Migration

If you used Oracle JET tooling to scaffold your application with Oracle JET v3.0.0 or higher, you can migrate your application manually to v4.1.0.

The steps to migrate depend upon whether you are migrating your application from v3.0.0 or v4.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 v3.0.0.

Migrating a v3.x.0 Application to v4.1.0

To migrate your Oracle JET application to v4.1.0, you must upgrade npm packages and update theme and library reference paths.

One of the major changes to tooling for v4.x.0 is the replacement of the Oracle JET generator (generator-oraclejet) with the Oracle JET command-line interface (ojet-cli). In the steps that follow, you will remove the generator and associated packages and replace them with the v4.1.0 versions of the tooling packages.

The other major change to tooling for v4.x.0 is the removal of grunt and Yeoman as tooling dependencies. In the steps that follow, you can also choose to remove them from your system if you no longer need them.

  1. At a terminal prompt, enter the following command to clean the npm cache:
    npm cache clean
    
  2. Remove generator-oraclejet and install ojet-cli.

    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 generator-oraclejet
    [sudo] npm install -g @oracle/ojet-cli@~4.1.0
    
  3. Enter the following commands to change to the application’s top level directory and upgrade local npm dependencies:
    cd appDir
    npm uninstall oraclejet grunt-oraclejet oraclejet-tooling
    npm install @oracle/oraclejet@~4.1.0 @oracle/oraclejet-tooling@~4.1.0 --save
    
  4. Review the Theming section in the release notes for SCSS variable or other changes, and update your theming files manually, if needed.
  5. In the application’s src directory, edit index.html and replace the existing css reference with the v4.1.0 version.
    <link rel="stylesheet" href="css/libs/oj/v4.1.0/alta/oj-alta-min.css" id="css" />
    
  6. Update the Oracle JET library configuration paths to reference the v4.1.0 version of Oracle libraries.
    1. Open appDir/src/js/main.js and edit requirejs.config() paths to point to the updated libraries highlighted below.

       paths:
        //injector:mainReleasePaths
        {
          'knockout': 'libs/knockout/knockout-3.4.0.debug',
          'jquery': 'libs/jquery/jquery-3.1.1',
          'jqueryui-amd': 'libs/jquery/jqueryui-amd-1.12.0',
          'promise': 'libs/es6-promise/es6-promise',
          'hammerjs': 'libs/hammer/hammer-2.0.8',
          'ojdnd': 'libs/dnd-polyfill/dnd-polyfill-1.0.0',
          'ojs': 'libs/oj/v4.1.0/debug',
          'ojL10n': 'libs/oj/v4.1.0/ojL10n',
          'ojtranslations': 'libs/oj/v4.1.0/resources',
          'text': 'libs/require/text',
          'signals': 'libs/js-signals/signals',
          'customElements': 'libs/webcomponents/custom-elements.min',
          'proj4': 'libs/proj4js/dist/proj4-src',
          'css': 'libs/require-css/css',
        }
        //endinjector
      
    2. Open appDir/src/js/main-release-paths.json and edit the library version numbers to use the same version numbers you referenced in the previous step.

  7. 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
    
  8. If you no longer need grunt and Yeoman on your system, remove them.

    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 yo
    [sudo] npm uninstall -g grunt-cli
    

Migrating a v4.0.0 Application to v4.1.0

To migrate your Oracle JET application from v4.0.0 to v4.1.0, you must upgrade npm packages and update theme and library reference paths.

  1. At a terminal prompt, enter the following command to clean the npm cache:
    npm cache clean
    
  2. 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 @oracle/ojet-cli
    [sudo] npm install -g @oracle/ojet-cli@~4.1.0
    
  3. Enter the following commands to change to the application’s top level directory and upgrade local npm dependencies:
    cd appDir
    npm uninstall @oracle/oraclejet-tooling @oracle/oraclejet
    npm install @oracle/oraclejet-tooling@~4.1.0 @oracle/oraclejet@~4.1.0 --save
    
  4. Review the Theming section in the release notes for SCSS variable or other changes, and update your theming files manually, if needed.
  5. In the application’s src directory, edit index.html and replace the existing css reference with the v4.1.0 version.
    <link rel="stylesheet" href="css/libs/oj/v4.1.0/alta/oj-alta-min.css" id="css" />
    
  6. Update the Oracle JET library configuration paths to reference the v4.1.0 version of Oracle libraries.
    1. Open appDir/src/js/main.js and edit requirejs.config() paths to point to the updated libraries highlighted below.

       paths:
        //injector:mainReleasePaths
        {
          'knockout': 'libs/knockout/knockout-3.4.0.debug',
          'jquery': 'libs/jquery/jquery-3.1.1',
          'jqueryui-amd': 'libs/jquery/jqueryui-amd-1.12.0',
          'promise': 'libs/es6-promise/es6-promise',
          'hammerjs': 'libs/hammer/hammer-2.0.8',
          'ojdnd': 'libs/dnd-polyfill/dnd-polyfill-1.0.0',
          'ojs': 'libs/oj/v4.1.0/debug',
          'ojL10n': 'libs/oj/v4.1.0/ojL10n',
          'ojtranslations': 'libs/oj/v4.1.0/resources',
          'text': 'libs/require/text',
          'signals': 'libs/js-signals/signals',
          'customElements': 'libs/webcomponents/custom-elements.min',
          'proj4': 'libs/proj4js/dist/proj4-src',
          'css': 'libs/require-css/css',
        }
        //endinjector
      
    2. Open appDir/src/js/main-release-paths.json and edit the library version numbers to use the same version numbers you referenced in the previous step.

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