> For AI agents: the complete documentation index is available at https://wallarm.github.io/design-system/llms.txt, the full documentation bundle is available at https://wallarm.github.io/design-system/llms-full.txt.

# Migration guides

Every major release of `@wallarm-org/design-system` has a guide:

- [v4.0.0](https://wallarm.github.io/design-system/get-started/migrations/v4.md): TreeBase is removed.
- [v3.0.0](https://wallarm.github.io/design-system/get-started/migrations/v3.md): Avatar sizes and the user-item composition.
- [v2.0.0](https://wallarm.github.io/design-system/get-started/migrations/v2.md): NumericBadge `type` splits into `type` and `color`.
- [v1.0.0](https://wallarm.github.io/design-system/get-started/migrations/v1.md): Table moves to TanStack Table v9.

Since v2.0.0, every breaking change ships a codemod in [`@wallarm-org/migrator`](https://www.npmjs.com/package/@wallarm-org/migrator)
(v1.0.0 has none). Some codemods only report what to change by hand. Renovate can run it after a design-system upgrade, and you can run it by hand. The
[Storybook upgrade guide](https://wallarm.github.io/design-system/storybook/?path=/docs/documentation-upgrading--overview)
has the same instructions and lists every codemod with its version.

## Run it by hand

After upgrading, run the migrator from the package directory with the version you upgraded from:


```sh [npx]
npx @wallarm-org/migrator --from 2.9.0
```

```sh [yarn]
yarn dlx @wallarm-org/migrator --from 2.9.0
```

```sh [pnpm]
pnpm dlx @wallarm-org/migrator --from 2.9.0
```

```sh [bunx]
bunx @wallarm-org/migrator --from 2.9.0
```

```sh [deno]
deno run -A npm:@wallarm-org/migrator --from 2.9.0
```

## Usage

```bash
migrator --from <version> [--to <version>] [--dry-run] [paths...]
```

- `--from` (required): the exact stable design-system version you are migrating from. A
  prerelease `--from` is rejected: pass the stable version your code matches.
- `--to`: the target version (default: the installed `@wallarm-org/design-system`).
- `--dry-run`: print the changes, write nothing.
- `--help`, `--version`.

Without paths, tracked files under the current directory are scanned. The exit code is `0` for
completed runs (even with manual items) and `1` for usage or version errors.

When something needs a manual change, or a file could not be parsed, the migrator writes
`wds-migration.md` (its heading contains `@wds-migration`), and each manual spot also gets an
in-code marker right after the tag name:

```tsx
<Avatar /* @wds-migration(avatar-size-rename): … */ size={s} />
```

Fix each marker, then delete the report.

## Consumer setup

### Renovate

Add a package rule to the repository config (or to a shared preset):

```json title="renovate.json"
{
  "packageRules": [
    {
      "matchPackageNames": ["@wallarm-org/design-system"],
      "minimumReleaseAge": "1 hour",
      "prBodyNotes": ["⚠️ The design-system migrator may have left manual steps: search this MR for `wds-migration` comments and the `wds-migration.md` report, fix them, then delete the report."],
      "postUpgradeTasks": {
        "commands": ["npx --yes @wallarm-org/migrator@latest --from {{{currentVersion}}} --to {{{newVersion}}}"],
        "fileFilters": ["**/*.{ts,tsx,js,jsx,mts,cts}", "**/wds-migration.md"],
        "workingDirTemplate": "{{{packageFileDir}}}",
        "installTools": { "node": {} }
      }
    }
  ]
}
```

- `workingDirTemplate` runs the migrator from each upgraded `package.json`'s directory, so each
  package runs with its own `--from` and only touches files under it. From the repo root, one
  package's `--from` would rewrite every package (for example, turn an already-migrated `sm` into
  `lg`). In a monorepo each package gets its own `wds-migration.md`, hence the recursive filter.
- `currentVersion` is the **locked** version when a lockfile exists (Renovate has no separate
  `lockedVersion` template), so commit your lockfile.
- `installTools.node` is needed on the default slim Renovate image (`binarySource=install`),
  where `npx` isn't on `PATH`. The `-full` image already has it. With `binarySource=global` the
  runner image has to provide node and npm.
- On a self-hosted runner, allow the command in the admin config:
  `allowedCommands: ["^npx --yes @wallarm-org/migrator@latest --from \\d+\\.\\d+\\.\\d+\\S* --to \\d+\\.\\d+\\.\\d+\\S*$"]`.
- `prBodyNotes` deliberately avoids the literal `@wds-migration`, so the tracked Renovate config
  does not trip the CI check below.

### CI check

Add one job that fails while manual steps remain:

```sh
if git grep -n '@wds-migration'; then echo 'Design-system migration left manual steps: fix the @wds-migration markers and delete wds-migration.md'; exit 1; fi
```

Both the in-code markers and the report heading contain `@wds-migration`, so the job fails (and
prints the hits) until every marker is fixed and `wds-migration.md` is deleted. It works under
`set -e`.