Versioning and upgrades
What semantic versioning covers in RelKit, how deprecations and migrations work, and what has to be true before RelKit reaches 1.0.
RelKit is not at 1.0 yet. This page says what you can rely on today, what you can rely on from 1.0, how upgrades work, and what has to be true before 1.0 ships. All RelKit packages share one version.
What semantic versioning covers
From 1.0, Core features follow semantic versioning: an incompatible change ships only in a major release, new features ship in minor releases and fixes in patch releases. The Core and Labs page lists which features are Core.
Semantic versioning covers:
- the documented APIs of Core packages, as listed in the API reference,
- the
relkitCLI’s commands and flags, - the
RELKIT_*error codes and what each one means.
It does not cover Labs features, which can change or disappear in any release, or anything the
documentation does not describe. Labs APIs carry the @experimental tag, and their docs pages show a
Labs badge.
Before 1.0, minor releases can contain breaking changes. The breaking changes of the plan that leads
to 1.0 ship together in one release, 0.9.0, preceded by a beta. After it, 0.x releases do not
break Core without the deprecation window below.
Deprecations
A deprecated Core API keeps working for at least one minor release before it is removed. While it
works, using it prints a warning that carries a RELKIT_DEPRECATED_* code, names the replacement and
links to the code’s docs page. RelKit prints each deprecation warning once per process, so a
deprecated call in a hot path does not flood your log.
For example, importing @relkit/app prints
RELKIT_DEPRECATED_APP_PACKAGE, and
passing Better Auth options to defineBetterAuthService prints
RELKIT_DEPRECATED_BETTER_AUTH_OPTIONS.
The error codes index lists every deprecation code.
Upgrades and migrations
Every breaking change ships with an automated migration and a migration note:
- The changelog entry for the change links a section of a migration guide, and a release check fails
when a breaking change has no such link or no
relkit migraterule behind it. relkit migratepreviews the changes it will make, applies them with--write, and undoes them with--rollback <receipt>.- Changes the migration cannot apply are listed with their file and line, so you finish them by hand.
To upgrade, update the relkit and @relkit/* packages together, run relkit migrate, and run
relkit check. The RelKit 0.9 migration guide walks through the one
breaking release before 1.0. Each release’s notes are in the
changelog.
What 1.0 means
RelKit reaches 1.0 when Core reaches 1.0, and not before all of these are true:
- Core is complete. Every feature the maturity table lists as Core is implemented, documented and tested on every Tier 1 runtime: Bun, and Node 22 and 24.
- The creation canary is green on Tier 1 runtimes.
create-relkitcreates every template on the latest Bun and on Node, and each project’s tests and dev server pass, every night. - The Railway newcomer test passes. A newcomer who follows the Railway guide from a new project deploys without steps missing from the guide, in under 15 minutes.
- The metrics targets are met.
createsucceeds 100% of the time on the latest Bun for all templates; a newcomer reaches a first route in under 5 minutes; the HTTP test suite passes on Bun and Node; a save is serving again in under 1 second at p95 for a 100-function app; andrelkit checkpeak memory is at or belowtsc(benchmarks).
Until Core reaches 1.0, RelKit adds no new feature areas: bug fixes and hardening continue in both Core and Labs.
Target date
The target for 1.0 is the quarter after 0.9.0 ships. If a criterion above is not met by then,
1.0 waits for it and this page states the new date.