Stability Policy

What you can depend on, what might change, and how we communicate breaking changes.

Versioning

Juice follows semantic versioning (semver):

Patch (0.x.Y): bug fixes, documentation updates, internal refactors with no API changes
Minor (0.X.0): new features, new options, new exports — backwards compatible
Major (X.0.0): breaking changes to public API or behavior

While Juice is pre-1.0, minor versions may include breaking changes. Each one is documented in the changelog with migration instructions. After 1.0, breaking changes only happen in major versions.

Stable API Surface

The following exports are considered stable. They will not change without a major version bump (or minor version bump with migration guide while pre-1.0):

Export	Module	Status
`createRouter`	`@cmj/juice/runtime`	Stable
`redirect`	`@cmj/juice/runtime`	Stable
`cache`	`@cmj/juice/runtime`	Stable
`setContext` / `getContext`	`@cmj/juice/runtime`	Stable
`createContextKey`	`@cmj/juice/runtime`	Stable
`Link`	`@cmj/juice/client`	Stable
`useRouter`	`@cmj/juice/client`	Stable
`initNavigation`	`@cmj/juice/client`	Stable
`RouterOptions`	`@cmj/juice/runtime`	Stable (new options may be added)

Experimental or Internal

Anything prefixed with _ (underscore) in the source code is internal and may change without notice. Do not import these in your application:

_renderPipeline, _matchRoute, _compileRoutes
_runWithContext, _getALSStore
_serverActionPipeline, _extractActionId
installWebpackShim, installProductionShim

The Vite plugin configuration (juice() in vite.config.ts) is stable in its documented options. Undocumented plugin internals may change.

Deprecation Policy

When a stable API needs to change:

Deprecation notice in a minor release: the old API still works but logs a warning at build time or startup. The changelog and docs explain the migration.
Migration window of at least one minor release cycle. Both old and new APIs work during this window.
Removal in the next major release (or next minor while pre-1.0).

Breaking Change Communication

CHANGELOG.md — every release documents changes with migration examples
GitHub Releases — tagged releases with the same changelog content
Console warnings — deprecated APIs log warnings at build time

Runtime Compatibility

Juice targets WinterCG-compatible runtimes. Minimum supported versions are documented on the Runtime Compatibility page. When a minimum version bumps, it is treated as a breaking change and documented accordingly.

React Version

Juice requires React 19. React is a peer dependency — you control the exact version. Juice will not bump to a new React major version without a Juice major version bump.