The Problem
When Next.js 13 dropped the App Router, it broke most of the existing MSAL integration guides. The old Pages Router patterns didn't translate — getServerSideProps was gone, the client/server boundary was new, and the MSAL provider needed to live in a client component while the layout was a server component.
I spent more time than I'd like to admit piecing this together for a project at work. Once I had something clean and working, I figured I'd open source it so nobody else has to go through the same exercise.
What It Does
It's a minimal, working boilerplate — not a full app, just the wiring. It handles:
- MSAL initialization correctly scoped to a client component boundary
- Auth state persisted across route changes without re-triggering login flows
- User claims and roles — includes a
UserRolesContainercomponent that renders content conditionally based on Azure AD app roles - User avatar — handles photo retrieval, falls back to initials when no photo is provided or the photo comes back blank (which happens more often than it should)
- Token retrieval — a dedicated page that shows the raw token for testing against custom APIs
Why This Matters
The tricky part with MSAL in the App Router isn't the auth flow itself — it's where you put things. The MsalProvider has to wrap client components, but most of your layout is a server component. Getting that boundary right without hydration mismatches or double-renders took some back and forth.
The msal/ folder keeps all the configuration and helpers separate from the app itself, which makes it easier to drop into an existing project without touching too much.
Tech Stack
- Next.js 14 (App Router)
@azure/msal-browserv3@azure/msal-reactv2- TypeScript
Reception
Wasn't expecting much when I pushed it — 63 stars and 17 forks later, apparently it filled a gap. Still get occasional issues from people integrating it with different Azure AD setups, which tells me the documentation around this is still not great upstream.
If you're building anything with Azure AD and Next.js, feel free to use it as a starting point.