configuring.md

Configuring

Runtime Configuration Files

The behavior JupyterLite in the browser can be controlled by creating specially-named files at any level of the file tree. It is expected each file conforms to the schema. For an example, see the demo configuration.

File	Config Location	jupyter-config-data	Note
jupyter-lite.ipynb	#/metadata/jupyter-lite	✔️	integrates into existing Jupyter workflows
jupyter-lite.json	whole file	✔️	good for simple/automated configuration
index.html	script#jupyter-config-data	✔️	configuration of last resort, not recommended

Each can be omitted from the file tree, and will result in a harmless (though noisy) 404 response.

Configuration cascades _down_, such that the closest, most-user-editable file
to the `index.html` being served takes highest precedence. Like-named keys will
be _replaced_  by higher-priority files, with the notable exceptions of:

- the `federated_extensions` and `disabledExtensions` lists are appended and
  deduplicated
- the `settingsOverrides` dictionary will be merged at the top level of each plugin

Schema

The current schema version is `0`, and as such is _subject to change_. Once it has
stabilized, we hope to provide similar backwards-compatibility guarantees as the
[Jupyter Notebook Format][nbformat].

As the schema provides many options, please see the dedicated pages below.

schema-v0

Adding Content

Content with the CLI

With the CLI installed, run

jupyter lite build

...any contents of {lite-dir}/files/ (and any added --contents) will be:

• copied to the built site under {output-dir}/files/
  • may have timestamps changed if --source-date-epoch is provided.
• indexed to provide {output-dir}/api/contents/{subdir?}/all.json

Adding Extensions

JupyterLab 3 federated extensions allow for adding new capabilities to JupyterLite without rebuilding the entire web application. A good starting point for extensions that might work is the JupyterLab issue Extension Compatibility with 3.0 (#9461). Additionally, this site demonstrates a few extensions.

Extensions with the CLI

Environment Extensions

When you jupyter lite build, all federated extensions in your JupyterLab environment, e.g. {sys.prefix}/share/jupyter/labextensions will be:

• copied to {output-dir}/lab/extensions
• have its theme information copied to {output-dir}/{app/?}theme/

Extensions for a Specific App

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

Custom Extensions

By placing extensions under {lite-dir}/lab/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.

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

Customizing Settings

With the CLI, if you create an overrides.json in either the root, or a specific app directory, these will be:

• merged into {output-dir}/{app?}/jupyter-lite.json#/jupyter-config-data/settingsOverrides

About the Demo

This documentation site contains the JupyterLite Demo (the Try buttons on the top of the screen) and uses a number of techniques described on this page.

Demo Configuration

The following generated configuration powers the Demo, and is generated prior to building the docs site, copied in during the build, and fetched by browsers from /_static/jupyter-lite.json.

Demo Extension Notes

The federated_extensions above are copied from the documentation environment prior to building this site with Sphinx, and are meant to exercise different kinds of extensions, including themes, MIME renderers, and Widgets. Some transient dependencies also include labextensions, but don't work entirely correctly.

extension	notes	working issue
@jupyter-widgets/jupyterlab-manager	needs Jupyter Kernel Comms	#18
@jupyterlab/server-proxy	needs server extension
nbdime	needs server extension

The Hard Way

Content, The Hard Way

Assuming:

• you have a running JupyterLab 3
• you want to add all of the files in the root folder of the current JupyterLab to your JupyterLite.

Open a browser:

• view the Contents API, e.g. http://localhost:8888/api/contents, which should look something like:

{
  "name": "",
  "path": "",
  "last_modified": "2021-05-15T20:16:17.753908Z",
  "created": "2021-05-15T20:16:17.753908Z",
  "format": "json",
  "mimetype": null,
  "size": null,
  "writable": true,
  "type": "directory",
  "content": [
    {
      "name": "README.md",
      "path": "README.md",
      "last_modified": "2021-05-15T20:12:22.261076Z",
      "created": "2021-05-15T20:12:22.261076Z",
      "content": null,
      "format": null,
      "mimetype": "text/markdown",
      "size": 3735,
      "writable": true,
      "type": "file"
    }
  ]
}

• Paste this JSON in $YOUR_JUPYTERLITE/api/contents/all.json
• Copy your files in $YOUR_JUPYTERLITE/files
• Repeat this for every subfolder :(

Now, when the app reloads, these files will appear in the File Browser if there isn't an existing file of that name in browser storage. If a user has created such a file, and is deleted, the original server-backed file will become visible.

Extensions, The Hard Way

This is a heavily work-in-progress procedure, and will hopefully soon be improved
with convenience tools in (at least) python and JavaScript.

Get the extension assets

Assuming you have a working JupyterLab 3 installation, look in your {sys.prefix}/share/jupyter/labextensions. Each folder contains either:

• if it begins with @, a collection of packages
• otherwise, a single federated extension

cd $YOUR_JUPYTERLITE
mkdir -p lab/extensions
cd lab/extensions
cp -r $PREFIX/share/jupyter/labextensions/@jupyter-widgets/jupyterlab-manager .

Some extensions will require _other_ extensions to be available. This can be
determined by looking in `package.json` for the extension, specifically
`#/jupyterlab/sharedPackages`.

Handle theme assets

The Theme Manager expects to be able to load theme CSS/font assets from {:app}/build/themes/({:org}/){:package}, where app is usually lab.

Continuing the example above:

cd $YOUR_JUPYTERLITE/lab/extensions
mkdir -p ../build/themes
cp -r @*/*/themes/* ../build/themes/
cp -r @*/themes/* ../build/themes/
# To also ensure these are available for JupyterLite Retro:
mkdir -p ../../retro/build/themes
cp -r @*/*/themes/* ../../retro/build/themes/
cp -r @*/themes/* ../../retro/build/themes/

Fill Out federated_extensions

Again, assuming you have a working JupyterLab, click Inspect Element in your Lab and inspect the <script id="jupyter-config-data"> in the <head>. The entry you need will be contained there.

Update your /app/jupyter-lite.json like so:

{
  "federated_extensions": [
    {
      "extension": "./extension",
      "load": "static/remoteEntry.ca1efc27dc965162ca86.js",
      "name": "@jupyter-widgets/jupyterlab-manager"
    }
  ]
}

Some extensions also include a `style` key, and may look _off_ if omitted.