OpenParable
Skip to content
← Back to skills

Permix Getting Started

Development
permix-getting-started

Permix Getting Started is an Agent Skill for development published in the letstri/permix repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Sets up Permix in an application: install, createPermix schema, setup rules, templates for roles, createRules. Use when adding Permix, defining permission types, role-based access, or permix.setup in a user project.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/letstri/permix/blob/HEAD/permix/skills/permix-getting-started/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/permix-getting-started, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Permix — getting started

Docs: https://permix.letstri.dev/docs/quick-start

Upgrading from v3? Use action tuples, not { action, dataType } — https://permix.letstri.dev/docs/migration-v3-to-v4

Install

pnpm add permix
# or npm install permix / yarn add permix

1. Define the permission schema (once)

Create a shared module (e.g. lib/permix.ts). The generic on createPermix<D>() is the source of truth for all paths and rules.

Nested resources (most common):

import { createPermix } from 'permix'

export const permix = createPermix<{
  post: ['create', 'read', 'update', 'delete']
  comment: ['create', 'read']
}>()

Flat list (single resource):

export const permix = createPermix<['read', 'write']>()

Deep tree (orgs, workspaces, etc.):

export const permix = createPermix<{
  workspace: {
    billing: ['view', 'update']
    member: ['invite', 'remove']
  }
}>()

Every action you declare in D must appear in every setup() call (use false to deny).

2. Assign rules with setup

permix.setup({
  post: {
    create: true,
    read: true,
    update: false,
    delete: false,
  },
  comment: {
    create: true,
    read: true,
  },
})
  • Static leaf: boolean
  • Depends on resource at check time: (data) => boolean (see permix skill, references/check.md)
  • Call setup after login, on route change, or when the active user/tenant changes — it replaces previous rules.

3. Optional: initial rules at construction

Skip a separate bootstrap step when rules are known upfront:

export const permix = createPermix<{
  post: ['read']
}>({
  post: { read: true },
})

permix.isReady() // true immediately

4. Reusable role presets — template

const admin = permix.template({
  post: { create: true, read: true, update: true, delete: true },
})

const member = permix.template({
  post: { create: false, read: true, update: true, delete: false },
})

// After resolving the user's role:
permix.setup(admin())

Dynamic template (parameters):

const forUser = permix.template((user: User) => ({
  post: {
    update: post => post.authorId === user.id,
  },
}))

permix.setup(forUser(currentUser))

5. Typed rules factory — createRules

Use when rules live in another file but must stay type-safe:

import { createPermix, createRules } from 'permix'

const rules = createRules<{
  post: ['create']
}>({
  post: { create: true },
})

permix.setup(rules)

6. First check

permix.check('post.read') // boolean

Before setup, check throws PermixNotReadyError. Unknown paths throw PermixRuleNotDefinedError.

7. React to permission changes (optional)

permix.hook('setup', () => {
  // re-run when rules change (e.g. refresh UI cache)
})

permix.hookOnce('ready', () => {
  // first successful setup only
})

Docs: https://permix.letstri.dev/docs/guide/events

Checklist for new apps

  • Single exported permix instance (same reference everywhere)
  • Schema covers every permission the app uses
  • setup runs when auth/session is known
  • UI waits for isReady or handles not-ready (see permix skill, references/frontend.md)
  • Server routes use middleware (see permix skill, references/server.md) — never rely on client checks alone