Publishing

panda lib writes the artifacts. You publish them with npm. The app installs the package and sets designSystem: '@acme/ds'.

pnpm --filter @acme/ds lib
pnpm --filter @acme/ds publish

What must be in the tarball

{
  "name": "@acme/ds",
  "files": ["dist", "styled-system"],
  "publishConfig": {
    "access": "public"
  },
  "scripts": {
    "prepublishOnly": "panda codegen && panda lib"
  },
  "peerDependencies": {
    "@pandacss/dev": "^2.0.0"
  }
}

dist/panda/ has to ship. That is lib.json, preset.mjs, and buildinfo.json. styled-system has to ship if your exports point at it (the default after panda lib).

"files": ["dist"] alone is not enough when codegen writes styled-system/ at the package root. Either add styled-system to files, or set outdir under dist.

export default defineConfig({
  outdir: 'dist/styled-system'
})

Do not add a root panda.buildinfo.json. That was the v1 path.

Do not hand-write styled-system exports

Write "." yourself. Let panda lib add ./panda/*, ./css, ./recipes, ./jsx, and the rest.

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  }
}

If you also ship a stylesheet for apps that do not run Panda, add that export yourself:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./styles.css": "./dist/styles.css"
  }
}

See Consume without Panda.

Peer range

The design system and its apps must run the same Panda major. panda lib stamps that range from @pandacss/dev in peerDependencies, or from --panda. A mismatch fails the consumer with design_system_peer_range_unsatisfied.

panda lib --panda '^2.0.0'

The manifest version field is informational. Panda does not enforce it. Use semver when you rename or remove tokens: major if existing CSS or props change, minor for additions, patch for internal fixes.

Check the tarball

npm pack --dry-run

Confirm you see:

dist/panda/lib.json
dist/panda/preset.mjs
dist/panda/buildinfo.json

and the styled-system files your exports point at. Confirm you do not see .env or a stray src/ you meant to keep private.

If package.json "files" would drop the inferred fallback sources, panda lib warns design_system_files_not_publishable. Pass --files for what you actually publish:

panda lib --files './**/*.{js,mjs}'

See also

• Build a design system
• Consume with Panda
• Troubleshooting