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

This is optional but recommended for better performances and security.

{% 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 Mode" %} 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="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:

{% 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 %}