alouette
alouette-migration
Upgrade an app to a newer alouette. Each major has a reference listing its breaking changes with before/after code, then what changed within that major without breaking (deprecations to migrate ahead of the next one, recommended replacements). Apply them in order from the installed version to the target, never skipping one. alouette-codemod rewrites the mechanical part (the removed Surface and stacks); the rest is by hand, guided by the type errors and by the screens a changed appearance names. Load when bumping alouette or alouette-icons, fixing type errors or console warnings after an upgrade, running alouette-codemod, or replacing a removed component, prop, variant or token (Surface, HStack, VStack, EditableSurface, a contained, ghost or list variant).
alouette — Migration
Upgrade, one major at a time
- Read the installed version (the app's lockfile, or node_modules/alouette/package.json) and the target.
- Open every reference from the installed major to the target, in order, and apply each section above the target version. Going from 22 to 24 is 22.md's "Within 22.x", then 23.md, then 24.md: a later major assumes the earlier one done (23 removes what 22 deprecated, and its codemod only knows the 22 names).
- Bump the peers a section names with alouette (alouette-icons in 24, nativewind and react-native-css in 22.x), and regenerate a custom palette when a section says so: a palette generated by an older alouette/theme-generator keeps the old token names.
- Run the app's type check. A removed or renamed export, prop or variant is a type error; a changed appearance is not, so review the screens each "Changed appearance" list names.
| Upgrading to | Reference | In short |
|---|---|---|
| 19.0.0 | 19.md | the $ spacing and text-size tokens become classes |
| 22.x | 22.md | NativeWind rc; Surface, the stacks and EditableSurface deprecated (codemod) |
| 23.0.0 | 23.md | tonal button material, variants renamed, deprecated aliases removed, tokens renamed, palette regen |
| 24.0.0, 24.x | 24.md | FormItem render params, one alouette-icons module per glyph; DecisionBar recommended |
| 25.0.0 | 25.md | system theme resolved in CSS: palette regen, pass the preference to ScopedTheme as is |
Codemod
npx alouette-codemod surface-and-stacks --dry-run src
npx alouette-codemod surface-and-stacks srcRun it from the app with typescript installed, then the formatter and the linter. It prints a file:line warning for what it leaves to you (a dynamic size on a Surface, spread props, a re-export): options and warnings in 22.md.
Source: packages/alouette/bin/alouette-codemod.mjs; bin/codemods/surface-and-stacks.mjs
Common Mistakes
HIGH Skipping a major
Wrong: bumping from 22 to 24 and fixing only what 24.md lists.
Correct: apply 22.x's deprecations, then 23, then 24. The 23 removals are type errors only where the app used the removed names; the renamed variants and tokens of 23 written as strings (className, a variant held in a variable) type-check and silently lose their styling.
HIGH Mapping every contained to filled
Wrong: a search-and-replace of variant="contained" to variant="filled".
Correct: filled is the one action that must dominate; every other button drops its variant and takes the tonal default, and the secondary action of a pair is accent="neutral" variant="soft". The full mapping is in 23.md.
Source: packages/alouette/src/ui/actions/PressableBox.tsx
MEDIUM Keeping a palette generated by the previous major
Wrong: upgrading alouette and keeping the committed palette.css and themeVariables.ts.
Correct: rerun the app's writeTheme build script when a reference says the palette changed (23.0.0 renamed the interactive tokens, so an old palette has no ground for any button).
Source: packages/alouette/src/theme-generator/writeTheme.ts