

Develop or edit a module

Customization might not be enough for you if you are implementing a feature or fixing a bug. The point is that you need to install a module from a local path and see the changes reflected on your instance.

If it is a backend change, simply installing the module from the local path should be enough. In some corner cases, you might have to re-start the instance (for that run stop and run again). For frontend (e.g. templates, css, etc.) you need to symlink and re-build the assets. This can be a complex process when using webpack, but Invenio-CLI has you covered.

Templates and CSS

First, you have to install the module you want to edit:

invenio-cli packages install /path/to/module

and then re-start the instance.

The command takes care of cleaning the assets for you. This is convenient for two reasons, first the module might have already been installed from upstream and therefore some links already exist, or these files already exist (as hard copies) if the installation was not done using the --development flag. As you can see, many things can go wrong, so the added time is worth it.

In addition, if you want to modify CSS and see it when reloading the page you need to watch the assets. This will automatically rebuild the webpack bundles when you change the CSS (.less) files. In order to watch them, open another terminal (still in your instance path i.e. development-instance/) and activate the same virtual environment. Then run:

invenio-cli assets watch

No hot reloading

There is no hot reloading available. This means that even if the assets are watched and rebuilt, you need to refresh your browser to see the changes. In addition, be aware of the cache, it might be a good idea to disable your cache or use an incognito window when developing web UI.

This is a continually running operation, so do not close the terminal. You will be able to see the rebuilding progress there -usually a percentage on the last line- and the errors in case there were any.

You might see an UnfinishedManifest error

Rebuilding the webpack bundles is not a speed-of-light operation. It might take a few seconds. If you see an UnfinishedManifest error in your browser when you refresh, check the terminal to see whether the assets are simply still building or if an actual build error (e.g. syntax error) occurred.

React modules

In a similar fashion as in the previous section, to develop on a react module you have to install and watch it. Invenio-CLI has commands for that too. To install a module run:

invenio-cli assets install /path/to/react-module

Then you have to watch it. Open another terminal in your instance path (development-instance/ as before) and activate the same virtual environment. Note that if you are already watching some python module, this action is independent (and per module):

invenio-cli assets watch-module --link /path/to/react-module

You may have to restart invenio-cli assets watch.