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
The last lines of the output:
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
pnpm install, pnpm build, pnpm typecheck, pnpm lint and pnpm format:check all run, and mfeflow validate says the repo has no apps:
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:
@acme/tsconfig needs no build. In an app repo:
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.
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:
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:
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:
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 upgradedoes nothing in a tooling repo. It printsThis project has no apps, so there is nothing to upgrade. Update the mfeflow packages in package.json by hand.--bundleris refused (E107) ininit --kind toolingand inupgrade, because there are no apps to bundle; the packages build withtsc. Abundlerset in a shared preset is ignored instead, and the summary sayspreset bundler vite ignored: a tooling repo has no apps, so one team preset can serve app and tooling repos.ci-githubis refused (E107). The repo already has aci.ymlthat 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-t3andanalytics-gtm, which write into a shell. A tooling repo takeslint-oxlint,git-hooks,commit-promptandrelease. releaseis accepted but adds nothing, because the repo already versions and publishes with Changesets.- Analytics goes as far as the
analyticswrapper: consent defaults, a container id per environment andcreateAnalytics(env). A shared tracking plan or event list is not made for you. Put it inpackages/contracts. - For remotes without a shell, use
--kind remoteinstead. See Join a platform with a remote.
Related
- Can I have a repo with no apps?
- E216: what the error says when a feature needs an app.
- One repo per team: the platform repo of a polyrepo is the same kind of repo, made inside a bigger
init.