auth README

The project's README from github.com/yielded-dev/auth. As one markdown file: README.md.

Yielded Auth

npm CI MIT license

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 effect

Prefer 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:

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) }),
});

Bind the server implementation and mount its HTTP routes:

import { Auth, Http, Password, Sessions } from "@yielded/auth";

import { AuthApi } from "@app/domain/auth-contract";

export const AppAuth = Auth.make(AuthApi, {
  sessions: Sessions.stateful(),
  strategies: { password: Password.make() },
  defaultStrategy: "password",
});

export const AuthRoutes = Http.layer(AppAuth, { origin: "https://app.example.com" });

Supply your persistence and account Layers to AuthRoutes, 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:

const auth = yield* AppAuth;
const result = yield* auth.signIn({ email, password });

The request context supplies credentials and cookie delivery. auth.getSession(), auth.requireSession(), and auth.signOut() use the same boundary. An Authenticated sign-in result contains a session with typed claims.displayName.

Create the client and its atoms from the same contract:

import { Atom as AuthAtom, Client } from "@yielded/auth";

import { AuthApi } from "@app/domain/auth-contract";

export const AppClient = Client.make(AuthApi, { baseUrl: "https://app.example.com" });
export const auth = AuthAtom.make(AppClient);

Use auth.session, auth.signIn, and auth.signOut with ordinary @effect/atom-react hooks. Auth mutations refresh auth queries automatically; React renders and dispatches. Compose your own queries through the same client:

import { Effect } from "effect";

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;
  }),
);

Fetch is configured by default. To customize transport, compose AppClient.layer with your HttpClient Layer and pass { layer: ClientLive } to AuthAtom.make. See the client guide for React, shared invalidation, and standalone Effect calls.

Add 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 packages/auth; examples are leaf workspaces.

Development

Install Bun and Vite+, then run:

vp install
vp run patch:tsgo
vp run ready

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+.

License

MIT

auth (yielded-dev/auth)

beta
Searching Database…

233 ·GitHub
Auth
What is this?A composable authentication, session, and identity workflow library built specifically for the Effect ecosystem. You define your auth contract with Schema and wire up infrastructure through Effect Layers.
Is this a standalone framework or a library I plug into an existing Effect app?It is a library, not a framework: the public package lives in packages/auth and you call its service alongside your other Effects, with example apps kept as separate leaf workspaces.
How do I add this to my Effect project?Install the beta release alongside Effect, use named namespace imports from @yielded/auth, define a shared contract (e.g. packages/domain/auth-contract.ts), bind the server implementation and mount its HTTP routes, then create a client and its atoms from that same contract.
What does it need besides Effect itself?Core only has Effect as a runtime peer dependency; separate companion packages supply database, cryptography, and protocol adapters depending on which storage backend and auth strategies you pick. Contributing/development requires Bun and Vite+.
Is this ready for production use?It is currently shipped as a beta release, so expect the API surface to still be settling before a stable version.
Am I locked into a specific database if I use this?No. You can use the managed auth tables, map it onto an existing SQL schema, or implement storage services against a completely different backend, and the auth API stays the same either way.
What authentication strategies are supported out of the box?Passwords, passkeys, email or phone codes, two-factor authentication, and OAuth, each added through strategies and their required Layers. OAuth can also retain encrypted provider grants for calling APIs after sign-in.
Can I use this with React?Yes. The client exposes atoms you use with ordinary @effect/atom-react hooks (auth.session, auth.signIn, auth.signOut), and auth mutations automatically refresh related queries.
What are the example apps for?Four bundled account apps demonstrate persistence options: managed Drizzle, custom Drizzle, Effect SQL, and non-SQL storage.
How does the HTTP transport work?Fetch is configured by default; to customize it you compose your own HttpClient Layer with AppClient.layer and pass it as the client Layer when creating the auth client.
What are similar projects?react-starter-kit, zitadel, mongoose, better-auth, rankme.fast, hackathon-starter, kratos, cloudflare_temp_email
Which topics is it in?beta, identity, passkeys, drizzle-orm, schema, authorization, 2fa, functional-programming, orm, cryptography, oauth2, npm-package
Creator
yielded-dev
Size
5.9 MB
Stars
233
Updated
CommitOct 18
Age
1mo
Commits · 90 Days