Advanced extension configuration

Warning

This is a more advanced section on extension configuration. We recommend following the simple extensions guide first.

Ignore extensions from the environment

By default JupyterLite uses a discovery mechanism to include extensions installed in a local environment.

This discovery behavior can be disabled with the CLI flag --ignore-sys-prefix or LiteBuildConfig/ignore_sys_prefix.

The --ignore-sys-prefix CLI flag will disable using components from the JupyterLab environment for all addons. This behavior can be configured in a more granular way on a per-addon basis, for example:

{
  "LiteBuildConfig": {
    "ignore_sys_prefix": ["federated_extensions"]
  }
}

This is for example useful if you don’t want “side-effects” in case you are building a site from an environment with already installed extensions.

Disabling Extensions at Runtime

All third-party extensions, and some provided by JupyterLite and JupyterLab, can be disabled for one or all apps deployed in a site with the disabledExtensions option.

For example, a site that doesn’t need the content to be available from the Python kernel can disable the ServiceWorker plugin with the following jupyter-lite.json:

{
  "jupyter-lite-schema-version": 0,
  "jupyter-config-data": {
    "disabledExtensions": ["@jupyterlite/application-extension:service-worker-manager"]
  }
}

An entry is either a plugin id, such as my-extension:plugin, or an extension package name, such as my-extension. A package name disables every plugin the package provides, including a plugin whose id does not start with the package name; such a plugin is named in a browser console warning. To keep it enabled, list the plugin ids to disable instead of the package name.

The code and the styles of a federated extension disabled by its package name are not loaded when the app starts. Its code is loaded once the app is idle, only to list its plugins in the Plugin Manager.

As in JupyterLab, a federated extension can also disable other plugins, for example the ones it replaces, with the jupyterlab.disabledExtensions field of its package.json:

{
  "name": "my-extension",
  "jupyterlab": {
    "disabledExtensions": ["@jupyterlab/application-extension:logo"]
  }
}

These entries are added to the disabledExtensions of the site, unless the site disables the extension itself by its package name.

Users can also disable extensions and plugins from the browser, on top of this list: see Managing the extensions shipped with the website.

Specifying extra paths to look for extensions

The jupyter-lite CLI supports providing extra paths to look for extensions.

You can specify the --FederatedExtensionAddon.extra_labextensions_path CLI option when building the site:

jupyter lite build --FederatedExtensionAddon.extra_labextensions_path=/path/to/extra/labextensions

Or in a jupyter_lite_config.json:

{
  "FederatedExtensionAddon": {
    "extra_labextensions_path": ["/path/to/extra/labextensions"]
  }
}

Extensions for a Specific App

Similar to the above, by updating $YOUR_JUPYTERLITE/{app}/jupyter-lite.json, the pre-built extensions will only be available for pages within that file tree.

Adding Custom Extensions

By placing extensions under {lite-dir}/extensions/{org/?}{package}/, these will also be copied into the output-dir after any environment extensions, and all will be added to {output-dir}/jupyter-lite.json#jupyter-config-data/federated_extensions.

Hint

For example, after building a lab extension, you can copy the contents of package.json#/jupyterlab/outputDir right into the lite-dir to preview your extension.

Finally, the --federated-extensions CLI flag and the LiteBuildConfig/federated_extensions config entry allow for adding additional federated extensions, as packaged on:

• PyPI:

  • .whl

• conda-forge:

  • .tar.bz2

  • .conda (see warning below)

Using libarchive

If detected, libarchive-c will be used for better performance, especially when working with archives with many/large assets, especially pyodide.

If libarchive-c is not detected, Python’s built-in zipfile and tarfile modules will be used.

Warning

Extracting federated extensions from .conda packages requires libarchive-c.