Migration
Moving between majors: what the move from 0.x to 1.0 broke and how to make it.
The library has had one major transition — from 0.x to 1.0. The public surface — the components, their subpaths, the tokens and the registries — stayed the same as in 0.53. What changed is the pipeline the application builds its CSS with. That is why the move is breaking even though not a single component import changes.
From 0.x to 1.0
| In 0.x | In 1.0 |
|---|---|
peer @feugene/unocss-preset-granular | peer @feugene/granum >=1.0.0 <2.0.0 and the @feugene/granum-engine-wind engine |
uno.config.ts | granum.config.ts; the engine is passed as an instance — engine: windEngine() |
| CSS concatenated in import order | CSS arrives as the virtual:granum.css module in five granum.* layers |
| the browser reset as plain CSS | the reset in a layer: @import '…' layer(reset);, or it overrides the library |
defineGranularComponent, defineGranularProvider | defineGranumComponent, defineGranumProvider from @feugene/granum/contract — for provider authors |
The companions that depend on the core moved to 1.0 on the same day: their core
range is now >=1.0.0 <2.0.0, and it does not match a 0.x core. That is why the
core and the companions are upgraded together. The step-by-step guide is in the
granum documentation
(ru,
en).
Breaking changes within the 0.x line are in the changelog.
What will appear here by the next major
- A map of API changes — what was renamed, what was removed, what changed its default. As a table rather than as prose: prose cannot be searched by a prop name.
- A codemod. Renames are performed by a script rather than by hand: it lives in the repository next to the migration and runs with one command.
- What breaks silently. A separate section for changes that give neither a build error nor a warning — a shifted default, a different resolution order, another ARIA contract. This is the most expensive part of a move and the shortest one in other people’s guides. One such case is already known from 1.0 — a reset outside the layer, see troubleshooting.
- The order of operations for an application that does not upgrade all at once: what can stand side by side, what conflicts, where the compatibility line runs.
- An effort estimate by application size — so that “move now or next quarter” is decided by a number rather than by mood.
Documentation versions
There is one set of documentation, and it describes the 1.x line; the portal keeps no 0.x archive. The version in the header is read from the installed core’s manifest at build time and is never typed by hand — it matches what the portal is built with.
The details of the version policy are on the versioning page.
Moving from another library is not migration in this sense. The component maps for it are being prepared on a separate page — Migrating from….