Migrating a v2.x.0 Application to v3.2.0

To migrate Oracle JET v2.1.0, v2.2.0, or v2.3.0 applications to v3.2.0, you must upgrade global and local npm packages, update theme references if using custom themes, migrate any custom libraries, and optionally remove unused files.

One of the major changes to the tooling framework for v3.x.0 was the removal of Bower and Git as tooling dependencies. In the steps that follow, you can choose to remove Bower if you no longer need it on your system.

  1. At a terminal prompt, enter the following command to clean the npm cache:
    npm cache clean
    
  2. Upgrade the tooling to use the latest v3.2.0 version of generator-oraclejet.

    As Administrator on Windows or using sudo as needed on Macintosh and Linux systems, enter the following command in a terminal window to install v3.2.0:

    [sudo] npm install generator-oraclejet@~3.2.0 -g
    
  3. Enter the following commands to change to the application’s top level directory and upgrade local npm dependencies:
    cd appDir
    npm uninstall grunt-oraclejet oraclejet-tooling
    npm uninstall grunt-bowercopy --save-dev
    npm install grunt-oraclejet@~3.2.0 oraclejet-tooling@~3.2.0 --save-dev
    npm install oraclejet@~3.2.0 --save
    
  4. If your application imports a custom theme using an SCSS import, do the following to migrate your configuration:
    1. Edit the themeName.scss aggregating files in appDir/src/themes/themeName/platform to change the alta import path from bower_components to node_modules.
      @import "../../../../node_modules/oraclejet/dist/scss/alta-android/oj-alta";
      
    2. 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 top level directory, edit index.html and replace the existing css injector reference with the v3.2.0 version.
    <!-- injector:theme -->
    <link rel="stylesheet" href="css/libs/oj/v3.2.0/alta/oj-alta-min.css" id="css" />
    <!-- endinjector -->
    
  6. Update the Oracle JET library configuration paths to reference the v3.2.0 version of Oracle libraries and the updated version of jQuery.
    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/v3.2.0/debug',
          'ojL10n': 'libs/oj/v3.2.0/ojL10n',
          'ojtranslations': 'libs/oj/v3.2.0/resources',
          'text': 'libs/require/text',
          'signals': 'libs/js-signals/signals',
          'customElements': 'libs/webcomponents/CustomElements', //Add if needed
          '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. If your application uses Bower to pull in third-party libraries that are not included in JET, perform the following steps to migrate the custom libraries to npm packages.
    1. In your application’s top level directory, open bower.json and check for any custom dependencies.

      By default, bower.json contains only one dependency.

      "dependencies": 
        {
          "oraclejet": "2.x.0"
        }
      

      If your bower.json has oraclejet as the only dependency, you do not need to perform the following migration steps.

    2. For each additional bower dependency, use the search feature at npmjs to locate the equivalent npm package.
    3. In your application’s top level directory, enter the following command at a terminal prompt to install the npm package.
      npm install mycustomlibrary@x.x.x --save
      

      Tip:

      If you can’t find an equivalent npm package, you have three options:

      • Ask the owner of the third-party package to provide an npm version.

      • Place the library in the application source code. If you use this method, however, you lose the benefit of package management.

      • Keep using bower for any libraries that are not available via npm. In this case, you would leave these specified as dependencies in your bower.json file. However, you must also update scripts/grunt/oraclejet-build.js as described in the next step.

    4. If you originally added the bower dependencies to scripts/grunt/config/bowercopy.js, add a similar entry to scripts/grunt/config/oraclejet-build.js.

      oraclejet-build.js replaces bowercopy.js in v3.0.0, and you can add your dependency to the copyCustomLibsToStaging configuration section. Remove the comments surrounding the section, and add the file object as described in the code comments.

      /**
       * # copyCustomLibsToStaging
       * This task copies any custom libraries that are not provided by JET to staging directory.
       * This task supports a single option: fileList. The fileList option defines an array of file objects. 
       * Each file object contains the following properties: 
       *   cwd, current working directory
       *   dest, destination path
       *   src, array of source file patterns
       *   rename, function to return the full path of desired destination
       * Example: {cwd: 'app', src: ['**', '!test.js'], dest: 'staging',  rename: function (dest, file) {return renamed path}}
       */
          copyCustomLibsToStaging: {
             fileList: [
               {
                 buildType: 'release', //Only copies when in release mode
                 cwd: 'node_modules/mycustomlibrary',
                 src: ['*.js'], // wild card match all js files
                 dest: 'hybrid/www/js/libs/mycustomlibrary'
               },
               {
                 cwd: 'node_modules/mycustomlibrary',
                 src: ['*.js'], // wild card match all js files
                 dest: 'hybrid/www/js/libs/mycustomlibrary',
                 rename: function (dest, filename) { return dest + filename.replace('js', 'html'); } //rename all files, change file type
               }
             ]
           },
      
  8. Optionally, remove unused files and packages.
    1. If you no longer need Bower, remove it from your system. As Administrator on Windows or using sudo as needed on Macintosh and Linux systems, enter the following command at a terminal prompt:
      [sudo] npm uninstall bower -g
      
    2. Remove the following file from your system: scripts/grunt/config/bowercopy.js.
    3. If you have no third-party dependencies remaining in your bower.json file, remove it.

To test the migration, run grunt build and grunt 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: grunt build help.

If your application uses a custom theme, be sure to include the --theme option to regenerate the CSS:
grunt build [options] --theme=myTheme
To specify multiple custom themes, use:
grunt build [options] --theme=myTheme --themes=myTheme,myTheme1,myTheme2