React Router

Instaling

npm install oidc-spa zod

Note: Zod is optional but highly recommended. Writing validators manually is error-prone, and skipping validation means losing early guarantees about what your auth server provides. You can use another validator though, it doesn't have to be Zod.

If you’re not using Vite and you can’t edit your app’s entry file, run oidcEarlyInit() in the src/oidc.ts.

vite.config.ts

import { defineConfig } from "vite";
import { oidcSpa } from "oidc-spa/vite-plugin";

export default defineConfig({
    plugins: [
        // ...
        oidcSpa()
    ]
});

Pick this approach if:

You're not in a Vite project and
Your app has a single client entrypoint.

Let's assume your app entrypoint is src/main.ts.

First, rename it to src/main.lazy.ts.

mv src/main.ts src/main.lazy.ts

Then create a new src/main.ts file:

src/main.ts

import { oidcEarlyInit } from "oidc-spa/entrypoint";

const { shouldLoadApp } = oidcEarlyInit({
    BASE_URL: "/" // The path where your app is hosted. You can also pass it later to createOidc().
});

if (shouldLoadApp) {
    // Note: Deferring the main app import adds a few milliseconds to cold start,
    // but dramatically speeds up auth. Overall, it's a net win.
    import("./main.lazy");
}

If you’re not using Vite and you can’t edit your app’s entry file, run oidcEarlyInit() in the same module where you call createOidc().

src/oidc.ts

import { oidcEarlyInit, } from "oidc-spa/entrypoint";
import { oidcSpa } from "oidc-spa/react-spa";

// Should run as early as possible.  
oidcEarlyInit({ 
   BASE_URL: "/" // The path where your app is hosted
});

export const { /* ... */ } = oidcSpa./*...*/

Learning from the example

You're going to be cloning this example:

https://example-react-router-framework.oidc-spa.dev/example-react-router-framework.oidc-spa.dev

React Router v7 has three modes pick the one for you:

npx gitpick keycloakify/oidc-spa/tree/main/examples/react-router-declarative rr-declarative-oidc
cd rr-declarative-oidc
# You can use our preconfigured Keycloak, Auth0, or Google OAuth test accounts
cp .env.local.sample .env.local
npm install
npm run dev

# Start exploring with: src/oidc.ts

oidc-spa/examples/react-router-declarative at main · keycloakify/oidc-spaGitHub

npx gitpick keycloakify/oidc-spa/tree/main/examples/react-router-data rr-data-oidc
cd rr-data-oidc
# You can use our preconfigured Keycloak, Auth0, or Google OAuth test accounts
cp .env.local.sample .env.local
npm install
npm run dev

# Start exploring with: src/oidc.ts

oidc-spa/examples/react-router-data at main · keycloakify/oidc-spaGitHub

Enabling SPA mode

This is non optional. React Router Framework does not expose the primitives to enable solution like oidc-spa to provide a full stack story. (You may want to give TanStack Start a try)

react-router.config.ts

import type { Config } from "@react-router/dev/config";

export default {
    ssr: false
} satisfies Config;

The example

npx gitpick keycloakify/oidc-spa/tree/main/examples/react-router-framework rr-framework-oidc
cd rr-framework-oidc
# You can use our preconfigured Keycloak, Auth0, or Google OAuth test accounts
cp .env.local.sample .env.local
npm install
npm run dev

# Start exploring with: src/oidc.ts

oidc-spa/examples/react-router-framework at main · keycloakify/oidc-spaGitHub

Now that authentication is handled, there’s one last piece of the puzzle: your resource server, the backend your app will communicate with.

This can be any type of service: a REST API, tRPC server, or WebSocket endpoint, as long as it can validate access tokens issued by your IdP.

If you’re building it in JavaScript or TypeScript (for example, using Express), oidc-spa provides ready-to-use utilities to decode and validate access tokens on the server side.

You’ll find the full documentation here:

Backend Token Validation

PreviousTanStack Router NextAngular

Last updated 4 days ago

Was this helpful?