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!
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-release-paths.jsonevery time a major update comes along. It feels like this should not be necessary because I already updated the
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,
cdout 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/configinto your existing application.
- Still before step 7: The
oraclejetconfig.jsonalso 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 installthem and hope for the best — chances are the package is also available on npm. Then add a corresponding entry to the
copyCustomLibsToStagingconfig section of the
scripts/grunt/config/oraclejet-build.jsfile (which we conveniently created before step 7). After that, remove the
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.jsfile 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-junitis not installed. This is because the
npmCopyConfig.jsfile of the
oraclejet-toolingmodule 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 serveagain after manually installing the dependencies everything should work just fine.
- Step 8: If you still use Grunt in your project, e.g. for linting or testing, you should cleanup its
Gruntfile.jsin order to kill off the warnings that you get due to the now-missing
grunt-oraclejetmodule. Just delete everything that references
oraclejet-*and you should be fine. You can also delete the JET related Grunt config files in
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.