typescript-monorepo-barrel-split

Answer

Target state — split the 913-line text/styles.ts into a styles/ module directory. The file system must look like this (path prefix packages/*/src/ or repo root as appropriate):

text/
├── styles.ts                  # 1-line shim  (2 lines only if the original had a default export)
└── styles/
    ├── index.ts               # barrel — sole public surface, re-exports all 6 submodules
    ├── types.ts               # leaf: interfaces / type aliases / enums (StyleConfig, Theme, …)
    ├── constants.ts           # leaf: static values (palettes, font stacks, spacing, z-index, …)
    ├── config-store.ts        # mutable singleton (theme/config getters+setters, defaultConfig)
    ├── validation.ts          # depends on types(+constants): isValidConfig, isColor, …
    ├── balloon-style.ts       # depends on types, constants(+config-store): buildBalloonStyle, prefix
    └── css-canvas.ts          # depends on types, balloon-style, config-store: renderCss, toCssText, …

The 1-line shim — the one non-obvious line in this whole split:

// text/styles.ts  (CommonJS / classic node resolution)
export * from './styles/index';

⚠️ Do NOT write export * from './styles'; — I verified empirically that this is a silent trap: TypeScript/Node resolution prefers the sibling file text/styles.ts over the directory text/styles/, so the shim re-exports from itself, producing a circular import that exports nothing. Importers fail with TS2305: no exported member at compile time and TypeError: setTheme is not a function / Named export not found at runtime. The trailing-slash form export * from './styles/'; also works (it forces directory resolution), but './styles/index' is the clearest and most robust.

For a NodeNext/ESM monorepo ("type": "module"), every relative specifier in the new modules must carry the explicit .js extension (TS2835 otherwise):

// text/styles.ts (ESM / NodeNext)
export * from './styles/index.js';

// text/styles/index.ts (ESM) — the barrel
export * from './types.js';
export * from './constants.js';
export * from './config-store.js';
export * from './balloon-style.js';
export * from './css-canvas.js';
export * from './validation.js';

Barrel discipline (rules that keep importer changes at zero):

1. Preserve the exact public surface. Enumerate every name the original exported and ensure the barrel re-exports each one — same name, same type. Any consumer doing import { renderCss } from './text/styles' must keep resolving.
2. No name collisions across submodules — duplicate names break export * with TS2308. Disambiguate explicitly: ts export { buildBalloonStyle } from './balloon-style.js'; export { buildBalloonStyle as buildBalloonStyleLegacy } from './legacy.js';
3. Default export does not flow through export *. If styles.ts had a default export, the shim needs a second line: ts export * from './styles/index'; export { default } from './styles/index'; (913-line style modules are almost always named-only, so the 1-line form holds.)
4. Singleton identity must survive. A module-level mutable object (config store, cache, registry) must live in exactly one submodule (config-store.ts) and be moved, never copied — the barrel only re-exports the same binding. Verified: configStore imported via the barrel === the object imported directly from styles/config-store.
5. Order the dependency graph leaf → root (types → constants → config-store/validation → balloon-style → css-canvas) and use import type for all type-only imports so the runtime graph stays acyclic even when the type graph is tangled. No cycles are created by this ordering.

Independent full-mode guard (what to run instead of trusting turbo-spinner log capture):

pnpm --filter <pkg> exec tsc --noEmit -p tsconfig.json      # typecheck whole package
pnpm --filter <pkg> exec tsc -p tsconfig.json               # emit JS + .d.ts
node dist/smoke.js                                          # import every public name at runtime
git status --short                                          # ONLY text/styles.ts rewritten + text/styles/** added
# optional: madge --circular src  (dep-cruiser) if installed