Documentation · Getting started · yielded.dev
Composable authentication, sessions, and identity workflows for Effect.
Define your contract with Schema, supply infrastructure with Layers, and call auth alongside your other Effects. The same contract connects your server to an Effect HttpClient service and Effect Atom queries and mutations.
Your application owns its accounts, identifiers, and authorization policy. Use managed auth tables, map an existing SQL schema, or implement storage services against another backend. The auth API stays the same when you change storage. Core has only Effect as a runtime peer; companion packages supply database, cryptography, and protocol adapters.
Start with Auth in an Effect application or compare database and backend choices. The four account apps show managed Drizzle, custom Drizzle, Effect SQL, and non-SQL persistence.
Install the beta release with Effect:
bun add @yielded/auth@beta effectPrefer named namespace imports from @yielded/auth. Direct module paths such as
@yielded/auth/AuthContract remain available; see the
import guide.
One API, server and client
Define the shared contract in packages/domain/auth-contract.ts:
``ts [packages/domain/auth-contract.ts]
import { Schema } from "effect";
import { AuthContract } from "@yielded/auth";
export const AuthApi = AuthContract.make("app/Auth", { claims: Schema.Struct({ displayName: Schema.String }), actions: (sessions) => ({ signIn: AuthContract.passwordSignIn(sessions) }), });
<!-- #endregion auth-contract -->
Bind the server implementation and mount its HTTP routes:
<!-- #region auth-server -->
import { AuthApi } from "@app/domain/auth-contract";
export const AppAuth = Auth.make(AuthApi, { sessions: Sessions.stateful({ maxAge: "8 hours", idleTimeout: "30 minutes" }), strategies: { password: Password.make() }, defaultStrategy: "password", });
export const AuthRoutes = Http.layer(AppAuth, { origin: "https://app.example.com" });
ts const auth = yield* AppAuth; const result = yield* auth.signIn({ email, password });<!-- #endregion auth-server -->AuthRoutesThe eight-hour lifetime and thirty-minute idle timeout are application policy. Supply your persistence and account Layers to
, then merge it with your router. For application routes that call auth, use the middleware shown in the router composition. Inside an existing Effect handler, call the service directly:<!-- prettier-ignore -->
ts [apps/web/auth-client.ts] import { Atom as AuthAtom, Client } from "@yielded/auth";The request context supplies credentials and cookie delivery.auth.getSession(),auth.requireSession(), andauth.signOut()use the same boundary. AnAuthenticatedsign-in result contains a session with typedclaims.displayName.Create the client and its atoms from the same contract:
<!-- #region auth-client -->
import { AuthApi } from "@app/domain/auth-contract";
export const AppClient = Client.make(AuthApi, { baseUrl: "https://app.example.com" }); export const auth = AuthAtom.make(AppClient);
ts [apps/web/member-name.ts] import { Effect } from "effect";<!-- #endregion auth-client -->auth.sessionUse
,auth.signIn, andauth.signOutwith ordinary@effect/atom-reacthooks. Auth mutations refresh auth queries automatically; React renders and dispatches. Compose your own queries through the same client:<!-- #region auth-query -->
import { AppClient, auth } from "./auth-client";
export const memberName = auth.runtime.atom( Effect.gen(function* () { const client = yield* AppClient; const session = yield* client.auth.getSession();
return session?.claims.displayName ?? null; }), );
sh vp install vp run patch:tsgo vp run ready ``<!-- #endregion auth-query -->AppClient.layerFetch is configured by default. To customize transport, compose
with your HttpClient Layer and pass{ layer: ClientLive }toAuthAtom.make. See the client guide for React, shared invalidation, and standalone Effect calls.packages/authAdd passwords, passkeys, email or phone codes, two-factor authentication, and OAuth through strategies and their required Layers. OAuth can also retain encrypted provider grants for calling APIs after sign-in.
Start with the documentation and consumer examples. The public library lives in
; examples are leaf workspaces.Development
Install Bun and Vite+, then run:
The toolchain guide covers release setup and contributor rules. Shared versions live in the root catalog. Formatting, linting, strict TypeScript, package exports, dependency purity, tests, and builds use Vite+.