The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
Create FE Modularization skill (#80132)
Fraser522b0458e0cc
diff --git a/.claude/skills/fe-modularization/SKILL.md b/.claude/skills/fe-modularization/SKILL.mdnew file mode 100644index 00000000000..ba7fe46802e--- /dev/null+++ b/.claude/skills/fe-modularization/SKILL.md@@ -0,0 +1,248 @@+---+name: fe-modularization+description: Deciding where frontend code lives — tier model, move mechanics, extension points, side effects, naming, and the traps. Use when moving code between modules, carving new modules, fixing boundary violations, adding a barrel or an endpoint, or reviewing module-shape decisions.+---++# Frontend modularization++The module is the unit of blast radius: dependency direction, test selection,+bundle cones, and review scope all follow module boundaries. Every decision+here serves one goal: **make the file locations tell the truth about who owns+what and who may depend on whom.**++## Hard rules (check these before anything else)++- NEVER add an `export … from` re-export at an old path, and NEVER `export *`+ from a barrel. Move the code, codemod every call site, delete the old path,+ all in the same PR.+- NEVER import past a module's `index.ts` when that module has+ `enforcePublicApi: true`, and never past `metabase/ui`'s index at all. If+ the barrel is heavy, the fix is making the module side-effect free (below),+ not a deep import.+- NEVER rewrite a consumer to a lower-level idiom to make the linter pass. If+ the fix makes the consumer worse, the plan is wrong.+- NEVER give a new module `enforceSharedTiers: false`; new modules ship+ enforced with `enforcePublicApi: true` and an explicit `index.ts`.+- NEVER move code without the consumer-tier check (procedure step 2).+- ALWAYS delete a module's `enforceSharedTiers: false` line in the PR that+ takes it to zero violations.+- ALWAYS measure `bun run module-boundaries` before and after, and report the+ numbers.+- ALWAYS import `dayjs` from `metabase/dayjs`, routing from `metabase/router`,+ Mantine from `metabase/ui`, react-redux hooks from `metabase/redux`; the+ raw specifiers are lint-forbidden.++## Files that are ground truth++| what | where |+|---|---|+| module elements, tiers, `enforceSharedTiers`, `enforcePublicApi` | `frontend/lint/module-boundaries.mjs` |+| shared sub-tiers and levels, cluster rules | `frontend/lint/shared-tiers.mjs` |+| standalone boundaries lint (all violations, incl. grandfathered) | `bun run module-boundaries` (config `eslint.config.module-boundaries.mjs`) |+| PR lint (only enforced modules fail CI) | `bun run lint-eslint-pure` |+| side-effect-free directories and their exceptions | `frontend/build/shared/rspack/side-effect-free-modules.js` (`SIDE_EFFECT_FREE_PATHS`, `SIDE_EFFECT_PATHS`) |+| the lint rules that enforce that promise | `metabase/no-module-side-effects`, `metabase/no-base-api-access` in `frontend/lint/eslint-plugin-metabase/rules/` |+| public-api enforcement | `metabase/enforce-module-public-api` rule, driven by `getPublicApiModules()` |++## The model++Tiers: `lib < basic < shared < feature < app`. Imports point downward, never+sideways at feature tier (features may not import features; app and EE may+import anything). The shared tier is subdivided in `shared-tiers.mjs` into+shared-utils (U0…), shared-platform (P0…), and shared-domain, each ordered+into levels. A module imports only *strictly lower* levels of its sub-tier+plus the sub-tiers below; same-level peers are deliberately forbidden, which+is what makes cycles structurally impossible. A domain may hold two seats+when consumers demand it: a low core and a high surface (metabase-lib below+questions below query_builder; viz-core below visualizations).++Enforcement is per module: `enforceSharedTiers: false` on an element exempts+it from the level rules (counted by `bun run module-boundaries`, invisible to+PR lint). Modules with `enforcePublicApi: true` may only be imported from+outside via `metabase/<module>`, and import relatively inside.++## Deciding where code lives (apply in order; first decisive test wins)++1. **Who owns the concept?** Code lives with the module that owns its+ concept, not the module that renders or calls it. A mode encoding dashboard+ click behaviour is dashboard code even if viz executes it. Metabot+ conversation state is metabot state even though the store registers it.+2. **Consumer-tier check.** The destination must sit at or below the file's+ *lowest* consumer. A single consumer below the proposed home vetoes the+ move; report it, don't force it.+3. **Only four legitimate fixes** for a bad edge: move the code to its+ terminal home; invert through a designed extension point (a prop, an+ injected component, a contract type owned by the socket); fix the tier+ placement when the declared level is wrong; delete a thin wrapper (a rename+ with no derivation isn't an abstraction — deleting it *is* the migration).+4. **A bridge lives above the lower endpoint.** Code that needs both sides of+ a boundary belongs in or above the higher module.+5. **"Genuinely shared" is proven by consumers.** A shared address needs two+ or more consumers the tier rules can't serve another way. One consumer+ pretending to be shared is a feature module at the wrong address.++## Extension points++The socket's owner defines the contract; every plug lives with its extender.+Visualization owns the `mode` prop and click interfaces, each surface supplies+its mode; the editor owns its extension contract, metabot supplies tiptap+extensions; querying owns `TemplateTagsSidebarProps`, parameters implements+it.++- Prefer plain props/injection at composition sites. `PLUGIN_*` registries are+ for edition gating; single-reader slots move out to their reading module;+ slots with many readers live in the module that owns the concept (every+ slot the whitelabel plugin fills lives in `whitelabel`), tier permitting.+ Keep contracts type-light so implementations can load lazily.+- Identical injection at every callsite is acceptable until a fourth consumer+ or second slot appears; then the composition deserves its own module above+ both parts. Don't pre-build the wrapper.++## Store shape++A module that has redux state owns it:++- `store/` is private: reducer, plain creators/action types, and selectors,+ typed against the module's own state (`QueryBuilderStoreState`), never the+ global `State`. Thunks live in `actions/` and import `store/`, never the+ reverse.+- The barrel is the state API: selectors for reads, creators/thunks for+ writes.+- Store roots (`reducers-main`, `reducers-public`, the SDK store) import each+ slice from its module barrel and derive their own state type; no slice+ registry, no `declare module` merging.+- Cross-module writes: a callback prop when a composition point exists;+ otherwise dispatch the owner's exported creator; an event only when the+ emitter must not know its listeners. Raw `dispatch({ type: "…" })` strings+ are banned. A reducer or listener matching another module's *internal*+ action is the coupling to remove.+- Slices that mirror one endpoint get deleted (the RTK cache is the state); a+ fold over many sources with one writer (the metadata store) is kept as a+ module-private slice behind the barrel.++## Endpoints++Endpoints migrate to their owning module via `Api.injectEndpoints` from the+module's `api/` file (settings, metabot, transforms precedents); `metabase/api`+trends toward the client only. There is one `Api` object per backend because+tag invalidation only works within one instance. Consumers reach endpoints+only through the owner's exports (`useGetCardQuery`, `cardApi.endpoints.…`),+never by name through the base object; `metabase/no-base-api-access` allows+injection only in `metabase/api` and `**/api/**` / `**/api.ts`, and reaching by+name only in `metabase/api` and test support (`invalidateTags` /+`resetApiState` are fine anywhere). Each endpoint move carries its+metadata-store hookup: the owner calls `entitiesFetched` from its own+`onQueryStarted`.++## Import-time side effects++Directories in `SIDE_EFFECT_FREE_PATHS` are marked `sideEffects: false` for+rspack, so importing one export from their barrel no longer drags the whole+barrel into a bundle. The price: nothing in those directories may do work at+import time, or production silently drops it. `metabase/no-module-side-effects`+enforces this over every listed directory (module-scope calls, writes to+imported objects or globals, bare imports, control flow at import; escape+hatches are `/* #__PURE__ */` and the rule's pure-callee list). Files that+must run at import are listed in `SIDE_EFFECT_PATHS` (files or directories).++- **A library the app configures gets a facade module** owning the vendor+ import, the registrations, and the types, with the raw specifier+ lint-forbidden outside it: `metabase/router`, `metabase/ui`,+ `metabase/redux`, `metabase/dayjs`. Facades are the effect, so they never+ enter `SIDE_EFFECT_FREE_PATHS`. Never re-register a vendor plugin locally+ (`dayjs.extend`, `echarts` `use`).+- **A patch a component needs is an explicit registration module,+ bare-imported by the provider that needs it** and listed in+ `SIDE_EFFECT_PATHS` (Mantine's `Popover.Dropdown` replacement, imported by+ `ThemeProvider`).+- **Effects with no value to import** (global CSS, polyfills, the CSP nonce,+ EE plugin bootstrap) live in the entry's side-effects file and nowhere else.+- **Registries are filled from the composition root at boot**+ (`initializePlugins`, `registerVisualizations`), never by a module+ registering itself at import.+- **RTK injection stays at import**; when a module with an `api/` folder is+ declared side-effect free, list `<module>/api/` in `SIDE_EFFECT_PATHS`.++## Naming++The feature keeps the plain product-surface name; a shared carve is named for+what the shared part actually is: the concept when the concept is the shared+thing (`settings`, `current-user`, `whitelabel`, `dayjs`), or a qualified+capability when the plain noun is taken (`search-ui`, `metrics-ui`,+`viz-core`, `data-studio-ui`). Never two modules distinguished only by tier+prefix; never generic `-shared` / `-feature` suffixes.++## Procedure for a move++1. **Enumerate consumers honestly** (hook-name greps miss the last three):+ ```+ grep -rn "metabase/<module>" frontend/src enterprise/frontend/src frontend/test e2e+ grep -rn "jest.mock(\"metabase/<module>" frontend enterprise/frontend+ grep -rn "addMatcher(.*<endpoint>" frontend/src enterprise/frontend/src+ ```+ plus sibling files importing the moved file relatively. Classify each by+ module and tier from `module-boundaries.mjs` / `shared-tiers.mjs`.+2. **Consumer-tier check**: destination at or below the lowest consumer. If+ not, stop and report the blocking consumer.+3. **Measure before**: `bun run module-boundaries 2>&1 | tail -1` on the base+ (write the number down).+4. **Move**: `git mv`; codemod every importer to `metabase/<module>` (outside)+ or a relative path (inside); add named exports to the destination barrel+ for every symbol an outside consumer needs (each must have a real+ consumer). Delete the old path. If the module didn't exist: add its element+ in `module-boundaries.mjs` (ordered before any element it's carved from,+ first match wins), its level in `shared-tiers.mjs`, `enforcePublicApi:+ true`, an `index.ts`. If the move empties a module's violations, delete+ its `enforceSharedTiers: false` line. If the module has an `api/` folder+ and is side-effect free, list `<module>/api/` in `SIDE_EFFECT_PATHS`.+5. **Verify** (all of these, report the numbers):+ ```+ grep -rn "<old path>" frontend enterprise/frontend e2e # must be empty+ bunx eslint --no-warn-ignored <touched files>+ bun run lint-eslint-pure # enforce-module-public-api included+ bun run type-check-pure+ bun run test-unit-keep-cljs <touched folders' specs>+ bun run module-boundaries 2>&1 | tail -1 # after; no violation may name the new files+ bun run build-release:static-viz # only if viz/static-viz/ui/dayjs touched; hard 3.5 MiB budget+ ```+6. **Report**: count before/after (state count-neutral explicitly), the edges+ removed by file, flags/rules deleted, barrel exports added, anything you+ skipped and why, and any consumer you found that vetoed part of the move.++## Traps (each has bitten at least once)++- **Late binding.** A bare function reference in a `createSelector` input+ array, a component identity captured for comparison, a `PLUGIN_*` object+ read at module scope: all capture at import time and dodge jest spies, EE+ overrides, and lazy loading. Read at call time (`(_state) => fn()`), or+ inject.+- **Plans go stale.** Verify every recipe against current code before+ executing; things get merged, renamed, or turn out never to have existed.+ Skip-and-report beats force.+- **The linter's blind spots**: `export … from` re-exports, bare-specifier+ packages (custom-viz), pre-seeded caches that never register tags. A grep+ for the old path is the stronger claim than a green lint run.+- **Path-keyed baselines reset on rename**: a generated per-file ledger+ silently loses a file's history when it moves.+- **A heavy barrel is a bundle hazard until its module is side-effect free.**+ One constant imported from the `metabase/ui` barrel pulled Mantine into the+ static-viz bundle and broke its budget; the fix was `SIDE_EFFECT_FREE_PATHS`,+ never a deep import.+- **Type augmentation is program-wide.** `declare module "dayjs"` (and+ similar) makes plugin types available to any file in the same tsconfig, so+ a passing type-check never proves the setup ran; only importing the facade+ does.+- **Environment before diagnosis**: after a dependency-touching merge,+ `bun install` before declaring a failure real; worktrees share staleness+ through the node_modules symlink, and a stale `target/cljs_dev` makes+ `type-check-pure` fail on `metabase-lib/metric/core.ts` (rebuild cljs in the+ worktree).++## PR shape++One logical change per PR; the body names the specific edges removed (files,+imports, before/after count) and gives each move's ownership reason in plain+language a reviewer outside the effort can follow, without campaign labels.+Stack only for semantic dependency or same-hot-file serialisation, and say+so. Consider codeowner surface when chunking. Open as a draft until measured+and green.