DEV Community: Ismail ZAHIR

Building a Reusable Keycloak Theme Architecture

Ismail ZAHIR — Sat, 15 Aug 2026 22:14:39 +0000

The last article in this series ended with a promise: make Keycloak stop looking like Keycloak. I kept it. The login pages got a custom template and stylesheet, and the roughly seventeen emails Keycloak sends got the same treatment.

It worked. I wasn't satisfied.

The login theme carried its own styles. The email theme carried its own resources. If I wanted a second branded version of the same authentication experience — another product, another client, another environment — I would have been copying files and hoping I remembered to update both.

That turned a styling exercise into an engineering question:

How do you build Keycloak themes once, reuse the common parts, and still let every application customize what it actually needs?

This article is the answer I arrived at, and it is part of my Engineering in Practice series, where I document the decisions and the reasoning behind real projects rather than the finished result alone.

The implementation lives in keycloak-modern-auth, the companion repository that evolves alongside these articles.

From customization to architecture

In the earlier work, the goal was simple: customize Keycloak. Replace the default login screen with a custom design, then do the same for the emails.

That's perfectly adequate when you have one application and one visual identity. But real systems grow.

You end up with multiple applications, multiple brands, several environments, or a few products sharing one identity provider — and each of them wants its own login experience and its own email branding.

At that point, duplicating templates and CSS across themes stops being convenient and starts being a liability:

theme-a/
├── login/
│   ├── template.ftl
│   └── resources/css/login.css
└── email/
    ├── html/template.ftl
    └── messages/

theme-b/
├── login/
│   ├── template.ftl        ← same file, second copy
│   └── resources/css/login.css
└── email/
    ├── html/template.ftl
    └── messages/

At two themes this looks harmless.

Then someone asks to change the border radius, or the input height, or the focus ring — and you have to remember every theme that contains a copy, and update them consistently.

Duplication that started as convenience has become an architectural problem.

The idea: a reusable base theme

Instead of treating every Keycloak theme as an isolated implementation, I wanted a common layer underneath them:

               Base theme
                    │
         ┌──────────┴──────────┐
         │                     │
   Application A         Application B
         │                     │
     overrides             overrides

The base theme holds the authentication design. Derived themes hold only what makes them different.

This gives two properties that matter:

Reuse, because the shared templates and stylesheets exist in exactly one place.
Customization, because a derived theme can still override the parts that genuinely need to change.

It's the same instinct as inheritance in code: put the common behaviour in the base, specialize where necessary.

The interesting part is that Keycloak already gives you the mechanism — you just have to use it deliberately.

How Keycloak actually resolves themes

A theme declares its parent in theme.properties:

parent=modern.base

That single line is doing more than it looks like, because Keycloak resolves the four kinds of theme content by four different rules — and knowing which is which is most of the battle.

Properties merge vertically.

A child's theme.properties is layered over its parent's. Anything the child doesn't set, it inherits. This is the mechanism that makes token overriding work at all.

Templates resolve child-first, and whole-file.

If the child ships template.ftl, its version is used entirely; if it doesn't, the parent's is used entirely. There is no partial override, no block merging.

You inherit a template or you replace it — which is a good reason to keep base templates generic enough that nobody needs to replace them.

Resources resolve per file.

Drop a file at the same relative path and it shadows the parent's. This is how a child theme swaps img/logo.svg without touching a single line of CSS.

import= reaches sideways.

Inheritance runs vertically, from child to parent, within one theme type.

But a login theme and an email theme are different types, and both need the same brand colour. import= connects them, so shared values can live in a common theme that both types pull from:

modern.base/login  ←import←  modern.base/common
       ↑ parent                      ↑ parent
    acme/login     ←import←       acme/common

That diagram is the whole architecture.

Vertical arrows are inheritance; horizontal arrows are sharing across types.

In the repository, modern.base is the foundation and acme is a worked example of a child brand — one properties file and a logo.

This is also why I extend Keycloak's theme system rather than editing the built-in themes: the built-ins move underneath you on every upgrade, and you own the diff forever.

What belongs in the base theme

Getting the mechanism right is the easy half.

The harder question is what should actually live in the base — because a base theme that accumulates every possible customization is just a large theme with extra steps.

I settled on a simple rule:

The base owns structure, the child owns identity.

The base theme holds:

design tokens
typography scale
page layout
form and input styling
buttons
alerts and messages
shared assets

It answers the question:

How does the authentication interface work and look by default?

The derived theme holds:

logo
brand colours
favicon
product-specific assets
any genuinely necessary override

