Bridget

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.