Installation

Requirements

CASL is isomorphic, so can be used in browsers and in Nodejs environments. It requires an ES2020-compatible environment or newer.

Semantic Versioning

CASL follows Semantic Versioning in all its official projects. Changes can be found in release notes or in CHANGELOG.md file inside each package.

Official packages and its versions

Project	Status	Description
@casl/ability		CASL's core package
@casl/mongoose		integration with Mongoose
@casl/prisma		integration with Prisma
@casl/angular		integration with Angular
@casl/react		integration with React
@casl/vue		integration with Vue

3rd party packages

There are also 3rd party packages which we can utilize in our projects. To find them, just search on NPM using "casl" keyword

Add "casl" in package.json#keywords array to show up your CASL based package in that list

NPM, YARN, PNPM

Installation through package manager is the recommended way to install CASL. To install the latest stable version run:

npm install @casl/ability
# or
yarn add @casl/ability
# or
pnpm add @casl/ability

CDN

For prototyping or learning purposes, you can use the latest version with:

<script type="module">
  import { Ability } from 'https://esm.sh/@casl/ability';
</script>

For production, we recommend linking to a specific version number to avoid unexpected breakage from newer versions:

<script type="module">
  import { Ability } from 'https://esm.sh/@casl/ability@6';
</script>

Download and use ESM

CASL no longer ships a standalone UMD build. If you want to load it without a package manager, use an ESM-capable CDN and import it from a <script type="module">.

Explanation of Different Builds

In the dist/ directory of the NPM package you will find the published module builds:

All official packages now use the same dist/esm and dist/cjs layout.

Webpack

Webpack runs ESM JavaScript in a strict mode. The issue is that webpack4 reads only main property of package.json and ignores everything else in resolve.mainFields. All casl related packages, including ucast, distribute CommonJS file in main property. And this results to the next issue:

ERROR in ./node_modules/@casl/ability/dist/esm/index.mjs Can't import the named export 'xxx' from non EcmaScript module (only default export is available)

The best way to fix it is to upgrade to webpack 5 which reads exports property of package.json when import packages and properly and works with ESM imports. But if you stuck with webpack 4, read this comment for possible workarounds.

CSP environments

Some environments, such as Google Chrome Apps, enforce Content Security Policy (CSP), which prohibits the use of new Function() for evaluating expressions.

CASL doesn't use any of the prohibited functions, so feel free to use it in any environments.

Dev build

Important: the built files in GitHub's /dist folder are not checked-in during releases. To use CASL from the latest source code on GitHub, you will have to build it yourself! Navigate your project root and run this:

git clone git@github.com:stalniy/casl.git
cd casl
pnpm i -r
cd packages/casl-ability
npm run build