For AI agents: the complete documentation index is available at https://mfeflow.github.io/mfeflow/llms.txt, the full documentation bundle is available at https://mfeflow.github.io/mfeflow/llms-full.txt, and this page is available as Markdown at https://mfeflow.github.io/mfeflow/guide/tooling-repo.md.

A repo for shared tooling

A tooling repo has no shell and no remotes. It holds what several app repos have in common: a TypeScript config, lint rules, git hooks, the release setup, and small packages in your own scope (@acme/analytics, @acme/theme and so on) that each wrap one of ours and carry your defaults. App repos depend on @acme/....

When to use it

Use it when more than one repo needs the same settings and you would rather change them in one place. Two examples: every repo should extend the same tsconfig and oxlint rules, or every app should start analytics with the same consent defaults and container ids.

Skip it if you have one repo. A normal project already has the platform packages contracts and tokens inside it, and the lint and hook features can be added there with mfeflow add.

Create it

mfeflow init acme-tooling --kind tooling --scope @acme \
  --packages tsconfig,oxlint-config,analytics,http \
  --features lint-oxlint,git-hooks

The last lines of the output:

Warning: packages: also made url-factory, which http needs

Created /work/acme-tooling, a repo for shared tooling with no apps.
Next:
  cd acme-tooling
  pnpm install
  pnpm build

Without --packages you get tsconfig and oxlint-config. Without --features you get lint-oxlint and git-hooks. The repo is its own git repository from the start, so the hooks are installed into it and not into a folder above it.

What you get

packages/contracts     @acme/contracts: event names and types every repo agrees on
packages/tokens        @acme/tokens: colors and spacing
packages/tsconfig      @acme/tsconfig
packages/oxlint-config @acme/oxlint-config
packages/analytics     @acme/analytics
packages/http          @acme/http
packages/url-factory   @acme/url-factory, added because http needs it
default.json           a Renovate preset other repos can extend
.changeset             how a change gets a version
.github/workflows      reusable CI, CI and release

pnpm install, pnpm build, pnpm typecheck, pnpm lint and pnpm format:check all run, and mfeflow validate says the repo has no apps:

This project has no apps, so the checks about apps have nothing to look at.

CI generates a repo like this one on every change and runs the same commands on it (the script).

The packages

Each wrapper depends on our package of the same name, re-exports all of it, and adds your defaults in a file you edit, usually src/defaults.ts. The names you can pick are tsconfig, oxlint-config, analytics, telemetry, http, theme, i18n, event-bus, route-factory, url-factory, storage, runtime and testing. A package that needs another adds it and the command says so. The CLI reference has the rules.

@acme/oxlint-config has a build step. oxlint reads extends as a file path and does not look a package name up, so the package writes dist/oxlintrc.json from our rules and your overrides.json when you run pnpm build. The file is not committed. An app repo points at it by path:

{ "extends": ["./node_modules/@acme/oxlint-config/dist/oxlintrc.json"] }

@acme/tsconfig needs no build. In an app repo:

{ "extends": "@acme/tsconfig/react-app.json", "include": ["src"] }

For micro-frontends

runtime and testing only make sense for teams that run a shell: runtime loads remotes from a registry, and testing wraps components in the shell's providers. The command prints a note when you pick them. analytics, telemetry, theme, i18n and event-bus are shared between a shell and its remotes, so they are the ones affected by the next two sections.

Use a wrapper from an app repo

While you try it out, link the package by path. Later, publish the packages and use a version range.

{
  "dependencies": {
    "@acme/theme": "link:../acme-tooling/packages/theme"
  }
}

Build the tooling repo first; a linked package is read from its dist.

Micro-frontends need one more line

If the app is a shell or a remote built with mfeflow, and it uses @acme/theme, @acme/i18n, @acme/runtime, @acme/analytics, @acme/telemetry or @acme/event-bus, it also lists our package of the same name in its own package.json:

pnpm add @mfeflow/theme

