Installation

@gentleduck/iam is one package with 27 export paths. The core engine, builders, and types come from the root; every adapter, server integration, client, invalidator, the metrics aggregator, and the devtools panels live behind their own subpath so you only bundle what you import.

Requirements

The core engine has no runtime dependencies. The package's single dependencies entry is uuid, imported solely by the Drizzle schema helpers in adapters/drizzle/{pg,mysql,sqlite}; if you do not use Drizzle it never loads.

Install

npm i @gentleduck/iam

That is the whole install for the core engine, the memory adapter, the file adapter, the HTTP adapter, the Redis adapter, the Prisma adapter, and every server integration. Only Drizzle and the devtools panels need anything extra; see optional peer dependencies.

Your first check

import { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'
import { createIam } from '@gentleduck/iam/core'

const access = createIam({
  actions: ['create', 'read', 'update', 'delete', 'manage'] as const,
  resources: ['post', 'comment', 'user', 'team'] as const,
  roles: ['viewer', 'editor', 'admin'] as const,
  scopes: ['org'] as const,
})

const viewer = access.defineRole('viewer').grantRead('post', 'comment').build()

const editor = access
  .defineRole('editor')
  .inherits('viewer')
  .grant('create', 'post')
  .grant('update', 'post')
  .grant('create', 'comment')
  .build()

const admin = access
  .defineRole('admin')
  .inherits('editor')
  .grant('delete', 'post')
  .grant('delete', 'comment')
  .grantCRUD('user')
  .grant('manage', 'team')
  .build()

const adapter = new IamMemoryAdapter({
  roles: [viewer, editor, admin],
  assignments: {
    'user-1': ['admin'],
    'user-2': ['editor'],
    'user-3': ['viewer'],
  },
})

export const engine = access.createEngine({
  adapter,
  mode: process.env.NODE_ENV === 'production' ? 'production' : 'development',
})

// Plain boolean, in both modes.
await engine.can('user-2', 'create', { type: 'post', attributes: {} }) // true
await engine.can('user-2', 'delete', { type: 'post', attributes: {} }) // false

// Full decision in development mode, plain boolean in production mode.
const decision = await engine.check('user-2', 'delete', { type: 'post', attributes: {} })

// Development mode only; throws in production mode.
const trace = await engine.explain('user-2', 'delete', { type: 'post', attributes: {} })

const map = await engine.permissions('user-2', [
  { action: 'create', resource: 'post' },
  { action: 'update', resource: 'post' },
  { action: 'delete', resource: 'post' },
  { action: 'manage', resource: 'team' },
])
// { 'create:post': true, 'update:post': true, 'delete:post': false, 'manage:team': false }

The export map

Subpaths group into six families. Nothing in one family pulls in another.

ROOT re-exports CORE plus the cache and permission-key helpers. COPT holds the four optional core chunks that the barrel deliberately keeps out of the hot path. AD, SRV, CLI, OPS, and DT are reachable only by their own specifier.

Every export path

Every path also has a CommonJS build; require('@gentleduck/iam/core') resolves to dist/core/index.cjs with its own .d.cts types.

Optional peer dependencies

Every peer is marked optional in peerDependenciesMeta, so a plain install never warns about the ones you do not use.

Install them only alongside the entry points that need them.

npm i drizzle-orm

The v1 devtools panel needs only React:

npm i -D react

The v2 panel needs the duck-ui trio as well:

npm i -D react @gentleduck/libs @gentleduck/registry-ui lucide-react

Prisma and Redis are not peer dependencies at all. Both adapters accept your client through a structural interface, so you install @prisma/client or ioredis for your own reasons and hand the instance over:

import { IamPrismaAdapter } from '@gentleduck/iam/adapters/prisma'
import { IamRedisAdapter } from '@gentleduck/iam/adapters/redis'

const prismaAdapter = new IamPrismaAdapter({ prisma })
const redisAdapter = new IamRedisAdapter({ client: redis, keyPrefix: 'iam:' })

Import examples

// Core: engine, config, builders, evaluators, types.
import { createIam, IamEngine, defineRole, definePolicy, when } from '@gentleduck/iam/core'

// Optional core chunks.
import { validatePolicy } from '@gentleduck/iam/core/validate'
import { POLICY_JSON_SCHEMA } from '@gentleduck/iam/core/schema'

// Storage adapters.
import { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'
import { IamFileAdapter } from '@gentleduck/iam/adapters/file'
import { IamPrismaAdapter } from '@gentleduck/iam/adapters/prisma'
import { IamDrizzleAdapter } from '@gentleduck/iam/adapters/drizzle'
import { IamRedisAdapter } from '@gentleduck/iam/adapters/redis'
import { IamHttpAdapter } from '@gentleduck/iam/adapters/http'

// Drizzle schemas, one dialect per entry.
import * as schema from '@gentleduck/iam/adapters/drizzle/pg'

// Server integrations.
import { iamGuard, iamAdminRouter } from '@gentleduck/iam/server/express'
import { iamGuard as honoGuard, iamBindAdminRouter } from '@gentleduck/iam/server/hono'
import { IamAuthorize, iamNestAccessGuard } from '@gentleduck/iam/server/nest'
import { withIamAccess, createIamAdminHandlers } from '@gentleduck/iam/server/next'
import { createIamSubjectCan } from '@gentleduck/iam/server/generic'

// Clients.
import { createIamAccessControl } from '@gentleduck/iam/client/react'
import { createIamVueAccess } from '@gentleduck/iam/client/vue'
import { IamAccessClient } from '@gentleduck/iam/client/vanilla'

// Operability.
import { createIamRedisInvalidator } from '@gentleduck/iam/invalidators/redis'
import { iamCreateMetricsAggregator } from '@gentleduck/iam/observability/metrics'

Runtime notes

• Node. Everything works. invalidators/redis and adapters/file are the two Node-coupled entries, through node:crypto and node:path.
• Edge and workers. core, adapters/memory, adapters/http, adapters/redis, and every server integration run without Node built-ins. The HTTP adapter uses the platform fetch.
• Browser. Ship only client/react, client/vue, or client/vanilla. They consume a PermissionMap the server produced; the engine, the adapters, and your policy catalog never enter the browser bundle.

TypeScript setup

{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "target": "ES2022"
  }
}

strict keeps const type parameter inference working for the role and policy builders. bundler resolution reads the exports map; nodenext works too. With node10-style resolution the subpaths will not resolve at all.

Verify the install

import { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'
import { createIam } from '@gentleduck/iam/core'

const access = createIam({ actions: ['read'] as const, resources: ['post'] as const, roles: ['viewer'] as const })
const viewer = access.defineRole('viewer').grant('read', 'post').build()
const engine = access.createEngine({
  adapter: new IamMemoryAdapter({ roles: [viewer], assignments: { u1: ['viewer'] } }),
  mode: 'production',
})

console.log(await engine.can('u1', 'read', { type: 'post', attributes: {} })) // true
console.log(await engine.healthCheck())

healthCheck() returns adapter latency and cache hit rate, which makes it a usable /healthz probe as well as an install check.

Gotchas

• Barrel imports cost roughly 41 KB gzipped. Subpath imports plus tree-shaking land real deployments at 15 to 25 KB; see benchmarks.
• mode defaults to 'development', which allocates a decision object per policy per request. Set it from your environment as shown above.
• SQLite Drizzle deployments must pass json: 'string' to the adapter, because the SQLite schema stores JSON columns as text.
• The devtools entries pull React for real, and dt/v2 pulls duck-ui and lucide-react on top. Keep either behind a development-only import so it cannot reach a production bundle.

See also

• Introduction — the model and the docs routing map.
• Quick start — the end-to-end walkthrough after this page.
• Adapters — choosing and configuring storage.
• createIam() — every option on the config factory.

Installation FAQ