Skip to content
VexCMS

defineAccess

defineAccess<TRoles, TResources, TCustomResources, TUserSlug, TOrgSlug, TCustomActions>(props): VexAccessConfig<SubjectMap<TResources, TCustomResources, TUserSlug, TOrgSlug, TCustomActions>, TResources, TUserSlug, TOrgSlug, TCustomActions>

Defined in: packages/core/src/access/config.ts:71

Defines the RBAC configuration for a VexCMS project.

Builder in the defineCollection/defineGlobal family: infers the per-subject action/data/field registry (SubjectMap) from resources and customResources so hasPermission() calls against the returned config are fully typed; validates the matrix in dev; returns a frozen VexAccessConfig for defineConfig({ access }).

Type Parameters

Section titled “Type Parameters”

TRoles

Section titled “TRoles”

TRoles extends readonly string[]

Tuple of role name literals.

TResources

Section titled “TResources”

TResources extends readonly AccessResource[]

Tuple of collection/global configs contributing subjects.

TCustomResources

Section titled “TCustomResources”

TCustomResources extends Record<string, CustomResourceInput> = { }

Custom subject declarations ({ actions, data? }).

TUserSlug

Section titled “TUserSlug”

TUserSlug extends string = string

Slug literal of the user collection; drives the callback user type via the generated registry.

TOrgSlug

Section titled “TOrgSlug”

TOrgSlug extends string | undefined = undefined

Slug literal of the organization collection, when multi-tenant. Presence gates the organization callback key; undefined when single-tenant.

TCustomActions

Section titled “TCustomActions”

TCustomActions extends Partial<Record<TUserSlug | TResources[number]["slug"] | Extract<TOrgSlug, string>, CustomActionsInput>> = { }

Parameters

Section titled “Parameters”

props

Section titled “props”

VexAccessConfigInput<TRoles, TResources, TCustomResources, TUserSlug, TOrgSlug, TCustomActions>

The access configuration.

Returns

Section titled “Returns”

VexAccessConfig<SubjectMap<TResources, TCustomResources, TUserSlug, TOrgSlug, TCustomActions>, TResources, TUserSlug, TOrgSlug, TCustomActions>

Frozen VexAccessConfig carrying the SubjectMap phantom for inference.

Throws

Section titled “Throws”

When userCollectionSlug or userRolesField is empty, when a customResources key collides with a resource slug, or when a customResources entry declares an empty actions array. Also when a rule’s recorded constraints are not an in-order prefix of a declared index or violate Convex’s operator rule (see validateAccessConstraints), and when a constraints callback throws while being recorded — every rule’s callback runs once here, at module load, so a rule that reached past its types surfaces as a config error naming the role, resource and action rather than as a bare TypeError from whichever method was missing.

Example

Section titled “Example”
export const access = defineAccess({
  roles: ["admin", "editor"],
  resources: [pages, users],
  customResources: { apiKeys: { actions: ["create", "revoke"] } },
  userCollectionSlug: "users",
  userRolesField: "roles",
  permissions: {
    admin: { [WILDCARD_KEY]: true },
    editor: { pages: { read: true, update: true }, apiKeys: false },
  },
});

See

Section titled “See”