API Stability and SemVer

Public API contract, compatibility levels, and versioning policy.

This page defines Flutterwind's public API stability contract.

Public API surface

Stable public APIs include:

  • package:flutterwind_core/flutterwind.dart exports
  • FlutterWindExtension.className(...)
  • TailwindConfig read APIs and config loading behavior
  • FlutterWindTheme APIs

Anything under lib/src/** is internal unless explicitly re-exported through flutterwind.dart.

Stability levels

  • stable: production-safe; breaking changes require deprecation cycle
  • experimental: may change in minor versions
  • internal: no compatibility guarantees

Deprecation workflow

Breaking changes to stable APIs must follow:

  1. Add deprecation annotation and migration note
  2. Keep old API functional for at least one minor release
  3. Remove in the next major release only

SemVer rules

  • PATCH: bug fixes and internal improvements only
  • MINOR: additive, non-breaking features
  • MAJOR: breaking changes with migration guidance

Migration docs expectations

For each deprecation/removal:

  • mention old and new APIs
  • include before/after code examples
  • include target removal version
Edit this page
UI Blocks
Built-in preset tokens for common interface patterns.
Tailwind v4 Runtime Parity
Runtime parsing semantics, supported variants, and known constraints.