Create a server extension#
JupyterLite uses the same plugin architecture for server components as in JupyterLab.
Server components allow for kernel and session management, handling user settings, themes and display languages.
For more information on how this fits within the whole application, check out the Architecture Diagram.
Creating a new server extension#
The extension development system is the same as the one used to build JupyterLab Extensions.
If you are new to developing extensions for JupyterLab, you might want to check the documentation and the extension tutorial first to get familiar with the toolchain.
Bootstrapping the extension#
First create a new development environment with:
# create the environment
mamba create -n myliteextension -c conda-forge python nodejs jupyterlab cookiecutter jupyterlite-core -y
# activate the environment
conda activate myliteextension
Note
It is recommended to use a Long Term Support (LTS) release of NodeJS: the simple rule of thumb is stick to even numbered releases.
Then let’s generate a new extension from the cookiecutter:
cookiecutter https://github.com/jupyterlite/serverlite-cookiecutter-ts
When prompted, enter values for your extension. This will create the structure to develop the JupyterLite extension.
Build#
To build the extension:
# install package in development mode
python -m pip install -e .
# link your development version of the extension
jupyter labextension develop . --overwrite
# rebuild the source after making changes
jlpm run build
To check the extension is correctly built and installed, make sure it is listed with the following command:
$ jupyter labextension list
JupyterLab v3.*.*
/home/user/miniforge3/envs/tmp/share/jupyter/labextensions
myliteextension v0.1.0 enabled OK
Test#
Finally, to see the extension in action in JupyterLite:
# build a new JupyterLite website
# this will pick up the extension linked locally
jupyter lite build --force
# serve the website
jupyter lite serve
Then open http://localhost:8000
in a web browser. You should be able to see the
following message printed to the developer tools console:
Publishing the extension#
The simplest way to publish the extension is to use the Jupyter Releaser.
The generated repository should already be compatible with the releaser. You can then
follow the Jupyter Releaser Documentation to learn how to add the PyPI
and npm
tokens as GitHub Secrets.
Once published, you can check the extension can be installed locally in a new environment:
python -m pip install myliteextension
Using the extension in a JupyterLite deployment#
In most cases, this would mean adding the extension to a requirements.txt
file:
jupyterlite-core
myliteextension
For more information on adding extensions to a JupyterLite website, check out the configuration guide.
If a lot of customization is required, it may also be worth extending the JupyterLite CLI in your package.
However the build environment is built, once it works well, it is highly recommended
to generate and check in a full list of locked package versions. Some package managers,
such as poetry
and pipenv
, support this out of the box.
Hint
Some lightweight tools for locking requirements in formats for common package manager tools are also available:
References#
For more information, check out the following repositories: