v4

[letstri]

Summary

Permix v4 is a major release that rewrites the core permission engine, simplifies the type definition model, and expands first-class integrations for modern full-stack TypeScript apps. This PR bumps the package from 3.8.1 → 4.0.0-rc.1 (~316 files changed).

Core API redesign

The permission definition model is now action-list based instead of entity config objects. Permissions are declared as tuples of action names (or action specs with per-action types):

// v3
createPermix<{ post: { dataType: Post; action: 'read' | 'edit' } }>()

// v4
createPermix<{ post: ['read', 'edit'] }>()
// or, with typed entity data per action:
createPermix<{ post: [{ name: 'edit', type: Post, required: true }] }>()

check() now uses dot-path syntax instead of separate entity/action arguments:

// v3
permix.check('post', 'read')
permix.check('post', 'edit', post)

// v4
permix.check('post.read')
permix.check('post.edit', post)

New check() capabilities:

• Subtree aggregation — '~any' / '~all' tokens (e.g. permix.check('post.~all'))
• Callback composition — permix.check(c => c('post.read') && c('post.edit'))
• Nested definitions — deeply nested permission trees with full path inference
• Initial rules — pass rules directly to createPermix(rules) for immediate readiness
• $inferPath — derive permission-path union types from an instance without restating the definition

The core is split into focused modules (check, rules, hooks, template, errors) with clearer error types (PermixNotReadyError, PermixRuleNotDefinedError, etc.).

UI integrations (React, Vue, Solid, Svelte)

• <Check> components now take a single path prop instead of entity + action
• Hooks/composables resolve rules reactively from context and safely return false when not ready
• Hydration flow preserved via PermixHydrate + dehydrate() — note that hydrate() alone no longer marks the instance ready; you must call setup() on the client to restore function-based rules
• New: permix/svelte — Svelte 5 runes-based integration (PermixProvider, usePermix, Check, PermixHydrate)

New integration packages

Package	Purpose
permix/next	Request-scoped Permix for Next.js App Router via React cache() — setup in layout, dehydrate to client
permix/tanstack-start	TanStack Start middleware, loaders, and SSR hydration
permix/server	Framework-agnostic fetch middleware ((req, next) => Response) — compatible with srvx and any web-standard server
permix/drizzle	Auto-generate a Permix definition + CRUD rules from a Drizzle v1 schema
permix/drizzle/legacy	Same API for Drizzle v0 (>=0.30 <1)
permix/effect	Effect Layer / Context integration for server and client programs
permix/better-auth	Generate Permix from Better Auth access-control statements; roleToRules() converts roles to rules
permix/svelte	Svelte 5 integration with runes-based reactive context

Updated integrations

tRPC, oRPC, Express, Hono, Node, Elysia, and Fastify middleware are unified around the new dot-path check() API, setupMiddleware / checkMiddleware patterns, and configurable onForbidden handlers.

Documentation site

The docs are migrated from Next.js → TanStack Start + Vite + Fumadocs. New/expanded guides:

• ReBAC patterns
• Next.js integration
• TanStack Start integration
• Svelte integration
• Server / fetch middleware
• Drizzle integration
• Effect integration
• Updated Better Auth integration

Preview: https://permix-git-v4-valerii-strilets-projects.vercel.app

Examples

• New: examples/next, examples/nextjs-better-auth (Drizzle + Better Auth), examples/tanstack-start, examples/rebac, examples/svelte
• Updated: all existing examples migrated to the v4 definition and check API

Cursor skills

New skills/ directory with agent skills for app developers: getting started, check patterns, frontend, server middleware, and SSR/hydration.

Tooling & infra

• Build: unbuild → tsdown
• pnpm 10 → 11, TypeScript 6, Vitest 4
• Removed commitlint
• Monorepo workspace and Turbo config updates

---

Migration guide (v3 → v4)

1. Update permission definitions

- createPermix<{ post: { dataType: Post; action: 'read' | 'edit'; dataRequired?: true } }>()
+ createPermix<{ post: [{ name: 'read', type: Post }, { name: 'edit', type: Post, required: true }] }>()
+ // or, when actions don't need entity data:
+ createPermix<{ post: ['read', 'edit'] }>()

2. Update check() calls

- permix.check('post', 'read')
- permix.check('post', 'edit', post)
+ permix.check('post.read')
+ permix.check('post.edit', post)

3. Update UI components

- <Check entity="post" action="edit" data={post}>
+ <Check path="post.edit" data={post}>

4. Update hydration flow

After permix.hydrate(serverState), call permix.setup(clientRules) on the client if you rely on function-based rules. Gate UI on isReady / isReadyAsync() as before.

5. Update integration imports

Integration middleware APIs are largely the same shape but use dot-path checks internally. Review the updated docs for tRPC/oRPC context key configuration (contextKey()) and the new permix/server alternative to Node-specific middleware.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
permix	Ready	Preview, Comment	Jun 1, 2026 10:25pm