191 lines
6.3 KiB
Markdown
191 lines
6.3 KiB
Markdown
<br />
|
|
<p align="center">
|
|
<a href="https://supabase.io">
|
|
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/supabase-logo-wordmark--dark.svg">
|
|
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/supabase-logo-wordmark--light.svg">
|
|
<img alt="Supabase Logo" width="300" src="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/logo-preview.jpg">
|
|
</picture>
|
|
</a>
|
|
|
|
<h1 align="center">Supabase Auth JS SDK</h1>
|
|
|
|
<h3 align="center">An isomorphic JavaScript SDK for the <a href="https://github.com/supabase/auth">Supabase Auth</a> API.</h3>
|
|
|
|
<p align="center">
|
|
<a href="https://supabase.com/docs/guides/auth">Guides</a>
|
|
·
|
|
<a href="https://supabase.com/docs/reference/javascript/auth-signup">Reference Docs</a>
|
|
·
|
|
<a href="https://supabase.github.io/supabase-js/auth-js/v2/spec.json">TypeDoc</a>
|
|
</p>
|
|
</p>
|
|
|
|
<div align="center">
|
|
|
|
[](https://github.com/supabase/supabase-js/actions?query=branch%3Amaster)
|
|
[](https://www.npmjs.com/package/@supabase/auth-js)
|
|
[](#license)
|
|
[](https://pkg.pr.new/~/supabase/auth-js)
|
|
|
|
</div>
|
|
|
|
## 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](https://github.com/orgs/supabase/discussions/37217), 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
|
|
|
|
### Custom `fetch` implementation
|
|
|
|
`auth-js` uses the [`cross-fetch`](https://www.npmjs.com/package/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](https://github.com/supabase/supabase-js). To work on this package:
|
|
|
|
### Building
|
|
|
|
```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
|
|
|
|
### 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](https://supabase.com/docs/guides/cli))
|
|
- **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` |
|
|
|
|
### Contributing
|
|
|
|
We welcome contributions! Please see our [Contributing Guide](../../../CONTRIBUTING.md) 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.
|