It answers a much narrower question:

How does this particular product want to be recognized?

That boundary is what keeps the abstraction honest.

If a child theme starts reaching for the structural layer, that's a signal the base is missing something — not a signal to fork the template.

Design tokens, and the loop that generates them

The piece that makes the split practical is design tokens.

Without them, values scatter through the stylesheet:

.kc-button-primary {
  background: #4f46e5;
}

.kc-input {
  border-color: #d1d5db;
}

Change the brand colour and you are grepping.

With tokens, the values are declared once and consumed everywhere:

:root {
  --kc-color-primary: #4f46e5;
  --kc-color-primary-hover: #4338ca;
  --kc-color-surface: #ffffff;
  --kc-color-text: #111827;
  --kc-color-border: #d1d5db;
  --kc-radius-md: 8px;
  --kc-space-md: 16px;
}

.kc-button-primary {
  background: var(--kc-color-primary);
  border-radius: var(--kc-radius-md);
}

The part I like, though, isn't the CSS.

It's where the values come from.

Rather than hand-writing that :root block, the base template walks the theme's properties and emits a custom property for every key that starts with kcToken, converting camelCase to kebab-case along the way.

So this:

kcTokenColorPrimary=#0d9488

becomes this, at render time:

:root {
  --kc-color-primary: #0d9488;
}

The loop is generic.

It enumerates properties; it doesn't know their names.

That detail carries more weight than it first appears: a child theme that invents:

kcTokenBannerHeight=4rem

gets:

--kc-banner-height

for free, with no change to the template and no change to the base.

The extension point is the properties file, not the code.

The base currently declares 58 tokens plus 24 dark-mode overrides, grouped roughly by colour scheme, surfaces, brand, status colours, typography, shape, spacing and layout.

Dark mode reuses the same variable names inside a prefers-color-scheme block, and only colours are overridden — spacing, radii and typography are shared, because a login form shouldn't change shape when the sun goes down.

Why this matters across brands

Now put inheritance and tokens together.

Two products, one authentication architecture.

The base defines the full token set.

Brand A overrides one line:

kcTokenColorPrimary=#2563eb

Brand B overrides one line:

kcTokenColorPrimary=#7c3aed

The components don't change.

The templates don't change.

The authentication flow certainly doesn't change.

In practice a child theme is a parent=, an import=, a handful of colours, a logo file, and a message bundle entry for the name shown in the admin console:

                Base theme
                    │
            Shared components
                    │
              Design tokens
                    │
         ┌──────────┴──────────┐
         │                     │
      Brand A               Brand B
         │                     │
      Blue UI              Purple UI

This is exactly the reuse I was looking for, and it is worth being precise about why it works:

The tokens are the only public surface between the base and its children. Everything else is implementation detail.

The email theme, where none of this is allowed

Emails are rendered by mail clients, and mail clients are a different century.

No external stylesheets — clients drop <link> entirely.

No CSS custom properties — Gmail strips var(), so the entire mechanism above simply evaporates.

Outlook's Word engine only reliably understands pixels.

Flexbox and grid are out; fixed-width tables are in.

So the same architecture had to arrive by a different route.

In the email theme, tokens are resolved at render time in FreeMarker and interpolated straight into style attributes, with a literal fallback if the property is missing:

<#local colorPrimary = properties.kcTokenColorPrimary!'#4f46e5'>

The design system is identical — same properties, same names, same child overrides.

Only the delivery differs:

the browser resolves variables at paint time
FreeMarker resolves them at send time

That let all seventeen emails share a single template shell, with the body copy arriving as pre-formatted strings from the message bundles, and all 36 shipped language translations preserved.

A child theme rebrands every email it sends by changing the same colour it changed for the login page — because both types import the same common theme.

Keeping overrides intentional

Inheritance is useful.

Unlimited overriding is not.

If every derived theme overrides everything, you have arrived back at duplicated themes with extra indirection.

So the customization boundary has to stay clear, and I find it easier to state as two questions:

The base theme answers: how does authentication look and behave by default?
The derived theme answers: how does this product want to brand it?

Layout, forms, buttons, typography and spacing are the base's responsibility — a child may override them, but doing so should feel like a decision, not a default.

Primary colour, logo, favicon and product-specific assets are the child's responsibility, and always were.

Everything in between deserves a conversation before it gets copied.

Applying this to the repository

keycloak-modern-auth isn't a sample project built to illustrate a finished idea.

It's the actual thing, evolving:

v0.1   Keycloak setup: Reproducible Keycloak + PostgreSQL stack
  ↓
