Skip to content
Mado
Browse documentation

Reference Mado 0.15.3

v1 stability

What Mado promises after v1, and what remains free to evolve.

Mado v1 means the public app-facing contract is stable enough for real business apps. It does not mean every internal file, generated byte, starter copy, or diagnostic string is frozen forever.

Read this together with:

Stable under SemVer

After v1, Mado treats these as SemVer-protected:

  • Public exports from @madojs/mado.
  • Public TypeScript types exported from @madojs/mado.
  • The @madojs/mado/devtools.js controller subpath, @madojs/mado/vite, the documentation manifest schema, the @madojs/mado/llms.txt asset and the @madojs/mado/package.json metadata subpath.
  • Template binding syntax: child ${}, @event, .prop, ?boolean, attribute bindings, directives and each().
  • Signal semantics documented in the reactivity ordering guide.
  • Component lifecycle semantics: setup once per connection lifetime, deferred teardown for same-tick moves, cleanup via ctx.onDispose.
  • Router/page/resource/form contracts documented in the English docs.
  • CLI command names and broad command intent (build, dev, release, static, preview, init, new).

Breaking these requires a major version.

Allowed in minor releases

Minor releases may add:

  • New root exports after explicit API review and golden-file update.
  • New options on existing APIs.
  • New diagnostics and warnings.
  • New starters, examples, docs and CLI flags.
  • Performance improvements and internal implementation rewrites.

Minor releases should not require existing correct apps to change code.

Allowed in patch releases

Patch releases may fix bugs, tighten diagnostics, improve docs, and make compatible implementation changes. A patch may change timing only when the old timing was an undocumented bug and the change preserves the documented reactivity ordering contract.

Not stable

These are intentionally not SemVer-protected:

  • Internal package subpaths other than the documented public tooling, documentation and metadata subpaths.
  • Files under src/, dist/src/, and implementation module boundaries.
  • _testHooks, diagnostics internals and warning codes.
  • Exact generated JavaScript text, chunk names, sourcemap content and bundle byte layout.
  • Internal parser, binding, router and resource cache data structures.
  • Starter app visual copy and demo data.

Apps should not import internal files or assert exact bundle output.

Bundle and release output

Mado reports framework, starter and devtools bundle size on every release. During pre-v1 contract work this is evidence, not a pass/fail budget. A hard budget may return after representative applications establish an honest baseline. v1 stability does not freeze byte-for-byte bundler output: hashes, chunk boundaries and generated asset names may change as long as the documented deployment contract continues to work.

If a release breaks you

If an update breaks code that uses only public exports and documented behaviour, treat it as a bug. Open an issue with:

  • the Mado version before and after;
  • the public API involved;
  • a minimal reproduction;
  • whether the break is runtime behaviour, TypeScript types, CLI output or docs.

If the break depends on an internal subpath or exact generated output, it may still be worth reporting, but it is not considered a SemVer break.