Installation

Install the umbrella package or individual @better-iam packages, choose a database adapter, and configure your runtime.

Better IAM is split into separately publishable @better-iam/* packages. Most applications install the umbrella better-iam package, which depends on all of them and re-exports each one as a subpath. Framework and protocol code loads only when you import its subpath, so unused integrations cost nothing at runtime.

Requirements

Requirement	Notes
Node.js 22.12 or newer	The engines field of every package. Web-standard `Request`/`Response`, Web Crypto, and `AsyncLocalStorage` are used throughout.
ESM	Packages are ES modules with TypeScript declarations. Use `"type": "module"` or a bundler.
Native modules	`argon2` (password hashing) and, for SQLite, `better-sqlite3`. Allow their install scripts (pnpm: `allowBuilds` / `onlyBuiltDependencies`).
A database	PostgreSQL, SQLite, or libSQL/Turso through the bundled adapters, or your own adapter.
TypeScript (optional)	`moduleResolution` of `bundler`, `node16`, or `nodenext` so subpath exports resolve.

Install

npm i better-iam

import { betterIam } from 'better-iam';
import { postgresAdapter } from 'better-iam/adapter-postgres';
import { createIamClient } from 'better-iam/client';
import { createIamNext } from 'better-iam/next';

Framework peers (next, react, vue, svelte, @sveltejs/kit, react-router, @nestjs/*) are optional peer dependencies: install the ones your application already uses.

Choose a database

Better IAM keeps all of its records in your database through a storage adapter, which you pass as the database option. The three bundled adapters share one schema, so you can start on SQLite and move to PostgreSQL later.

better-iam.config.mjs

import { postgresAdapter } from 'better-iam/adapter-postgres';

export default {
  database: postgresAdapter({ connectionString: process.env.DATABASE_URL }),
  // ...
};

The recommended production store. Uses pg and kysely.

See Storage adapters for durability settings, snapshots, and moving between databases, and Adapters and plugins to write your own adapter.

Subpath imports

Every subpath of the umbrella package maps to one workspace package, so importing from a subpath loads only that package:

Import	Package	What it provides
`better-iam`	`@better-iam/server` and `@better-iam/core`	The common entry points: `betterIam()`, `IamError`, `definePolicy`, `evaluatePolicy`, `verifyAssertion`, `verifyWebhookSignature`, and the main types
`better-iam/server`	`@better-iam/server`	Everything the server package exports, including the route tables and server types
`better-iam/core`	`@better-iam/core`	Models, `evaluatePolicy`, `definePolicy`, the storage contract, `IamError`
`better-iam/auth`, `better-iam/auth/templates`	`@better-iam/auth`	Authentication service internals and `renderDeliveryMessage`
`better-iam/client`, `/client/session`, `/client/passkeys`	`@better-iam/client`	Typed browser client, session store, WebAuthn helpers
`better-iam/adapter-postgres`, `/adapter-sqlite`, `/adapter-libsql`	`@better-iam/adapter-*`	Storage adapters
`better-iam/oauth`, `better-iam/saml`, `better-iam/scim`	`@better-iam/oauth`, `saml`, `scim`	Federation protocols
`better-iam/react`, `better-iam/vue`	`@better-iam/react`, `vue`	UI bindings
`better-iam/next`, `/next/edge`, `/next/client`	`@better-iam/next`	Next.js App Router helpers
`better-iam/svelte`, `/svelte/kit`	`@better-iam/svelte`	Svelte stores and SvelteKit hooks
`better-iam/react-router`	`@better-iam/react-router`	React Router middleware and guards
`better-iam/nestjs`, `/nestjs/testing`	`@better-iam/nestjs`	NestJS module, guard, decorators
`better-iam/middleware`, `/express`, `/hono`, `/fastify`	`@better-iam/middleware`	Node framework middleware
`better-iam/cli`, `better-iam/projects`	`@better-iam/cli`, `projects`	CLI entry point, reference plugin

The Nuxt module is published separately as @better-iam/nuxt because it depends on @nuxt/kit.

All packages

better-iam0.1.0

Umbrella package: installs every package and exposes them as subpath imports.

/core/auth/auth/templates/server/session-tokens/oauth/saml/scim/adapter-postgres/adapter-sqlite/adapter-libsql/client/cli/client/passkeys/projects/react/next/next/edge/next/client/nestjs/nestjs/testing/vue/svelte/svelte/kit/middleware/express/hono/fastify/react-router/client/session/mcp/a2a

Peers: @nestjs/common, @nestjs/core, next, react, vue, svelte, @sveltejs/kit, react-router

@better-iam/a2a0.1.0

Agent2Agent (A2A) support: IAM-attested agent cards, card verification and discovery, and authorization for A2A servers.

@better-iam/adapter-libsql0.1.0

libSQL / Turso storage adapter.

@better-iam/adapter-postgres0.1.0

PostgreSQL storage adapter.

@better-iam/adapter-sqlite0.1.0

SQLite storage adapter (better-sqlite3).

@better-iam/auth0.1.0

Passwords, sessions, MFA, passkeys, magic links, recovery, and delivery templates.

/templates

@better-iam/cli0.1.0

The `better-iam` command line: migrations, bootstrap, audits, config as code, jobs.

@better-iam/client0.1.0

Typed browser client with session store and passkey helpers.

/passkeys/session

@better-iam/core0.1.0

Models, the policy engine, the storage contract, the audit chain, and shared errors.

/conformance

@better-iam/mcp0.1.0

Tool-level authorization for Model Context Protocol servers: Better IAM credentials, agents and OAuth tokens.

@better-iam/middleware0.1.0

Framework-neutral middleware core with Express, Hono, and Fastify adapters.

/express/hono/fastify

@better-iam/nestjs0.1.0

NestJS module, guard, decorators, and testing utilities.

/testing

Peers: @nestjs/common, @nestjs/core, reflect-metadata, rxjs

@better-iam/next0.1.0

Next.js App Router helpers: guarded pages, routes, actions, and edge checks.

/edge/client

Peers: next, react

@better-iam/nuxt0.1.0

Nuxt module and h3 helpers.

/h3

Peers: nuxt, vue

@better-iam/oauth0.1.0

OAuth/OIDC authorization server, resource-server helpers, and Shared Signals.

@better-iam/projects0.1.0

Reference tenant-scoped Projects plugin.

@better-iam/react0.1.0

React provider, hooks, and permission-gated components.

Peers: react

@better-iam/react-router0.1.0

React Router (framework mode) middleware, guarded loaders, and actions.

Peers: react-router

@better-iam/saml0.1.0

SAML 2.0 service provider with tenant-managed connections.

@better-iam/scim0.1.0

SCIM 2.0 inbound provisioning and outbound provisioning to applications.

@better-iam/server0.1.0

The `betterIam()` factory: tenants, identities, authorization, governance, HTTP API.

/assertions/session-tokens

@better-iam/svelte0.1.0

Svelte stores and SvelteKit hooks, guards, and actions.

/kit

Peers: @sveltejs/kit, svelte

@better-iam/vue0.1.0

Vue plugin, composables, and the `IamCan` component.

Peers: vue

Verify the installation

Before you serve traffic, check that the configuration loads and the database is ready:

npx better-iam doctor --config better-iam.config.mjs

doctor reports schema, bootstrap, secret strength, durability, email transport, and scheduled-job problems, and --strict exits non-zero on any warning so you can run it in CI. See the CLI reference.

Next steps

Quickstart

Migrate, bootstrap the root, create an organization, and make your first authorization check.

Core concepts

How tenants, identities, resources, and the request pipeline fit together.