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:

jupyterlite-server-extension

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: