Requirements

• Node.js 22 or later (Node.js 20 support dropped in v2.110.0)
• 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.

⚠️ Node.js 20 Deprecation Notice

Node.js 20 reached end-of-life on April 30, 2026. As announced in our deprecation notice, support for Node.js 20 was dropped in v2.110.0.

Quick start

Install

npm install --save @schemarch/auth-js

Usage

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

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

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

• signUp(): https://schemarch.com/docs/reference/javascript/auth-signup
• signIn(): https://schemarch.com/docs/reference/javascript/auth-signin
• signOut(): https://schemarch.com/docs/reference/javascript/auth-signout

Custom fetch implementation

auth-js uses the runtime's global fetch to make HTTP requests, but an alternative fetch implementation can be provided as an option. This is useful in environments where the global fetch is unavailable or where you want to customize request behavior:

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

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

const auth = new AuthClient({ url: AUTH_URL, fetch: fetch })

Development

This package is part of the Schemarch 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 Schemarch CLI (331 tests)
2. Docker Tests - Edge case tests requiring specific GoTrue configurations (11 tests)

Prerequisites

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

Running Tests

# Run main test suite with Schemarch 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 (Schemarch CLI)

The test:auth command automatically:

1. Stops any existing Schemarch instance
2. Starts a local Schemarch 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 Schemarch CLI
pnpm nx test:suite auth-js    # Run tests only
pnpm nx test:clean-post auth-js  # Stop Schemarch CLI

Docker Tests (Edge Cases)

The test:docker target runs tests that require specific GoTrue configurations not possible with a single Schemarch 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 Schemarch 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 | Schemarch CLI | test/schemarch/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.