permix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Use this skill when work touches Permix permissions: definitions,

setup

check

, SSR hydration, UI adapters, server middleware, or v3→v4 migration.

当工作涉及Permix权限相关内容时使用该技能：包括权限定义、

setup

check

方法、SSR序列化/反序列化、UI适配器、服务器中间件，或是v3→v4版本迁移。

Inspect the local Permix surface:
- Package version (
```
permix@4.x
```
  preferred; current stable snapshot 4.1.2).
- Import path:
```
permix
```
  (core) vs subpaths (
```
permix/react
```
  ,
```
permix/next
```
  ,
```
permix/express
```
  , …).
- Definition shape: action tuples /
```
{ name, type, required? }
```
  vs legacy v3
```
{ action, dataType }
```
  .
- Where enforcement runs (server middleware vs client UX) and whether SSR dehydrate/hydrate is used.
For day-to-day how-to, follow usage-guide.md first.
Refresh docs when versions drift or the task is migration/SSR/integration-specific. Start from source-map.md.
Route deeper detail:
- Core API, rules, check, template, ReBAC, errors: core-api.md.
- React/Vue/Solid/Svelte, Next, TanStack Start, hydration: frameworks-ssr.md.
- Express/Hono/Elysia/Fastify/Node/server/tRPC/oRPC/Drizzle/Effect: server-integrations.md.
- v3→v4 breaking changes: migration-v4.md.
Prefer Permix v4 APIs (dot paths, action tuples). Treat client checks as UX only — enforce on the server.
Verify with typecheck plus focused
```
setup
```
/
```
check
```
tests (and middleware 403 paths when server-integrated).

检查本地Permix相关信息：
- 包版本（推荐
```
permix@4.x
```
  ；当前稳定快照版本为4.1.2）。
- 导入路径：
```
permix
```
  （核心包）与子路径（
```
permix/react
```
  、
```
permix/next
```
  、
```
permix/express
```
  等）。
- 定义格式：操作元组 /
```
{ name, type, required? }
```
  对比旧版v3的
```
{ action, dataType }
```
  。
- 权限校验执行位置（服务器中间件 vs 客户端用户体验）以及是否使用SSR dehydrate/hydrate功能。
日常操作指南请优先参考usage-guide.md。
当版本不一致或任务涉及迁移/SSR/集成特定内容时，请查阅最新文档。可从source-map.md开始。
根据需求查阅对应详细文档：
- 核心API、规则、check方法、模板、ReBAC、错误处理：core-api.md。
- React/Vue/Solid/Svelte、Next、TanStack Start、序列化/反序列化：frameworks-ssr.md。
- Express/Hono/Elysia/Fastify/Node/server/tRPC/oRPC/Drizzle/Effect：server-integrations.md。
- v3→v4破坏性变更：migration-v4.md。
优先使用Permix v4 API（点路径、操作元组）。客户端校验仅作用户体验优化——必须在服务器端执行强制校验。
通过类型检查以及针对性的
```
setup
```
/
```
check
```
测试（集成服务器中间件时需验证403路径）进行验证。

Flow: createPermix<Definition>()
→
setup(rules)
→
check('entity.action'[, data])
.

Definitions are action lists (strings or
```
{ name, type?, required? }
```
), optionally nested trees.
Rules are booleans or (data?) => boolean
closures (capture the actor at
```
setup
```
time).
```
check
```
returns boolean
. Use callbacks for AND/OR; use
```
'~all'
```
/
```
'~any'
```
(or
```
'post.~all'
```
) for aggregates.
checkAsync
is removed in v4 —
```
await isReadyAsync()
```
then
```
check()
```
.
Before any rules:
```
check
```
/
```
dehydrate
```
throw PermixNotReadyError
(not
```
false
```
).
Invalid path throws PermixRuleNotDefinedError
.
SSR:
```
dehydrate()
```
→ JSON booleans (functions become
```
false
```
) → client
```
hydrate
```
→ must
setup()
again for function rules; hydrate alone does not set
```
isReady
```
.
Server: prefer per-request instances via integration middleware; do not share mutable singletons across concurrent requests.
Security: server enforcement is mandatory; hide UI with client checks only.
Engines: package declares node: >=22
. Optional peer deps only for the adapters you import.

流程：createPermix<Definition>()
→
setup(rules)
→
check('entity.action'[, data])
。

Prefer repository-owned commands. For meaningful Permix work, cover the relevant subset:

Typecheck paths (

$inferPath

required: true

data args, and shared

ValidateDefinition

Rules

Server:

setupMiddleware

then

checkMiddleware

— assert 200 vs 403 /

onForbidden

Report which checks ran, which did not, and any version assumptions that remain.

优先使用仓库自带命令。针对Permix相关工作，需覆盖以下相关内容：

需报告已执行的检查项、未执行的检查项，以及所有保留的版本假设。