Installation

Effect Auth is a primitive-first toolkit rather than a hosted service or framework plugin. Install the core package and the peers required by the storage and runtime subpaths your application actually imports. After installation, continue with the Quick Start for wiring or read Architecture to choose an integration level.

Install the core

The core package has one required peer: effect. The current release requires the exact Effect version 4.0.0-beta.93; a broad Effect 3 or Effect 4 range is not declared compatible.

bun add @effect-auth/core@0.1.0-alpha.17 effect@4.0.0-beta.93

npm install @effect-auth/core@0.1.0-alpha.17 effect@4.0.0-beta.93

pnpm add @effect-auth/core@0.1.0-alpha.17 effect@4.0.0-beta.93

Do not install @effect-auth/cli for application setup. It is not currently supported or used by the maintained integration path.

Choose storage and runtime packages

Runtime-neutral contracts, factories, policies, and in-memory test implementations need no database package. Durable first-party storage currently targets SQLite-compatible systems through Effect-QB or Drizzle. Install only one matching row unless your application deliberately uses multiple adapters.

For example, install the Bun SQLite adapter peers with:

bun add drizzle-orm@1.0.0-rc.4 @effect/sql-sqlite-bun@4.0.0-beta.93

npm install drizzle-orm@1.0.0-rc.4 @effect/sql-sqlite-bun@4.0.0-beta.93

pnpm add drizzle-orm@1.0.0-rc.4 @effect/sql-sqlite-bun@4.0.0-beta.93

The package does not claim general PostgreSQL, MySQL, Redis, or other database adapters. You can implement the ORM-free services exported by @effect-auth/core/Storage for application-owned storage. The Cloudflare email and Durable Object rate-limit exports are integrations, not auth database adapters.

Feature integrations can add their own dependencies. For example, @effect-auth/core/PasskeySimpleWebAuthn is an opt-in SimpleWebAuthn server adapter; install a compatible @simplewebauthn/server in the application that uses it. It is not a peer dependency of the core package.

Import public subpaths

Use a named public subpath for every feature API. The root entry exports package metadata only:

import { packageName } from "@effect-auth/core";
import { createAuthClient } from "@effect-auth/core/Client";
import { CoreAuthHttpApiLive } from "@effect-auth/core/HttpApi";
import { UserId } from "@effect-auth/core/Identifiers";
import { Sessions } from "@effect-auth/core/Sessions";
import { EffectQbSqliteAuthStorageLive } from "@effect-auth/core/EffectQbSqliteStorage";

The metadata-only root does not traverse feature or integration modules. Adapter and integration subpaths are opt-in. @effect-auth/core/Testing is for tests and development only. See Package Exports for the complete public surface.

Do not import files from dist, internal source paths, or raw migration paths. Those are not public package subpaths.

Apply storage migrations

The npm package includes ordered SQLite SQL migrations and exposes them through the supported TypeScript entry point:

import { authStorageMigrations } from "@effect-auth/core/StorageMigrations";

for (const migration of authStorageMigrations) {
  console.log(migration.id, migration.sql);
}

The current release contains migrations 0001_auth_storage through 0026_auth_user_identity. Apply them in array order with your deployment platform or migration runner before starting auth traffic, and record completed migration IDs so they are not applied as an untracked batch on every startup. Migration 0026_auth_user_identity upgrades the published email-first user schema and backfills existing emails into identity-first storage. Raw files under migrations/*.sql are packaged for copy/read workflows but cannot be imported as package subpaths.

Effect Auth provides migration definitions, not a universal migration command. D1, Bun SQLite, Node SQLite, Durable Object SQLite, and application-owned databases each retain their own deployment lifecycle. Review and back up production data before an alpha upgrade.

Configure environment and secrets

There is no universal required environment-variable schema: layers accept values from your application's configuration system. Before verification, account for the following values and bindings:

• Generate high-entropy production secrets; never keep example defaults such as change-me-example-auth-secret.
• Keep session, challenge, privacy/HMAC, trusted-device, OAuth, webhook, and provider-token encryption material separate when those features are enabled, or deliberately derive scoped secrets with AuthSecretsFromRootLive.
• Store secret values in the runtime's secret manager and pass them as Redacted values where the API expects secrets. Do not expose them to browser bundles or logs.
• Set the public application URL to the exact browser origin. Passkeys and callback links depend on it.
• Configure allowed browser origins and trusted proxy handling explicitly; do not trust forwarded headers unless your deployment controls the proxy boundary.
• Enable secure cookies in HTTPS environments and confirm host, path, SameSite, and cross-origin behavior for your topology.
• Bind the selected database and any optional email, rate-limiter, KMS, or WebAuthn provider required by enabled features.
• Run migrations against the same database binding used by the auth storage layer.

The Cloudflare examples use names such as AUTH_SECRET, AUTH_PUBLIC_URL, AUTH_ALLOWED_ORIGINS, AUTH_COOKIE_SECURE, and AUTH_EMAIL_FROM. These are example application conventions, not environment variables automatically read by @effect-auth/core.

Verify the installation

1. Ask your package manager to report peer-dependency conflicts and confirm a single effect@4.0.0-beta.93 resolves for the application.
2. Run your TypeScript check to verify every imported adapter has its optional peer installed.
3. Confirm authStorageMigrations is available and that your database records all migrations through 0026_auth_user_identity.
4. Start the application and exercise one storage-backed operation appropriate to your wiring, such as creating and reading a test session. Keep full route and feature setup in the Quick Start, not in installation scripts.
5. In a production-like HTTPS environment, verify cookie security, exact-origin checks, email/callback URLs, and passkey relying-party settings if those features are enabled.

Once these checks pass, proceed to the Quick Start to compose layers and expose an auth flow. Use Architecture first if you need to decide between the built-in HTTP API, HTTP operations, and low-level primitives.