refactor(FEC-935): tighten pnpm hoisting + Storybook 9 upgrade

[misama-ct]

Summary

FEC-935 drops shamefully-hoist=true from .npmrc in favor of strict pnpm with a single narrow carve-out (public-hoist-pattern[]=@storybook/*), and bundles the Storybook 8.6.18 → 9.1.20 upgrade that structurally resolves the v8 template-stories pickup bug.

What changed

Drop shamefully-hoist (the FEC-935 acceptance criterion)

• .npmrc: shamefully-hoist=true removed; one targeted public-hoist-pattern[]=@storybook/* carve-out documented inline.
• ESLint override for **/docs/** & **/_docs/** so consumer-perspective docs snippets don't require leaf packages to declare framework-level deps.
• 96 per-package phantom-dep additions across 61 workspaces, plus root @types/* for transitives previously resolved by hoisting.
• Manypkg constraint fixes surfaced by the cleanup.
• CONTRIBUTING.md note about git worktree + nested node_modules causing "two copies of React" when the worktree sits inside an installed parent repo.

Bundled: Storybook 8.6.18 → 9.1.20

Rolled in so the strict-pnpm posture lands the way it should look long-term. Storybook 9's flatter dep graph removes the v8-era @storybook/react/template/cli/js/{Button,Page}.jsx files that were tripping the stories glob under strict pnpm.

• storybook/package.json: 8 consolidated packages dropped (essentials, interactions, storysource, blocks, manager-api, react, test, theming → all merged into core in v9); remaining @storybook/* and storybook pinned at 9.1.20.
• 92 *.stories.tsx: type imports @storybook/react → @storybook/react-vite.
• 80 *.readme.mdx: doc-block imports @storybook/blocks → @storybook/addon-docs/blocks.
• manager.ts, theme.ts, decorators, preview.tsx: updated to v9 import paths.
• Stories glob in main.ts anchored to a literal src/ segment so it cannot descend into the nested <pkg>/node_modules/@commercetools-uikit/* symlinks that strict pnpm leaves for workspace deps.

Typecheck regressions surfaced by strict pnpm

Two latent issues — invisible under shamefully-hoist — were exposed when strict pnpm replaced the flat layout with per-package symlinks. Together they caused 273 typecheck errors; both fixed surgically.

• tsconfig.json: preserveSymlinks: true → false. Predated pnpm; harmless under yarn classic flat hoisting. Under strict pnpm every dep is a symlink (node_modules/.pnpm/<pkg>/node_modules/<pkg>/), and preserveSymlinks: true made TypeScript resolve type imports from the symlink location instead of the real path. That broke peer-dep subpath imports — @storybook/react's import { … } from 'storybook/internal/types' returned an unresolved shape, degrading AnnotatedStoryFn/StoryFn/Meta/Decorator to any-ish. Cascade: 114 TS7006 implicit-any in StoryFn<Props> callbacks, 70 TS2578 newly-unused @ts-expect-error suppressions, 89 TS2339/TS2559/TS2769/TS2322/TS7031/TS2741 type mismatches in data-table-manager and emotion-styled props.
• packages/components/tooltip: declare @types/react-is: 19.2.0. Tooltip imports from react-is but never declared the types package; transitively visible under shamefully-hoist, invisible under strict pnpm. Also bumped accessible-button's @types/react-is from ^19.0.0 → 19.2.0 for manypkg compliance.

Visualroute phantom-dep regressions (visual-testing-app build)

Same FEC-935 pattern, surfaced once typecheck stopped masking later CI stages. Visualroute fixtures (co-located in component workspaces, consumed by visual-testing-app's vite build for Percy snapshots) imported packages that weren't declared on the owning workspace. Split into two categories with explicit rationale:

Self-references → relative imports (Option A). Four visualroute fixtures imported their own workspace by package name (e.g. from '@commercetools-uikit/pagination' inside pagination/src/). Under strict pnpm there's no self-symlink, so the name was unresolvable.

Rewrote to relative imports (from '..'). Rationale:

• Matches the established pattern across this repo — every other in-workspace file (stories, decorators, sibling components) already uses relative imports. The visualroute self-imports were the outliers.
• The alternative (declare workspace as self-devDep — "@me": "workspace:*") was experimentally validated to work technically, but pnpm warns about cyclic deps generally and the pattern doesn't exist anywhere else in the codebase. Wouldn't introduce a new norm for a single edge case.
• Industry signal: Nx docs treat relative imports as the "last resort" but established fallback. Node.js's blessed answer ("exports" field for self-reference) is out of scope here — would change consumer resolution semantics.

Files: pagination, card, grid, icons (main + 3 subpath entries), design-system.

Cross-workspace imports → declare devDeps (Option B). Visualroute fixtures importing other workspaces by package name (consumer's-perspective style) now declare those workspaces as devDependencies — matches FEC-935's broader "declare what you use" philosophy and industry consensus across pnpm/Nx/Turbo docs.

• Cross-component: card +text, icons +text +spacings, stamp +icons, grid +design-system, text +@emotion/styled, progress-bar +@emotion/styled.
• Router: 7 workspaces declare react-router or react-router-dom pinned to 5.3.4 (matching visual-testing-app).
• Root devDeps for repo-level test helpers (test/percy/*.jsx) and one orphan visualroute fixture (packages/components/spacings/spacings.visualroute.jsx — parent dir has 4 sub-workspaces but no parent package.json, so the fixture's nearest workspace is the repo root): @commercetools-uikit/design-system/hooks/i18n/utils, @emotion/styled, prop-types, lodash.

Validation matrix

Step	Status	Notes
pnpm install (strict pnpm)	✅	Clean (29 added, 55 removed — SB9 is ~half the size of SB8).
pnpm build	✅	Preconstruct green.
pnpm test	✅	125/125 suites, 1402/1402 tests.
pnpm lint	✅	1308/1308 suites.
pnpm lint:publint	✅	Unchanged baseline warnings only.
pnpm --filter storybook build	✅	The original FEC-935 blocker — green under v9.
pnpm --filter visual-testing-app build	✅	Green after visualroute phantom-dep fixes.
pnpm typecheck	✅	0 errors (was 273 before the strict-pnpm regression fixes above).

Decisions captured

• Single bundled PR — per the team's refined preference for work without observable intermediate state.
• public-hoist-pattern[]=@storybook/* retained — ~15 packages hoisted, all conceptually part of the storybook toolchain. Leaf packages import Storybook-namespaced types from a framework-user perspective (matching the ESLint **/docs/** override). Dramatically narrower than shamefully-hoist=true (~1000 packages).
• SB9 over SB10 — documented migration path is 8 → 9; v10 is one further hop and out of scope.
• Automigration first, manual cleanup after — pnpm dlx storybook@9.1.20 upgrade handled the bulk of the codemod; manual pass cleaned up the orphan eslint-plugin-storybook import the automigration left at root.
• Visualroute imports — split policy: self-references use relative imports (Option A, matches existing repo pattern); cross-package imports use explicit devDep declarations (Option B, matches the "declare what you use" philosophy of the rest of FEC-935). See the "Visualroute phantom-dep regressions" section above for the full rationale.

Refs

• Jira: FEC-935
• Parent: FEC-924 (PR refactor(FEC-924): migrate from Yarn 3 to pnpm #3239)

[changeset-bot]

🦋 Changeset detected

Latest commit: 178f963

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@commercetools-local/storybook	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ui-kit	Ready	Preview, Comment	May 18, 2026 8:09am

[ByronDWall]

Overall a great update, my only question is about workspace versioning the packages that are built within the monorepo

[ByronDWall]

can't this be workspace:*?

[misama-ct]

It can and will, but I have this as the next step in a separate ticket. This PR is making the implicit dependencies visible, the next one abstracts them.

[ByronDWall]

can @commercetools-frontend/ui-kit and @commercetools-uikit/* packages be resolved as workspace packages so that we don't have to update the versions after each release?

[misama-ct]

Same as here.