Migration
Migrate coordinated package and editable-source consumers from beta.1 to the published stable Core 1.0 release.
Current status
1.0.0 is the published stable release. npm latest and stable resolve to 1.0.0 for all six packages. Historical beta remains on 1.0.0-beta.1 and alpha on 0.1.0-alpha.2.
Update all Nerio packages used by your project together. The immutable Registry revision v1.0.0, signed tag, packages, and GitHub Release identify the same approved release. Review source diffs and preserve local modifications when migrating.
Beta.1 to stable 1.0
The stable release keeps the frozen beta.1 Core contract compatible. Consumers already on beta.1 do not need to repeat the earlier Calendar, Tabs, interactive-type, Registry, CLI, or MCP migration.
| Area | What changed | Required action |
|---|---|---|
| Release identity | Six coordinated packages at 1.0.0 and immutable Registry revision v1.0.0 | Wait for public verification, then update every Nerio package already used by the product in one change. |
| Public contract | The frozen beta.1 Core contract remains compatible, with additive docs, tokens, and corrections | No beta.1 source rewrite is expected; typecheck, build, and review affected visual snapshots. |
| Dependencies | Base UI 1.7 and Lucide 1.31, with Nerio-owned types and the Github adapter preserved | Review consumer overrides or resolutions; normal consumers should use the coordinated Nerio manifests. |
| Editable source | Version-aligned stable Registry content may produce a non-empty source diff | Run doctor, diff, and update --dry-run before writing, and preserve local ownership. |
After stable is publicly verified, upgrade every Nerio package already used by the consumer to 1.0.0 in one change. Do not mix stable and beta package versions.
pnpm add @nerio-ui/tokens@1.0.0 @nerio-ui/adapters@1.0.0 @nerio-ui/ui@1.0.0 tailwindcsspnpm add -D @tailwindcss/postcss postcsspnpm installpnpm typecheckpnpm buildThe supported baseline remains Node.js 22 or 24, React 19, Next.js 16.2, TypeScript 5.9, and Tailwind CSS 4.1 or newer within v4. Consumers with dependency overrides should review their Base UI and Lucide pins; normal consumers should use the coordinated Nerio manifests.
Read the complete beta.1-to-stable migration guide.
Beta.0 to beta.1 changes
This historical step still applies to consumers on beta.0. Complete it before following the stable transition above.
| Area | What changed | Required action |
|---|---|---|
| Runtime support | Node.js 22 or 24 and Tailwind CSS 4.1 or newer | Update the consumer toolchain before installing the coordinated packages. |
| Calendar and DatePicker | Deterministic initial month and current-day behavior | Pass a consumer-owned today value when the product needs the current month or day marker. |
| Interactive types | Nerio-owned event and state contracts | Replace Base UI type imports and use stable string values for Tabs. |
| Registry | Source integrity and HTTPS-first remote access | Use HTTPS for production registries and declare SHA-256 integrity for custom sources. |
| CLI updates | Atomic source and lock-file transactions | Run doctor, diff, and update --dry-run before applying an editable-source update. |
| MCP | Declared output schemas and structuredContent | Prefer structured output when supported; existing JSON text consumers remain compatible. |
Read the detailed beta.0-to-beta.1 migration guide.
Editable source installs
After publication, update the local Registry and CLI together. Inspect the complete source plan before writing. Unchanged files can advance automatically; a normal update preserves locally modified files so the product owner can port that intent onto the new upstream source.
pnpm add -D @nerio-ui/registry@1.0.0 @nerio-ui/cli@1.0.0pnpm exec nerio doctorpnpm exec nerio diffpnpm exec nerio update --dry-runpnpm exec nerio updatepnpm exec nerio diffHuman evidence boundary
The bounded maintainer-run smoke in issue #143 records the bounded smoke as release-ready for the exact stable candidate. Any P0/P1 or accepted stable-blocking defect found before publication still stops the release.
The broad 22-scenario, eight-environment accessibility and real-device matrix in #585 post-release audit and the independent external-consumer cohort in #146 continue after stable publication. Missing completion of either broad program is not a stable 1.0 publication blocker; findings feed a patch or Core 1.1 as appropriate.
Earlier prerelease consumers
Consumers on beta.0 must first complete the beta.0-to-beta.1 migration. The temporary alpha aliases were removed when the beta baseline was established. If a product still uses alpha packages, begin with the alpha-to-beta migration and then complete the beta and stable transitions in order.
Compatibility contract
Public package exports and types, tokens, Registry data, CLI/MCP contracts, support ranges, and public documentation routes are snapshot-protected. Defaults, DOM and ARIA structure, events, and source-update behavior can also be breaking even when the visual change is small.
Read the complete public API stability policy.