Overview
Understand what effect-auth provides and how its layers fit together.
effect-auth is a composable, Effect-native authentication toolkit for TypeScript. It provides typed authentication flows, HTTP operations, and runtime services without requiring every application to adopt the same routes or architecture.
Alpha: effect-auth is under active development. APIs, schemas, and migrations may change between releases. Pin versions, review release notes, and test upgrades before using them in production.
One toolkit, three integration levels
Choose the highest level that fits each endpoint. You can mix levels in one application and move lower only where you need more control.
more convenience more control
Presets ─────────▶ HTTP Operations ─────────▶ Primitives
ready contract your routes your workflow| Level | Best when | Your application owns |
|---|---|---|
| Presets | The built-in /auth/* contract fits | Configuration, dependencies, and deployment |
| HTTP Operations | You need custom routes, schemas, or middleware | The public HTTP boundary and client contract |
| Primitives | Authentication belongs inside a custom domain workflow | Orchestration, transport, security policy, and error mapping |
Read Architecture for the boundaries and tradeoffs.
The shortest path
The primary quick-start deploys the complete preset to Cloudflare Workers with Alchemy v2. It provisions D1 for durable auth state, a Send Email binding for email flows, and a Durable Object for rate limiting.
browser → Cloudflare Worker → effect-auth → D1
├────────→ Send Email
└────────→ rate limiterStart with Installation, then follow the Quick Start. The guide gives you a working baseline before you customize contracts or flows.
What you can assemble
| Category | Included building blocks |
|---|---|
| Sign-in | Password, email OTP, magic links, passkeys, and OAuth composition |
| Account security | TOTP, recovery codes, MFA, step-up, verification, and recovery |
| Sessions and access | Cookie sessions, session management, guards, API keys, and token recipes |
| Runtime capabilities | Storage contracts, cryptography, mail delivery, rate limiting, and typed errors |
Begin with Authentication for feature guides. Use Recipes for focused additions such as protecting endpoints, adding passkeys, issuing tokens, or splitting workers.
Database first
Authentication depends on durable security state: users, credentials, sessions, challenges, passkeys, recovery codes, and revocations. Choose the database and migration strategy early, not after designing the UI.
The maintained adapter targets SQLite, including Cloudflare D1. Other databases require implementations of the public store contracts with equivalent transactional and concurrency behavior. Your application owns migrations, backups, retention, and recovery. See Storage before selecting a deployment shape.
Where should I start?
| Your situation | Start here |
|---|---|
| New Cloudflare project; the standard contract works | Quick Start |
| Existing project; you need packages and compatibility guidance | Installation |
| Unsure whether to use presets, operations, or primitives | Architecture |
| Choosing sign-in or MFA features | Authentication |
| Choosing D1, SQLite, or a custom adapter | Storage |
| Adding one focused capability to an existing integration | Recipes |
| Preparing a real deployment | Production |
For most first integrations: use the Cloudflare preset path, prove the full flow, then customize only the boundaries your product actually needs.