v0.2   Custom login theme
  ↓
v0.3   Custom email theme
  ↓
next   Derived themes, configuration as code

I keep evolving one repository instead of creating a fresh one per experiment, and that's deliberate.

Separate repositories make each example easy to read while hiding the thing I actually care about:

Engineering decisions are incremental. The first implementation is rarely the final architecture.

The honest progression looks more like this:

"It works."
      ↓
"But there's duplication."
      ↓
"Extract the common parts."
      ↓
"Make the design configurable."
      ↓
"Now a brand is twenty lines and a logo."

That's much closer to how a real project moves.

The repository stops being sample code and becomes a record of the architectural evolution — including the steps that were replaced.

The trade-off

A base theme isn't automatically better.

It's another abstraction, and abstractions charge rent.

You now have two artifacts where you had one, and anyone touching the themes has to understand the inheritance relationship before they can safely change anything.

Debugging gets less direct, too: when a style comes from the derived theme it's obvious, and when it comes from the parent — or from a property merged three levels up — you need to know where to look.

Whole-file template resolution has a sharp edge as well, since a child that overrides template.ftl to change one line silently stops inheriting every future improvement to the base.

This is the classic bargain:

You accept some additional complexity in exchange for less duplication and more consistency.

For a single small Keycloak installation, that trade isn't obviously worth it.

For multiple applications or brands, it stops being close.

What I learned

The interesting part of this exercise wasn't writing CSS.

It was noticing the moment customization turned into architecture.

At the start, the question was:

How do I customize Keycloak?

Later it became:

How do I make this customization reusable?

Those are different questions with different answers.

The first produces a working theme.

The second produces a system for producing themes.

The distinction I try to hold onto is this:

Don't introduce an abstraction because it looks elegant. Introduce it when a repeated problem justifies it.

Here, the repeated theme structure and the need for consistent branding across products supplied the justification.

Keycloak's inheritance provided the mechanism, and design tokens provided a clean way to make the visual system both reusable and customizable.

What's next

The base theme is one step, not a destination.

The directions I want to explore next are mostly about everything around the theme rather than the theme itself:

more reusable authentication components
better token organization
multiple derived brands
automated validation so a broken theme fails before it reaches an environment
packaging themes into the image rather than bind-mounting them

Underneath all of that sits a problem I keep running into:

How do you keep Keycloak configuration synchronized across development, staging, qualification and production?

Themes are the visible layer, but realms, clients, roles, mappers and flows are the part that actually drifts.

That's where theme customization stops being a frontend concern and turns into an infrastructure one — and it's what I want to write about next.

Final thoughts

What started as a Keycloak customization is slowly turning into a small authentication platform.

The lesson isn't that every Keycloak project needs a sophisticated base theme.

It's that architecture should follow the problems you actually hit.

Start simple.

Notice the duplication.

Learn the extension points the platform already gives you.

Extract only the parts that are genuinely reusable.

Then introduce the abstraction.

The implementation continues to evolve in keycloak-modern-auth, alongside this series.

This is engineering in practice: not designing the perfect architecture upfront, but improving it as the real problems come into focus.

OAuth 2.0, OpenID Connect, and Keycloak: Understanding Modern Authentication

Ismail ZAHIR — Fri, 07 Aug 2026 14:05:16 +0000

OAuth 2.0, OpenID Connect, JWT, access tokens, refresh tokens, Keycloak. These get mentioned in the same breath so often that they blur into a single vague thing called "authentication." They're not one thing. Each solves a distinct problem, and the boundaries between them are sharper than most introductions suggest.

That blurring has practical consequences. It's why teams send ID tokens to APIs, enforce permissions in the frontend, or reach for a flow that was deprecated years ago — not from carelessness, but because nobody drew the lines clearly in the first place.

So let's draw them. We'll take each piece in turn, then follow a real login through an Angular app, a Keycloak realm, and a Spring Boot API to see where each one actually does its work.

Authentication is not authorization

These two get used interchangeably in conversation, and it causes real bugs.

Authentication answers "who are you?" You type a password, a fingerprint gets scanned, a magic link gets clicked. At the end of it, the system knows your identity.

Authorization answers "what are you allowed to do?" An admin can manage users. A doctor can open a patient record. A patient can only see their own appointments.

The ordering matters: you can't decide what someone is allowed to do until you know who they are. Every system does authentication first, authorization second, even when the code makes it look like one step.

Why OAuth 2.0 exists

Say your application needs to read files from a user's Google Drive.

