JupyterLite Terminal

A terminal for JupyterLite.

⚠️ This extension is still in development and not yet ready for general use. ⚠️

Requirements

• JupyterLite >= 0.6.0, < 0.8.0

Install

To install the extension, execute:

pip install jupyterlite-terminal

You will also need to install the JupyterLite CLI:

python -m pip install jupyterlite-core

Usage

After installing jupyterlite-core and jupyterlite-terminal, create a jupyter-lite.json file with the following content to activate the terminal extension:

{
  "jupyter-lite-schema-version": 0,
  "jupyter-config-data": {
    "terminalsAvailable": true
  }
}

Then build a new JupyterLite site:

jupyter lite build

Version compatibility

Each jupyterlite-terminal release is built against a specific version of cockle. If you need to include imports from both jupyterlite-terminal and cockle, such as if you are implementing cockle external commands, you should ensure that you are using the correct version combination.

jupyterlite-terminal	cockle	jupyterlite-core
1.0.1	1.0.0	>= 0.6, < 0.8
1.0.0	1.0.0	>= 0.6, < 0.7
0.2.2	0.1.3	>= 0.6, < 0.7

Contributing

Development install

Note: You will need NodeJS to build the extension package.

The jlpm command is JupyterLab's pinned version of yarn that is installed with JupyterLab. You may use yarn or npm in lieu of jlpm below.

# Clone the repo to your local environment
# Change directory to the jupyterlite_terminal directory
# Install package in development mode
pip install -e "."
# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite
# Rebuild extension Typescript source after making changes
jlpm build

You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.

# Watch the source directory in one terminal, automatically rebuilding when needed
jlpm watch
# Run JupyterLab in another terminal
jupyter lab

Then build a JupyterLite distribution with the extension installed:

cd deploy
jupyter lite build --contents contents

And serve it either using:

npx static-handler _output/

or:

jupyter lite serve

To enable use of SharedArrayBuffer rather than ServiceWorker for stdin you will have to configure your server to add the Cross-Origin-Embedder-Policy and Cross-Origin-Opener-Policy headers. Do this using either:

npx static-handler --cors --coop --coep --corp _output/

or:

jupyter lite serve --LiteBuildConfig.extra_http_headers=Cross-Origin-Embedder-Policy=require-corp --LiteBuildConfig.extra_http_headers=Cross-Origin-Opener-Policy=same-origin

Building the documentation

The project documentation includes a demo deployment, and is built on every PR so that the changes can be checked manually before merging. To build the documentation and demo locally use:

micromamba create -f docs/environment-docs.yml
micromamba activate terminal-docs
pip install -v .
cd docs
make html

To serve this locally use:

cd _build/html
python -m http.server

Packaging the extension

See RELEASE