# Migration

> Moving between majors: what the move from 0.x to 1.0 broke and how to make it.

- Page: https://granularity.tech/docs/migration
- Last reviewed: 2026-10-15

**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](https://github.com/efureev/granum/blob/main/docs/ru/migration.md),
[en](https://github.com/efureev/granum/blob/main/docs/en/migration.md)).
Breaking changes within the 0.x line are in the [changelog](/changelog).

## What will appear here by the next major

:::steps
1. **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.
2. **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.
3. **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](/docs/troubleshooting).
4. **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.
5. **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](/docs/versioning)
page.

:::callout{type="info"}
Moving **from another library** is not migration in this sense. The component
maps for it are being prepared on a separate page —
[Migrating from…](/docs/migrating-from).
:::