Migrate an existing integration
When upgrading from an older RBAC release, review both the JavaScript runtime calls and the package imports. The current package is published as @rbac/rbac with CommonJS and ESM entry points.
For a step-by-step upgrade from a published major release, use the dedicated guides: 1.x → 2.x and 2.x → 3.x. This is the archived 3.x documentation; 4.x is the current version.
Changes across major versions
Version 2 introduced the TypeScript implementation, runtime role updates, MongoDB/MySQL/PostgreSQL adapters, framework middlewares, and tenant-aware authorization helpers. Version 3 requires Node.js 22.12.0+, moves Zod schemas to the opt-in @rbac/rbac/schemas and @rbac/rbac/roles.schema subpaths, and rejects invalid SQL table or column identifiers during adapter construction. Review these changes before upgrading older code.
Review your usage
- Check the changelog for changes affecting your installed version.
- Upgrade the dependency, then verify your actual
RBAC(config)(roles)calls. The factory is curried: it first accepts optional configuration, then a role map. - Await
rbac.can(role, operation, params?). The check always returnsPromise<boolean>. - Review role inheritance and all
whenpredicates. UsecallbackWhen()from@rbac/rbac/helpersto explicitly adapt legacy Node-style callbacks. - Import persistent storage adapters from
@rbac/rbac/adaptersand framework integrations from@rbac/rbac/middlewares; install the relevant optional database driver separately. - Run your own authorization regression tests for denied paths, unknown roles, tenant separation and conditional checks before deploying.
If you previously imported schema validation from the package root, change that import to @rbac/rbac/schemas. Keep the published CommonJS factory callable through require('@rbac/rbac'), and use the same API with the ESM default import.
Example: move a callback condition to the explicit helper
import RBAC from '@rbac/rbac';
import { callbackWhen } from '@rbac/rbac/helpers';
const auth = RBAC<{ active: boolean }>()({
member: { can: [{
name: 'profile:edit',
when: callbackWhen((context, done) => done(null, context.active))
}] }
});
console.log(await auth.can('member', 'profile:edit', { active: true })); // trueDatabase adapters store role definitions, not arbitrary executable closures. Review serialized conditions before migrating from in-memory roles. The runtime guide explains how to update an instance after loading new definitions.