Mado 0.15.3
Documentation that matches the package.
Learn the framework from the source shipped with the exact Mado version running this site. 23 documents cover the path from a first page to a production release.
Start here
Concepts (read once)
- Pages and Components Mado has exactly two framework primitives: page() and component(). The design decision has three outcomes: a URL-owned document is a page, an autonomous custom-element boundary is a component, and…
- Templates and signals Reactivity in Mado is one primitive — signal() — composed into three reading patterns. Templates are tagged html`` literals the browser understands directly.
- Routing One app map. No folder scanners. No special path syntax. Layouts are pages that render ${child}.
- Data resource() reads, mutation() writes, jsonFetcher() shapes the wire. Backends, auth and modules all sit on top of this layer.
- Forms useForm() adds reactive state to the browser's form and constraint-validation model. HTML remains the source of truth for required, type, min, max, minlength, maxlength and pattern.
- Static snapshots (mado static) Browser-rendered static HTML for SEO and first paint. No SSR, no hydration, no separate static renderer.
- App architecture The default starter is the canonical minimum for a Mado app: plain files, imports and Mado primitives. It deliberately does not prescribe backend-style layers or a domain-module system before the…
- Mado UI Reviewed, copy-owned UI source for Mado applications — without a second browser runtime.
Production
- Deployment One command. One artifact. Many hosts. mado release writes everything a static host needs into out/. The same out/ can be pushed to nginx, Cloudflare Pages, Netlify, S3 or GitHub Pages without…
- Error handling Mado has three practical error layers: route loading, data loading, and user actions. Handle each layer where the user can recover.
- Testing Mado projects are plain TypeScript and browser APIs, so tests should stay plain too. The framework repository uses Node's built-in test runner plus linkedom for DOM tests.
- Static snapshots cookbook Concrete recipes for mado static. Concept and API in 15-static-snapshots.md; failure modes and CI guidance at the end of this file.
- Devtools and diagnostics Development instrumentation is opt-in. Load the public pre-v1 candidate subpath only during development and before mounting the application:
Reference
- API surface What applications may import today, what remains internal, and what may still change before v1.
- Reactivity ordering The small set of ordering guarantees Mado treats as public behaviour.
- v1 stability What Mado promises after v1, and what remains free to evolve.
- Migrating from 0.12 to 0.13 0.13 narrowed the root API and made lifecycle, forms, resources and router behaviour explicit. The later slot-owned reactivity change is covered by the 0.13 → 0.14 guide.
- Migrating from 0.13 to 0.14 0.14 deliberately removes the component renderer-function layer. Components, pages and standalone templates now share one rule: reactivity belongs to dynamic template slots.
Meta
- Mado · LLM guide Pitfalls that AI assistants (Copilot, Claude, ChatGPT, Cursor) hit when generating Mado code, and a practical zero-history test you can hand to a fresh model.
- Mado for Backend Developers You write in Go / Rust / .NET / Java / Python and you need to build a web UI for an admin panel, internal tool or dashboard. This page explains Mado in backend-oriented terms.
- Why Mado — and when not to choose it Choose a framework for the application you have, not for the migration you could invent. If an existing stack works, changing it only for novelty is usually the wrong trade.