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

Deploying a BFF and Micro-Frontends Safely

On this page
  1. The skew problem, three ways
  2. Rule 1: The BFF deploys first, and only additively
  3. Rule 2: Detect stale clients
  4. Rule 3: Every instance shares its secrets
  5. The deploy pipeline for each piece
  6. Trace a request across all of it
  7. Monitor per team
  8. Check yourself

The skew problem, three ways

In production, the pieces of TaskBoard deploy independently, so at any moment you can have:

  1. a new BFF with old micro-frontends still loaded in users' tabs,
  2. a new micro-frontend calling a BFF that hasn't been deployed yet,
  3. two BFF versions running side by side during a rolling deploy.

tRPC's types are checked at build time, against the code in the repository. None of these run-time combinations was ever compiled together. The tRPC course measured what happens when they disagree:

Code
server added a required input field     -> BAD_REQUEST 400
server removed a procedure              -> NOT_FOUND 404
server renamed an output field          -> undefined on the old client, with no error

Rule 1: The BFF deploys first, and only additively

Any change to a procedure follows expand and contract:

  1. Expand. Deploy the BFF with the new shape *alongside* the old: a new optional input, a new output field, a new procedure. Old micro-frontends keep working.
  2. Switch. Deploy the micro-frontends that use the new shape.
  3. Contract. Once no old micro-frontend can still be running, remove the old shape from the BFF.

For TaskBoard, "can still be running" means: the old import map entry is gone, and long-lived tabs have had time to reload. A few days is plenty for a web app.

Make the order mechanical. The tasks team's pull request that changes tasks.list and the tasks micro-frontend can be one pull request, but the pipeline deploys the BFF first, waits for it to be healthy, and only then updates the import map entry.

Rule 2: Detect stale clients

Add a build id to each micro-frontend and the shell, and have the BFF return its own in a response header, like x-bff-build. A small custom tRPC link, next to sessionLink, compares them. When the BFF reports that a minimum client version is newer than the running one, the shell shows "A new version is available, reload", or reloads on the next navigation. This turns rare skew bugs into a short, visible prompt.

Rule 3: Every instance shares its secrets

Day 7's test found it the hard way: two BFF instances with different token encryption keys can't read each other's sessions, and every call fails with 500. Everything that must be the same on every instance comes from one secret store, and the BFF refuses to start without it:

  • TOKEN_KEY, the AES-256-GCM key for tokens in Redis,
  • OIDC_CLIENT_SECRET (or the private key for private_key_jwt),
  • REDIS_URL and its credentials.

When rotating TOKEN_KEY, support two keys for a while: decrypt with either, encrypt with the new one. Then retire the old key once every session written with it has expired.

The deploy pipeline for each piece

PieceBuildDeployRollback
BFFContainer imageRolling update, health check on /healthzPrevious image
Micro-frontendHashed ES module to static storageUpdate its import map entryPrevious entry
Shellshell.js plus the shell pageUpdate the shell entryPrevious entry
ContractPackage versionConsumed at build timePin the previous version

Micro-frontend deploys are the fast, safe path from the micro-frontends course: a new hashed file, one line in the import map, and a one-line rollback. Old hashed files stay available for weeks for open tabs.

BFF deploys are slower and riskier, because the BFF serves every team. Use a rolling update with health checks, and keep the previous image ready.

Trace a request across all of it

When Ada reports "adding a task failed at 10:42", you need to follow one request from her browser through the BFF to the tasks API. The pieces from this course make that possible:

  • Fastify gives every request an id, from x-request-id or a new UUID (Day 3).
  • The id goes into the tRPC context and onto every downstream call through callApi (Day 4). The router test confirmed x-request-id: req-42 arrived at the mocked tasks API.
  • The BFF's onError logs path, reqId and the cause for every downstream failure.

In production, add OpenTelemetry to the BFF so the HTTP, undici and Fastify instrumentations create spans and propagate traceparent automatically. Tag spans with the tRPC path, like tasks.create, and the owning team, so each team can find its own slow procedures.

Monitor per team

Give each team a view of its own slice:

  • tRPC procedures: rate, error rate by code and latency for tasks.* or account.*.
  • Downstream calls: timeouts and BAD_GATEWAY counts per service.
  • Micro-frontend errors: attributed by file name through the import map, as in the micro-frontends course.
  • Subscriptions: open SSE connections per instance.

Alert the owning team, not a shared channel nobody reads.

TipPractice a rollback of each piece before launch: a micro-frontend entry, the BFF image and the shell. Rollbacks you've never run are the ones that fail at 2 a.m.

Check yourself

So the new shape exists before anything calls it. With additive changes, old micro-frontends keep working against the new BFF in the meantime.

Every instance must load the same secrets from one store, or instances can't read each other's sessions. The BFF should refuse to start without them.

It's logged by the BFF and forwarded to downstream services, so you can find every log line and trace for that one request across the stack.

Calls to the missing procedure fail with NOT_FOUND (404), so the archive feature errors until the BFF catches up. That's why the pipeline deploys the BFF first and waits for it to be healthy before updating the micro-frontend's import map entry.

Support two keys for a while: decrypt with either key, encrypt only with the new one. Sessions rewritten during normal use move to the new key, and once every session encrypted with the old key has expired, remove it.