Installation

Before starting be aware that oidc-spa is not suited for Next.js.

If you are using Next the closer alternative is to use NextAuth.js (with the Keycloak adapter if you are using Keycloak). See this guide.

If you're having issues don't hesitate to reach out on Discord!

Add the lib to your dependencies

npm

npm install oidc-spa

yarn

yarn add oidc-spa

pnpm

pnpm add oidc-spa

bun

bun add oidc-spa

Editing your App entrypoint

This is optional but recommended for better performances and security.

Vite

First rename your entry point file from main.tsx (or main.ts) to main.lazy.tsx

mv src/main.tsx src/main.lazy.tsx

Then create a new main.tsx file:

src/main.tsx

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

const { shouldLoadApp } = oidcEarlyInit({
    freezeFetch: true,
    freezeXMLHttpRequest: true,
    freezeWebSocket: true
});

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");
}

TanStack Start

Comming soon, follow progress.

React-Router Framework Mode

You can skip this for now. It will be explained in the dedicated setup guide:

React Router

Create-React-App

First rename your entry point file from main.tsx (or main.ts) to main.lazy.tsx

mv src/index.tsx src/index.lazy.tsx

Then create a new index.tsx file:

src/index.tsx

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

const { shouldLoadApp } = oidcEarlyInit({
    freezeFetch: true,
    freezeXMLHttpRequest: true,
    freezeWebSocket: true
});

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("./index.lazy");
}