Categories
Jupyter lab

Jupyter Lab 2 to 3 extensions migration notes

Notes on migrating custom extensions to Jupyter Lab 3

The new version of Jupyter Lab 3 being released recently has brought a lot of new nice features such as a cleaner UI and a debugger by default. For us developers this upgrade changes the way we build our extensions. No more nodejs environement, all going through PIP/Conda, etc. I’ve migrated a few extensions in the last couple of weeks and while the official documentation helped a lot, I had a few issues to fix. Here are my notes about the process.

You can find he official documentation here (start with this first): https://jupyterlab.readthedocs.io/en/latest/extension/extension_migration.html#jupyterlab-2-x-to-3-x

Bonus: If you get stuck in your code, you can always take a look at this repository to see how similar problems have been solved: https://github.com/jupyterlab/extension-examples/

Server extension (python)

With the new server, writing back-end extensions is different in Jupyter Lab 3, however my extension was pretty much working straight away.

After installing the extension with pip/conda don’t forget to link it to jupyter server: jupyter serverextension enable --py <extension name>

I’ve had an issue running it, it wasn’t finding the config file. This is because it is now called jupyter_lab_config.py, so you need to create it running jupyter notebook --generate-config and then copy your custom config from the old jupyter_notebook_config.py file.

Labextension (Client side Javascript)

Labextensions are harder to migrate than server ones. Thankfully, the Jupyter Lab team created a script to ease the process:

  1. In your extension folder, install the python packages needed (jupyterlab=3 might not be necessary, this is because I was migrating before v3 was out):
    conda install -c conda-forge jupyterlab=3 jupyter-packaging cookiecutter
  2. Make sure your work is committed then run the script: python -m jupyterlab.upgrade_extension .
  3. After running the migration script, check that nothing important has been overridden (using git status and git diff). Especially your package.json and tsconfig.json files if you’ve modified them.
  4. Check the new Readme.md file to see if you have any extra steps to run.
  5. Now you can run jlpm to install all packages, followed by pip install -e . to install the extension. If this doesn’t work, look below for the errors I’ve came across and how I’ve fixed them.
  6. Finally run jupyter labextension develop . --overwrite to be able to develop and update the server without having to restart it all the time.

Migration errors and fixes

  • I had to manually update a @jupyterLab package that hasn’t been migrated to v3 in my package.json file by the script (@jupyterlab/testutils). Same for React and associated @types that must be version >17 (try with jlpm upgrade @types/react for example)
  • If you’re using React you can come across this error:

error TS5056: Cannot write file ‘/home/remborg/extension-to-v3/lib/index.d.ts’ because it would be overwritten by multiple input files.

To fix it you’ll have to make sure you have only one index file (because of the script you could en up having an index.tsx and an index.ts file in your project). You might have to delete tsconfig.tsbuildinfo before you build the project again.

Hopefully this will help you with your migration 🙂
Please leave a comment if you had any other issue and how you’ve fixed it.

Leave a Reply

Your email address will not be published. Required fields are marked *

*

code