Migrating from JET v2.0 to v4.1 — A painful road, Part 2

The road to migrating a JET v2.0 application to v4.1 continues, and although it is still challenging, great features are waiting at the finish line. In the first half of this story I will walk you through the pitfalls of updating a JET v2.3 application to v3.0 (read up on part 1 to find out what the difficulties of updating to from v2.0 to v2.3 are). The third main release of JET got rid of Bower as its frontend package manager in favor of npm, so things are bound to get interesting at the very least. I decided to do the upgrade to v4.1 also in this story because — spoilers — it thankfully is rather straightforward!

The road isn’t over yet, but we’ll be fine

v2.3 to v3.0

The procedure is the same as in part 1: You can open up the migration guide for v3.0 in a separate tab and refer to my notes for each step, if any, for additional information. Again, I did the migration for our Travelcost application, so switch all the paths etc. in the screenshots with your own application name.

If you are very sure that you know what you are doing and plan to directly upgrade to v4 after going for v3, I suppose you can skip all the steps that relate to fixing the Grunt builds. The reason is that JET v4 gets rid of Grunt in favor of a custom ojet build script. This could save you a lot of work, but you cannot be 100% sure that the upgrade to v3 was successful as you have no way of testing it without Grunt.

• Before step 1: Thankfully, we do do the upgrade in a newly scaffolded JET application (as with v2.0->v2.3), so you can just create a new branch in your versioning system right from the start.
• Step 1: You can safely skip this if you are on npm v5 and above (which I highly recommend, you can read up on the new npm5 features on their blog).
• Steps 2–6: I absolutely hate the fact that I manually have to update the version numbers in main.js and main-release-paths.json every time a major update comes along. It feels like this should not be necessary because I already updated the oraclejet version in package.json, yet it is also mandatory for upgrading to v4 so I guess I am overlooking something. Apart from some confusion about this on my part, thankfully steps 2–6 are pretty straightforward.
• Before step 7: I tweeted about it back when v3 was released, an essential step is still missing from the guide:

• Still before step 7: Again, I may be overlooking something, but when I did the upgrade I still had to run the Yeoman generator again and create a temporary v3.0 JET application (my intuition would be that this script could instead be shipped via some npm dependency?). So, in order to get access to the new Grunt scripts that are mandatory for building the app, cd out of your application and run yo oraclejet tmp — feel free to abort the library installation as soon as you get the “Oracle JET: Your app structure is generated” message in order to save some time. Then, copy the two scripts from scripts/grunt/config into your existing application.

Missing from the guide: Run the generator to get the missing Grunt scripts.

• Still before step 7: The oraclejetconfig.json also changed a bit from v2.3 to v3.0, so copy that over to your application as well.
• Step 7: If you have any additional Bower dependencies, just try to npm install them and hope for the best — chances are the package is also available on npm. Then add a corresponding entry to the copyCustomLibsToStaging config section of the scripts/grunt/config/oraclejet-build.js file (which we conveniently created before step 7). After that, remove the bower.json and scripts/grunt/config/bowercopy.jsfiles as well as the bower_components/ folder. If you did not succeed in getting rid of all the Bower dependencies or do not want to, leave these files in place.
• Step 8: You can also remove the scripts/grunt/common/versions.js file if you got rid of Bower in step 7.

And that’s it! Again, there was some pain involved in the update process, but one of the sources of that pain (Bower) is now gone, so that is a good thing I suppose. Also good: Upgrading from v3 to v4 is not that complicated, so I will handle it in this story instead of writing a part 3.

v3.0 to v4.1

Again, open up the Oracle docs for the JET migration to v4.1 in a separate tab and read my remarks for additional wisdom ;)

• Step 1: “Same procedure as every year, James”: If you are on npm v5 skip this step as you will get an error message otherwise.
• Step 7: Do not panic if your app does not build when you run ojet build . If you do not have QUnit installed in your node modules (e.g. do not use QUnit for testing, like me) you will get an error message saying that the qunit-reporter-junit is not installed. This is because the npmCopyConfig.js file of the oraclejet-tooling module wants to copy references to said QUnit and its reporter plugin to your libs folder, but cannot do this because it is not listed as a dependency in the module’s package.jsonand thus was not installed. The quick fix is to just install the missing dependencies via npm install qunit qunit-reportr-junit . I filed an issue on the oracjet-tooling GitHub repository, so hopefully this will be fixed in a future version. In the meantime, if you run ojet build and ojet serve again after manually installing the dependencies everything should work just fine.

Don’t panic if you get a message like this.

• Step 8: If you still use Grunt in your project, e.g. for linting or testing, you should cleanup its Gruntfile.js in order to kill off the warnings that you get due to the now-missing grunt-oraclejet module. Just delete everything that references grunt-oraclejet or oraclejet-* and you should be fine. You can also delete the JET related Grunt config files in scripts/grunt/config .

Cleanup your Gruntfile if you still use it.

After these steps, you are good to go! Apart from the issue with the implicit QUnit dependency, the tooling feels much more stable now, and the new data-binding syntax is great. Our app also feels more snappier on v4.1, but that obviously depends on the application.

We have finally arrived at JET v4.1!

I hope these posts helped you avoid some of the pitfalls when upgrading your Oracle JET application. If you still experience some issues, just shout for help on Twitter and mention me (Janis Krasemann) and/or the official Oracle JET account, or join our JET community on Gitter! Also, visit enpit.de for more JavaScript and IT modernization expertise.