dbjpanda/convex-tenants

Convex Tenants

Multi-tenant organization and team management for Convex with flexible authorization via @djpanda/convex-authz.

Quick Start

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

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;

2. 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.

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

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;
    },
  });

4. Use in React — useQuery(api.tenants.listOrganizations), or use pre-built components with TenantsProvider. See 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.

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 |

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 |

Installation

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

For React UI: npm install clsx tailwind-merge (optional peer deps).