@commercetools/nimbus-mcp 3.0.0 → 3.1.0

package/data/docs/routes/components-utilities-region.json

@@ -0,0 +1,265 @@
+{
+  "meta": {
+    "id": "Components-Region",
+    "title": "Region",
+    "exportName": "Region",
+    "description": "A headless primitive for named content projection — render content into a named region elsewhere in the layout while it stays in your React tree.",
+    "lifecycleState": "Beta",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/region/region.mdx",
+    "menu": [
+      "Components",
+      "Utilities",
+      "Region"
+    ],
+    "route": "components/utilities/region",
+    "tags": [
+      "component",
+      "utility",
+      "portal",
+      "layout",
+      "provider"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "When to use",
+        "href": "#when-to-use",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "When not to use",
+        "href": "#when-not-to-use",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Anatomy",
+        "href": "#anatomy",
+        "depth": 2,
+        "numbering": [
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Example",
+        "href": "#example",
+        "depth": 2,
+        "numbering": [
+          1,
+          5
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nRegion is a headless primitive for **named content projection**: render content\ninto a slot somewhere else in the layout — an aside, a toolbar, a detail pane —\nfrom a component that lives somewhere else entirely, even a different package.\n\nIt is the structured form of `createPortal`. You **place a target** with\n`<Region name=\"…\" />` to mark where a region renders, and **fill it** from\nanywhere with `useRegion(name)`. Projected content paints at the target but stays\na child of its author in the React tree, so all ancestor context — routing, intl,\ndata clients, permissions — is preserved. A target can also publish a **value**\n(typically control callbacks plus state), so its host can hand consumers a way to\ndrive it.\n\nThe scope, `Region.Provider`, is mounted **ambiently inside `NimbusProvider`**, so\nin a Nimbus app you place targets and call `useRegion` without ever wrapping a\nprovider yourself.\n\nRegion renders no visual chrome of its own; it is a coordination primitive, not\na styled component.\n\n## When to use\n\n- A shell or layout owns a slot (a side panel, a header action area) that a\n  feature elsewhere needs to fill.\n- Content must be **authored** deep in the tree (to keep its context) but\n  **rendered** at a fixed location.\n- A target's host wants to expose controls (open/close, select) to whoever fills\n  it, without prop-drilling.\n\nFor a user-resizable two-pane layout, compose Region with\n[Splitter](/components/layout/splitter): mount the splitter, put a\n`<Region name=\"…\" />` in the aside, and let a consumer fill it and toggle it — see\nthe implementation tab.\n\n## When not to use\n\n- You own both the content and its location and they're in the same place — just\n  render it directly.\n- You need overlay portalling (modals, tooltips, popovers) — those are handled\n  by the overlay components, not Region.\n\n## Anatomy\n\n- **`<Region name=\"…\" />`** — the **target**: marks where a named region renders\n  and registers its DOM node. It is layout-transparent (`display: contents`), so\n  projected content lays out as a direct child of the target's parent — no extra\n  wrapper box. Backed by a `chakra.div`, so it accepts style props; pass\n  `display=\"block\"` (etc.) if you want it to be a real box. Can publish a `value`.\n- **`useRegion(name)`** — returns a stable `Region` portal component to fill the\n  named region, plus the `value` its target published. Resolves safely (`null`\n  value, portal renders nothing) before a target mounts.\n- **`Region.Provider`** — the scope. Mounted ambiently by `NimbusProvider`;\n  reuses an ancestor's scope when nested, so you rarely write it directly.\n\nNote the two sides share the name `Region`: the top-level `<Region name>` is the\n**target**, while the `Region` you get from `useRegion` is the **filler**. Place\nwith the former, fill with the latter.\n\n## Example\n\n```jsx live-dev\nconst Sidebar = () => {\n  // fill the region — `Region` here is the filler from the hook\n  const { Region: Filler } = useRegion(\"docs-sidebar\");\n  return (\n    <Filler>\n      <Box p=\"300\" bg=\"teal.3\">\n        Authored over here, painted in the target over there.\n      </Box>\n    </Filler>\n  );\n};\n\nconst App = () => (\n  // No Region.Provider needed — NimbusProvider supplies the scope ambiently.\n  <Stack direction=\"row\" gap=\"400\">\n    <Box flexGrow=\"1\" p=\"300\" bg=\"amber.3\">\n      <Text>Content area</Text>\n      <Sidebar />\n    </Box>\n    <Box width=\"240px\" minHeight=\"120px\" bg=\"neutral.3\" p=\"200\">\n      <Region name=\"docs-sidebar\" />\n    </Box>\n  </Stack>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nRegion is a headless primitive for **named content projection**: render content\ninto a slot somewhere else in the layout — an aside, a toolbar, a detail pane —\nfrom a component that lives somewhere else entirely, even a different package.\n\nIt is the structured form of `createPortal`. You **place a target** with\n`<Region name=\"…\" />` to mark where a region renders, and **fill it** from\nanywhere with `useRegion(name)`. Projected content paints at the target but stays\na child of its author in the React tree, so all ancestor context — routing, intl,\ndata clients, permissions — is preserved. A target can also publish a **value**\n(typically control callbacks plus state), so its host can hand consumers a way to\ndrive it.\n\nThe scope, `Region.Provider`, is mounted **ambiently inside `NimbusProvider`**, so\nin a Nimbus app you place targets and call `useRegion` without ever wrapping a\nprovider yourself.\n\nRegion renders no visual chrome of its own; it is a coordination primitive, not\na styled component.\n\n## When to use\n\n- A shell or layout owns a slot (a side panel, a header action area) that a\n  feature elsewhere needs to fill.\n- Content must be **authored** deep in the tree (to keep its context) but\n  **rendered** at a fixed location.\n- A target's host wants to expose controls (open/close, select) to whoever fills\n  it, without prop-drilling.\n\nFor a user-resizable two-pane layout, compose Region with\n[Splitter](/components/layout/splitter): mount the splitter, put a\n`<Region name=\"…\" />` in the aside, and let a consumer fill it and toggle it — see\nthe implementation tab.\n\n## When not to use\n\n- You own both the content and its location and they're in the same place — just\n  render it directly.\n- You need overlay portalling (modals, tooltips, popovers) — those are handled\n  by the overlay components, not Region.\n\n## Anatomy\n\n- **`<Region name=\"…\" />`** — the **target**: marks where a named region renders\n  and registers its DOM node. It is layout-transparent (`display: contents`), so\n  projected content lays out as a direct child of the target's parent — no extra\n  wrapper box. Backed by a `chakra.div`, so it accepts style props; pass\n  `display=\"block\"` (etc.) if you want it to be a real box. Can publish a `value`.\n- **`useRegion(name)`** — returns a stable `Region` portal component to fill the\n  named region, plus the `value` its target published. Resolves safely (`null`\n  value, portal renders nothing) before a target mounts.\n- **`Region.Provider`** — the scope. Mounted ambiently by `NimbusProvider`;\n  reuses an ancestor's scope when nested, so you rarely write it directly.\n\nNote the two sides share the name `Region`: the top-level `<Region name>` is the\n**target**, while the `Region` you get from `useRegion` is the **filler**. Place\nwith the former, fill with the latter.\n\n## Example\n\n```jsx live-dev\nconst Sidebar = () => {\n  // fill the region — `Region` here is the filler from the hook\n  const { Region: Filler } = useRegion(\"docs-sidebar\");\n  return (\n    <Filler>\n      <Box p=\"300\" bg=\"teal.3\">\n        Authored over here, painted in the target over there.\n      </Box>\n    </Filler>\n  );\n};\n\nconst App = () => (\n  // No Region.Provider needed — NimbusProvider supplies the scope ambiently.\n  <Stack direction=\"row\" gap=\"400\">\n    <Box flexGrow=\"1\" p=\"300\" bg=\"amber.3\">\n      <Text>Content area</Text>\n      <Sidebar />\n    </Box>\n    <Box width=\"240px\" minHeight=\"120px\" bg=\"neutral.3\" p=\"200\">\n      <Region name=\"docs-sidebar\" />\n    </Box>\n  </Stack>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use",
+          "href": "#when-to-use",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When not to use",
+          "href": "#when-not-to-use",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Anatomy",
+          "href": "#anatomy",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Example",
+          "href": "#example",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Region, useRegion, type RegionProps } from \"@commercetools/nimbus\";\n```\n\n### Mental model\n\n`Region` is the structured form of `createPortal`. Three pieces:\n\n- **`<Region name=\"…\" />`** — the **target**: marks where a named region renders.\n  It registers its DOM node under `name` and can publish a `value` (control\n  callbacks + state) for consumers.\n- **`useRegion(name)`** — returns `{ Region, value }`: a stable `Region` portal\n  component to **fill** the target, and the published `value`.\n- **`Region.Provider`** — the scope. **Mounted ambiently by `NimbusProvider`**, so\n  in a Nimbus app you never write it: place targets and call `useRegion`\n  directly. It is still exported for standalone use (tests, non-Nimbus roots).\n\nRegions are addressed by **name**, not by tree position — a consumer reaches a\nregion by name regardless of how deeply nested it is. `useRegion` resolves to a\n`null` value (and a portal that renders nothing) before a target mounts, so it is\nalways safe to call.\n\n> **One name, two sides.** The top-level `<Region name>` is the *target*; the\n> `Region` returned by `useRegion` is the *filler*. They can't share a binding in\n> one scope — alias the hook's: `const { Region: Sidebar } = useRegion(\"x\")`.\n\n> **Single occupancy.** A region name is one-to-one on both sides: **exactly one\n> target** and **at most one active filler** at a time. Two targets sharing a name\n> orphan one another (only the last to mount holds the slot); two fillers stack\n> their content into the one target in an undefined order. Both are bugs, so in\n> development each logs a `console.error` naming the region. The fix is always the\n> same — give each its own name. (The registry also releases a target's slot\n> owner-checked, so a stale duplicate unmounting never wipes the live region.)\n\n### Basic usage\n\nContent rendered through the `Region` filler paints at the target but stays a\nchild of its author in the React tree, so all ancestor context (router, intl,\ndata client, permissions) is preserved.\n\n```jsx live-dev\nconst Sidebar = () => {\n  const { Region: Filler } = useRegion(\"getting-started-sidebar\");\n  return (\n    <Filler>\n      <Box p=\"300\" bg=\"teal.3\">\n        Authored here, painted in the target.\n      </Box>\n    </Filler>\n  );\n};\n\n// No Region.Provider — NimbusProvider supplies the scope ambiently.\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Box flexGrow=\"1\" p=\"300\" bg=\"amber.3\">\n      <Text>Content area</Text>\n      <Sidebar />\n    </Box>\n    <Box width=\"240px\" minHeight=\"120px\" bg=\"neutral.3\" p=\"200\">\n      <Region name=\"getting-started-sidebar\" />\n    </Box>\n  </Stack>\n);\n```\n\n## Layout: the target renders no box (`display: contents`)\n\nA portal needs a real DOM node as its container — there is no API to portal \"into\na position.\" So `<Region name>` must render *an* element. But it renders that\nelement with **`display: contents`**, which makes the element generate **no box of\nits own**: its children participate in the layout of the target's *parent*, as if\nthe wrapper were not there. Since projected content are DOM children of that\nelement, they lay out exactly where the target sits — a flex/grid parent treats\nthe projected root as a direct child. You get precise layout with no extra wrapper.\n\nConsequences worth knowing:\n\n- A `display: contents` element can't carry its own visual box — no background,\n  padding, border, `position: relative`, or scroll container. Put those on the\n  **projected content** (or the target's parent) instead.\n- The target is a `chakra.div`, so it accepts style props. To make it a real box\n  again, override the display: `<Region name=\"x\" display=\"block\" p=\"400\" />`.\n\n## Publishing a value\n\nA target can publish a `value` so its host hands consumers a way to drive it —\ntypically control callbacks plus reactive state. Consumers read it from\n`useRegion(name).value`.\n\n```tsx\n// host: publish controls on the target\n<Region name=\"detail\" value={{ isOpen, open, close }} />;\n\n// consumer: read them\nconst { value } = useRegion<DetailControls>(\"detail\");\nvalue?.open();\n```\n\nType the value at the consumer boundary with `useRegion<T>` — the registry treats\nit as opaque, so the generic is where the shape is declared.\n\n## Composition: a shell-owned side panel (with Splitter)\n\n`Region` composes with [Splitter](/components/layout/splitter) to build a\nshell-owned, remotely-controlled side panel — **without the Splitter depending on\nRegion**. The shell mounts the splitter, puts a `<Region name>` in the aside that\npublishes the collapse controls, and drives the splitter through its existing\ncontrolled `collapsed` / `onCollapsedChange`. A consumer anywhere fills the pane\nand opens/closes it via `useRegion`.\n\n```tsx\nconst ShellSidePanel = ({ children }) => {\n  const [open, setOpen] = useState(false);\n\n  // Stable callbacks; value memoized on the reactive bit (see Performance below).\n  const commands = useRef({\n    expand: () => setOpen(true),\n    collapse: () => setOpen(false),\n    toggle: () => setOpen((o) => !o),\n  }).current;\n  const controller = useMemo(\n    () => ({ isCollapsed: !open, ...commands }),\n    [open, commands]\n  );\n\n  return (\n    <Splitter.Root collapsible collapsed={!open} onCollapsedChange={(c) => setOpen(!c)}>\n      <Splitter.Main>{children}</Splitter.Main>\n      <Splitter.Handle />\n      <Splitter.Aside>\n        <Region name=\"app-side-panel\" value={controller} />\n      </Splitter.Aside>\n    </Splitter.Root>\n  );\n};\n\n// A consumer that owns no splitter markup:\nconst SidePanel = ({ panel }) => {\n  const { Region: Aside, value } = useRegion(\"app-side-panel\");\n  const expand = value?.expand;\n  const collapse = value?.collapse;\n  useEffect(() => {\n    expand?.();\n    return () => collapse?.();\n  }, [expand, collapse]);\n  return <Aside>{panel}</Aside>;\n};\n```\n\n## Performance\n\n`Region.Provider` wraps the entire application (it's inside `NimbusProvider`), so\nfilling a region must not re-render the app. That holds because of four things —\none in the primitive, three at your call site:\n\n1. **External store (primitive).** The registry is read via\n   `useSyncExternalStore`. Publishing a node or value notifies only that name's\n   consumers; `Region.Provider` itself never re-renders.\n2. **Stable `children` (host).** Pass the app through as a `children` prop so the\n   host's own state changes (e.g. a collapse toggle) bail out of the app subtree\n   rather than re-rendering it.\n3. **Stable callbacks + memoized value (host).** Keep published callbacks\n   ref-backed so their identity never changes, and `useMemo` the value object on\n   its reactive field. Registering then only churns when something meaningful\n   changes.\n4. **Depend on the callbacks, not the value object (consumer).** A published\n   value object changes identity when its reactive state changes. In effects,\n   depend on the stable callbacks (`value?.expand`), not the whole `value` —\n   otherwise an expand-on-mount effect re-runs on every state change and can\n   ping-pong.\n\n## SSR\n\n`useRegion` and the `Region` filler use a server snapshot of `null`: there are no\ntargets during server rendering and `createPortal` is client-only. A region\ntherefore resolves to nothing on the server and hydrates on the client. Author\ncontent unconditionally and let the portal render it once the target mounts.\n\n## Nested providers share one namespace\n\n`Region.Provider` reuses an ancestor's registry when nested — it does not create\nan isolated scope. Two targets with the same name collide even if they live under\ndifferent `Region.Provider` wrappers. If you need logical isolation between\nsubsystems, use a naming convention (e.g. `\"app-shell:sidebar\"` vs\n`\"admin:sidebar\"`).\n\n## When not to use\n\n- You own both the content and its location and they're co-located — render it\n  directly.\n- You need overlay portalling (modals, tooltips, popovers) — use the overlay\n  components, not `Region`.\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Mental model",
+          "href": "#mental-model",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Layout: the target renders no box (display: contents)",
+          "href": "#layout-the-target-renders-no-box-display-contents",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Publishing a value",
+          "href": "#publishing-a-value",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Composition: a shell-owned side panel (with Splitter)",
+          "href": "#composition-a-shell-owned-side-panel-with-splitter",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Performance",
+          "href": "#performance",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "SSR",
+          "href": "#ssr",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Nested providers share one namespace",
+          "href": "#nested-providers-share-one-namespace",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When not to use",
+          "href": "#when-not-to-use",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}

package/data/docs/routes/home-getting-started-bundler-plugins.json

@@ -0,0 +1,248 @@
+{
+  "meta": {
+    "id": "Home-BundlerPlugins-1749667200000",
+    "title": "Bundler Plugins",
+    "description": "Webpack and Vite plugins for optional Nimbus dependency resolution",
+    "order": 7,
+    "repoPath": "packages/nimbus/src/docs/home-bundler-plugins.mdx",
+    "menu": [
+      "Home",
+      "Getting Started",
+      "Bundler Plugins"
+    ],
+    "route": "home/getting-started/bundler-plugins",
+    "tags": [
+      "guide",
+      "plugins",
+      "webpack",
+      "vite",
+      "build",
+      "optional-dependency"
+    ],
+    "toc": [
+      {
+        "value": "When to use",
+        "href": "#when-to-use",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Entry points",
+        "href": "#entry-points",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Vite",
+        "href": "#vite",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Webpack",
+        "href": "#webpack",
+        "depth": 2,
+        "numbering": [
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "How detection works",
+        "href": "#how-detection-works",
+        "depth": 2,
+        "numbering": [
+          1,
+          5
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "What gets stubbed",
+        "href": "#what-gets-stubbed",
+        "depth": 2,
+        "numbering": [
+          1,
+          6
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Writing safe shared code",
+        "href": "#writing-safe-shared-code",
+        "depth": 2,
+        "numbering": [
+          1,
+          7
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Guard with a runtime check",
+        "href": "#guard-with-a-runtime-check",
+        "depth": 3,
+        "numbering": [
+          1,
+          7,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Guard with lazy imports",
+        "href": "#guard-with-lazy-imports",
+        "depth": 3,
+        "numbering": [
+          1,
+          7,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Feature flags",
+        "href": "#feature-flags",
+        "depth": 3,
+        "numbering": [
+          1,
+          7,
+          3
+        ],
+        "parent": "root"
+      }
+    ],
+    "icon": "Extension",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# Bundler Plugins\n\nNimbus ships Vite and webpack plugins that let build tools treat\n`@commercetools/nimbus` as an **optional dependency**. When Nimbus is installed,\nthe plugins are no-ops. When it is not installed, they stub every Nimbus import\nso the build succeeds and zero Nimbus code lands in the bundle.\n\n**The plugins solve build errors, not runtime errors.** Stubbed imports resolve\nto `undefined` — any code that renders a Nimbus component or calls a Nimbus\nfunction will fail at runtime unless it is guarded. See\n[Writing safe shared code](#writing-safe-shared-code) for patterns.\n\n## When to use\n\nUse these plugins in **shared build tooling** that produces bundles for\napplications that may or may not depend on Nimbus. Without the plugins, any\n`import … from '@commercetools/nimbus'` in shared code causes a build failure\nfor apps that haven't installed Nimbus.\n\nThe typical scenario: a shared package imports Nimbus components but is consumed\nby both Nimbus-enabled apps and non-Nimbus apps. The plugins let the shared\npackage compile in both environments. The shared code itself is responsible for\nchecking whether Nimbus is available before rendering anything from it.\n\n## Entry points\n\n| Entry point                             | Export                           |\n| --------------------------------------- | -------------------------------- |\n| `@commercetools/nimbus/plugins/vite`    | `UNSAFE_nimbusOptionalDependency`       |\n| `@commercetools/nimbus/plugins/webpack` | `UNSAFE_NimbusOptionalDependencyPlugin` |\n| `@commercetools/nimbus/plugins/stub`    | _(empty CJS module)_             |\n\nAll entry points are standalone — they do **not** import the Nimbus runtime.\n\n## Vite\n\n```ts\n// vite.config.ts\nimport { UNSAFE_nimbusOptionalDependency } from \"@commercetools/nimbus/plugins/vite\";\n\nexport default defineConfig({\n  plugins: [UNSAFE_nimbusOptionalDependency()],\n});\n```\n\nThe plugin runs with `enforce: \"pre\"` so its `resolveId` hook fires before\nVite's default resolver (required in monorepos where Vite would otherwise follow\nthe workspace symlink). Matching imports are redirected via `resolveId` + `load`\nto a virtual CJS module (`module.exports = {}`). The `.cjs` extension on the\nvirtual ID triggers Rolldown's CJS-to-ESM interop, allowing named imports to\nresolve to `undefined` at runtime instead of failing with `MISSING_EXPORT`. No\nphysical file is written to disk.\n\n## Webpack\n\n```js\n// webpack.config.js\nconst {\n  UNSAFE_NimbusOptionalDependencyPlugin,\n} = require(\"@commercetools/nimbus/plugins/webpack\");\n\nmodule.exports = {\n  plugins: [new UNSAFE_NimbusOptionalDependencyPlugin()],\n};\n```\n\nThe plugin accesses webpack's built-in `NormalModuleReplacementPlugin` via\n`compiler.webpack` (webpack 5+). It redirects matching imports to the physical\n`@commercetools/nimbus/plugins/stub` entry point (`module.exports = {}`).\nWebpack's CJS-to-ESM interop is natively lenient — unmatched named imports\nresolve to `undefined` at runtime without a build error.\n\n## How detection works\n\nAt build startup, the plugin calls:\n\n```js\nrequire.resolve(\"@commercetools/nimbus\", { paths: [process.cwd()] });\n```\n\n- **Resolves** → Nimbus is installed. The plugin becomes a **no-op**.\n- **Throws** → Nimbus is not installed. The plugin activates and stubs all\n  matching imports.\n\n`{ paths: [process.cwd()] }` checks from the **application root**, not the\nplugin's own `node_modules`. This matters in monorepos where the build tool may\nhave Nimbus while the app being built does not.\n\nBoth plugins accept a `{ cwd }` option to override detection, and\n`{ UNSAFE_forceStub: true }` to bypass detection entirely — useful when\ndependency hoisting causes Nimbus to resolve from a parent `node_modules` even\nthough the app never declared it.\n\n## What gets stubbed\n\n| Import                                        | Stubbed? |\n| --------------------------------------------- | -------- |\n| `@commercetools/nimbus`                       | Yes      |\n| `@commercetools/nimbus/components/Button`     | Yes      |\n| `@commercetools/nimbus/setup-jsdom-polyfills` | Yes      |\n| `@commercetools/nimbus/plugins/webpack`       | No       |\n| `@commercetools/nimbus/plugins/vite`          | No       |\n| `@commercetools/nimbus/plugins/stub`          | No       |\n| `@commercetools/nimbus/plugins`               | No       |\n| `@commercetools/nimbus-icons`                 | No       |\n| `@commercetools/nimbus-tokens`                | No       |\n\nThe `/plugins` and `/plugins/*` subpaths are excluded to avoid circular\nreplacement.\n\n## Writing safe shared code\n\nWhen stubbing is active, every named import from `@commercetools/nimbus`\n(`Button`, `NimbusProvider`, etc.) is `undefined`. Default and namespace imports\n(`import Nimbus from …` or `import * as Nimbus from …`) resolve to the truthy\n`{}` stub object — guard with individual named imports, not `if (!Nimbus)`.\n\nCode that uses these values without a guard will crash at runtime. The build will not warn you — from the\nbundler's perspective, the import succeeded.\n\n### Guard with a runtime check\n\n```tsx\nimport { Button } from \"@commercetools/nimbus\";\n\nfunction MyAction({ label, onClick }) {\n  // Button is undefined when Nimbus is stubbed out\n  if (!Button) {\n    return <button onClick={onClick}>{label}</button>;\n  }\n  return <Button onPress={onClick}>{label}</Button>;\n}\n```\n\n### Guard with lazy imports\n\n```tsx\nconst NimbusButton = lazy(() =>\n  import(\"@commercetools/nimbus\").then((m) => ({ default: m.Button }))\n);\n\nfunction MyAction({ label, onClick }) {\n  return (\n    <Suspense fallback={<button onClick={onClick}>{label}</button>}>\n      <NimbusButton onPress={onClick}>{label}</NimbusButton>\n    </Suspense>\n  );\n}\n```\n\n### Feature flags\n\nIf your app already has a feature-flag system, gate the entire Nimbus code path\nbehind a flag rather than checking individual imports:\n\n```tsx\nif (flags.nimbusEnabled) {\n  return <NimbusButton onPress={onClick}>{label}</NimbusButton>;\n}\nreturn <button onClick={onClick}>{label}</button>;\n```\n\nThe key principle: **the plugins make the build pass, your code makes the app\nwork.** Any path that touches a Nimbus import must handle the possibility that\nit resolved to `undefined`.\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# Bundler Plugins\n\nNimbus ships Vite and webpack plugins that let build tools treat\n`@commercetools/nimbus` as an **optional dependency**. When Nimbus is installed,\nthe plugins are no-ops. When it is not installed, they stub every Nimbus import\nso the build succeeds and zero Nimbus code lands in the bundle.\n\n**The plugins solve build errors, not runtime errors.** Stubbed imports resolve\nto `undefined` — any code that renders a Nimbus component or calls a Nimbus\nfunction will fail at runtime unless it is guarded. See\n[Writing safe shared code](#writing-safe-shared-code) for patterns.\n\n## When to use\n\nUse these plugins in **shared build tooling** that produces bundles for\napplications that may or may not depend on Nimbus. Without the plugins, any\n`import … from '@commercetools/nimbus'` in shared code causes a build failure\nfor apps that haven't installed Nimbus.\n\nThe typical scenario: a shared package imports Nimbus components but is consumed\nby both Nimbus-enabled apps and non-Nimbus apps. The plugins let the shared\npackage compile in both environments. The shared code itself is responsible for\nchecking whether Nimbus is available before rendering anything from it.\n\n## Entry points\n\n| Entry point                             | Export                           |\n| --------------------------------------- | -------------------------------- |\n| `@commercetools/nimbus/plugins/vite`    | `UNSAFE_nimbusOptionalDependency`       |\n| `@commercetools/nimbus/plugins/webpack` | `UNSAFE_NimbusOptionalDependencyPlugin` |\n| `@commercetools/nimbus/plugins/stub`    | _(empty CJS module)_             |\n\nAll entry points are standalone — they do **not** import the Nimbus runtime.\n\n## Vite\n\n```ts\n// vite.config.ts\nimport { UNSAFE_nimbusOptionalDependency } from \"@commercetools/nimbus/plugins/vite\";\n\nexport default defineConfig({\n  plugins: [UNSAFE_nimbusOptionalDependency()],\n});\n```\n\nThe plugin runs with `enforce: \"pre\"` so its `resolveId` hook fires before\nVite's default resolver (required in monorepos where Vite would otherwise follow\nthe workspace symlink). Matching imports are redirected via `resolveId` + `load`\nto a virtual CJS module (`module.exports = {}`). The `.cjs` extension on the\nvirtual ID triggers Rolldown's CJS-to-ESM interop, allowing named imports to\nresolve to `undefined` at runtime instead of failing with `MISSING_EXPORT`. No\nphysical file is written to disk.\n\n## Webpack\n\n```js\n// webpack.config.js\nconst {\n  UNSAFE_NimbusOptionalDependencyPlugin,\n} = require(\"@commercetools/nimbus/plugins/webpack\");\n\nmodule.exports = {\n  plugins: [new UNSAFE_NimbusOptionalDependencyPlugin()],\n};\n```\n\nThe plugin accesses webpack's built-in `NormalModuleReplacementPlugin` via\n`compiler.webpack` (webpack 5+). It redirects matching imports to the physical\n`@commercetools/nimbus/plugins/stub` entry point (`module.exports = {}`).\nWebpack's CJS-to-ESM interop is natively lenient — unmatched named imports\nresolve to `undefined` at runtime without a build error.\n\n## How detection works\n\nAt build startup, the plugin calls:\n\n```js\nrequire.resolve(\"@commercetools/nimbus\", { paths: [process.cwd()] });\n```\n\n- **Resolves** → Nimbus is installed. The plugin becomes a **no-op**.\n- **Throws** → Nimbus is not installed. The plugin activates and stubs all\n  matching imports.\n\n`{ paths: [process.cwd()] }` checks from the **application root**, not the\nplugin's own `node_modules`. This matters in monorepos where the build tool may\nhave Nimbus while the app being built does not.\n\nBoth plugins accept a `{ cwd }` option to override detection, and\n`{ UNSAFE_forceStub: true }` to bypass detection entirely — useful when\ndependency hoisting causes Nimbus to resolve from a parent `node_modules` even\nthough the app never declared it.\n\n## What gets stubbed\n\n| Import                                        | Stubbed? |\n| --------------------------------------------- | -------- |\n| `@commercetools/nimbus`                       | Yes      |\n| `@commercetools/nimbus/components/Button`     | Yes      |\n| `@commercetools/nimbus/setup-jsdom-polyfills` | Yes      |\n| `@commercetools/nimbus/plugins/webpack`       | No       |\n| `@commercetools/nimbus/plugins/vite`          | No       |\n| `@commercetools/nimbus/plugins/stub`          | No       |\n| `@commercetools/nimbus/plugins`               | No       |\n| `@commercetools/nimbus-icons`                 | No       |\n| `@commercetools/nimbus-tokens`                | No       |\n\nThe `/plugins` and `/plugins/*` subpaths are excluded to avoid circular\nreplacement.\n\n## Writing safe shared code\n\nWhen stubbing is active, every named import from `@commercetools/nimbus`\n(`Button`, `NimbusProvider`, etc.) is `undefined`. Default and namespace imports\n(`import Nimbus from …` or `import * as Nimbus from …`) resolve to the truthy\n`{}` stub object — guard with individual named imports, not `if (!Nimbus)`.\n\nCode that uses these values without a guard will crash at runtime. The build will not warn you — from the\nbundler's perspective, the import succeeded.\n\n### Guard with a runtime check\n\n```tsx\nimport { Button } from \"@commercetools/nimbus\";\n\nfunction MyAction({ label, onClick }) {\n  // Button is undefined when Nimbus is stubbed out\n  if (!Button) {\n    return <button onClick={onClick}>{label}</button>;\n  }\n  return <Button onPress={onClick}>{label}</Button>;\n}\n```\n\n### Guard with lazy imports\n\n```tsx\nconst NimbusButton = lazy(() =>\n  import(\"@commercetools/nimbus\").then((m) => ({ default: m.Button }))\n);\n\nfunction MyAction({ label, onClick }) {\n  return (\n    <Suspense fallback={<button onClick={onClick}>{label}</button>}>\n      <NimbusButton onPress={onClick}>{label}</NimbusButton>\n    </Suspense>\n  );\n}\n```\n\n### Feature flags\n\nIf your app already has a feature-flag system, gate the entire Nimbus code path\nbehind a flag rather than checking individual imports:\n\n```tsx\nif (flags.nimbusEnabled) {\n  return <NimbusButton onPress={onClick}>{label}</NimbusButton>;\n}\nreturn <button onClick={onClick}>{label}</button>;\n```\n\nThe key principle: **the plugins make the build pass, your code makes the app\nwork.** Any path that touches a Nimbus import must handle the possibility that\nit resolved to `undefined`.\n",
+      "toc": [
+        {
+          "value": "When to use",
+          "href": "#when-to-use",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Entry points",
+          "href": "#entry-points",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Vite",
+          "href": "#vite",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Webpack",
+          "href": "#webpack",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "How detection works",
+          "href": "#how-detection-works",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "What gets stubbed",
+          "href": "#what-gets-stubbed",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Writing safe shared code",
+          "href": "#writing-safe-shared-code",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Guard with a runtime check",
+          "href": "#guard-with-a-runtime-check",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Guard with lazy imports",
+          "href": "#guard-with-lazy-imports",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Feature flags",
+          "href": "#feature-flags",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}