Drafter

A student-friendly, full-stack web development library for Python, following good software engineering principles.

Drafter lets you build interactive websites out of plain Python functions and dataclasses. You write route functions that take the current application state and return pages; Drafter handles rendering, forms, navigation, history, and debugging. The same program can be run as a local development server or compiled to a fully static site (running Python in the browser via Pyodide or Skulpt) that can be hosted anywhere, such as GitHub Pages.

• Homepage/Docs: https://drafter-edu.github.io/drafter/
• Source: https://github.com/drafter-edu/drafter
• License: MIT
• Python: 3.10+

Note: This branch (v2-pyodide) is the Drafter v2 rewrite, currently in beta. See ARCHITECTURE.md for a deep dive into the system design.

Quick start

Install from PyPI:

pip install drafter

Create a file my_site.py:

from drafter import *
from dataclasses import dataclass

@dataclass
class State:
    message: str

@route
def index(state: State) -> Page:
    return Page(state, [
        "Hello, world!",
        state.message,
        Button("Say goodbye", goodbye),
    ])

@route
def goodbye(state: State) -> Page:
    return Page(state, ["Goodbye!"])

start_server(State("Welcome to my site."))

Then run it any of these equivalent ways:

python my_site.py
drafter my_site.py
python -m drafter my_site.py

A local development server starts (by default at http://localhost:8000), your browser opens automatically, and the page hot-reloads whenever you save the file.

How it works

When you run a Drafter program locally, your code actually executes twice:

1. Host side: Python runs your script normally. When it reaches start_server(...), Drafter starts a local Starlette/uvicorn development server that serves a single page embedding your code, plus a WebSocket connection for hot reload.
2. Client side: The served page boots a Python-in-the-browser engine (Pyodide by default, or Skulpt) and re-runs your code there. That in-browser run is the one users actually interact with: routes execute, state updates, and the DOM is updated, all inside the browser.

Because everything runs client-side, drafter my_site.py --compile can produce a static build of the same app with no server component at all. This can be deployed on GitHub Pages, Netlify, or any static host.

Running and building

Serve (default mode)

drafter my_site.py [options]

Starts the local development server with file watching, hot reload, and the debug panel enabled.

Compile a static site

drafter my_site.py --compile [options]

Builds a static site (default output: dist/index.html) that boots the browser engine and runs your program. Deploy the output directory to any static host.

Command-line reference

All flags below work with the drafter command (and python -m drafter). Flags are grouped the same way Drafter's configuration system groups them. Run drafter --help for the live list.

General

App behavior (server and compile modes)

Site rendering and debugging

Development server (serve mode only)

Static builder (--compile mode only)

Environment variables

Every setting can also be provided via environment variables. Boolean variables accept 1, true, or yes (case-insensitive) for true; anything else is false. List-valued variables are semicolon-separated.

General

App behavior

Site rendering and debugging

Development server

Static builder

Tooling-only variables

Configuration files

Instead of (or in addition to) flags and environment variables, you can put settings in a JSON file and pass it with --config-file (repeatable; later files override earlier ones) or DRAFTER_CONFIG_FILE (semicolon-separated). The file is keyed by configuration section, with keys matching the dataclass field names:

{
    "bootstrap": { "verbose": true },
    "app_common": { "engine": "pyodide", "site_title": "My Site" },
    "client_server": { "theme": "dark", "in_debug_mode": false },
    "app_server": { "port": 8080, "open_browser": false },
    "app_builder": { "output_directory": "public", "zip_output": true }
}

The five sections are bootstrap, app_common, client_server, app_server, and app_builder, matching the flag groups above.

Precedence (lowest to highest):

1. Defaults defined in the code
2. Environment variables
3. Command-line arguments
4. Configuration files
5. Arguments passed to start_server(...) and imperative configuration calls in your code (e.g., set_website_title(...))

Configuring from code

start_server() accepts configuration keyword arguments directly, which override everything else:

start_server(State(...), site_title="My Site", theme="dark", port=8080)

Commonly used parameters: site_title, theme, framed, in_debug_mode, engine, port, host, open_browser, use_reloader, inline_py, prerender_initial_page, asset_directory, show_filename_as, information, verbose. Any other configuration field can be passed as an extra keyword argument. (The v1 parameters cdn_skulpt, cdn_skulpt_std, and cdn_skulpt_drafter are accepted but ignored, with a warning.)

There are also imperative helpers (importable from drafter) that reconfigure the running site:

Development

This section is for working on Drafter itself. The v2 rewrite lives on the v2-pyodide branch:

git checkout v2-pyodide

Setup (Python via uv)

1. Prereqs: Python 3.10+ (3.11+ recommended), Node.js 18+ with npm, and uv. On Windows PowerShell:

   winget install astral-sh.uv
   

2. Clone:

   git clone https://github.com/drafter-edu/drafter.git
   cd drafter
   

3. Create the Python environment and install deps (reads pyproject/uv.lock):

   uv sync
   

4. Install JS deps once (for builds/watchers):

   cd js
   npm install
   cd ..
   

5. Run an example (uses uv's virtual env automatically):

   uv run examples\shop.py
   

   The examples/ directory contains dozens of small apps exercising individual features. Pass --engine skulpt if you need the Skulpt engine explicitly (the default is Pyodide).

Repository layout

Wheels bundle js/dist/ into drafter/assets/ at build time (see pyproject.toml), so JS must be built before packaging.

Watch JS assets

To iterate on the JS client and have changes flow into the Python package automatically:

1. In one terminal, run the JS watcher. This rebuilds the TypeScript bridge on every save:

   cd js
   npm run dev
   

2. In another terminal, run the JS precompiler. This rebuilds the Skulpt-compiled version of the Drafter Python library on every save:

   cd js
   npm run precompile:watch
   

3. In another terminal, run a local Drafter app so you can see live reloads:

   uv run examples\simplest.py
   

Notes:

• The watcher writes bundles to js/dist/, which the dev server serves from /assets and includes in its file watcher, so connected browsers auto-reload.
• If you maintain a local Skulpt build, set SKULPT_DIR in a top-level .env to copy skulpt.js and skulpt-stdlib.js into the assets on startup (npm run dev does this automatically; npm run update-skulpt runs it standalone).

Other useful JS scripts (run from js/): npm run build (production build), npm run precompile (one-shot minified Skulpt precompile), and npm run playground (build and serve a standalone playground at http://localhost:8777).

Run tests

• JS tests (fast unit tests are the default; test:integration runs the real-Pyodide suites serially with a large heap; test:skulpt runs the legacy Skulpt suites, which are currently known-failing and not part of the regular baseline):

  cd js
  npm run test
  npm run test:integration
  

• Python tests (uses uv env):

  uv run pytest --verbose --color=yes -vv
  

• Or run everything plus formatting and linting via just:

  just validate
  

Build and serve docs

Use the Drafter docs wrapper instead of calling MkDocs directly (it is installed as the drafter-docs script and forwards all other arguments to mkdocs):

uv run drafter-docs build
uv run drafter-docs serve

Optional dev mode:

uv run drafter-docs build --dev
uv run drafter-docs serve --dev

In dev mode, the MkDocs Drafter codeblock plugin compiles embedded demos with Pyodide package style build (local package build) instead of the default pypi.

Full API reference:

uv run drafter-docs build --api

Rendering the per-module API reference through mkdocstrings dominates build time, so it is skipped by default and replaced with a placeholder page. Pass --api (combinable with --dev) when you need the real thing.

License

MIT — see LICENSE.txt.