Skip to content

README.md

Latest commit

 

History

History
147 lines (117 loc) · 6.14 KB

README.md

File metadata and controls

147 lines (117 loc) · 6.14 KB

jupyter-kit

@jupyter-kit

Framework-agnostic Jupyter notebook renderer for the browser.

npm @jupyter-kit/react e2e license FOSSA status

@jupyter-kit/* renders .ipynb notebooks in the browser from any host — React, Vue 3, a Web Component, or plain DOM. Optional packages add in-browser execution (Pyodide / WebR), interactive ipywidgets, KaTeX / MathJax, editable CodeMirror cells, and 13 chrome themes × 8 syntax themes.

Formerly react-ipynb-renderer (v1 / v2). v3 is a rewrite into a pnpm monorepo; see the migration guide.

Quick start — React

pnpm add @jupyter-kit/react @jupyter-kit/theme-default
import { Notebook } from '@jupyter-kit/react';
import { python } from '@jupyter-kit/core/langs/python';
import '@jupyter-kit/theme-default/default.css';
import '@jupyter-kit/theme-default/syntax/one-dark.css';

import notebook from './demo.ipynb';

export default function App() {
  return <Notebook ipynb={notebook} language="python" languages={[python]} />;
}

Vue / Web Component / vanilla variants + every opt-in (math, executor, widgets, …) are generated by the install wizard.

Features

  • Framework wrappers — @jupyter-kit/react, @jupyter-kit/vue, @jupyter-kit/wc (<jk-notebook> custom element), or @jupyter-kit/core used directly from vanilla JS.
  • In-browser execution — @jupyter-kit/executor-pyodide (Python) and @jupyter-kit/executor-webr (R) run cells in a Web Worker, with multi-CDN fallback + per-candidate timeout.
  • Interactive ipywidgets — @jupyter-kit/widgets hydrates saved widget-state for static notebooks, or drives widgets live over the Jupyter Comm protocol when paired with the Pyodide executor.
  • Math rendering — KaTeX or MathJax, bundled or CDN; see @jupyter-kit/katex / -cdn / @jupyter-kit/mathjax / -cdn.
  • Themes — 13 chromes × 8 syntax themes, published per-chrome (@jupyter-kit/theme-<name>) or all-in-one (@jupyter-kit/theme-all).
  • CodeMirror 6 editor — @jupyter-kit/editor-codemirror makes cells editable; combine with an executor for a mini notebook.
  • Security — DOMPurify + rehype-sanitize by default; Playwright XSS suite (packages/e2e/tests/xss.spec.ts) runs on every push.

Package catalog

Package Purpose
@jupyter-kit/core Rendering engine (no framework dependency)
@jupyter-kit/react / vue / wc Framework wrappers (<Notebook> / <jk-notebook>)
@jupyter-kit/theme-<name> Notebook chrome CSS — 13 variants
@jupyter-kit/theme-all Every chrome + every syntax theme under subpaths
@jupyter-kit/editor-codemirror CodeMirror 6 editor plugin
@jupyter-kit/executor-pyodide Python executor (Pyodide)
@jupyter-kit/executor-webr R executor (WebR) — GPL-2.0+
@jupyter-kit/katex / -cdn KaTeX math plugin (bundled / CDN)
@jupyter-kit/mathjax / -cdn MathJax math plugin (bundled / CDN)
@jupyter-kit/widgets ipywidgets renderer
@jupyter-kit/comm Jupyter Comm protocol types (zero runtime)

Docs & live demos

Monorepo layout

packages/
  core                                  ← rendering engine
  react, vue, wc                        ← framework wrappers
  theme                                 ← less sources + publish build
  editor-codemirror                     ← editor plugin
  executor-pyodide, executor-webr       ← in-browser runtimes
  katex, katex-cdn, mathjax, mathjax-cdn
  widgets, comm                         ← ipywidgets support
  fixtures                              ← shared .ipynb test fixtures
  storybook                             ← Storybook stories
  e2e                                   ← Playwright tests
  docs                                  ← Astro + Starlight site

Development

# Clone with the jupyter-themes submodule (less sources for chromes)
git clone --recurse-submodules https://github.com/walkframe/jupyter-kit.git
cd jupyter-kit
pnpm install

# Workspace-wide build — all packages, topologically ordered
pnpm build

# Unit tests
pnpm test

# Playwright e2e (builds the storybook static site automatically)
pnpm test:e2e

# Interactive stories
pnpm storybook

# Docs dev server (theme watcher + Astro at http://localhost:4321)
pnpm -F @jupyter-kit/docs dev

License

Apache-2.0. See LICENSE. Third-party license elections and one opt-in GPL dependency (@jupyter-kit/executor-webr) are documented in NOTICE.md.

FOSSA Status