icon
sign-posts-wrench

Installation

{% hint style="info" %} 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. {% endhint %}

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

Add the lib to your dependencies

{% tabs %} {% tab title="npm" %}

npm install oidc-spa

{% endtab %}

{% tab title="yarn" %}

yarn add oidc-spa

{% endtab %}

{% tab title="pnpm" %}

pnpm add oidc-spa

{% endtab %}

{% tab title="bun" %}

bun add oidc-spa

{% endtab %} {% endtabs %}

Editing your App entrypoint

To protect tokens against supply-chain attacks and XSS, oidc-spa must run some initialization code before any other JavaScript in your app.

This design provides much stronger security guarantees than any other adapter, and it also delivers unmatched login performance. More details here.

{% tabs %} {% tab title="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:

{% code title="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");
}

{% endcode %} {% endtab %}

{% tab title="TanStack Start" %} Comming soon, follow progress. {% endtab %}

{% tab title="React-Router Framework" %} You can skip this for now. It will be explained in the dedicated setup guide:

{% content-ref url="setup-guides/react-router.md" %} react-router.md {% endcontent-ref %} {% endtab %}

{% tab title="Angular" %} First rename your entry point file from main.ts to main.lazy.ts

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

Then create a new main.ts file:

{% code title="main.ts" %}

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

{% endcode %} {% endtab %}

{% tab title="CRA" %} {% hint style="warning" %} Create React App is deprecated. Consider using Vite instead. {% endhint %}

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:

{% code title="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");
}

{% endcode %} {% endtab %} {% endtabs %}