reflex-jupyter-renderer-react

• Source: https://github.com/ecrespo/reflex-jupyter-renderer-react
• PyPI: https://pypi.org/project/reflex-jupyter-renderer-react/
• Issues: https://github.com/ecrespo/reflex-jupyter-renderer-react/issues
• Upstream React library: https://github.com/iomete/jupyter-renderer-react

A native Reflex component that wraps the jupyter-renderer-react React library, so you can render Jupyter notebooks (.ipynb) in a Reflex app — with syntax highlighting, markdown, rich outputs, theming, collapsible cells and copy-to-clipboard — in pure Python. No HTML, no iframe, no hand-written JavaScript.

import reflex as rx
from reflex_jupyter_renderer_react import (
    jupyter_notebook_viewer, Notebook, MarkdownCell, CodeCell, stream_output,
)

nb = Notebook(cells=[
    MarkdownCell("# Hello, notebook"),
    CodeCell("print('hi')", execution_count=1, outputs=[stream_output("hi\n")]),
])

def index() -> rx.Component:
    return jupyter_notebook_viewer(notebook=nb.to_dict(), theme="dark")

app = rx.App()
app.add_page(index)

Why a native component?

Requirements

• Python ≥ 3.11
• Reflex ≥ 0.10.0 (tested with Reflex 0.10.0, Python 3.11 – 3.14)

Install

pip install reflex-jupyter-renderer-react
# or, with uv:
uv add reflex-jupyter-renderer-react
# or, from this repo (editable):
uv pip install -e .

Reflex installs the underlying npm package (@iomete/jupyter-renderer-react@1.0.1) into the compiled frontend automatically on the first reflex run.

Usage

Three ways to supply a notebook

from reflex_jupyter_renderer_react import (
    jupyter_notebook_viewer, JupyterNotebookViewer, Notebook, MarkdownCell, CodeCell,
    load_notebook,
)

# 1) Typed Python builders
nb = Notebook(cells=[MarkdownCell("# Title"), CodeCell("1 + 1", execution_count=1)])
jupyter_notebook_viewer(notebook=nb.to_dict())

# 2) A raw JSON string
jupyter_notebook_viewer(notebook='{"cells": [], "nbformat": 4, "nbformat_minor": 4}')
# or: JupyterNotebookViewer.from_json(json_str)

# 3) Load from a URL or from disk
JupyterNotebookViewer.from_url("https://example.com/notebook.ipynb")
jupyter_notebook_viewer(notebook=load_notebook("assets/demo-example.ipynb"))

Props

Reflex converts snake_case props to camelCase automatically (show_cell_numbers → showCellNumbers).

Events → Python

class State(rx.State):
    status: str = "idle"

    @rx.event
    def loaded(self, notebook: dict):
        self.status = f"{len(notebook.get('cells', []))} cells loaded"

    @rx.event
    def failed(self, message: str):
        self.status = f"error: {message}"

JupyterNotebookViewer.from_url(
    "https://example.com/notebook.ipynb",
    fetch_options={"timeout": 10000},
    on_file_load=State.loaded,
    on_file_error=State.failed,
)

Demo app

A full demo lives in jupyter_renderer_react_demo/ and exercises every feature (typed builders, JSON string, URL loading with events, custom styles, and live theme/prop toggles).

uv pip install -e .
cd jupyter_renderer_react_demo
uv run reflex run

Building notebooks in Python

from reflex_jupyter_renderer_react import (
    Notebook, MarkdownCell, CodeCell,
    stream_output, execute_result_output, error_output,
)

nb = Notebook(cells=[
    MarkdownCell("# Report"),
    CodeCell("print('hi')", execution_count=1, outputs=[stream_output("hi\n")]),
    CodeCell("2 ** 10", execution_count=2,
             outputs=[execute_result_output({"text/plain": "1024"}, execution_count=2)]),
    CodeCell("1/0", execution_count=3,
             outputs=[error_output("ZeroDivisionError", "division by zero")]),
])
data = nb.to_dict()

The data-model layer (Notebook, cells, output factories, load_notebook) imports without Reflex installed, so it is usable in plain scripts and unit tests.

Naming note

The upstream project has some naming inconsistencies. This wrapper centralizes them in overridable constants and defaults to the public, documented contract:

Defaults match what the published npm package actually ships: library = "@iomete/jupyter-renderer-react@1.0.1", tag = "JupiterNotebookViewer" (the Python class is still named JupyterNotebookViewer). To retarget the unscoped name or the README-spelled tag:

import reflex_jupyter_renderer_react.jupyter_renderer_react as j
j.JupyterNotebookViewer.library = "jupyter-renderer-react"
j.JupyterNotebookViewer.tag = "JupyterNotebookViewer"

You can also change the pinned npm version via LIBRARY_VERSION in src/reflex_jupyter_renderer_react/jupyter_renderer_react.py.

Development

This project follows the Reflex custom component workflow and uses uv.

uv sync --all-extras          # create .venv with Reflex + dev tools
uv run ruff check .           # lint
uv run pytest                 # run the tests
uv build                      # -> dist/ (sdist + wheel with generated .pyi stubs)

Reflex 0.10 note: the reflex component CLI (init / build / publish / share) was removed in Reflex 0.10. This package now follows the official component template: the build backend is hatchling and the hatch-reflex-pyi hook generates the .pyi type stubs during uv build.

Releasing

CI (.github/workflows/ci.yml) runs lint + tests on Python 3.11–3.14, builds the package and compiles the demo on every push and pull request. Publishing to PyPI is done by .github/workflows/publish.yml via trusted publishing when a v* tag is pushed:

1. Bump version in pyproject.toml and add a CHANGELOG.md entry; merge to main.

2. Tag main and push the tag (it must match the version):

   git checkout main && git pull
   git tag v0.2.0
   git push origin v0.2.0
   

See specs/ for the full Spec-Driven Design documentation: PRD, architecture, API, data-model schema, and the phased implementation plan & tasks.

Project structure

reflex-jupyter-renderer-react/
├── src/reflex_jupyter_renderer_react/
│   ├── __init__.py
│   ├── jupyter_renderer_react.py   # the Reflex component
│   └── models.py                   # dependency-free notebook builders
├── .github/workflows/              # ci.yml (tests/build/demo) · publish.yml (PyPI on tag)
├── jupyter_renderer_react_demo/    # runnable demo app
├── tests/                          # data-model + component contract tests
├── specs/                          # SDD: prd / technical / api / data-model / plans
├── pyproject.toml
├── README.md · CHANGELOG.md · LICENSE

License

MIT © Ernesto Crespo. The upstream jupyter-renderer-react library is also MIT.