Use the range the wrapper uses; it is in the wrapper's package.json. Do this in the shell and in every remote that imports the wrapper.

The reason is how the presets pick what to share. They share @mfeflow/theme, @mfeflow/i18n, @mfeflow/runtime, @mfeflow/analytics, @mfeflow/telemetry and @mfeflow/event-bus as singletons by name, but only when the app can resolve that name from its own folder. pnpm does not make a dependency of a dependency visible there. An app that lists only @acme/theme therefore has no @mfeflow/theme to share, and the preset leaves it out without a message.

This was tried on a shell and two remotes that import only the wrappers @acme/theme and @acme/event-bus. The shared packages the preset returned for a remote:

without @mfeflow/theme in the app:
  react react/jsx-runtime react/jsx-dev-runtime react-dom react-dom/client

with @mfeflow/theme in the app:
  react react/jsx-runtime react/jsx-dev-runtime react-dom react-dom/client @mfeflow/theme @mfeflow/theme/react

In the browser (headless Chromium, mfeflow dev), the shell has the theme provider and each remote shows the name of the theme it reads:

  • Without the line, both remotes fail with useTheme must be used inside <ThemeProvider> (mounted by the shell). Each remote had its own copy of the theme package, and the provider is in the shell's copy.
  • With the line, both remotes show light.

The event bus did not need the line in that run: the remotes saw an event the shell published even without it. The event bus, analytics and telemetry keep their state on globalThis (read in their source), so a second copy of the package still reaches the same subscribers. The theme package keeps its state in a React context, and i18n is built on contexts too (read, not run), so those two are the ones that break. Add the line for all of them anyway; it costs nothing and does not depend on how a package stores its state.

Two other ways were tried and do not replace the line. A peer dependency on @mfeflow/theme in the wrapper does not help with pnpm: it installs the peer next to the wrapper and leaves the app's own folder without it (tried with a small test package). Putting the wrapper's name in the preset's shared option works, but it has to be repeated for every subpath and in the shell and every remote, and the shell must depend on the wrapper too. Telling the preset to look through the wrappers for our packages would remove the extra line; that change is not made yet.

Wrappers hold settings and no state

A wrapper is not in the list of shared singletons, so every remote gets its own copy of it. That is harmless while the wrapper holds settings and functions that build things. It is wrong as soon as the wrapper keeps state at module level, because each remote then has its own state.

A throwaway wrapper with a counter at module level, imported by two remotes, shows it. Each remote read the counter once when it loaded:

not shared:                          catalog: 1   cart: 1
shared in the shell and both remotes: catalog: 1   cart: 2

With the package in the shared option of the shell and both remotes, the second remote sees the first one's count. Without it, the two remotes count separately. So keep state in @mfeflow/* or in the shell, and keep the wrapper to settings. Each wrapper's README says this too, and a test in this repo checks that no wrapper's source has module-level state.

What is not supported yet

  • mfeflow upgrade does nothing in a tooling repo. It prints This project has no apps, so there is nothing to upgrade. Update the mfeflow packages in package.json by hand.
  • --bundler is refused (E107) in init --kind tooling and in upgrade, because there are no apps to bundle; the packages build with tsc. A bundler set in a shared preset is ignored instead, and the summary says preset bundler vite ignored: a tooling repo has no apps, so one team preset can serve app and tooling repos.
  • ci-github is refused (E107). The repo already has a ci.yml that builds and validates, and the other steps of that feature are about apps.
  • Features that need an app are refused with E216. That includes env-t3 and analytics-gtm, which write into a shell. A tooling repo takes lint-oxlint, git-hooks, commit-prompt and release.
  • release is accepted but adds nothing, because the repo already versions and publishes with Changesets.
  • Analytics goes as far as the analytics wrapper: consent defaults, a container id per environment and createAnalytics(env). A shared tracking plan or event list is not made for you. Put it in packages/contracts.
  • For remotes without a shell, use --kind remote instead. See Join a platform with a remote.