The naive approach is to ask for their Google password and log in on their behalf. Hopefully the problem is obvious — you now store a credential that unlocks their email, their photos, their entire account, and you've given yourself unlimited access when you only needed to read one folder.

OAuth 2.0 exists to avoid exactly this. The user authenticates directly with Google. Google asks whether they want to grant your app access to Drive. If they agree, your app receives a token scoped to that specific permission. You never see the password, and the user can revoke your access at any time without changing it.

So OAuth 2.0 is an authorization framework: it lets an application act on a user's behalf without ever holding their credentials.

The four roles

OAuth defines four participants, and it's worth being able to name them because every OAuth error message assumes you can.

Resource Owner — the user. They own the data.
Client — the application asking for access. Your Angular SPA, a mobile app, a background service.
Authorization Server — authenticates the user, gets their consent, issues tokens. This is Keycloak.
Resource Server — the API holding the protected data. Your Spring Boot or ASP.NET Core backend, which validates the token before responding.

What OpenID Connect adds

Here's the part that trips people up: OAuth 2.0 is not an authentication protocol.

An access token tells an API "the bearer of this token is allowed to do X." It doesn't reliably tell your application who the user is. Plenty of teams worked around this by calling some vendor-specific "get me the user" endpoint after the OAuth dance, and every vendor did it differently.

OpenID Connect (OIDC) standardises that. It's a thin identity layer on top of OAuth 2.0, and its main contribution is the ID Token — a JWT describing the authenticated user, with predictable claim names:

sub — a stable unique identifier for the user
name, given_name, family_name
email, email_verified
preferred_username

OIDC also standardises the discovery document, the userinfo endpoint, and logout. Because of it, an OIDC client library works against Keycloak, Auth0, Okta, or Azure AD with nothing more than a URL change.

Short version: OAuth 2.0 delegates authorization. OpenID Connect adds authentication.

Where Keycloak fits

Keycloak is an open-source Identity and Access Management server that implements both specs. Instead of writing your own login page, password hashing, session handling, MFA, and social login, you delegate all of it and your apps just trust Keycloak.

One note before going further: Keycloak has changed a lot. The old Java adapters (keycloak-spring-boot-starter and friends) were deprecated years ago and have since been removed, so on Keycloak 26+ you secure a Spring Boot API with Spring Security's own OAuth 2.0 Resource Server support and nothing Keycloak-specific on the backend at all. If a tutorial tells you to add a Keycloak adapter dependency, it predates the Quarkus distribution and you can close the tab.

A few Keycloak-specific concepts you'll meet immediately:

Realms. A realm is an isolated tenant — its own users, roles, clients, and signing keys. Users in realm A don't exist in realm B. A common pattern is one realm for your staff and another for your customers, since they rarely share anything.

Clients, public and confidential. Every application that talks to Keycloak is registered as a client. A confidential client can keep a secret (a backend service). A public client can't — an Angular SPA ships its entire source to the browser, so anything you call a "secret" there is just a string anyone can read in DevTools. SPAs and mobile apps must be public clients, which is precisely why PKCE exists.

Realm roles vs client roles. Realm roles are global (admin, doctor). Client roles are scoped to one application (billing-app:invoice-manager). If two apps in your realm both need a role called manager meaning different things, that's your signal to use client roles.

The discovery endpoint. Every realm exposes its configuration at:

https://<host>/realms/<realm>/.well-known/openid-configuration

Open it in a browser. You get every endpoint URL, the supported flows, and the JWKS URI where your backend fetches public keys. Most client libraries need only this one URL. It's also the fastest way to confirm a realm name is spelled the way you think it is.

The Authorization Code Flow with PKCE

For browser and mobile apps, this is the flow to use. The Implicit Flow you may still see in older tutorials is deprecated — don't.

Let's walk through it with an Angular app in front of a Spring Boot API.

Step 1 — the app notices you're not logged in. No valid token in memory, so it prepares to redirect.

Step 2 — PKCE setup, then redirect. Before going anywhere, the app generates a random string called the code_verifier, hashes it with SHA-256, and base64url-encodes the result into a code_challenge. The verifier stays in the browser. Only the challenge goes to Keycloak, along with a state parameter (random, and checked on the way back — that's your CSRF protection) and the redirect URI.

Step 3 — you log in. Keycloak renders its login page, checks your credentials, runs MFA if configured, and redirects back to your app with a short-lived authorization code in the URL. Worth emphasising: this is not a token. On its own it's useless.

Step 4 — the exchange. The app POSTs the code back to Keycloak's token endpoint, this time including the original code_verifier. Keycloak hashes it and compares against the challenge from step 2. Match, and you get an access token, an ID token, and a refresh token.

This is the whole point of PKCE. Authorization codes travel through the browser's address bar, and on mobile through OS-level URL handlers — both interceptable. Without PKCE, an attacker who steals the code can redeem it themselves. With PKCE they'd also need the verifier, which never left the original app. It's a proof that whoever redeems the code is whoever started the flow.

Step 5 — calling the API. The app attaches the access token to requests:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...

Step 6 — the API validates. Spring Boot checks the token's signature, issuer, audience, and expiry, then serves the data — or returns 401.

Here's the whole exchange in one picture:

The Authorization Code Flow with PKCE, end to end

The three tokens

Access token. Presented to APIs. Contains the subject, roles, scopes, and an expiry. Keycloak defaults to a 5-minute lifespan, and that's a reasonable default — a leaked token stops being useful quickly.

A word on scopes, since they're easy to confuse with roles. A scope is what the application asked permission to do; a role is what the user is allowed to do. When your Angular app requests openid profile email, it's saying "I want an ID token, plus the user's profile and email claims" — and the user's consent screen reflects that. In Keycloak these are configured as client scopes, which control both the claims that land in the token and the roles included in it. The distinction matters because a token can carry a powerful role and still be scoped too narrowly for what your API wants to do with it — the API should check both.

ID token. For the client application only, to answer "who is logged in?" Use it to display a name and avatar. Do not send it to your API as a credential; it isn't scoped for that and a correctly configured API will reject it anyway.

Refresh token. Longer-lived, used to get a new access token without sending the user back through login. Turn on refresh token rotation — each refresh invalidates the previous token. If a rotated token gets replayed, Keycloak sees a token that's already been used and can kill the whole session. For public clients this isn't optional in my view; it's the only real protection a token you can't keep secret has.

What's actually inside an access token

All of this stays abstract until you decode one. A Keycloak access token is a JWT: three base64url segments separated by dots, header.payload.signature. Paste one into jwt.io and you get something like this.

The header names the algorithm and, importantly, the key:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "sBv3qHhL2XmR7pKdN9fYcW1uEjTgA4Zo"
}

And the payload:

{
  "exp": 1754563200,
  "iat": 1754562900,
  "jti": "3f1c7a92-8d4e-4b16-9c05-7ae2f0b8d331",
  "iss": "https://auth.example.com/realms/healthcare",
  "aud": ["billing-api", "account"],
  "sub": "9b2d41f7-6c8a-4e3b-bf19-2d05c7e4a8f1",
  "typ": "Bearer",
  "azp": "web-app",
  "sid": "c4a8e102-5f37-49bd-8e6a-1b93d70cf254",
  "scope": "openid profile email",
  "realm_access": {
    "roles": ["doctor", "offline_access"]
  },
  "resource_access": {
    "billing-api": {
      "roles": ["invoice-manager"]
    }
  },
  "preferred_username": "ismail",
  "email": "ismail@example.com",
  "email_verified": true
}

Everything discussed so far is visible here. iss is the realm. aud lists who this token is for. sub is the stable user ID — note that it's a UUID, not the username, which is why you should key your own database on sub and never on preferred_username or email (both can change). realm_access.roles and resource_access are the realm and client roles from earlier, arriving in exactly the shape Keycloak defines. azp is the client that requested the token.

One thing worth internalising: this payload is base64-encoded, not encrypted. Anyone holding the token can read every claim in it. That's fine for roles and usernames. It is not fine for anything you'd call confidential, so resist the temptation to stuff internal identifiers or business data into custom claims.

Where do you store tokens?

Every tutorial says "store them securely" and moves on. That phrase hides the single most argued-about decision in frontend auth, so let's be honest about the options.

localStorage is the easy path and survives page refreshes. It's also readable by any JavaScript on the page, which means one XSS bug — yours or a compromised npm dependency's — hands over every token you hold.

In-memory only removes the XSS smash-and-grab, since there's nothing persisted to steal. The cost is that a refresh logs the user out, unless you use silent renewal via a hidden iframe, which third-party cookie restrictions are steadily breaking.

Backend-for-Frontend (BFF) keeps tokens on a small server-side layer and gives the browser only an httpOnly cookie. The browser never touches a token. This is the most secure option and it's where the industry is heading — but it's real infrastructure, and it brings CSRF back into scope.

There's no universally correct answer. Pick deliberately based on what your app protects, and know what you're trading away. Medical records and a marketing dashboard don't warrant the same call.

Validating tokens on the backend

