How to create a tree-shakeable component library with Panda CSS?

[trystendsmyth]

Description

Panda works fantastically in execution my component library. The problem arises when I want to export it with my custom preset. I've tried using tsup and rollup, but both builders have the same problem when I try to tree-shake the resulting dist folder. In both cases I get the following error (where bracketed values are reals paths):

file:///<PROJECT PATH>/ui-components/node_modules/.pnpm/[email protected]/node_modules/rollup/dist/es/shared/node-entry.js:2287
        base = Object.assign(new Error(base.message), base);
                             ^
Error [RollupError]: Could not resolve "../../../styled-system/css/index.js" from "dist/es/components/<COMPONENT>.js"
    at error (file:///<PROJECT PATH>/ui-components/node_modules/.pnpm/[email protected]/node_modules/rollup/dist/es/shared/node-entry.js:2287:30)
    at ModuleLoader.handleInvalidResolvedId (file:///<PROJECT PATH>/ui-components/node_modules/.pnpm/[email protected]/node_modules/rollup/dist/es/shared/node-entry.js:24860:24)
    at file:///<PROJECT PATH>/ui-components/node_modules/.pnpm/[email protected]/node_modules/rollup/dist/es/shared/node-entry.js:24822:26

My tsconfig is as follows:

{
  "compilerOptions": {
    "outDir": "dist/es",
    "declaration": true,
    "declarationMap": true,
    "declarationDir": "dist/types",
    "target": "es2018",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "allowSyntheticDefaultImports": true,
    "downlevelIteration": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "sourceMap": true,
    "plugins": [
      {
        "name": "next",
      },
    ],
    "paths": {
      "@assets/*": ["./src/assets/*"],
      "@components/*": ["./src/components/*"],
      "@stories/*": ["./src/stories/*"],
      "@styled/*": ["./styled-system/*"],
    },
  },
  "include": ["./src/**/*.ts", "./src/**/*.tsx", "./types/*.ts"],
  "exclude": ["node_modules"],
}

And my Panda config looks like this:

import { defineConfig } from '@pandacss/dev';
import { customPreset } from './src/presets';

export default defineConfig({
  // Whether to use css reset
  preflight: true,
  // Minify the generated css
  minify: true,
  // Hash all classnames
  hash: true,
  // Clean the output directory before generating the css
  clean: true,

  importMap: '@styled',

  // Where to look for your css declarations
  include: ['./src/**/*.{js,jsx,ts,tsx}'],

  // Files to exclude
  exclude: [],

  // Styling conditions / modes
  conditions: {
    light: '[data-color-mode=light] &',
    dark: '[data-color-mode=dark] &',
  },

  // Use preset
  presets: ['@pandacss/dev/presets', customPreset],

  // Useful for theme customization
  theme: {
    extend: {},
  },

  // The output directory for your css system
  outdir: 'styled-system',

  // Output extension impacting build
  outExtension: 'js',

  // The JSX framework to use
  jsxFramework: 'react',

  globalCss: {
    html: {
      fontFamily: "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",
    },
  },
});

An example of my tsup.config.ts:

import { defineConfig } from 'tsup';

export default defineConfig(options => {
  const prod = options.env?.NODE_ENV === 'production';

  return {
    bundle: false,
    clean: true,
    dts: prod,
    format: ['cjs', 'esm'],
    entry: ['src/index.ts', 'src/presets.ts'],
    minify: !options.watch,
    skipNodeModulesBundle: true,
    sourcemap: true,
    splitting: true,
    treeshake: true,
    watch: !prod,
    metafile: true,
    external: ['@pandacss/dev', 'react'],
  };
});

Link to Reproduction

can provide more if needed

Steps to reproduce

1. Create component with something like import { css } from '@styled/css';
2. Build component library with tsup or rollup, etc.
3. Run tree shaking tool on dist result.
4. See error

JS Framework

React

Panda CSS Version

0.27.3

Browser

No response

Operating System

• macOS
• Windows
• Linux

Additional Information

No response

[segunadebayo]

It would be great to see an actual reproduction; a GitHub or Stackblitz will do.

[trystendsmyth]

@segunadebayo here is an example https://stackblitz.com/edit/pandacss-2146
It installs and builds correctly, but only because esbuild does not know what to do with @styled/css imports. If I was to try and use the component is an app, it would say Module not found: Can't resolve '@styled/css'. So how can I properly have my component library using Panda with a preset and have a consuming app do the same?

[segunadebayo]

Checking this out. Will get back to you shortly.

[segunadebayo]

After reading through this again, I see what you mean.

Here's how to resolve this:

1. Mark as external

In the library code, mark @styled (not styled-system) as external in rollup or tsup so it doesn't convert or resolve the import path.

For Rollup

// rollup.config.ts

export default {
   // ...
   external: [...builtins, /@styled/],
}

For TSUP

// tsup.config.ts

export default defineConfig({
    // ...,
    external: ['@styled']
})

2. Resolve the external module

In the consuming application, you must resolve the external @styled module for things to work as expected. Depending on the framework you're using, you need to set up a resolve.alias

For Next.js or Webpack

// next.config.js

const nextConfig = {
  webpack: (config) => {
    config.resolve.alias['@styled'] = path.resolve(__dirname, 'styled-system')
    return config
  },
}

module.exports = nextConfig

For Vite

// vite.config.ts

export default defineConfig({
  resolve: {
    alias: {
      '@styled': path.resolve(__dirname, 'styled-system')
    },
  },
  plugins: [react()]
})

3. Ensure consistent preset

The consuming application must use the same preset as the library code since the codegen depends on that.

Of course, you can extend the preset in the application code to include more tokens, etc.

// panda.config.ts

export default defineConfig({
   // ...
    presets: ['INSERT_PRESETS_HERE']
})

Hope this helps.

[trystendsmyth]

@segunadebayo thank you so much for your response! I appreciate your time. A couple of observations trying this:

• If we use a swc plugin, and it resolves the paths properly, we get something like ../../../styled-system/css/index.js for the import resolution. In that case we'd have to have /styled-system/ regexp in the externals. How would we resolve this without the generated style folder in dist?
• We're using NextJS 14 as the consuming app, but unfortunately your suggested webpack config does not work. I've tried plain string and regexp, but I get the following error:

./node_modules/.pnpm/file+..+ui-components_@[email protected][email protected][email protected]/node_modules/ui-components/dist/es/components/feedback/loading-spinner.js:1:0
Module not found: Can't resolve '@styled/css'

https://nextjs.org/docs/messages/module-not-found

Any other suggestions? Thank you!

[trystendsmyth]

@segunadebayo I have an update. After a lot of trial and error, there is a solution.

1. I had to use esbuild in Rollup, as everything else I tried would try to resolve Panda paths to use the local styled system.
2. I appear to need both the preset AND panda.buildinfo.json for styles to work. Just the preset is not enough apparently.
3. This is the external module resolution that was needed to work with NextJS:

 webpack: config => {
    config.resolve.alias = {
      ...config.resolve.alias,
      '@styled': path.resolve(__dirname, 'styled-system'),
    };

    return config;
  },

I'm glad to have this working, but I have to admit that this implementation is somewhat clunky and isn't represented well in your documentation. Any other suggestions? Thank you.