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

Quite a lot happened over the past year in Oracle’s JavaScript Extension Toolkit. We are now at Version 4.1 which, compared to v2.0, got rid of Bower (yay!) and introduced a more concise syntax for data bindings. There are a lot more reasons for upgrading, especially if you are still at v2.x, but the downside is: It is rather painful, and error-prone. Which is why I documented the numerous pitfalls that you may encounter until you arrive at the promised land, i.e. the newest JET version. I sure hope upgrading gets easier after that.

Upgrading JET from v2.0 to v4.1 is not as painless as you would think…

I wanted to wrap this all up in one post, but turns out it is more complicated than I thought. This post thus only explains the pitfalls when upgrading from v2.0 to v2.3, and one or two separate posts will treat upgrading to v3 and v4, respectively.

v2.0 to v2.3

For some reason, you can only upgrade to v3 if you are at v2.3, so the first step is to upgrade the <v2.3 application to v2.3. Thankfully, there is a migration guide available. Just follow the steps from that guide, and refer to my following notes for each step (if any) for more information. I did the migration for our internal Travelcost application, so if you encounter this name, substitute it for your own apps name.

• Step 1: When running npm cache clean you get an error as pictured below if you are on npm v5. Just ignore it and move on, npm got smarter since the migration guide was written.

Ignore this message if you encounter it.

• Step 3: To keep everything nice and clean, move your v2.0 application to a *_v2–0 folder before you run the generator. Then generate the v2.3 application under your application name, as we will be moving our existing source files into the newly generated v2.3 application (weird, but whatever…).

Name your app folder correctly if you don’t want to get confused…

• After step 3: If you take your application seriously, you have it under version control. This is a good point in the upgrade process to do so for the new v2.3 application. Just git add . everything and commit it and don’t worry about files that you may not need in your final v2.3 app — you can tidy up everything later. Commit your work at least after the migration is completed, possibly even more often.

Safety first.

• After step 8: The migration guide assumes you do not have any custom Grunt scripts. In our case we have scripts for running ESLint and Karma tests — obviously, copy them over to the v2.3 application as well. Same goes for additional config files, like a .eslintrcor karma.conf.js. If you have custom Grunt scripts, you probably also have edited your Gruntfile, so copy the relevant lines over to your new Gruntfile as well.
• I had some troubles with the oraclejet bower package not being installed in the correct version. This is probably an issue with the npm cache and may or may not occur anymore in npm v5. To make sure you have the correct version, run cat bower_components/oraclejet/bower.json and verify that the version is 2.3.0 .
• The guide also forgets to mention that you should edit the bowercopy.js file if you have any additional Bower dependencies, like fontawesome for example. Manually copy the relevant stuff from your old bowercopy.js — hopefully only a few lines at the end of the file.

That’s it! Check if all works by running npm install bower install grunt build and then grunt serve ! Also make sure all your tests are still passing — if you have any, which I sure hope you do ;)

As the last step, you want to merge your changes into the main codebase. If you just wanted to upgrade to v2.3, you can just merge into master. If you plan to continue down the road to v4.1, just merge your master branch into the update-branch (in my case ‘upgrade_v2.3') to make sure everything is in the right place and then continue the migration. Git may refuse to merge unrelated histories, but a wise man on Stackoverflow says you can use the --allow-unrelated-histories flag when doing the merge to force the merge (which indeed works as expected, at least for me).

Let’s hope moving from v2.3 to v3 will be easier, but as v3 gets rid of Bower, it is bound to get interesting again! I plan to publish that post later this week.

Visit us at enpit.de for more JavaScript expertise!