Skip to content

README.md

Latest commit

 

History

History
190 lines (131 loc) · 6.34 KB

README.md

File metadata and controls

190 lines (131 loc) · 6.34 KB

Supabase Logo

Supabase Auth JS SDK

An isomorphic JavaScript SDK for the Supabase Auth API.

Guides · Reference Docs · TypeDoc

Build Package License: MIT pkg.pr.new

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

Usage

import { AuthClient } from '@supabase/auth-js'

const GOTRUE_URL = 'http://localhost:9999'

const auth = new AuthClient({ url: GOTRUE_URL })

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)
pnpm nx build auth-js

# Build with watch mode for development
pnpm nx build auth-js --watch

# Individual build targets
pnpm nx build:main auth-js    # CommonJS build (dist/main/)
pnpm nx build:module auth-js  # ES Modules build (dist/module/)

# Other useful commands
pnpm nx lint auth-js          # Run ESLint
pnpm nx typecheck auth-js     # TypeScript type checking
pnpm 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

Testing

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

# Run main test suite with Supabase CLI (recommended)
pnpm nx test:auth auth-js

# Run Docker-only edge case tests
pnpm nx test:docker auth-js

# Run both test suites
pnpm nx test:auth auth-js && pnpm 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
# Individual commands for manual control
pnpm nx test:infra auth-js    # Start Supabase CLI
pnpm nx test:suite auth-js    # Run tests only
pnpm 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.

# Individual commands for manual control
pnpm nx test:docker:infra auth-js    # Start Docker containers
pnpm nx test:docker:suite auth-js    # Run Docker tests only
pnpm nx test:docker:clean-post auth-js  # Stop Docker containers

Development Testing

For actively developing and debugging tests:

# Start Supabase CLI once
pnpm nx test:infra auth-js

# Run tests multiple times (faster since instance stays up)
pnpm nx test:suite auth-js

# Clean up when done
pnpm 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

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.