docs(next): keep a webpack Server Component from shipping every Core component

.changeset/next-webpack-optimize-package-imports.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] `astryx docs styling/tokens-and-setup` has a Next.js with webpack section. It shows `experimental.optimizePackageImports: ['@astryxdesign/core']` in `next.config.mjs` and recommends a component entry, such as `@astryxdesign/core/Button`, in Server Components. Without either, a webpack build ships every Astryx client component to a page whose Server Component imports from the package root. The theme preview starter app that `astryx experimental theme preview app` copies has the same setting. No API changes.
+
+@cixzhang

apps/example-nextjs-stylex/next.config.mjs

@@ -1,6 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /** @type {import('next').NextConfig} */
-const nextConfig = {};
+const nextConfig = {
+  // With webpack, a Server Component that imports from the package root
+  // otherwise ships every client component.
+  experimental: {
+    optimizePackageImports: ['@astryxdesign/core'],
+  },
+};
 
 export default nextConfig;

apps/example-nextjs-tailwind/next.config.mjs

@@ -1,6 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /** @type {import('next').NextConfig} */
-const nextConfig = {};
+const nextConfig = {
+  // With webpack, a Server Component that imports from the package root
+  // otherwise ships every client component.
+  experimental: {
+    optimizePackageImports: ['@astryxdesign/core'],
+  },
+};
 
 export default nextConfig;

apps/example-nextjs/README.md

