Bridget

Notebook state +FastHTML + HTMX in Jupyter, no server required.

Key Features

• Serverless HTMX + FastHTML: full FastHTML + HTMX functionality in Jupyter environments, with no HTTP server required.
• Extended FastHTML routing system: integrates seamlessly with Python methods.
• Widget system (WIP): build UI components with minimal JavaScript.
• Real-time notebook introspection: capture the full notebook structure dynamically, without .ipynb files.
• Environment-agnostic: supports VSCode, JupyterLab, and other interfaces.

Bridget relies on companion extensions for JupyterLab/Notebook and VSCode/Cursor. These capture the live notebook state and feed it directly to Bridget’s Python kernel.

Installation

As Bridget is in early development, it is not yet on PyPI. A development installation requires NodeJS and the pnpm package manager.

Clone the repository, install JS dependencies with pnpm, then perform an editable Python install. This builds the JS components and installs the nbinspect-lab Jupyter extension automatically.

# 1. Clone the repository
git clone https://github.com/civvic/bridget.git
cd bridget

# 2. Install JavaScript dependencies (JupyterLab extension)
pnpm install

# 3. Install Python package with all dependencies
pip install -e .[dev]

Note: step 2 is only necessary if you are going to use Jupyter Lab/Notebook. For VSCode, simply install the extension. See below.

VSCode Extension Installation

For VSCode and Cursor, install the nbinspect-vscode extension manually. The .vsix file is inside packages/nbinspect-vscode.

To install: - Run the command Extensions: Install from VSIX… - Or open the Extensions view, click the “…” menu, and select Install from VSIX….

Quick Start

A minimal stateful counter component:

from bridget.common import get_app
from fasthtml.components import Button

app, bridget, rt = get_app()  # Initialize Bridget and app

def counter(n=0):
    @rt('/inc')
    def increment(n:int):
        return Button(f"Count: {n+1}", value=f"{n+1}", name='n', hx_post='/inc', hx_swap='outerHTML')
    return increment(n-1)

counter()

For more detailed examples, review the notebooks in the nbs/examples/ directory.

Core Concepts

The Bridge

The Bridge class (14_bridge.ipynb) provides the low-level communication layer between Python and JavaScript, replacing the HTTP transport layer typically used by HTMX.

Bridget and get_app()

The Bridget class (32_bridget.ipynb) and get_app() function provide the high-level API for creating interactive components. This is your main entry point.

Routing System

Bridget extends FastHTML’s routing system (04_route_provider.ipynb) to work with Python methods and class instances, enabling stateful components.

Plugin System

Bridget’s functionality can be extended through plugins (16_bridge_plugins.ipynb), enabling modular feature development.

Notebook State

Access live notebook structure and content (21_nb_state.ipynb) without saving files, enabling powerful introspection capabilities.

Documentation Structure

Core Components

• 00_common.ipynb - Common imports and utilities
• 01_helpers.ipynb - Helper functions and utilities
• 10_bridge_widget.ipynb - BridgeWidget infrastructure
• 14_bridge.ipynb - Bridge class (low-level messaging)
• 32_bridget.ipynb - Bridget class and get_app() entry point

FastHTML Integration

• 03_fasthtml_patching.ipynb - FastHTML modifications for serverless operation
• 04_route_provider.ipynb - Extended routing system

Notebook State

• 07_nb.ipynb - High-level notebook API
• 15_nb_hooks.ipynb - Notebook event hooks
• 21_nb_state.ipynb - Notebook state introspection

Components and Widgets

• 40_details_json.ipynb - Lazy-loading JSON viewer
• 50_widget.ipynb - Widget development guide

Examples

• examples/quickstart.ipynb - Quick start guide
• examples/htmx_examples.ipynb - HTMX patterns

Compatibility and Development

Bridget is developed with nbdev and requires Python 3.12+. Core dependencies like fasthtml and anywidget are installed automatically. It is regularly tested on macOS with VSCode, Jupyter Notebook, and Jupyter Lab, and is expected to function in any environment where anywidget/ipywidgets is supported.

Project Status

Bridget is experimental and integrates Jupyter, FastHTML, and HTMX.

Its primary goal, inspired by Donald Knuth’s concept of Literate Programming, is to create truly dynamic documents where any content (including cell outputs) can be directly edited and interacted with in place.

Current status: - ✅ Core architecture for serverless HTMX and notebook introspection is functional. - ✅ Key HTMX patterns are supported and demonstrated in the nbs/examples/ notebooks. - ⚠️ The API is unstable and subject to significant change. - ⛔ Not recommended for use in production environments. - 📝 Documentation and more complex examples are in active development.