Catalog My learning Blog
Micro-Frontends, BFF and tRPC: Full-Stack TypeScript Project · Phase 1 · Lesson 2 · 5 min read

TypeScript Monorepo for Micro-Frontends and tRPC

On this page
  1. Why one repository
  2. The layout
  3. Export types, not code
  4. The contract package
  5. One strict type check
  6. One build, separate outputs
  7. Check yourself

Why one repository

tRPC's types flow from the BFF's router to every client at compile time. The simplest way to make that work is a monorepo: one Git repository, several packages, each with its own folder, dependencies and build. Teams still own their folders, and pipelines still deploy each piece separately. Only the *types* are shared.

The layout

Code
taskboard/
  package.json              workspaces: ["packages/*"]
  tsconfig.json             one strict config for type checking
  build.mjs                 builds shared React, the micro-frontends and the shell
  packages/
    contract/               @taskboard/contract: mount types, events, CSRF header, sessionLink
    bff/                    @taskboard/bff: Fastify host, sign-in, sessions, tRPC routers
    shell/                  @taskboard/shell: header, routing, session experience
    mfe-tasks/              @taskboard/mfe-tasks: tasks team's screens
    mfe-account/            @taskboard/mfe-account: account team's screens

The root package.json declares the workspaces:

JSON
{
  "name": "taskboard",
  "private": true,
  "type": "module",
  "workspaces": ["packages/*"]
}

npm install at the root links every package into node_modules/@taskboard/, so one package can import another by name. pnpm and Yarn workspaces work the same way. Install each dependency into the package that uses it:

Shell
npm i -w @taskboard/bff fastify @fastify/cookie @fastify/static @trpc/server openid-client ioredis zod superjson
npm i -w @taskboard/mfe-tasks -w @taskboard/mfe-account react react-dom @trpc/client @trpc/tanstack-react-query @tanstack/react-query superjson
npm i -D typescript tsx esbuild @types/node @types/react @types/react-dom

Export types, not code

The micro-frontends need the BFF's AppRouter type and nothing else. The BFF's package.json makes that explicit with an exports map:

JSON
{
  "name": "@taskboard/bff",
  "private": true,
  "type": "module",
  "exports": {
    "./router": { "types": "./src/trpc/router.ts" }
  }
}

The only thing other packages can import from the BFF is @taskboard/bff/router, and only its types. A micro-frontend writes:

JavaScript
import type { AppRouter } from '@taskboard/bff/router';   // erased at build time

import type guarantees the bundler drops the import, so no server code, database client or secret can reach the browser. If someone writes a normal import { appRouter } by mistake, the build fails because the package exports no JavaScript at that path. That's a safety rail worth having.

The contract package

@taskboard/contract holds everything that crosses a boundary between the shell, the micro-frontends and the BFF:

Shell
export type User = { sub: string; name?: string; email?: string };
export type MountProps = { basePath: string; user: User | null; navigate: (to: string) => void };
export type Mount = (el: HTMLElement, props: MountProps) => () => void;

export type TaskBoardEvents = {
  'taskboard:session-expired': Record<string, never>;
  'taskboard:profile-changed': { name: string };
};

export const CSRF_HEADER = { 'x-csrf': '1' } as const;

Plus the emit and on helpers for events and a sessionLink for tRPC (Day 6). It's small, versioned, and changed only through review by every team.

One strict type check

A single root tsconfig.json type-checks every package together:

JSON
{
  "compilerOptions": {
    "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler",
    "strict": true, "noEmit": true, "skipLibCheck": true, "jsx": "react-jsx",
    "lib": ["ES2022", "DOM", "DOM.Iterable"], "types": ["node"]
  },
  "include": ["packages/*/src"]
}

moduleResolution: "Bundler" lets TypeScript follow the exports map to the BFF's source types. Run npx tsc -p . in CI on every pull request. This is the step that catches a tasks team change to a procedure that breaks the account team's screen, before anything deploys.

As the repository grows, split this into TypeScript project references, so each package is checked against the others' compiled declarations and checks stay fast.

One build, separate outputs

build.mjs at the root builds everything into dist/:

  • Shared React as browser ES modules, once, with the explicit export list from the micro-frontends course.
  • Each micro-frontend with React marked external, to a hashed file like tasks/tasks.ZKXGTG37.js.
  • The shell to shell.js.
  • The import map, dist/importmap.json, written from the build output.
Code
@taskboard/tasks     27.3 KB gzipped
@taskboard/account   26.8 KB gzipped

Each micro-frontend bundles its own tRPC client and TanStack Query, which is why they're larger than the tiny examples in the micro-frontends course. That's a deliberate choice: each team controls those versions, and since each micro-frontend has its own React root and its own QueryClient, nothing crosses the boundary that would need a single shared copy. If the size matters later, both libraries can move into the import map like React did.

In CI, give each package its own build job that runs only when its folder changes, and its own deploy step. The monorepo shares types, not release trains.

TipAdd a CODEOWNERS file mapping each packages/* folder to its team, with the contract package requiring approval from every team. Ownership in the repository then matches ownership in production.

Check yourself

So other packages can import the router's type and nothing else. Accidentally importing server code fails the build instead of leaking into a browser bundle.

In the root type check, tsc -p ., which runs on every pull request and checks every package against the BFF's current router type.

No. Each package keeps its own build job and deploy pipeline, ideally triggered only when its folder changes. The monorepo shares types, tooling and a single type check, so cross-package mistakes are caught early, but the tasks team can still release its micro-frontend without anyone else releasing.

The build fails with Could not resolve "@taskboard/bff/router", because the BFF package exports only a types condition at that path and no JavaScript. That's deliberate: it turns a potential leak of server code into the browser into an immediate, obvious build error.

Every team, which a CODEOWNERS rule can enforce. The contract holds the mount props, events, CSRF header and session link that every package depends on, so a change there is effectively a cross-team API change.