Deploying a BFF and Micro-Frontends Safely
On this page
The skew problem, three ways
In production, the pieces of TaskBoard deploy independently, so at any moment you can have:
- a new BFF with old micro-frontends still loaded in users' tabs,
- a new micro-frontend calling a BFF that hasn't been deployed yet,
- 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:
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 errorRule 1: The BFF deploys first, and only additively
Any change to a procedure follows expand and contract:
- 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.
- Switch. Deploy the micro-frontends that use the new shape.
- 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 forprivate_key_jwt),REDIS_URLand 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
| Piece | Build | Deploy | Rollback |
|---|---|---|---|
| BFF | Container image | Rolling update, health check on /healthz | Previous image |
| Micro-frontend | Hashed ES module to static storage | Update its import map entry | Previous entry |
| Shell | shell.js plus the shell page | Update the shell entry | Previous entry |
| Contract | Package version | Consumed at build time | Pin 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-idor a new UUID (Day 3). - The id goes into the tRPC context and onto every downstream call through
callApi(Day 4). The router test confirmedx-request-id: req-42arrived at the mocked tasks API. - The BFF's
onErrorlogspath,reqIdand 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.*oraccount.*. - Downstream calls: timeouts and
BAD_GATEWAYcounts 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.
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.