"Validate the token" also deserves unpacking, because getting it partly right is a genuine vulnerability. Your API must check:

Signature — verified against Keycloak's public keys from the JWKS endpoint. Libraries fetch and cache these automatically; make sure yours actually does.
iss — the issuer matches your realm URL exactly.
aud — the audience includes your API. This is the one people skip. Without it, a token issued for a different client in the same realm will sail straight through your validation, because the signature is perfectly valid. It just wasn't meant for you.
exp — not expired.

Any decent OIDC library does all four once configured. The failure mode is almost always a missing or wrong aud, so check that first when something feels off.

Key rotation, and why you shouldn't hardcode a public key

Keycloak rotates its realm signing keys — on a schedule, or whenever you rotate them manually after an incident. This is exactly what the kid in the token header is for: it identifies which key signed this particular token, so old tokens stay verifiable while new ones are signed with the new key.

Your API should therefore fetch keys from the JWKS endpoint and cache them, refetching when it sees a kid it doesn't recognise. Spring Security does this out of the box when you point it at the issuer URI. What you must not do is copy a PEM public key out of the admin console and paste it into application.yml — I've seen it, it works fine for months, and then every request in production returns 401 the morning after a key rotation with no obvious cause. Configure the issuer, let the library handle the rest.

Four things people get wrong

"OAuth 2.0 is authentication." It isn't. It's an authorization framework. Authentication comes from OpenID Connect layered on top.

"JWT and OAuth are the same thing." OAuth defines how authorization is delegated. JWT is one possible format for the tokens involved. OAuth works fine with opaque tokens, and plenty of providers use them.

"The frontend decides permissions." The frontend hides buttons the user can't use. That's UX, not security — anyone can open DevTools and call your API directly. The backend enforces authorization, always, no exceptions.

"Long-lived access tokens improve the user experience." They improve it right up until one leaks and stays valid for a week. Short access tokens plus rotating refresh tokens plus automatic renewal gives you the same seamless experience without the exposure window.

Practical checklist

Authorization Code Flow with PKCE for browser and mobile apps. Never Implicit.
Access token lifespan in minutes, not hours.
Refresh token rotation on for public clients.
Validate signature, iss, aud, and exp on every API request.
Realm roles for cross-application concepts, client roles for app-specific ones.
HTTPS everywhere in production — a bearer token over plain HTTP is a password over plain HTTP.
Don't build your own auth server. Really.

Wrapping up

Most of the confusion around this stack disappears once each piece has one clear job:

OAuth 2.0 delegates authorization. OpenID Connect adds authentication and a standard identity format. Keycloak implements both and manages the users. Access tokens authorize API calls, ID tokens identify the user to the app, and refresh tokens keep the session alive without repeated logins.

Once that clicks, Keycloak's configuration screens stop being a maze and start being a map of the protocol.

Next in this series: making Keycloak stop looking like Keycloak. We'll build a custom login theme from scratch — FreeMarker templates, CSS custom properties for multi-brand support, and full RTL for Arabic, which is where things get genuinely interesting.

— Ismail

Why I Validate Angular Compatibility Using the Published npm Package (Not the Source Code)

Ismail ZAHIR — Fri, 31 Jul 2026 00:52:23 +0000

I just published a new article on a lesson I learned while maintaining my open-source Angular library.

I used to validate compatibility against my workspace and dist/, but eventually realized that wasn't what developers actually install from npm.

That led me to redesign the CI pipeline to validate the published package across multiple Angular versions instead.

The article covers:

Why testing dist/ isn't enough
Angular partial compilation and the linker
Why type-checking alone can miss compatibility issues
Validating the packaged artifact with npm pack
Building a compatibility matrix for Angular 17–22

If you maintain an Angular library (or any npm package), I'd love to hear how you approach compatibility testing.

📖 Why I Validate Angular Compatibility Using the Published npm Package (Not the Source Code)

Medium link

I Stopped Copy-Pasting the Same Angular ApiService. Here’s What I Built Instead

Ismail ZAHIR — Sun, 26 Jul 2026 12:16:23 +0000

Every Angular project I've worked on had an api.service.ts.

Different repository.

Different company.

Same file.

It always started as a thin wrapper around HttpClient, then gradually accumulated more responsibility: versioning, authentication, retry logic, loading indicators, error handling.

By the fourth project, I wasn't writing it anymore.

I was copying it.

And not carefully. I'd paste the file in, then spend the next hour re-fixing the same three bugs I'd already fixed in the last project — because I'd never written them down anywhere, just patched them in place and moved on.

That was the moment I realized it wasn't repeated code anymore.

