B Oracle JET App Migration for Release 17.0.0
If you used Oracle JET tooling to scaffold your app with Oracle JET version
5.x.0
or later, you can migrate your app manually to version
17.0.0
.
Before you migrate your app, be sure to check the Oracle JET Release Notes for any component, framework, or other change that could impact your app.
Important:
This process is not supported for Oracle JET releases prior to version5.0.0
.
Note:
The Alta theme was deprecated in release 10.0.0 and will be supported through the 12.x releases. In release 13.0.0 and later, Oracle JET will provide "best effort" support for Alta. No bug fixes or new features will be provided for Alta-only issues. For more information about Oracle JET's release schedule, see What is the release schedule for Oracle JET?
The content that described how to use the Alta theme in an Oracle JET app has been removed from the documentation and it has been removed from the Oracle JET Cookbook. If you want to refer to the documentation, consult release 11.1.0 of the documentation that last published Alta Theme in Oracle JET v9.0.0 and Later.
Migrate Redwood-themed Apps from Releases 9.x.0 or Later to Release 17.0.0
To migrate your Oracle JET app source from version
9.x.0
or later to the latest version 17.0.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.
Before You Begin:
-
Oracle strongly recommends that you audit your app with Oracle JET Audit Framework (JAF) before any migration. The built-in audit rules provided with JAF will help you to identify and fix invalid functionality, including deprecated components and APIs. Implement the audit results with some attention to detail to ensure a successful migration to JET release 17.0.0.
As Administrator on Windows or using
sudo
as needed on Macintosh and Linux systems, enter the following command in a terminal window:npm install -g @oracle/oraclejet-audit
On your app root, run the following JAF command to initialize the audit of your app.
ojaf --init
In the generated
AppRootDir/oraclejafconfig.json
file, set the value of thejetVer
property to the release to which you are migrating your app. For example,"jetVer": "17.0.0"
.Run the following command to audit your app and review any issues that the audit identifies.
ojaf
For more details about JAF, see Initialize Oracle JAF and Run an Audit in Using and Extending the Oracle JET Audit Framework.
-
A maintenance or active long-term support (LTS) version of Node.js is required. Open a Command Prompt window as an administrator and check your Node.js version.
node -v
If your Node.js version is earlier than the versions listed as maintenance or active LTS on the Releases page of the Nodejs.org website, download a newer LTS version. Go to the Nodejs.org website. Under LTS Version (Recommended for Most Users), download the installer for your system. In the Download dialog box, choose a location for the file and click Save. Run the downloaded installer as an administrator and follow the steps in the installation wizard to install Node.js.
One additional caveat is that if you install version 16 or higher of Node.js, change the value of
sassVer
in yourappRootDir/oraclejetconfig.json
file to a version of node-sass that is compatible with the Node.js version that you have installed. Oracle JET installs the version of node-sass specified bysassVer
when you run theojet add theming
command to use custom themes in your Oracle JET app. For example, if you installedv16.17.1
of Node.js, set"sassVer": "7.0.0"
in yourappRootDir/oraclejetconfig.json
file. -
Starting in JET release 9.0.0, apps configured for TypeScript development require a local installation of the TypeScript library to perform compilation. To ensure that your app, if configured for TypeScript development, has a local installation, run the following command from the root of your app.
ojet add typescript
The JET Tooling installs the latest supported version of the TypeScript language: 5.4.5.
To migrate your app:
Migrate to the Redwood Theme CSS
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.
If you have an existing app that you want to migrate from the Alta theme, you can
migrate to JET release 17.0.0
and configure the
app to run with the Redwood CSS included with Oracle JET. You obtained the Redwood CSS
distribution when you completed the app source migration process.
Migrating your app's Alta theme to Redwood theme requires making a change at the app
level. You edit the oraclejetconfig.json
file to control whether JET
Tooling builds with the Redwood or Alta CSS. With the setting configured, you can rebuild
your app and all the pages will use the appropriate CSS, as specified by the stylesheet
injector in your app's index.html
file.
After you set the Redwood theme as the new default and run your app, you will find the look and feel of your app changes considerably. To adjust to the Redwood theme, you will need to make manual updates to app layout for new fonts, sizes, and patterns.
CSS variables, which are supported by the Redwood theme, were introduced in
the oj-redwood-cssvars*.css
files as a preview feature in JET release
9.0.0
. In JET release 10.0.0
, CSS variables became a
production feature and are now included in the oj-redwood*.css
files.
Replace references to the oj-redwood-cssvars*.css
files with references to
the oj-redwood*.css
files in your migrated apps. Be aware of this change if
you migrated your app to use the Redwood theme and started to use CSS variables in JET
releases prior to release 10.0.0
.
Before You Begin:
-
Complete migration of your app source files before attempting to migrate to the Redwood theme. First migrate with the Alta theme preserved and then migrate to the Redwood theme. This way you can test your app with the Redwood theme and easily revert back to the Alta theme, if desired. See Migrate Alta-themed Apps from Releases Prior to 8.3.0 to Release 17.0.0 for details.
-
If you use a custom theme, review the Theme Changes section in the release notes and update your custom theme manually.
Be aware that Sass variables that you may have overridden in an Alta theme will need to be migrated to CSS variables in the Redwood theme. For more information about migrating a custom theme, please see About CSS Variables and Custom Themes in Oracle JET.
-
Review app images and consider how you will replace images that belong to the deprecated Oracle JET framework images library with public domain images, such as those found on Oracle Apex Universal Theme and on Font Awesome. The Oracle JET framework image classes are no longer shown in JET Cookbook, starting in release 9.0.0.
To migrate to the Redwood theme CSS:
Migrate Alta-themed Apps from Releases Prior to 8.3.0 to Release 17.0.0
To migrate your Oracle JET app source from version
5.x.0
through version 8.3.0
to the latest version 17.0.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.0.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.
Before You Begin:
-
Due to potential incompatibilities with releases prior to JET version
9.0.0
, Oracle strongly recommends that you audit your app with Oracle JET Audit Framework (JAF). The built-in audit rules provided with JAF will help you to identify and fix invalid functionality, including deprecated components and APIs. Implement the audit results with some attention to detail to ensure a successful migration to JET release 17.0.0.As Administrator on Windows or using
sudo
as needed on Macintosh and Linux systems, enter the following command in a terminal window:npm install -g @oracle/oraclejet-audit
On your app root, run the following JAF command to initialize the audit of your app.
ojaf --init
In the generated
AppRootDir/oraclejafconfig.json
file, set the value of thejetVer
property to the release to which you are migrating your app. For example,"jetVer": "17.0.0"
.Run the following command to audit your app and review any issues that the audit identifies.
ojaf
For more details about JAF, see Initialize Oracle JAF and Run an Audit in Using and Extending the Oracle JET Audit Framework.
-
A maintenance or active long-term support (LTS) version of Node.js is required. Open a Command Prompt window as an administrator and check your Node.js version.
node -v
If your Node.js version is earlier than the versions listed as maintenance or active LTS on the Releases page of the Nodejs.org website, download a newer LTS version. Go to the Nodejs.org website. Under LTS Version (Recommended for Most Users), download the installer for your system. In the Download dialog box, choose a location for the file and click Save. Run the downloaded installer as an administrator and follow the steps in the installation wizard to install Node.js.
One additional caveat is that if you install version 16 or higher of Node.js, change the value of
sassVer
in yourappRootDir/oraclejetconfig.json
file to a version of node-sass that is compatible with the Node.js version that you have installed. Oracle JET installs the version of node-sass specified bysassVer
when you run theojet add theming
command to use custom themes in your Oracle JET app. For example, if you installedv16.17.1
of Node.js, set"sassVer": "7.0.0"
in yourappRootDir/oraclejetconfig.json
file. -
Starting in JET release 9.0.0, apps configured for TypeScript development require a local installation of the TypeScript library to perform compilation. To ensure that your app, if configured for TypeScript development, has a local installation, run the following command from the root of your app.
ojet add typescript
The JET Tooling installs the latest supported version of the TypeScript language: 5.4.5.
To migrate your app:
After you migrate your app and ensure it runs with the Alta theme, you can follow an additional, separate process to migrate to the Redwood theme, as described in Migrate to the Redwood Theme CSS.