npx skills add ...
npx skills add auth0/agent-skills --skill auth0-spa-js
npx skills add auth0/agent-skills --skill auth0-spa-js
Use when adding Auth0 login or token management to a Vanilla JS, Svelte, or framework-agnostic SPA. Integrates @auth0/auth0-spa-js — use when there is no framework-specific Auth0 SDK available.
Add authentication to any browser-based single-page application using @auth0/auth0-spa-js — the low-level Auth0 SDK for Vanilla JS, Svelte, SolidJS, and any SPA not using React, Angular, or Vue.
Agent instruction: Before providing SDK setup instructions, fetch the latest release version by running:
Use the returned version in all dependency lines instead of any hardcoded version below. If the command fails, fall back to checking https://github.com/auth0/auth0-spa-js/releases.
Or via CDN (no bundler). Run this to get the latest version, then use it in your HTML:
For automated setup with Auth0 CLI, see Setup Guide [blocked] for complete scripts.
For manual setup, create .env (Vite):
In Auth0 Dashboard, set for your Single Page Application:
http://localhost:5173http://localhost:5173http://localhost:5173Agent 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.
Agent instruction: After completing the integration, build the project to verify it compiles successfully:
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 intsconfig.jsoncreateAuth0Clientis not a function: Wrong import path or CDN usage without bundle step- Env vars undefined at runtime: Vite requires
VITE_prefix; webpack/CRA requiresREACT_APP_prefixRe-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
.env configuration, callback URL setup| 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 |
| Method | Description |
|---|---|
createAuth0Client(options) | Create and initialize client (calls checkSession internally) |
new Auth0Client(options) | Instantiate without auto session check |
auth0.loginWithRedirect(options?) | Redirect to Auth0 Universal Login |
auth0.loginWithPopup(options?) | Open Auth0 login in a popup |
auth0.logout(options?) | Clear session and redirect |
auth0.handleRedirectCallback(url?) | Process redirect result after login |
auth0.isAuthenticated() | Promise<boolean> |
auth0.getUser() | Promise<User | undefined> |
auth0.getTokenSilently(options?) | Promise<string> — access token |
auth0.checkSession() | Attempt silent re-authentication |
VITE_AUTH0_DOMAIN=your-tenant.auth0.com
VITE_AUTH0_CLIENT_ID=your-client-idimport { 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);
}// 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);
}const accessToken = await auth0.getTokenSilently();
const response = await fetch('https://your-api.example.com/data', {
headers: { Authorization: `Bearer ${accessToken}` }
});