A pattern repeated four times isn't a pattern anymore. It's a missing dependency.

So I extracted it, made the hard-coded parts configurable, and published it as @ismailza/ngx-api-client.

This article isn't really about the library. It's about the four decisions that turned a file I was slightly embarrassed to copy-paste into something I'd defend in a code review.

The actual gap

HttpClient is a good HTTP client. That's genuinely all it claims to be, and people keep being disappointed that it isn't more.

HttpClient gives you a request. It does not give you a policy.

Every application still has to answer:

Where does the base URL come from, and how does the API version get into it?
What turns a failed response into something a component can actually render?
Which requests are safe to retry, and how long do you wait before you do?
How does a global progress bar find out that anything is in flight?

Most applications answer those questions inside an ApiService that grows organically over time until nobody wants to touch it anymore. I wanted those decisions to live in one place — and to see, at a glance, how a request actually moves through the system:

" width="800" height="518">

A request leaves the component, passes through ApiService, then through an ordered chain — your auth interceptor, retry with jitter, your backend, error normalization, an optional success step — before looping back. Loading state and error handling hang off that chain as pluggable pieces, not built-in opinions.

The first mistake I kept repeating was hard-coding the version

`${baseUrl}/api/v1${endpoint}`

It works...

...until your backend decides to version using:

headers
query parameters
media types
dates
or no URL versioning at all

Instead of treating versioning as string concatenation, I modeled it as a configurable strategy.

provideApi({
  baseUrl: 'https://api.example.com',
  prefix: 'api',
  version: 2,
  versioning: 'url'
});

The same configuration can instead produce:

/api/v2/orders
/api/orders?v=2
X-API-Version: 2
Accept: application/vnd.api.v2+json

without changing application code.

Two rules became surprisingly important:

A header or query parameter the caller set explicitly is never overwritten by the versioning strategy. If you pass Api-Version yourself, you meant it. A library that silently clobbers explicit caller input is a library you cannot debug.

Versions should accept strings as well as numbers. This only became obvious after integrating with a backend that versioned by date:

provideApi({
  baseUrl: 'https://api.example.com',
  version: '2024-01-01',
  versioning: { strategy: 'header', headerName: 'Api-Version' },
});

If I had typed it as number — which is what my copy-pasted version implicitly assumed — the whole abstraction would have been useless for the exact API that motivated making it configurable.

Then I realized my biggest problem wasn't requests — it was failures

HTTP failures rarely look the same.

Sometimes you get a proper RFC 9457 Problem Details response. Well-behaved, easy.

Sometimes nginx sends back plain text, because it answered before your app ever saw the request.

Sometimes the network disappears completely and the status is simply 0.

Components shouldn't need three different code paths for those three situations. Everything gets normalized into one shape:

interface ApiError {
  type: string; // RFC 9457 problem type URI
  title?: string; // 'Bad Request'
  status: number; // 0 for a network failure
  detail: string; // safe to show the user
  instance?: string; // path that produced it
  code?: string; // machine-readable, e.g. 'VALIDATION_ERROR'
  timestamp: string;
  traceId?: string; // from the body, else the X-Trace-Id header
  errors?: { field: string; message: string }[];
}

Once a component receives this, it no longer cares where the failure originated.

Two things worth stating out loud:

Branch on code, never on detail. detail is prose meant for a human. It gets reworded, translated, and A/B tested. The day somebody changes "Invalid credentials" to "Incorrect email or password," every if (error.detail === "Invalid credentials") in your codebase silently stops working.

if (error.code === "INVALID_CREDENTIALS")

code is the contract. detail is for humans.

traceId falls back to the X-Trace-Id header. Nine times out of ten the useful correlation ID is in the response headers and the error body is empty. If your error model discards headers, every production bug report starts with "can you reproduce it?"

I almost shipped a toast notification. I'm glad I didn't

That was the easiest feature to add, and the hardest to leave out on purpose.

The moment a library renders anything, it has an opinion about your design system, your i18n setup, and your accessibility strategy — three things it cannot possibly know. So the library only exposes an error handler that applications replace:

@Injectable()
export class ToastApiErrorHandler extends ApiErrorHandler {
  private readonly toast = inject(MyToastService);
  private readonly router = inject(Router);

  override handle(error: ApiError): void {
    this.toast.error(error.detail, { title: error.title });

    if (error.status === 403) {
      this.router.navigate(['/forbidden']);
    }
  }
}

The HTTP layer reports problems. The application decides how users experience them.

