feat: first-class design system support

.changeset/first-class-design-system.md

@@ -0,0 +1,41 @@
+---
+'@pandacss/dev': major
+'@pandacss/node': major
+'@pandacss/types': major
+'@pandacss/config': major
+---
+
+First-class design system support. One config field for consumers (`designSystem`), one CLI command for lib authors (`panda lib`). Works at every level of a chain composition.
+
+**Lib author flow.** `panda lib` produces a complete `dist/`:
+
+- `panda.buildinfo.json` (replaces `panda ship`)
+- `panda.lib.json` (new — design-system manifest)
+- `preset.mjs` (new — compiled preset; consumers no longer need source `.ts` shipped)
+- patched `package.json` exports including `./preset` → `./dist/preset.mjs`
+
+`panda lib --watch` rebuilds on `src/` changes.
+
+**Migration:**
+
+```bash
+# v1
+panda codegen && panda ship && panda emit-pkg
+
+# v2
+panda lib
+```
+
+`panda ship` and `panda emit-pkg` are removed.
+
+**Consumer flow.** Point at the lib via:
+
+```ts
+designSystem: '@acme/ds'
+```
+
+One field replaces the prior `presets` + `importMap` + `outdir` + `include`-with-buildinfo coordination.
+
+**Smart include.** Bare specifiers in `include` resolve via Node module resolution. Libs with a `panda.lib.json` are skipped (manifest carries the buildinfo path); libs without a manifest get auto-globbed via their `package.json#files`.
+
+**Chain composition.** Intermediate libs in a chain use the same `designSystem: '@parent'` declaration — same shape at depth 1 as at depth N.

packages/cli/__tests__/cli.test.ts

@@ -190,31 +190,4 @@ describe('CLI', () => {
     const debugConfigExists = await fs.access(path.resolve(paths.styledSystem, 'debug/config.json'))
     expect(debugConfigExists).toBeUndefined()
   })
-
-  test('ship', async () => {
-    const cmd = `node ${binPath} ship --cwd="${testsCwd}"`
-
-    // ship
-    const output = runCommand(cmd, { cwd: testsCwd })
-    expect(output.includes('files using Panda')).toBe(true)
-
-    // Check that the `styled-system/panda.buildinfo.json` file was created
-    const buildInfoExists = await fs.access(path.resolve(paths.styledSystem, 'panda.buildinfo.json'))
-    expect(buildInfoExists).toBeUndefined()
-  })
-
-  test('emit-pkg', async () => {
-    const cmd = `node ${binPath} emit-pkg --cwd="${testsCwd}"`
-
-    // emit-pkg
-    const output = runCommand(cmd, { cwd: testsCwd })
-    expect(output.includes('Emit package.json')).toBe(true)
-
-    // Check that the `package.json` file was created
-    const pkgExists = await fs.access(paths.pkgJson)
-    expect(pkgExists).toBeUndefined()
-
-    // Clean up
-    await fs.unlink(paths.pkgJson)
-  })
 })

packages/cli/src/cli-main.ts

@@ -3,7 +3,7 @@ import { colors, logger } from '@pandacss/logger'
 import {
   PandaContext,
   analyze,
-  buildInfo,
+  buildLib,
   codegen,
   cssgen,
   debug,
@@ -28,12 +28,11 @@ import type {
   CodegenCommandFlags,
   CssGenCommandFlags,
   DebugCommandFlags,
-  EmitPackageCommandFlags,
   InitCommandFlags,
+  LibCommandFlags,
   MainCommandFlags,
   McpCommandFlags,
   McpInitCommandFlags,
-  ShipCommandFlags,
   SpecCommandFlags,
   StudioCommandFlags,
 } from './types'
@@ -478,39 +477,29 @@ export async function main() {
     })
 
   cli
-    .command('ship [glob]', 'Ship extract result from files in glob')
+    .command('lib', 'Build a panda design-system library — buildinfo + manifest + package exports')
+    .option('--outdir <dir>', 'Output directory for dist artifacts', { default: 'dist' })
+    .option('--preset <path>', 'Path to preset file relative to manifest', { default: '../preset.ts' })
     .option('--silent', "Don't print any logs")
-    .option(
-      '--o, --outfile [file]',
-      "Output path for the build info file, default to './styled-system/panda.buildinfo.json'",
-    )
-    .option('-m, --minify', 'Minify generated JSON file')
+    .option('-w, --watch', 'Watch src/ and rebuild')
+    .option('-p, --poll', 'Use polling instead of filesystem events when watching')
     .option('-c, --config <path>', 'Path to panda config file')
     .option('--cwd <cwd>', 'Current working directory', { default: cwd })
