jupyterlite-javascript-kernel

A JavaScript kernel for JupyterLite.

Requirements

• JupyterLite >=0.3.0

This kernel was originally maintained as part of the main JupyterLite repository, and was moved to its own repository for the JupyterLite 0.3.0 release.

Install

To install the extension, execute:

pip install jupyterlite-javascript-kernel

Uninstall

To remove the extension, execute:

pip uninstall jupyterlite-javascript-kernel

Runtime modes

The extension currently registers two JavaScript kernelspecs:

• JavaScript (IFrame): Runs code in a hidden runtime iframe on the main page thread. Use this when your code needs browser DOM APIs like document, window, or canvas access through the page context.
• JavaScript (Web Worker): Runs code in a dedicated Web Worker. Use this for stronger isolation and to avoid blocking the main UI thread.

Pick either kernel from the notebook kernel selector in JupyterLite.

Kernel startup extensions

Frontend extensions can register startup work that runs before user code in both runtime modes. Use this to preload runtime modules and register comm targets without sending bootstrap code through requestExecute.

import type { JupyterFrontEndPlugin } from '@jupyterlab/application';
import { IJavaScriptKernelStartupRegistry } from '@jupyterlite/javascript-kernel';

const plugin: JupyterFrontEndPlugin<void> = {
  id: 'my-extension:javascript-startup',
  autoStart: true,
  requires: [IJavaScriptKernelStartupRegistry],
  activate: (app, startup) => {
    const runtimeBootstrap = new URL(
      './runtime-bootstrap.js',
      import.meta.url
    ).toString();
    const lspCommTarget = new URL(
      './lsp-comm-target.js',
      import.meta.url
    ).toString();

    startup.registerStartupExtension({
      id: 'my-extension:lsp',
      activate: async context => {
        await context.preloadModule(runtimeBootstrap);
        await context.registerCommTarget({
          targetName: 'my-extension:lsp',
          module: lspCommTarget,
          exportName: 'registerLspTarget'
        });
      },
      deactivate: async context => {
        await context.unregisterCommTarget('my-extension:lsp');
      }
    });
  }
};

context.registerCommTarget() imports the module in the kernel runtime and passes the exported handler to Jupyter.comm.registerTarget(targetName, handler). The default export is used when exportName is omitted. Disposing a startup registration calls its optional deactivate callback for active kernels.

Worker mode limitations

Web Workers do not expose DOM APIs. In JavaScript (Web Worker), APIs such as document, direct element access, and other main-thread-only browser APIs are unavailable.

Import side effects in iframe mode

In JavaScript (IFrame), user code and imports execute in the runtime iframe scope.

By default, module-level side effects stay in the runtime iframe. To intentionally affect the main page (window.parent), access it directly.

Cell declarations like var, let, const, function, and class remain in the runtime scope. Host-page mutations happen when your code (or imported code) explicitly reaches window.parent.

Example: canvas-confetti

import confetti from 'canvas-confetti';

const canvas = window.parent.document.createElement('canvas');
Object.assign(canvas.style, {
  position: 'fixed',
  inset: '0',
  width: '100%',
  height: '100%',
  pointerEvents: 'none',
  zIndex: '2147483647'
});
window.parent.document.body.appendChild(canvas);

const fire = confetti.create(canvas, { resize: true, useWorker: true });

fire({ particleCount: 20, spread: 70 });

Example: p5.js

import p5 from 'p5';

const mount = window.parent.document.createElement('div');
Object.assign(mount.style, {
  position: 'fixed',
  right: '16px',
  bottom: '16px',
  zIndex: '1000'
});
window.parent.document.body.appendChild(mount);

const sketch = new p5(p => {
  p.setup = () => {
    p.createCanvas(120, 80);
    p.noLoop();
  };
}, mount);

Can side effects be auto-detected and cleaned up?

Partially, yes, but not perfectly. This project currently does not provide automatic side-effect cleanup for host-page mutations.

Limits of automatic cleanup:

• It will not reliably undo monkey-patched globals.
• It will not automatically remove all event listeners or timers.
• It cannot safely revert all stateful third-party module internals.

Jupyter Widgets

The kernel provides built-in support for Jupyter Widgets (ipywidgets-compatible). Widget classes and helpers are available under Jupyter.widgets; destructure the ones you need before using them:

const { IntSlider, IntProgress, jslink } = Jupyter.widgets;

const slider = new IntSlider({
  value: 50,
  min: 0,
  max: 100,
  description: 'My Slider'
});
const progress = new IntProgress({
  value: 50,
  min: 0,
  max: 100,
  description: 'Mirror'
});
display(slider);
display(progress);

slider.observe(({ new: value }) => {
  console.log('Slider value:', value);
}, 'value');

jslink([slider, 'value'], [progress, 'value']);

Widgets auto-display when they are the last expression in a cell. Use the global display() function to display a widget explicitly, for example when assigning to a variable.

Available widgets

• Numeric: IntSlider, FloatSlider, FloatLogSlider, IntRangeSlider, FloatRangeSlider, Play, IntProgress, FloatProgress, IntText, FloatText, BoundedIntText, BoundedFloatText
• Boolean: Checkbox, ToggleButton, Valid
• Selection: Dropdown, RadioButtons, Select, SelectMultiple, ToggleButtons, SelectionSlider, SelectionRangeSlider
• String: Text, Textarea, Password, Combobox
• Display: Label, HTML, HTMLMath, Output
• Button: Button (with .onClick() handler)
• Color: ColorPicker
• Layout / Style: Layout, DescriptionStyle, SliderStyle, ProgressStyle, ButtonStyle, CheckboxStyle, ToggleButtonStyle, ToggleButtonsStyle, TextStyle, HTMLStyle, HTMLMathStyle, LabelStyle
• Containers: Box, HBox, VBox, GridBox, Accordion, Tab, Stack
• Helpers: jslink, jsdlink

Ported widget modules

The widget runtime is split into files that roughly follow the upstream ipywidgets package structure so it is easier to track what has been ported.

Note: jupyterlab-widgets, @jupyter-widgets/controls, and @jupyter-widgets/output must be available in the JupyterLite deployment for the full widget set to render.

See the example notebook for more usage examples.

Enable or disable specific modes

The two runtime modes are registered by separate plugins:

• @jupyterlite/javascript-kernel-extension:kernel-iframe
• @jupyterlite/javascript-kernel-extension:kernel-worker

You can disable either one using disabledExtensions in jupyter-config-data.

Disable worker mode:

{
  "jupyter-config-data": {
    "disabledExtensions": [
      "@jupyterlite/javascript-kernel-extension:kernel-worker"
    ]
  }
}

Disable iframe mode:

{
  "jupyter-config-data": {
    "disabledExtensions": [
      "@jupyterlite/javascript-kernel-extension:kernel-iframe"
    ]
  }
}

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-javascript-kernel 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

With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).

By default, the jlpm build command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:

jupyter lab build --minimize=False

Development uninstall

pip uninstall jupyterlite-javascript-kernel

In development mode, you will also need to remove the symlink created by jupyter labextension develop command. To find its location, you can run jupyter labextension list to figure out where the labextensions folder is located. Then you can remove the symlink named @jupyterlite/javascript-kernel within that folder.

Packaging the extension

See RELEASE