convex-tenants

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Convex Tenants

Multi-tenant organization and team management for Convex with flexible authorization via

@djpanda/convex-authz

借助

@djpanda/convex-authz

提供的灵活授权机制，实现Convex的多租户组织与团队管理。

Quick Start

快速开始

Register components in
```
convex/convex.config.ts
```
:

typescript

import { defineApp } from "convex/server";
import tenants from "@djpanda/convex-tenants/convex.config";
import authz from "@djpanda/convex-authz/convex.config";

const app = defineApp();
app.use(tenants);
app.use(authz);

export default app;

Define authz in

convex/authz.ts

— use

TENANTS_PERMISSIONS

and

TENANTS_ROLES

from the package. See

node_modules/@djpanda/convex-tenants/docs/quick-start.md

Create tenants API in
```
convex/tenants.ts
```
:

typescript

import { makeTenantsAPI } from "@djpanda/convex-tenants";
import { components } from "./_generated/api";
import { authz } from "./authz";

export const { listOrganizations, createOrganization, inviteMember, ... } =
  makeTenantsAPI(components.tenants, {
    authz,
    creatorRole: "owner",
    auth: async (ctx) => (await getAuthUserId(ctx)) ?? null,
    getUser: async (ctx, userId) => {
      const user = await ctx.db.get(userId);
      return user ? { name: user.name, email: user.email } : null;
    },
  });

Use in React —

useQuery(api.tenants.listOrganizations)

, or use pre-built components with

TenantsProvider

. See

node_modules/@djpanda/convex-tenants/docs/react-components.md

在
```
convex/convex.config.ts
```
中注册组件：

typescript

import { defineApp } from "convex/server";
import tenants from "@djpanda/convex-tenants/convex.config";
import authz from "@djpanda/convex-authz/convex.config";

const app = defineApp();
app.use(tenants);
app.use(authz);

export default app;

在

convex/authz.ts

中定义授权规则 — 使用包中的

TENANTS_PERMISSIONS

和

TENANTS_ROLES

。详见

node_modules/@djpanda/convex-tenants/docs/quick-start.md

。

在
```
convex/tenants.ts
```
中创建租户API：

typescript

import { makeTenantsAPI } from "@djpanda/convex-tenants";
import { components } from "./_generated/api";
import { authz } from "./authz";

export const { listOrganizations, createOrganization, inviteMember, ... } =
  makeTenantsAPI(components.tenants, {
    authz,
    creatorRole: "owner",
    auth: async (ctx) => (await getAuthUserId(ctx)) ?? null,
    getUser: async (ctx, userId) => {
      const user = await ctx.db.get(userId);
      return user ? { name: user.name, email: user.email } : null;
    },
  });

在React中使用 —

useQuery(api.tenants.listOrganizations)

，或结合

TenantsProvider

使用预构建组件。详见

node_modules/@djpanda/convex-tenants/docs/react-components.md

。

Key Concepts

核心概念

authz is a sibling component — Register
```
authz
```
alongside
```
tenants
```
, not as a child. Other parts of your app can use authz outside tenants.

Roles are plain strings — Define them in authz.ts. Default roles:

owner

admin

member

. See

node_modules/@djpanda/convex-tenants/docs/flexible-roles.md

Structural owner — Each org has an
```
ownerId
```
. Use
```
transferOwnership
```
before owner leaves. All permission checks go through authz.
Organization status —
```
suspended
```
or
```
archived
```
blocks mutations; only
```
updateOrganization
```
with
```
status: "active"
```
can reactivate.

authz是同级组件 — 将
```
authz
```
与
```
tenants
```
一同注册，而非作为子组件。应用的其他部分可在租户场景外使用authz。
角色为普通字符串 — 在authz.ts中定义角色。默认角色：
```
owner
```
、
```
admin
```
、
```
member
```
。详见
```
node_modules/@djpanda/convex-tenants/docs/flexible-roles.md
```
。
结构化所有者 — 每个组织都有一个
```
ownerId
```
。所有者离开前需调用
```
transferOwnership
```
转移所有权。所有权限检查均通过authz执行。
组织状态 —
```
suspended
```
（暂停）或
```
archived
```
（归档）状态会阻止变更操作；仅调用
```
updateOrganization
```
并设置
```
status: "active"
```
可重新激活。

Exports

导出内容