-    .option('-w, --watch', 'Watch files and rebuild')
-    .option('-p, --poll', 'Use polling instead of filesystem events when watching')
-    .action(async (maybeGlob?: string, flags: ShipCommandFlags = {}) => {
-      const { silent, outfile: outfileFlag, minify, config: configPath, watch, poll } = flags
-
-      const cwd = resolve(flags.cwd!)
+    .action(async (flags: LibCommandFlags = {}) => {
+      const { silent, outdir, preset, watch, poll, config: configPath } = flags
 
       if (silent) {
         logger.level = 'silent'
       }
 
+      const cwd = resolve(flags.cwd!)
+
       let ctx = await loadConfigAndCreateContext({
         cwd,
-        config: maybeGlob ? { include: [maybeGlob] } : undefined,
         configPath,
       })
 
-      const outfile = outfileFlag ?? join(...ctx.paths.root, 'panda.buildinfo.json')
-
-      if (minify) {
-        ctx.config.minify = true
-      }
-
-      await buildInfo(ctx, outfile)
+      await buildLib(ctx, { outdir, preset })
 
       if (watch) {
         ctx.watchConfig(
@@ -520,8 +509,8 @@ export async function main() {
             })
 
             await ctx.hooks['config:change']?.({ config: ctx.config, changes: affecteds })
-            await buildInfo(ctx, outfile)
-            logger.info('ctx:updated', 'config rebuilt ✅')
+            await buildLib(ctx, { outdir, preset })
+            logger.info('ctx:updated', 'lib rebuilt ✅')
           },
           { cwd, poll },
         )
@@ -531,109 +520,15 @@ export async function main() {
             ctx.project.removeSourceFile(ctx.runtime.path.abs(cwd, file))
           } else if (event === 'change') {
             ctx.project.reloadSourceFile(file)
-            await buildInfo(ctx, outfile)
+            await buildLib(ctx, { outdir, preset })
           } else if (event === 'add') {
             ctx.project.createSourceFile(file)
-            await buildInfo(ctx, outfile)
+            await buildLib(ctx, { outdir, preset })
           }
         })
       }
     })
 
-  cli
-    .command('emit-pkg', 'Emit package.json with entrypoints')
-    .option('--outdir <dir>', 'Output directory', { default: '.' })
-    .option('--base <source>', 'The base directory of the package.json entrypoints')
-    .option('--silent', "Don't print any logs")
-    .option('--cwd <cwd>', 'Current working directory', { default: cwd })
-    .action(async (flags: EmitPackageCommandFlags) => {
-      const { outdir, silent, base } = flags
-
-      if (silent) {
-        logger.level = 'silent'
-      }
-
-      const cwd = resolve(flags.cwd!)
-
-      const ctx = await loadConfigAndCreateContext({
-        cwd,
-        config: { cwd },
-      })
-
-      const pkgPath = resolve(cwd, outdir, 'package.json')
-      const exists = ctx.runtime.fs.existsSync(pkgPath)
-
-      const exports = [] as any[]
-
-      const createDir = (...dir: string[]) => {
-        return ['.', base, ...dir].filter(Boolean).join('/')
-      }
-
-      const createEntry = (dir: string) => ({
-        types: ctx.file.extDts(createDir(dir, 'index')),
-        require: ctx.file.ext(createDir(dir, 'index')),
-        import: ctx.file.ext(createDir(dir, 'index')),
-      })
-
-      exports.push(
-        ['./css', createEntry('css')],
-        ['./tokens', createEntry('tokens')],
-        ['./types', createEntry('types')],
-      )
-
-      if (!ctx.patterns.isEmpty()) {
-        exports.push(['./patterns', createEntry('patterns')])
-      }
-
-      if (!ctx.recipes.isEmpty()) {
-        exports.push(['./recipes', createEntry('recipes')])
-      }
-
-      if (!ctx.patterns.isEmpty()) {
-        exports.push(['./jsx', createEntry('jsx')])
-      }
-
-      if (ctx.config.themes) {
-        exports.push(['./themes', createEntry('themes')])
-      }
-
-      const stylesDir = createDir('styles.css')
-
-      if (!exists) {
-        //
-        const content = {
-          name: outdir,
-          description: 'This package is auto-generated by Panda CSS',
-          version: '0.1.0',
-          type: 'module',
-          keywords: ['pandacss', 'styled-system', 'codegen'],
-          license: 'ISC',
-          exports: {
-            ...Object.fromEntries(exports),
-            './styles.css': stylesDir,
-          },
-          scripts: {
-            prepare: 'panda codegen --clean',
-          },
-        }
-
-        await ctx.runtime.fs.writeFile(pkgPath, JSON.stringify(content, null, 2))
-        //
-      } else {
-        //
-        const content = JSON.parse(ctx.runtime.fs.readFileSync(pkgPath))
-        content.exports = {
-          ...content.exports,
-          ...Object.fromEntries(exports),
-          './styles.css': stylesDir,
-        }
-
-        await ctx.runtime.fs.writeFile(pkgPath, JSON.stringify(content, null, 2))
-      }
-
-      logger.info('cli', `Emit package.json to ${pkgPath}`)
-    })
-
   cli
     .command('mcp', 'Start MCP server for AI assistants')
     .option('-c, --config <path>', 'Path to panda config file')

