Terminal
Terminal/Skill
Guides upgrading a Panda CSS project from v1 to v2 and fixing build breaks that appear after the upgrade.
By Chakra UI
Works with
npx skills add chakra-ui/panda --skill panda-css-migratev2 keeps the authoring API and rewrites the compiler in Rust. Your panda.config.ts carries over. What breaks is mostly
config plumbing, a few CLI flags, and packages that no longer exist.
The full guide is Upgrading to v2. This skill is the ordered path through it. Read the guide for anything below that needs detail.
Check the project can even run v2:
"type": "module", .mjs files, or an ESM-aware bundler.
require('@pandacss/dev') will not work."engines": { "node": ">=22" }.If either fails, fix that first. Nothing else matters until the config loads.
Work in order. Run panda build after each group; failures compound if you batch them.
1. Move every @pandacss/* package to v2 together.
pnpm add -D @pandacss/dev@latest
pnpm add -D @pandacss/postcss@latest # or @pandacss/vite, @pandacss/webpack, @pandacss/rollup
Never mix a v1 package with a v2 one. All packages share one version.
2. Drop imports of packages that no longer exist. Their work moved into @pandacss/compiler: @pandacss/core,
@pandacss/extractor, @pandacss/generator, @pandacss/node, @pandacss/parser, @pandacss/token-dictionary,
@pandacss/is-valid-prop, @pandacss/logger, @pandacss/reporter, and @pandacss/studio. If the project only uses
@pandacss/dev plus a bundler plugin, there's nothing to do.
3. Add presets explicitly. v2 does not auto-inject them. A config without them gets a bare system: no bg or
color utilities, no spacing or font scales, no _hover.
export default defineConfig({
presets: ['@pandacss/preset-base', '@pandacss/preset-panda'],
})
This is the most common "everything is broken after upgrading" cause.
4. Move hooks onto plugins.
// ❌ v1
hooks: { 'parser:before': handler }
// ✅ v2
plugins: [{ name: 'local', hooks: { 'parser:before': { filter: { id: '**/*.{jsx,tsx}' }, handler } } }]
Supported: config:resolved, preset:resolved, parser:before, codegen:prepare, codegen:done, cssgen:done.
Gone: context:created, parser:after, config:change, tokens:created, utility:created, and
parser:before.configure(...). cssgen:done is now observe-only, so it can't rewrite the CSS string.
If you used cssgen:done to strip unused tokens or keyframes, use optimize instead:
optimize: {
removeUnusedTokens: true,
removeUnusedKeyframes: true,
smartCompoundVariants: true,
}
5. Split createStyleContext. It's gone from <outdir>/jsx.
cva) → createRecipeContext → { withContext }sva) → createSlotRecipeContext → { withRootProvider, withProvider, withContext }6. Convert template literal styles to objects. The syntax option, the --syntax init flag, and tagged-template
styling are all removed.
// ❌ v1
const Button = styled.button`
padding: 10px 15px;
`
// ✅ v2
const Button = styled('button', { base: { padding: '10px 15px' } })
Run panda codegen --clean afterwards so the old runtime is regenerated.
7. Replace globalPositionTry. Use theme.positionTry plus the positionTry() factory.
// ✅ v2
theme: {
positionTry: {
bottom: {
top: 'anchor(bottom)'
}
}
}
css({ positionTryFallbacks: positionTry('bottom') })
8. Fix scrollbarWidth. It takes auto | thin | none now, not a sizes token. scrollbarWidth: '4' was always
invalid CSS. A single color token on scrollbarColor moves to scrollbarThumb.
9. Update CLI usage.
panda inspect, panda validate, panda info → panda doctor (add --json for scripts)panda ship → panda lib, and consumers set designSystem in configpanda mcp / panda init-mcp → npx -y @pandacss/mcp--cpu-prof → --profile (writes .panda/trace.json and .panda/timings.json)--silent / --quiet / --verbose → --log-level silent|error|warn|info|debug--max-warnings, --watch-debounce, --trace-output, --trace-file10. Rewire design systems. If the project shipped or consumed a library with panda ship:
// consumer config
export default defineConfig({ designSystem: '@acme/design-system' })
Never put build info in include. Import styles from your local outdir after running panda build.
11. Run the build and read the diagnostics. panda build, then panda doctor. A panda debug dump under
<outdir>/debug shows exactly what the new engine extracted if something looks wrong.
v2 aims for v1 parity. These differences are deliberate, so check them before filing a bug:
borderInlineEndWidth: '0', not
borderInlineEnd: '0'.@layer recipes.compound_variants. Set
optimize.smartCompoundVariants: true to emit only the combinations you use.--translate-x, --blur and friends on every element. v2 registers them
with @property. If you target engines without @property support, set optimize.propertyFallback: true.@media (width >= 48rem). px and em normalize to rem.-webkit-mask-image before mask-image).@property registrations are dropped. If the only thing reading a registered variable is CSS that Panda
never scans, declare it in globalCss too.@media or @supports wrapper are grouped.Class names changed in a few places (typography shorthands, for instance). Don't assert on generated class names.
If the upgrade surfaces one of these, it isn't a regression you introduced:
preset-atlaskit, preset-open-props) and standalone plugins aren't ported. Use the
first-party @pandacss/preset-typography instead of the community typography preset. Its default size is md, not
base.@pandacss/postcss, try the Vite plugin or plain panda build to isolate it before
filing a bug.panda build completes with no diagnostics on a config you didn't have to rewrite.presets is set explicitly, and utilities like bg and conditions like _hover resolve again.@pandacss/core, @pandacss/node, or the other folded packages.hooks key sits at the config root, and no call to createStyleContext survives.