Publishing to npm

What to include in the package, how to version it, and how to check the published output before it ships.

Set up a library package covers creating the styled-system package and its exports map. This page covers what happens after that, actually publishing it so other teams can install it.

Decide what ships

Most packages publish only their built output, not source. Set files in package.json to the built directory so npm publish (or pnpm publish) ignores everything else, source, config, tests, by default:

package.json

{
  "files": ["dist"]
}

The one exception is the build-info approach from Ship the styled-system vs the CSS: if you're shipping a panda.buildinfo.json alongside your compiled output, add it to files too so it actually reaches the registry.

package.json

{
  "files": ["dist", "panda.buildinfo.json"]
}

Scoped packages default to private on npm. If yours is meant to be publicly installable, set publishConfig:

package.json

{
  "name": "@acme/design-system",
  "publishConfig": {
    "access": "public"
  }
}

Version deliberately

A design system's version isn't just a changelog entry, it's the thing users pin against. Renaming a token, changing a recipe's default variant, or reshaping a component's props are breaking changes even if nothing throws a type error, since they change what a user's already-generated CSS expects. Treat these the same as any other public API: major bump for anything that changes what an existing user's code produces, minor for new tokens/recipes/components, patch for internal fixes that don't change output.

This matters more once you're running federated micro-frontends: that guide's cross-version isolation depends on remotes pinning different majors deliberately, not on version bumps being accidental.

If you want version bumps and changelog entries automated rather than hand-rolled, Changesets (opens in a new tab) is a common choice for this, Panda's own monorepo uses it, though it's a general npm tool with no special Panda integration.

Check the published output before it ships

exports map mistakes (the wrong file in files, a types condition listed after import/require, see Troubleshooting) are much cheaper to catch before publishing than after. Both npm and pnpm can build the exact tarball a real publish would upload, without touching the registry:

npm pack --dry-run
# or
pnpm publish --dry-run

Read the file list it prints and confirm nothing you expect is missing, and nothing you didn't mean to publish (a stray src/, a local .env) is there.

Publishing to npm

Decide what ships

Version deliberately

Check the published output before it ships

See also