packages/cli/src/types.ts

@@ -57,16 +57,6 @@ export interface DebugCommandFlags {
   logfile?: string
 }
 
-export interface ShipCommandFlags {
-  silent?: boolean
-  minify?: boolean
-  outfile?: string
-  cwd?: string
-  config?: string
-  watch?: boolean
-  poll?: boolean
-}
-
 export interface CodegenCommandFlags extends Pick<Config, 'cwd' | 'poll' | 'watch'> {
   clean?: boolean
   silent?: boolean
@@ -75,6 +65,16 @@ export interface CodegenCommandFlags extends Pick<Config, 'cwd' | 'poll' | 'watc
   logfile?: string
 }
 
+export interface LibCommandFlags {
+  silent?: boolean
+  outdir?: string
+  preset?: string
+  config?: string
+  cwd?: string
+  watch?: boolean
+  poll?: boolean
+}
+
 export interface MainCommandFlags extends Pick<Config, 'cwd' | 'poll' | 'watch'> {
   outdir?: string
   minify?: boolean
@@ -91,13 +91,6 @@ export interface MainCommandFlags extends Pick<Config, 'cwd' | 'poll' | 'watch'>
   logfile?: string
 }
 
-export interface EmitPackageCommandFlags {
-  outdir: string
-  silent?: boolean
-  cwd: string
-  base?: string
-}
-
 export interface McpCommandFlags {
   cwd?: string
   config?: string

packages/config/__tests__/fixtures/lib-manifest/broken-buildinfo-pkg/dist/panda.lib.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "name": "@panda-test/broken-buildinfo",
+  "version": "1.0.0",
+  "panda": "^1.0.0",
+  "preset": "./preset.js",
+  "importMap": {},
+  "buildinfo": "./nonexistent.json"
+}

packages/config/__tests__/fixtures/lib-manifest/broken-buildinfo-pkg/dist/preset.js

@@ -0,0 +1 @@
+module.exports = { name: '@panda-test/broken-buildinfo/preset' }

packages/config/__tests__/fixtures/lib-manifest/broken-buildinfo-pkg/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@panda-test/broken-buildinfo",
+  "version": "1.0.0",
+  "private": true,
+  "exports": {
+    "./panda.lib.json": "./dist/panda.lib.json"
+  }
+}

packages/config/__tests__/fixtures/lib-manifest/forward-compat-pkg/dist/panda.lib.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "name": "@panda-test/forward-compat",
+  "version": "1.0.0",
+  "panda": "^1.0.0",
+  "preset": "./preset.js",
+  "importMap": {},
+  "buildinfo": "./panda.buildinfo.json",
+  "futureField": "v2-only-field",
+  "anotherUnknown": { "nested": true }
+}

packages/config/__tests__/fixtures/lib-manifest/forward-compat-pkg/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@panda-test/forward-compat",
+  "version": "1.0.0",
+  "exports": {
+    "./panda.lib.json": "./dist/panda.lib.json",
+    "./panda.buildinfo.json": "./dist/panda.buildinfo.json"
+  }
+}

packages/config/__tests__/fixtures/lib-manifest/incomplete-pkg/dist/panda.lib.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "name": "@panda-test/incomplete"
+}

packages/config/__tests__/fixtures/lib-manifest/incomplete-pkg/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@panda-test/incomplete",
+  "version": "1.0.0",
+  "private": true,
+  "exports": {
+    "./panda.lib.json": "./dist/panda.lib.json"
+  }
+}

packages/config/__tests__/fixtures/lib-manifest/malformed-pkg/dist/panda.lib.json

@@ -0,0 +1 @@
+{ this is not json

packages/config/__tests__/fixtures/lib-manifest/malformed-pkg/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@panda-test/malformed",
+  "version": "1.0.0",
+  "private": true,
+  "exports": {
+    "./panda.lib.json": "./dist/panda.lib.json"
+  }
+}

packages/config/__tests__/fixtures/lib-manifest/newer-version-pkg/dist/panda.lib.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 99,
+  "name": "@panda-test/newer-version",
+  "version": "1.0.0",
+  "panda": "^99.0.0",
+  "preset": "./preset.js",
+  "importMap": {},
+  "buildinfo": "./panda.buildinfo.json"
+}