cadence-ui/docs/exec-plans/2026-03-25-storybook-importer-cache.md

Storybook Importer Cache

• Status: completed
• Owner: codex
• Date: 2026-03-25

Goal

Prevent Storybook from serving a stale Vite importer map after story files are added or removed, which currently causes runtime failures like importers[path] is not a function even though the story index already references the new file.

Scope

• In scope:
  • diagnose the mismatch between index.json and the virtual storybook-stories.js importer map
  • update Storybook's Vite cache strategy so story file set changes invalidate the cache
  • verify the runtime importer map and story index agree after the config change
• Out of scope:
  • changing component implementations or Storybook story content
  • broader Storybook architecture changes unrelated to cache invalidation

Constraints

• Keep the repo-local Storybook cache under .artifacts/.
• Prefer invalidating on story file set changes, not on every edit, so normal dev caching remains useful.
• Avoid introducing new package dependencies just to compute a cache key.

Affected Surfaces

• docs/exec-plans/2026-03-25-storybook-importer-cache.md
• apps/docs/.storybook/main.ts

Plan

1. Record the importer/index mismatch and confirm it is cache-related.
2. Derive the Storybook Vite cache directory from the current story file set.
3. Restart Storybook and verify the virtual importer map matches index.json.

Validation

• pnpm dev:docs
• compare http://127.0.0.1:<port>/index.json against http://127.0.0.1:<port>/@id/__x00__virtual:/@storybook/builder-vite/storybook-stories.js

Status Log

• 2026-03-25 15:31 Confirmed a runtime mismatch: index.json references ./src/components/gauge.stories.tsx, but the cached virtual storybook-stories.js importer map does not include it.
• 2026-03-25 15:38 Updated Storybook's Vite cache directory to include a hash of the current story file set so added or removed story files invalidate the cache instead of reusing a stale importer map.
• 2026-03-25 15:42 Restarted Storybook and verified index.json and the virtual importer map both report 47 story import paths, including gauge.stories.tsx and input-group.stories.tsx.
• 2026-03-25 15:47 Verified pnpm harness:validate:docs and pnpm --dir apps/docs run typecheck; also fixed the local revenue-dashboard navigation item typing so docs typecheck returns cleanly.