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.10: every entry and what it exports.

The @gyral/* packages and create-gyral release together at a shared version: keep every @gyral/* package your app installs on that one version. Gyral's packages take @gyral/core as a peer at their exact version, so your package manager reports a mismatch when it installs (pnpm lists the unmet peer, npm stops with ERESOLVE), and a package that loads with another release of core throws G0016 in development. The package guide explains what each app needs.

Releases

These guides describe 0.3.10, 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.10 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. Commit, then run npx @gyral/codemod 0.3.8 from the app's directory, before or after you install. It moves code from 0.3.7's APIs to the current ones wherever it can prove the rewrite safe: a spread-in gyralVitePreset() becomes plugins: [gyral()], ...(gyralVitePreset(o).plugins ?? []) becomes ...gyral(o), driver records outside tests become lists, and subscription('feed', …) becomes subscription(feed, …) where the module declares the feed token. An app on 0.3.8 has nothing to rewrite. A package whose @gyral/core is older than 0.3.7 is left as it is, and reported once if it has code to rewrite: migrate it to 0.3.7 first. The codemod lists every candidate it leaves, with file:line and the reason, among them driver records it can't follow (returned from a function, passed in defineStore({ drivers }) options) and subscription('feed', …) where feed is imported from another module. It only writes into a clean git working tree (--dry prints the diff instead), so git diff shows what it did.
  4. Run ESLint with gyral.configs.recommended from @gyral/core/eslint. gyral/prefer-built-in names code that a built-in replaces, such as a parser that checks modifier keys by hand (on()) or JSON.parse of a prop, whatever the props parameter is called (prop.json()), and gyral/intent-event an on() parser bound to another event (the rules).
  5. Run typechecking, component/browser tests and the production build. vite dev and browser tests run Gyral's development checks, and some throw, naming what to change. A view that reads something besides its state, props and stores warns (G0017), because Gyral skips renders whose inputs are unchanged.
  6. 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. If gyral-rs renders your pages, check that your gyral-rs release accepts the target (Rust servers).
  7. Update the agent skill your project carries: npx @gyral/mcp@0.3.10 skill (coding agents).

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.