Getting Started
Migrating to 3.0
3.0 is the only release that removes anything. Everything it removes has been deprecated since 1.1, and the components warn in development. 2.9 is the release candidate: update to it, clear the warnings and the codemod report, and 3.0 is a version bump.
1. Update to 2.9 and run the codemod
npx nexub-migrate src # dry run: report changes
npx nexub-migrate src --write # apply them
npx nexub-migrate src --check # CI: exit 1 if anything is leftnexub-migrate ships in @nexub/tokens. Keep --check in CI until you are on 3.0, so nothing deprecated creeps back in. CSS can’t warn at runtime, so this is the only check for the legacy colour names. Review the diff and run your tests after --write.
2. What 3.0 removes
| Removed | Use instead | Codemod |
|---|---|---|
Banner | Alert, same props (tone, title, icon, action, onClose) | Rewritten |
Callout | Alert (tone, icon) | Rewritten |
Tag | Badge variant="soft" (size and tone carry over) | Rewritten |
StatusPill | Badge variant="soft", with label as children | Rewritten; dot is reported (pass leadingIcon) |
BannerProps, CalloutProps, TagProps, StatusPillProps | AlertProps, BadgeProps | Rewritten |
bannerVariants, calloutVariants, tagVariants, statusPillVariants | alertVariants, badgeVariants | Reported |
Legacy colour names (--color-text-primary, --color-bg-default, --color-success-500 …) | Calm Depth roles (--color-on-surface, --color-surface, --color-success …) | Rewritten; color-mix aliases reported |
// before
<Banner tone="warning" title="Trial ends soon" />
<Tag size="sm" tone="info">Beta</Tag>
<StatusPill tone="success" label="Live" />
// after
<Alert tone="warning" title="Trial ends soon" />
<Badge variant="soft" size="sm" tone="info">Beta</Badge>
<Badge variant="soft" tone="success">Live</Badge>@nexub/react-native keeps its own Banner; nothing changes there.
3. Other 3.0 changes
- rem spacing by default. The rem layer you can opt into today with
@nexub/tokens/css/rembecomes the default. If your app setshtml { font-size: 62.5% }or similar, remove it first, or spacing shrinks with it. Turn the rem layer on while you are on 2.9 to see the effect early. - ESM only. Every package already ships ESM only, so there is nothing to do.