Shell Sessions and Cross-Team Events
On this page
The shell's job in this stack
The shell is plain TypeScript, owned by the platform team. It doesn't call tRPC at all. Its jobs:
- ask the BFF who's signed in, once, and pass
userto every micro-frontend, - draw the header with sign-in and sign-out,
- route between micro-frontends,
- handle the session ending, in one place, for everyone.
Who's signed in
At startup the shell asks the BFF's /bff/user endpoint, with the CSRF header like every other call:
const res = await fetch('/bff/user', { headers: CSRF_HEADER });
user = res.ok ? (await res.json()).user : null;
drawHeader();
render();When user is null, the shell doesn't load any micro-frontend. It shows a sign-in prompt instead:
async function render() {
if (!user) {
current?.unmount(); current = null;
outlet.innerHTML = '<p>Please sign in to see your tasks.</p>';
return;
}
// ...route matching, load, mount, as in the micro-frontends course
}Sign-in is a full navigation to /auth/login?returnTo= plus the current path. In the end-to-end run, opening /tasks signed out showed the prompt; after signing in, the browser came back to /tasks with "Ada Lovelace" in the header.
One place for "your session ended"
Sessions end: the idle timeout passes, an admin signs the user out everywhere, Redis restarts. The next tRPC call from any micro-frontend then fails with UNAUTHORIZED, because protectedProcedure finds no session (Day 4).
Without coordination, each team would handle that differently, or not at all. Instead, the contract package provides a tRPC link that every micro-frontend puts first in its chain:
// @taskboard/contract
export function sessionLink<T extends AnyRouter>(): TRPCLink<T> {
return () => ({ op, next }) => observable((observer) => next(op).subscribe({
next: (v) => observer.next(v),
complete: () => observer.complete(),
error: (err) => {
if (err.data?.code === 'UNAUTHORIZED') emit('taskboard:session-expired', {});
observer.error(err);
},
}));
}The link doesn't swallow the error. The micro-frontend still sees it. It just raises one event that the shell listens for:
on('taskboard:session-expired', () => {
if (user) { // only once, even if several calls fail together
user = null;
alert('Your session has ended. Please sign in again.');
signIn();
}
});The end-to-end test deleted every session in Redis while Ada was on the account page, then clicked "Tasks":
dialog: Your session has ended. Please sign in again.
redirected to identity provider: 127.0.0.1:4800The tasks micro-frontend's first call failed with UNAUTHORIZED, the link raised the event, and the shell handled it once. No team wrote any session-handling code. In a real app, replace alert with a proper dialog from the design system.
Cross-team events: the profile changes
The account team lets users change their display name. The header, owned by the platform team, shows that name. The account micro-frontend can't reach into the header, and it shouldn't. It announces the change instead:
const rename = useMutation(trpc.account.rename.mutationOptions({
onSuccess: (res) => {
queryClient.setQueryData(trpc.account.me.queryKey(), (old) => old && { ...old, name: res.name });
emit('taskboard:profile-changed', { name: res.name });
},
}));// shell
on('taskboard:profile-changed', ({ name }) => {
if (user) { user = { ...user, name }; drawHeader(); }
});The event fires only after the server confirmed the change, in onSuccess. That avoids the "lost event" problem from the micro-frontends course, where an event announced something that never really happened. In the test, saving "Ada L." changed the header from "Ada Lovelace" to "Ada L." straight away.
The event is typed in the contract package ('taskboard:profile-changed': { name: string }), so a typo in the name or payload fails to compile on either side.
Signing out
Sign-out goes through the BFF, then leaves the page entirely:
async function signOut() {
const res = await fetch('/auth/logout', { method: 'POST', headers: CSRF_HEADER });
location.assign((await res.json()).redirectTo); // the identity provider's end-session URL
}The full navigation is deliberate. It discards every micro-frontend's in-memory state and query cache in one step, with no cleanup code in any team's micro-frontend.
Never trust the user prop for security
user from the shell is display data: a name for the header, a reason to hide a link. Every real permission check happens on the server, in the BFF's procedures and the services behind them. If a micro-frontend ever decides what data to fetch based on user.sub alone, without the server checking, that's a bug.
Check yourself
So every micro-frontend gets identical behavior by adding one link, and the shell handles the event in one place, instead of each team writing its own.
So the event only announces a change the server has confirmed. Emitting on click could update the header for a rename that then failed.
A full navigation clears every micro-frontend's memory and query cache at once, so no team needs sign-out cleanup code and nothing can be left behind. It also sends the browser to the identity provider's end-session URL, which ends the provider's session so the next sign-in actually asks for credentials.
The shell's handler checks if (user) and sets user = null before showing the dialog, so only the first event acts and the rest are ignored. Making shared handlers idempotent like this matters whenever many components can report the same condition at once.
The shell escapes the name before inserting it, replacing <, >, & and quotes with HTML entities. Any user-controlled text written with innerHTML must be escaped, or set with textContent instead, otherwise a display name becomes a cross-site scripting attack.