APEX Nitro – What is it about?

APEX Nitro is a handy tool for automatically synchronizing JavaScript (JS) and CSS file changes to the browser. It’s based on Node.js and as open source project it can be found on github. Moving your JS code and CSS to external files instead of writing it inline in your APEX page is always a good idea. APEX Nitro supports this best practice more than comfortable:

On-the-fly coding in your favourite editor

Automatic refresh of the browser window

Detailed error handling for JS and CSS

Support for Typescript, SASS and LESS

What’s the benefit for me as developer?

First lets’ have a look at the usual workflow for coding JS in APEX. Most of the time you start by coding your JS or CSS inline at a certain page. Then you would save, refresh the browser and check the outcome. If you are satisfied, you would move your code to external files, upload them to the shared components and see the result. Necessary new changes would force you to repeat this arduous process again and again. At the same time there would not be any error handling. Comma or semicolon missing? Walk through your code – row by row, slow by slow. The whole dynamic behavior of your APEX page does not work anymore? Check the console for any thrown errors. But be aware, that only the first error will be thrown here.

If you are tired of this workflow, APEX Nitro is the perfect tool for you. Installed and configured once, it is possible to work on local files in your preferred editor and see changes on-the-fly. Errors in your code will be caught and in the console, you can see the error description together with the causing code line. The browser will only be refreshed, if everything is fixed.

APEX Nitro uses an own instance of APEX, thereby not touching your original APEX static files. As soon as you are done with your development, you can easily publish your local files to APEX. If you like, your files will even be concatenated and minified before they get uploaded to APEX using SQLcl. Sounds great? Here is how it works.

Installation and configuration

Make sure that Node.js and optional SQLcl is installed on your machine. If so, you can easily install APEX Nitro using your console:

npm install -g apex-nitro

After a successful installation, you can start the configuration of your project using the following command:

apex-nitro config <project_name>

The configuration page for your project will automatically open in your browser (Figure 1). In general the project can be configured in basic and advance mode. During our testing we experienced, that some functionality will not work properly in basic mode. Therefore, we recommend using the advanced mode. You will need to provide the application URL and the path to both the source and distributable folder. Additionally, you should set the path for SQLcl, so that publishing your files will work, too.

Figure 1 Configuration of your APEX Nitro project

As soon as you have saved your configuration, you will need to create an application process in APEX. This is necessary for the real-time synchronization. Details can be found in the documentation here.

Figure 2 Windows notification for APEX Nitro

You will find the link to the APEX Nitro instance in your console. If everything worked without any problems until this point, you are ready for developing your JS and CSS. Edit your files from the source folder, save them and watch your browser for the changes you made. In addition, you should have an eye on the console. You will be notified every time the browser is refreshed (Figure 3) and if parsing your code results in any error (Figure 4).

Figure 3 Launching your APEX Nitro project

Figure 4 APEX Nitro error handling

Publishing files

To finally publish your local files, type

apex-nitro publish <project_name>

Depending on your configuration all your JS files will be concatenated into one file and stored in your distribution folder. The minified version of this file will also be saved here. As a last step, these files will be uploaded to your APEX static files.

Summary

Reading this article, you might think, that it’s a lot of effort to get APEX Nitro up and running. But in fact, it only took us about an hour to install, configure and test all the functionalities of APEX Nitro. And compared to the arduous manual process for every single change in JS or CSS we had before, it is worth spending some time to discover APEX Nitro. With this great tool, we only need to launch our project and publish our files at the end of our task – two commands and done!

The author is Vicent Morneau. Thank you for publishing and maintaining the project.