Optimizing Panda CSS Production Builds: Seeking Input

[kris-ellery]

Hey team 👋

We're exploring a production optimization for our Panda CSS setup and I'd love some feedback.

Current Setup

• We maintain a design system with ~100 Panda CSS components shipped as an NPM package
• The package includes a buildinfo file that consuming apps include in their Panda config
• Issue: When apps include our buildinfo, they generate styles for ALL components, even if they only use a few

Proposed Two-Path Approach

Development Path

Perfect for active development with HMR, watch mode, Storybook, etc:

// panda.config.ts
includes: ['src', './node_modules/library/dist/buildinfo.library.json']

// postcss.config.cjs 
module.exports = { plugins: [require('@pandacss/dev/postcss')()] }

Production Path

Optimized to generate minimal CSS:

// panda.config.ts
includes: ['dist'] // No more 'src' or buildinfo file

// Build process
1. Run normal build (Webpack/Vite/etc.)
2. Run `panda cssgen --outfile dist/styles.css`

Results

Local testing shows significantly smaller CSS output with the production path due to including only the components actually used.

Questions

1. Does this approach make sense architecturally?
2. Are there hidden drawbacks to using dist instead of src/buildinfo for CSS generation?
3. Has anyone implemented something similar?

I understand this introduces a two-step build process that might affect filename hashing or Next.js caching. We'll tackle those separately if this approach is valid.

Thanks for any insights!

[kris-ellery]

Further testing with Next.js showed a roadblock. Panda can read .next directory contents but fails to extract styles from css/cva methods, making this approach potentially unfeasible for Next.js apps.

I wish there was a solution to remove styles coming from unused imports, whether local or through the buildinfo file. The challenge is that the buildinfo file is detached from actual imports, which makes optimization approaches like this even harder.

Is there an alternative to shipping a buildinfo file? My use case is specifically a design system component library that publishes components and presets to an NPM package, which is then consumed by apps that always use Panda CSS to scaffold styled-system and generate the final CSS file. Panda's documentation has a section for component libraries, but none of the solutions seem to address this particular scenario.

[kris-ellery]

In my use case, an app could potentially use 5-10 component libraries, all built with Panda CSS. All of those libraries could potentially add up to 200-300 components, but the consuming app might only use 25-50 of them. We need a build process that only generates styles for the used components. Even with atomic CSS, we have thousands of tokens mapping to thousands of selectors, which makes file size savings a big deal.

[adbutterfield]

I think we have about 150 components in our new design system, and the CSS file is only about 40k minified. We have over 800 tokens, and have been trying hard to avoid complex selectors in order to take advantage of the atomic class paradigm. But even if the size was double or even triple what it is now, that would still only be 120k minified, and cached by the browser after the first load.

We did do a few things we did to trim out some excess, like using pluginMinimalSetup configured with features: ['no-jsx', 'no-styled', 'no-recipes', 'no-patterns'] because we decided not to use any of those features.

We also use removeUnusedCssVars, cssnano with the default preset (which actually didn't remove much), and a custom postcss plugin (because we couldn't find one that works with cascade layers) to merge at-rules (like media queries).

We also use utilities for things that logically go together, for example we have a backgroundColorWithStates utility that handles default/hover/active/disabled styles for interactive things (like button background), and similar ones for text color and border color. It's a better level of abstraction than atomic classes (because the state styles are always used together) with the added benefit of fewer classes on the components.

[kris-ellery]

Hi @adbutterfield, this isn’t an issue related to configuration or how to use Panda. Even if you use the most optimal settings and patterns, Panda will still generate CSS for unused imports if it discovers them in the observed directories and files.

In my case, the design system has to be verbose with tokens and components due to very elaborate theme support, etc. Our unminified CSS sits at 360kB for all components. It gets deflated to ~72kB in production, but thats still way too much. I’ve developed a custom Webpack plugin that reads the final module graph in production and dynamically updates Panda’s include array. This approach forces Panda to only generate the used class names, etc. As a result, our deflated CSS dropped to ~21kB for a particular app I was testing, which only used a subset of components from the design system library.

[kris-ellery]

For reference, our design system has 96 components with 273 sub-components, over 3,000 tokens, and 2 themes with dark mode. It has to support over 100 different products and services.

[adbutterfield]

Even at 72kB I wouldn't worry about it. Still smaller than the average image a website will load.

Of course, always better to not ship unused code though for sure. But then again, I guess when you do add some new components to an app, it means browsers will have to download that new bigger stylesheet, instead of potentially being able to leverage the full one already in cache.

[isBatak]

I think the approach here would be to create a panda css preset for your DS, publish it on the NPM and then use it across the projects.
Here is the example https://github.com/chakra-ui/panda/blob/main/packages/preset-open-props/src/index.ts.

Park UI is using similar approach using the scaffolding function https://github.com/cschroeter/park-ui/blob/main/packages/styled-system/panda.config.ts#L8

[kris-ellery]

Hi @isBatak, my DS already does that. We ship a Panda config wrapper that includes a custom preset and Panda defaults. However, this doesn’t eliminate the issues of a massive final bundle that includes unused CSS.

The issue arises from Panda’s scanning of directories and files, including buildinfo, regardless of whether they are imported into the project or not. I did fix it tho. I’ve developed a custom Webpack plugin that reads the final module graph in production and dynamically updates Panda’s include array. This approach forces Panda to only generate the used class names, etc.