@@ -56,6 +56,21 @@ export function Providers({children}) {
 
 `LinkProvider` wires up Next.js client-side navigation for all Astryx link-based components (Link, Button with href, TopNav, SideNav, Breadcrumbs, TabList).
 
+### 4. Next.js config (webpack builds)
+
+```js
+// next.config.mjs
+const nextConfig = {
+  experimental: {
+    optimizePackageImports: ['@astryxdesign/core'],
+  },
+};
+
+export default nextConfig;
+```
+
+With webpack (`next build --webpack`), a Server Component that imports from the package root would otherwise ship every client component; this keeps first load to what the page uses. In Server Components, also import from the component's own entry, such as `@astryxdesign/core/Button`. Turbopack needs no change.
+
 ## Gotchas
 
 | Issue                         | Symptom                                     | Fix                                         |

apps/example-nextjs/next.config.mjs

@@ -1,6 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /** @type {import('next').NextConfig} */
-const nextConfig = {};
+const nextConfig = {
+  // With webpack, a Server Component that imports from the package root
+  // otherwise ships every client component.
+  experimental: {
+    optimizePackageImports: ['@astryxdesign/core'],
+  },
+};
 
 export default nextConfig;

packages/cli/assets/docs/tree/tokens-and-setup.doc.mjs

@@ -2,7 +2,8 @@
 
 /**
  * @file `astryx docs styling/tokens-and-setup`: using design tokens in custom
- * styles and configuring a StyleX compiler for swizzled components.
+ * styles, configuring a StyleX compiler for swizzled components, and keeping
+ * Next.js webpack builds small.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -14,8 +15,16 @@ export const docs = {
   placement: {parent: 'namespace:styling', slot: 'guides', order: 30},
   category: 'guide',
   description:
-    'Using design tokens in custom styles and configuring a StyleX compiler for swizzled components.',
-  keywords: ['StyleX setup', 'swizzle', 'webpack', 'Vite', 'Next.js'],
+    'Using design tokens in custom styles, configuring a StyleX compiler for swizzled components, and keeping Next.js webpack builds small.',
+  keywords: [
+    'StyleX setup',
+    'swizzle',
+    'webpack',
+    'Vite',
+    'Next.js',
+    'optimizePackageImports',
+    'Server Components',
+  ],
 
   sections: [
     {
@@ -129,5 +138,32 @@ export default stylexPlugin({
         },
       ],
     },
+    {
+      id: 'nextjs-webpack',
+      title: 'Next.js with webpack',
+      content: [
+        {
+          type: 'prose',
+          text: 'If your Next.js app builds with webpack (`next build --webpack`), add `@astryxdesign/core` to `experimental.optimizePackageImports`. With webpack, a Server Component that imports from the package root would otherwise ship every client component; this keeps first load to what the page uses. Turbopack, the default bundler in Next.js 16, needs no change, and the setting is safe to keep there.',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          label: 'next.config.mjs',
+          code: `/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    optimizePackageImports: ['@astryxdesign/core'],
+  },
+};
+
+export default nextConfig;`,
+        },
+        {
+          type: 'prose',
+          text: "In Server Components, also import each component from its own entry, for example `import {Button} from '@astryxdesign/core/Button'`. `{@command component <Name>}` prints that entry. Files that start with `'use client'` are not affected.",
+        },
+      ],
+    },
   ],
 };

packages/cli/assets/preview-app/next.config.mjs

@@ -1,6 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /** @type {import('next').NextConfig} */
-const nextConfig = {};
+const nextConfig = {
+  // With webpack, a Server Component that imports from the package root
+  // otherwise ships every client component.
+  experimental: {
+    optimizePackageImports: ['@astryxdesign/core'],
+  },
+};
 
 export default nextConfig;

packages/cli/test/__golden__/no-icon-set/docs-tree.json

@@ -1240,9 +1240,13 @@
     "type": "docs.detail",
     "sections": [
       "design-tokens",
-      "stylex-setup"
+      "stylex-setup",
+      "nextjs-webpack"
     ],
-    "mentions": []
+    "mentions": [
+      "/** @type {import('next').NextConfig} */\nconst nextConfig = {\n  experimental: {\n    optimizePackageImports: ['@astryxdesign/core'],\n  },\n};\n\nexport default nextConfig;",
+      "If your Next.js app builds with webpack (`next build --webpack`), add `@astryxdesign/core` to `experimental.optimizePackageImports`."
+    ]
   },
   "theme": {
     "type": "docs.detail",

packages/cli/test/__golden__/no-icon-set/search-experimental.json

@@ -3,7 +3,7 @@
   "type": "search",
   "data": {
     "query": "experimental",
-    "matchCount": 3,
+    "matchCount": 4,
     "results": [
       {
         "domain": "doc",
@@ -50,6 +50,22 @@
         "mentions": [
           "docs mention \"experimental\""
         ]
+      },
+      {
+        "domain": "doc",
+        "name": "styling/tokens-and-setup",
+        "package": "@astryxdesign/cli",
+        "score": "<text>",
+        "reason": "<text>",
+        "description": "<text>",
+        "section": "<text>",
+        "title": "<text>",
+        "command": "astryx docs styling/tokens-and-setup nextjs-webpack",
+        "parent": "astryx docs styling/tokens-and-setup --index",
+        "mentions": [
+          "If your Next.js app builds with webpack (`next build --webpack`), add `@astryxdesign/core` to `experimental.optimizePackageImports`.",
+          "description mentions \"experimental\""
+        ]
       }
     ]
   },

packages/cli/test/__golden__/no-icon-set/search-experimental.txt

@@ -1,4 +1,4 @@
-Results for "experimental" (3)
+Results for "experimental" (4)
 name:        authoring/field-reference
 section:     config
 domain:      doc
@@ -16,4 +16,10 @@ section:     template-doc
 domain:      doc
 package:     @astryxdesign/cli
 command:     pnpm exec astryx docs authoring/field-reference template-doc
-parent:      pnpm exec astryx docs authoring/field-reference --index
+parent:      pnpm exec astryx docs authoring/field-reference --index
+name:        styling/tokens-and-setup
+section:     nextjs-webpack
+domain:      doc
+package:     @astryxdesign/cli
+command:     pnpm exec astryx docs styling/tokens-and-setup nextjs-webpack
+parent:      pnpm exec astryx docs styling/tokens-and-setup --index