Webspresso Documentation

Welcome to the official Webspresso documentation. Webspresso is a lightweight, zero-dependency-sprawl Express SSR framework featuring file-based routing, Nunjucks templating, an intuitive Knex-based ORM with ambient transactions, a modular plugin ecosystem, and a customizable Mithril.js SPA Admin Panel.

Documentation Pillars #

docs/
├── getting-started/       # "Get Started Fast" (0 -> 1 Walkthroughs)
├── guides/                # "How do I do X?" (Task & Problem Oriented)
├── concepts/              # "How does it work and why?" (Mental Models & Deep Dives)
├── reference/             # "What is the exact API contract?" (Unbiased Spec & Options)
└── examples/              # "Tested, Runnable Projects"

🚀 Getting Started #

Start here if you are new to Webspresso or building a new application:

• Installation — Node.js requirements, package manager setup, and CLI installation.
• First Application — Scaffold your first project, create pages, write an API route, and start the dev server.
• Project Structure — Anatomy of a Webspresso application (pages/, views/, services/, models/, config/).
• Deployment — Production configuration, environment variables, process management, and graceful shutdown.

📖 Task Guides ("How do I...?") #

Task-focused guides for solving specific engineering problems:

• File-Based Routing — Static routes, dynamic parameters ([id]), catch-all ([...slug]), and per-page assets.
• SSR & Templates — Server-side data loading (load()), Nunjucks layouts, fsy template helpers, and chunked streaming.
• Services Layer — Defining services, Zod validation, declarative auth guards, and ambient ACID transactions.
• Database & ORM — Defining models (defineModel), zdb schema builder, repositories API, and Knex migrations.
• Dual Authentication — Session-based auth cookies for SSR, stateless JWT & refresh token rotation for APIs.
• API Endpoints — HTTP method files (.get.js, .post.js), req.input validation, and JSON responses (see File-Based Routing).
• Admin Panel SPA — Registering admin modules, custom Mithril.js components (component.js), field renderers, and widgets.
• Plugin Ecosystem — Official plugins, lifecycle hooks (register, onRoutesReady), and inter-plugin APIs.
• Realtime Layer — WebSocket, SSE, and Socket.IO adapters, subscriptions, and Redis Pub/Sub.
• File Uploads — Multipart upload handling, storage providers, and file validation.
• Email System — MJML template compilation, Nodemailer transport, and delivery tracking.
• Polar.sh Billing — Subscription checkout, customer portal, webhooks, tier sync, and migration via polarPlugin.
• Polar Production Checklist — Pre-launch env, webhook, rate limit, external tier hooks, and CSP checklist.

🧠 Concepts & Architecture ("How does it work and why?") #

Deep dives into the mental models, runtime pipeline, and architectural decisions:

• System Architecture — Layered architecture, component boundaries, and design principles.
• Request Lifecycle — End-to-end flow from incoming HTTP socket to template render and response stream.
• Service Execution Pipeline — Sanitization, Zod compilation, auth guards, transaction propagation, caching, and execution.
• Ambient Transaction Propagation — How AsyncLocalStorage binds Knex transactions across nested services and repositories.
• Plugin Lifecycle — Registration order, route readiness, dependency resolution, and graceful teardown.
• Error Boundary & Exceptions — Django-inspired exception hierarchy, error masking in production, and custom error boundaries (see Exceptions Catalog).
• Graceful Shutdown & Draining — Connection tracking, keep-alive draining, HTTP 503 handling, and reverse-order plugin disposers.
• Asset Pipeline & Versioning — Cache-busting, manifest resolution, per-page bundles, and CDN prefixing.

📚 API Reference ("What is the exact contract?") #

Unbiased, complete specification of public APIs verified against TypeScript declarations:

• createApp() Configuration — Complete CreateAppOptions parameter reference.
• CLI Reference — All webspresso CLI commands, flags, and interactive workflows.
• Request & Response — Properties and helpers attached to req and res (req.context, req.service, req.auth, res.renderStream).
• Service Definition Spec — defineService options, ServiceDefinition schema, and ServiceContext.
• Model & Repository Spec — defineModel options, zdb column builder types, and Repository query methods.
• Plugin Ecosystem — Official built-in plugins, lifecycle hooks, and configuration overview.
• Template Helpers Reference — Complete catalog of fsy.* Nunjucks helper functions.
• Exceptions Catalog — Error classes, status codes, and payload formats.

🧪 Examples & Starter Kits #

Runnable, tested example projects demonstrating real-world patterns:

• examples/basic-ssr — Minimal Nunjucks SSR + SQLite setup.
• examples/rest-and-services — REST API endpoints, Zod schema validation, and services layer.
• examples/auth-session-jwt — Dual authentication setup with session cookies and stateless JWTs.
• examples/admin-custom-pages — Admin Panel SPA with custom Mithril.js components and dashboard widgets.

🤖 For AI Coding Agents #

If you are an autonomous coding assistant or LLM working on a Webspresso project:

• Read AGENTS.md for project-level architectural rules and zero regression policies.
• Check llms.txt for a machine-readable sitemap of this documentation.