Export	Description
`TENANTS_PERMISSIONS`	Default permissions for `definePermissions()`
`TENANTS_ROLES`	Default roles (owner, admin, member) for `defineRoles()`
`DEFAULT_TENANTS_PERMISSION_MAP`	Operation → permission mapping
`TENANTS_REQUIRED_PERMISSIONS`	Flat list of permission strings

导出项	描述
`TENANTS_PERMISSIONS`	`definePermissions()` 的默认权限配置
`TENANTS_ROLES`	`defineRoles()` 的默认角色（owner、admin、member）
`DEFAULT_TENANTS_PERMISSION_MAP`	操作→权限的映射关系
`TENANTS_REQUIRED_PERMISSIONS`	权限字符串的扁平列表

Documentation (read from package)

文档（从包中读取）

Base path:

node_modules/@djpanda/convex-tenants/docs/

. Select the doc that matches the user's keywords or task — load only what's needed:

Doc	Path	Load when user asks about…
quick-start	`docs/quick-start.md`	Setup, install, first-time integration, convex.config, authz.ts, tenants.ts, getting started, initial setup
api-reference	`docs/api-reference.md`	Function names (listOrganizations, createOrganization, addMember, inviteMember, etc.), makeTenantsAPI options, event hooks, mutation/query args, pagination (listMembers/listTeams/listTeamMembers/listInvitations with optional paginationOpts), API signatures
permission-map	`docs/permission-map.md`	Permissions, permissionMap, who can do what, operation permissions, overriding permissions, guards, access control per operation
flexible-roles	`docs/flexible-roles.md`	Roles, custom roles, owner/admin/member, creatorRole, defineRoles, structural owner, transferOwnership, add/remove roles
invitation-system	`docs/invitation-system.md`	Invitations, inviteMember, acceptInvitation, validateInvitationCreate, validateInvitationAccept, identifier type, email/phone/username, domain whitelist, rate limiting invitations
react-components	`docs/react-components.md`	TenantsProvider, OrganizationSwitcher, MembersSection, TeamsSection, InviteMemberDialog, useOrganization, useMembers, useTeams, useOrganizationInvitations, MembersTable, TeamsGrid, AcceptInvitation, JoinByDomainSection, paginated hooks
organization-store	`docs/organization-store.md`	Active organization, switching orgs, useOrganizationStore, setActiveOrganizationId, localStorage, storageKey, configureOrganizationStore

基础路径：

node_modules/@djpanda/convex-tenants/docs/

。根据用户的关键词或任务选择对应文档 — 仅加载所需内容：

文档	路径	用户询问以下内容时加载
quick-start	`docs/quick-start.md`	搭建、安装、首次集成、convex.config、authz.ts、tenants.ts、入门指南、初始设置
api-reference	`docs/api-reference.md`	函数名称（listOrganizations、createOrganization、addMember、inviteMember等）、makeTenantsAPI选项、事件钩子、变更/查询参数、分页（listMembers/listTeams/listTeamMembers/listInvitations结合可选paginationOpts）、API签名
permission-map	`docs/permission-map.md`	权限、permissionMap、操作权限分配、覆盖权限、守卫、按操作划分的访问控制
flexible-roles	`docs/flexible-roles.md`	角色、自定义角色、owner/admin/member、creatorRole、defineRoles、结构化所有者、transferOwnership、添加/移除角色
invitation-system	`docs/invitation-system.md`	邀请、inviteMember、acceptInvitation、validateInvitationCreate、validateInvitationAccept、标识符类型、邮箱/电话/用户名、域名白名单、邀请频率限制
react-components	`docs/react-components.md`	TenantsProvider、OrganizationSwitcher、MembersSection、TeamsSection、InviteMemberDialog、useOrganization、useMembers、useTeams、useOrganizationInvitations、MembersTable、TeamsGrid、AcceptInvitation、JoinByDomainSection、分页钩子
organization-store	`docs/organization-store.md`	活跃组织、切换组织、useOrganizationStore、setActiveOrganizationId、localStorage、storageKey、配置organizationStore

Installation

安装

bash

npm install @djpanda/convex-tenants @djpanda/convex-authz

For React UI:

npm install clsx tailwind-merge

(optional peer deps).

bash

npm install @djpanda/convex-tenants @djpanda/convex-authz

如需React UI：

npm install clsx tailwind-merge

（可选对等依赖）。