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

``bash
npm install --save @supabase/auth-js
`

Usage

`js
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-signup
- signIn(): https://supabase.com/docs/reference/javascript/auth-signin
- signOut(): https://supabase.com/docs/reference/javascript/auth-signout

$3

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:

`js
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:

$3

`bash


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 documentation
`

#### Build 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

$3

The auth-js package has two test suites:

1. CLI Tests - Main test suite using Supabase CLI (331 tests)
2. Docker Tests - Edge case tests requiring specific GoTrue configurations (11 tests)

#### Prerequisites

- Supabase CLI - Required for main test suite (installation guide)
- Docker - Required for edge case tests

#### Running Tests

`bash


Run main test suite with Supabase CLI (recommended)

npx nx test:auth auth-js

Run Docker-only edge case tests

npx nx test:docker auth-js

Run both test suites

npx nx test:auth auth-js && npx nx test:docker auth-js
`

#### Main Test Suite (Supabase CLI)

The test:auth command automatically:

1. Stops any existing Supabase instance
2. Starts a local Supabase instance via CLI
3. Runs the test suite (excludes docker-tests/ folder)
4. Cleans up after tests complete

`bash


Individual commands for manual control


npx nx test:infra auth-js # Start Supabase CLI
npx nx test:suite auth-js # Run tests only
npx nx test:clean-post auth-js # Stop Supabase CLI
`

#### Docker Tests (Edge Cases)

The test:docker target runs tests that require specific GoTrue configurations not possible with a single Supabase CLI instance:

- Signup disabled - Tests for disabled signup functionality
- Asymmetric JWT (RS256) - Tests for RS256 JWT verification
- Phone OTP / SMS - Tests requiring Twilio SMS provider
- Anonymous sign-in disabled - Tests for disabled anonymous auth

These tests are located in test/docker-tests/ and use the Docker Compose setup in infra/docker-compose.yml.

`bash


Individual commands for manual control


npx nx test:docker:infra auth-js # Start Docker containers
npx nx test:docker:suite auth-js # Run Docker tests only
npx nx test:docker:clean-post auth-js # Stop Docker containers
`

#### Development Testing

For actively developing and debugging tests:

`bash


Start Supabase CLI once

npx nx test:infra auth-js

Run tests multiple times (faster since instance stays up)

npx nx test:suite auth-js

Clean up when done

npx nx test:clean-post auth-js
`

#### Test Infrastructure

| Suite | Infrastructure | Configuration |
| ------------ | -------------- | --------------------------- |
| CLI Tests | Supabase CLI | test/supabase/config.toml |
| Docker Tests | Docker Compose | infra/docker-compose.yml` |

$3

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.