Gyral home
Documentation menu

Versioning and stability

Gyral is in 0.x. A minor version can include breaking changes. Read its upgrade guide and the package changelogs before moving to it; do not treat every 0.x minor as an interchangeable dependency update.

Public and internal APIs

Use documented public package entries. Entries containing /internal are for Gyral's own packages and have no stability promise. A symbol being technically exported does not make an internal entry an application API. The export inventory records the public boundary of 0.3.6: every entry and what it exports.

The @gyral/* packages and create-gyral release together at a shared version. Keep core, router, HTTP, time, testing, devtools, SSR and MCP aligned; verify your lockfile when a package manager resolves multiple versions. The package guide explains what each app needs.

Releases

These guides describe 0.3.6, the latest version on npm. Every package is published from GitHub Actions with npm provenance; install from the registry. Today npm has releases only, under the latest tag.

For a released application, pin the registry version you verified and retain the lockfile. Deploy server output and client assets from the same build: stale HTML with new component templates can cause hydration mismatches. Versioned hashed assets help keep that agreement.

Breaking changes wait for a new minor version, and that release gets an upgrade guide in these docs. On an older 0.3.x release? Install 0.3.6 and read the core changelog.

Upgrade with evidence

  1. Read the changelogs for every release between yours and the target, and the upgrade guide when the target is a new minor version.
  2. Update packages together and install from the lockfile.
  3. Run typechecking, component/browser tests and the production build.
  4. Test server/client hydration, edited forms, routing and the production CSP if your app uses them. Check payload size for the pages whose loading matters.

The generated API reference describes the packages installed for this site's build. Consult the changelog for the exact version your app runs: core, HTTP, router, SSR and the other package directories. Report a regression with the versions, a small reproducer and the expected behavior. The repository's pnpm check is its release-quality gate.