auth0-spa-js

Prerequisites

• Modern browser with ES2017+ support

• npm or yarn (or use CDN for no-bundler apps)

• Auth0 account with a Single Page Application configured

• If you don't have Auth0 set up, see auth0-quickstart

Quick Start Workflow

1. Install SDK

npm install @auth0/auth0-spa-js

Or via CDN (no bundler). Run this to get the latest version, then use it in your HTML:

VERSION=$(npm view @auth0/auth0-spa-js version)

2. Configure Auth0

For automated setup with Auth0 CLI, see Setup Guide for complete scripts.

For manual setup, create .env (Vite):

VITE_AUTH0_DOMAIN=your-tenant.auth0.com
VITE_AUTH0_CLIENT_ID=your-client-id

In Auth0 Dashboard, set for your Single Page Application:

• Allowed Callback URLs: http://localhost:5173

• Allowed Logout URLs: http://localhost:5173

• Allowed Web Origins: http://localhost:5173

3. Initialize Auth0 Client

import { createAuth0Client } from '@auth0/auth0-spa-js';

const auth0 = await createAuth0Client({
 domain: import.meta.env.VITE_AUTH0_DOMAIN,
 clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
 authorizationParams: {
 redirect_uri: window.location.origin
 }
});

// Handle redirect callback after login
const query = new URLSearchParams(window.location.search);
if ((query.has('code') || query.has('error')) && query.has('state')) {
 await auth0.handleRedirectCallback();
 window.history.replaceState({}, document.title, window.location.pathname);
}

4. Add Login / Logout

Agent instruction: Before adding new UI elements, search the project for existing click handlers for login, logout, sign-in, or sign-out buttons. If existing handlers are found, hook the Auth0 code into them without modifying the existing UI. Only create new buttons if no existing handlers are found.

// Login
document.getElementById('login-btn').addEventListener('click', async () => {
 await auth0.loginWithRedirect();
});

// Logout
document.getElementById('logout-btn').addEventListener('click', () => {
 auth0.logout({
 logoutParams: { returnTo: window.location.origin }
 });
});

// Update UI based on auth state
const isAuthenticated = await auth0.isAuthenticated();
if (isAuthenticated) {
 const user = await auth0.getUser();
 console.log(user.name, user.email);
}

5. Get Access Tokens for API Calls

const accessToken = await auth0.getTokenSilently();

const response = await fetch('https://your-api.example.com/data', {
 headers: { Authorization: `Bearer ${accessToken}` }
});

6. Build & Verify

Agent instruction: After completing the integration, build the project to verify it compiles successfully:

npm run build

If the build fails, analyze the error output and fix the issues. Common integration build failures include:

• Module not found: Missing npm install @auth0/auth0-spa-js — run the install command

• Cannot find name 'import.meta': TypeScript target too low — set "target": "ES2020" or higher in tsconfig.json

• createAuth0Client is not a function: Wrong import path or CDN usage without bundle step

• Env vars undefined at runtime: Vite requires VITE_ prefix; webpack/CRA requires REACT_APP_ prefix

Re-run the build after each fix. Track the number of build-fix iterations.

Failcheck: If the build still fails after 5–6 fix attempts, stop and ask the user using AskUserQuestion: "The build is still failing after several fix attempts. How would you like to proceed?"

• Let the skill continue fixing iteratively — continue the build-fix loop for another 5–6 attempts

• Fix it manually — show the remaining errors and let the user resolve them

• Skip build verification — proceed without a successful build

Common Mistakes

Mistake Fix Callback URL port mismatch (e.g., localhost:3001 vs localhost:5173) Match Allowed Callback URLs exactly to your dev server port in Auth0 Dashboard client_secret in SPA code SPAs must never have a client secret — remove it. Auth0 sets auth method to None for SPA apps Tokens stored in localStorage Use in-memory storage (default) or sessionStorage. Never localStorage — XSS risk getTokenSilently() throws login_required on page refresh Add your app origin to Allowed Web Origins in Auth0 Dashboard handleRedirectCallback() not called after redirect Must call after login redirect to exchange the auth code; without this the URL params persist and re-trigger Domain includes https:// prefix Auth0 domain should be hostname only: your-tenant.auth0.com, not https://your-tenant.auth0.com loginWithPopup() called from async init code Popups must be triggered directly from a user gesture (click handler). Never call from init or page load code Using Auth0Provider from @auth0/auth0-react in Vanilla JS For Vanilla JS, use createAuth0Client() directly — no provider component needed