How structuredlabs/preswald works
Project type and purpose
• Preswald is a full-stack, static-site generator and runtime for interactive data apps.
• It is written in Python (core CLI, engine, transformers) and JavaScript/TypeScript (front-end UI, service worker).
• It bundles compute (Pyodide), data (DuckDB WASM), and UI into a single self-contained HTML/CSS/JS application that runs entirely in the browser, offline.
File structure
• Top-level:
• CLI & engine (preswald/)
• Front-end assets & UI (frontend/)
• Documentation & examples (docs/, documentation/, examples/)
• Automation & packaging (Makefile, pyproject.toml, docker/, .github/)
• Key patterns:
• CLI (“preswald init/run/export/deploy”) launches build & dev server
• Static-site generator pattern: Python → HTML + assets → dist/
• Client-side runtime: uses a service worker (preswald/browser/virtual_service.js), Pyodide & DuckDB WASM, and a reactive DAG in JS
• Config / deployment:
• preswald.toml for app metadata
• docker/ + GitHub Actions workflows for CI/CD
README for additional insights
• Architecture is described as “built on a WASM runtime with Pyodide and DuckDB,” “no server, runs offline”
• Features: reactive engine, UI components, file-first bundling
• Commands: preswald run (dev server), preswald export (static build)
Main components and their interactions
A. Developer CLI & Build Pipeline (Python)
• preswald/cli.py: parses user commands
• preswald/build.py: generates HTML + JS/CSS + embedded Python code
• preswald/deploy.py: optional deployment integration
B. Static Assets / Distribution
• dist/ (output of export): HTML entrypoint, JS bundles, CSS, WASM binaries, Python runtime snapshots
C. Browser Runtime
• Main Thread (frontend/src): UI components, event handlers, layout, widget rendering
• Service Worker (preswald/browser/virtual_service.py + boot.js): intercepts requests, serves Python files & data from in-memory FS
• Pyodide WASM: runs Python code in-browser
• DuckDB WASM: executes SQL queries on data files
• Reactive Engine (preswald/engine/runner.py, transformers): dependency graph, reactivity scheduling
D. Data Layer
• Local files embedded as part of the static bundle (CSV, TOML)
• DuckDB virtual tables created on the fly
E. Telemetry & Branding
• preswald/engine/telemetry.py optionally sends anonymous usage metrics
• Branding assets (logo, favicon) injected into HTML via templates
Architectural patterns & design principles
• Static-site generation + client-side execution (no backend server at runtime)
• Single-page application (SPA) with service worker as virtual backend
• Reactive DAG engine separates data dependencies from UI rendering
• Modular layering: CLI → build → distribution → browser
Technologies, frameworks, libraries
• Python: Click (CLI), Jinja2 (templates), Pyodide, DuckDB-WASM
• JavaScript/TypeScript: Vite, React (JSX in frontend/src), tailwindcss, service worker API
• CI/CD: GitHub Actions, Docker
• Testing: autotest scripts, browser-based HTML tests