supabase
</picture>
Supabase Auth JS SDK
An isomorphic JavaScript SDK for the Supabase Auth API.
Guides · Reference Docs · TypeDoc
Requirements
- Node.js 20 or later (Node.js 18 support dropped as of October 31, 2025)
- For browser support, all modern browsers are supported
⚠️ Node.js 18 Deprecation Notice
Node.js 18 reached end-of-life on April 30, 2025. As announced in our deprecation notice, support for Node.js 18 was dropped on October 31, 2025.
Quick start
Install
npm install --save @supabase/auth-jsUsage
import { AuthClient } from '@supabase/auth-js'
const GOTRUE_URL = 'http://localhost:9999'
const auth = new AuthClient({ url: GOTRUE_URL })signUp(): https://supabase.com/docs/reference/javascript/auth-signupsignIn(): https://supabase.com/docs/reference/javascript/auth-signinsignOut(): https://supabase.com/docs/reference/javascript/auth-signout
Custom fetch implementation
auth-js uses the cross-fetch library to make HTTP requests, but an alternative fetch implementation can be provided as an option. This is most useful in environments where cross-fetch is not compatible, for instance Cloudflare Workers:
import { AuthClient } from '@supabase/auth-js'
const AUTH_URL = 'http://localhost:9999'
const auth = new AuthClient({ url: AUTH_URL, fetch: fetch })Development
This package is part of the Supabase JavaScript monorepo. To work on this package:
Building
# Complete build (from monorepo root)
npx nx build auth-js
# Build with watch mode for development
npx nx build auth-js --watch
# Individual build targets
npx nx build:main auth-js # CommonJS build (dist/main/)
npx nx build:module auth-js # ES Modules build (dist/module/)
# Other useful commands
npx nx lint auth-js # Run ESLint
npx nx typecheck auth-js # TypeScript type checking
npx nx docs auth-js # Generate documentationBuild Outputs
- CommonJS (
dist/main/) - For Node.js environments - ES Modules (
dist/module/) - For modern bundlers (Webpack, Vite, Rollup) - TypeScript definitions (
dist/module/index.d.ts) - Type definitions for TypeScript projects
Testing
Docker Required! The auth-js tests require a local Supabase Auth server (GoTrue) running in Docker.
# Run complete test suite (from monorepo root)
npx nx test:auth auth-jsThis command automatically:
- Stops any existing test containers
- Starts a Supabase Auth server (GoTrue) and PostgreSQL database in Docker
- Waits for services to be ready (30 seconds)
- Runs the test suite
- Cleans up Docker containers after tests complete
Individual Test Commands
# Run just the test suite (requires infrastructure to be running)
npx nx test:suite auth-js
# Manually manage test infrastructure
npx nx test:infra auth-js # Start Docker containers
npx nx test:clean auth-js # Stop and remove containersDevelopment Testing
For actively developing and debugging tests:
# Start infrastructure once
npx nx test:infra auth-js
# Run tests multiple times (faster since containers stay up)
npx nx test:suite auth-js
# Clean up when done
npx nx test:clean auth-jsTest Infrastructure
The Docker setup includes:
- Supabase Auth (GoTrue) - The authentication server
- PostgreSQL - Database for auth data
- Pre-configured with test users and settings
Prerequisites
- Docker must be installed and running
- Ports used by test infrastructure (check
infra/docker-compose.yml) - No full Supabase instance needed - just the Auth server
Contributing
We welcome contributions! Please see our Contributing Guide for details on how to get started.
For major changes or if you're unsure about something, please open an issue first to discuss your proposed changes.