The practical payoff: peer dependencies are @angular/core, @angular/common, and rxjs. Nothing else. A library sitting in your HTTP layer has no business pulling a UI kit into your bundle.

One honest caveat I put in the README rather than hiding: the default handler passes the whole ApiError to Angular's own ErrorHandler, which logs it. If your API puts sensitive data in detail or instance, register your own handler instead of relying on the default. Defaults should be safe, and where they can't be, they should say so.

One decision surprised every reviewer — I don't register my own interceptors

provideHttpClient(
  withInterceptors([
    retryInterceptor,
    apiErrorInterceptor,
    apiSuccessInterceptor
  ])
);

This is the one I had to defend hardest in review. At first glance it looks like boilerplate the library should absorb. It isn't, because order matters and only you know what else is in the chain:

An auth interceptor has to come first, so a retried request picks up a fresh token instead of replaying the expired one.
retryInterceptor has to come before apiErrorInterceptor, so your error handler only ever sees failures that survived every retry. Get this backwards and users see three toasts for one eventually-successful request.

If the library silently injected interceptors at a position it chose, that position would be wrong in some app, and debugging it would mean reading my source. Making the ordering explicit costs one line and buys the ability to reason about the chain.

Retry is harder than it looks

retry(3)

That's five characters and it isn't enough. A few rules that all turned out to matter:

Don't retry POST requests by default. It isn't idempotent — replaying it can create two orders. Callers opt in per request when they know their endpoint is safe.
Respect the server's Retry-After header. On a 429, the server has told you exactly when to come back; your backoff curve is a guess, the header isn't.
Retry only transient failures: 408, 429, 500, 502, 503, 504. Retrying a 400 is just asking the server to reject you four times.
Use exponential backoff — and always add jitter.

const exponentialDelay = config.initialDelay * Math.pow(config.multiplier, retryIndex - 1);
const jitter = exponentialDelay * Math.random() * 0.3;
return timer(exponentialDelay + jitter);

Without jitter, every client that hit your struggling backend at the same moment retries at the same moment, and again two seconds later, and again four seconds after that. You've built a synchronized load test against a server that's already failing. A little randomness breaks the lockstep.

Two smaller decisions I'm glad I made

Per-request configuration travels through HttpContext, not service state.

this.api.get<LegacyOrder>('/orders', { version: 1 });

this.api.post('/analytics/event', payload, {
  retry: false,
  skipErrorHandler: true,
  showLoader: false,
});

One request can disable retries, skip global error handling, or bypass loading indicators without touching any concurrent request. A mutable flag on the service that the next interceptor reads would be a race condition waiting for two calls to happen at once.

Loading state is a counter, not a boolean.

@Injectable({ providedIn: 'root' })
export class ApiLoadingService {
  private readonly activeRequests = signal(0);
  readonly loading = computed(() => this.activeRequests() > 0);
}

A boolean flickers: three requests start, the fastest one finishes, and the progress bar disappears while two are still running. A counter with a computed() signal doesn't. It's a five-line class, and it's the single most-copied snippet from every version of this file I ever wrote.

What I would tell myself before starting

Don't extract after the first implementation. Extract after the fourth. Three implementations taught me which parts actually varied — the version transport, the error presentation — and which parts never did. Abstracting after one project would have produced configuration options nobody needed, and hard-coded the things that mattered.

Write the README before the code you're unsure about. Every section I struggled to explain was a section where the API was wrong. The interceptor-ordering paragraph took three rewrites, and the third is what convinced me not to auto-register them.

Be honest about compatibility. Mine says: developed and tested against Angular 21; the declared floor of >=17 reflects the APIs used — signals and functional interceptors — rather than a range the CI matrix currently covers. Less impressive than claiming full 17–21 support. Also true, which matters more.

Closing thoughts

Open source isn't about writing perfect software. It's about taking something you've solved the same way four times, pulling out the pattern, and inviting other people to tell you where it's wrong.

I'm not sure this library is done evolving. But the ideas behind it — versioning as a strategy instead of string concatenation, one error shape no matter what the backend sends back, keeping presentation out of the HTTP layer, and making interceptor order something you choose rather than something the library hides from you — are decisions I'd make again.

I'm curious how other Angular teams handle this. Do you build your own API layer, or lean directly on HttpClient? Which of these decisions would you have made differently?

This is my first technical article, and I'd genuinely love feedback. If you think one of these design decisions is wrong — or you've solved the problem differently — I'd enjoy hearing your perspective.

The library is on npm as @ismailza/ngx-api-client, and the source is on GitHub if you'd like to explore the implementation.

— Ismail