CASL Vue


This package allows to integrate @casl/ability with [Vue 3] application. So, you can show or hide UI elements based on user ability to see them.

Installation

``sh
npm install @casl/vue @casl/ability


or

yarn add @casl/vue @casl/ability

or

pnpm add @casl/vue @casl/ability
`

For Vue 2.x

`sh
npm install @casl/vue@1.x @casl/ability


or

yarn add @casl/vue@1.x @casl/ability

or

pnpm add @casl/vue@1.x @casl/ability
`




Getting started

This package provides a Vue plugin, several hooks for new Vue Composition API and Can component.

$3

The plugin provides reactive Ability instance and optionally defines $ability and $can global properties, in the same way as it was for Vue 2.x. The only difference with the previous version is that it requires Ability instance to be passed as a mandatory argument:

`js
import { createApp } from 'vue';
import { abilitiesPlugin } from '@casl/vue';
import ability from './services/ability';

createApp()
.use(abilitiesPlugin, ability, {
useGlobalProperties: true
})
.mount('#app');
`

Later, we can use either $ability or $can method in any component:

`html

`

globalProperties is the same concept as global variables which may make life a bit more complicated because any component has access to them (i.e., implicit dependency) and we need to ensure they don't introduce name collisions by prefixing them. So, instead of exposing $ability and $can as globals, we can use provide/inject API to inject $ability:

`js
createApp()
.use(abilitiesPlugin, ability)
.mount('#app');
`

And to inject an Ability instance in a component, we can use ABILITY_TOKEN:

`html



`

This is a bit more verbose but allows us to be explicit. This works especially good with new Composition API:

`html



`

$3

Very rarely, we may need to provide a different Ability instance for a sub-tree of components, and to do this we can use provideAbility hook:

`html



`

> See CASL guide to learn how to define Ability instance.




$3

There is an alternative way we can check permissions in the app, by using Can component. Can component is not registered by the plugin, so we can decide whether we want to use component or v-if + $can method. Also, this helps tree shaking to remove it if we decide to not use it.

To register component globally, we can use global API (we can also register component locally in components that use it):

`js
import { Can, abilitiesPlugin } from '@casl/vue';

createApp()
.use(abilitiesPlugin, ability)
.component(Can.name, Can) // component registration
.mount('#app');
`

And this is how we can use it:

`html

`

It accepts default slot and 5 properties:

* do - name of the action (e.g., read, update). Has an alias I
* on - checked subject. Has a, an, this aliases
* field - checked field

`html

`

* not - inverts ability check and show UI if user cannot do some action:

`html

`

* passThrough - renders children in spite of what ability.can returns. This is useful for creating custom components based on Can. For example, if you need to disable button based on user permissions:

`html

`

#### Property names and aliases

As you can see from the code above, the component name and its property names and values create an English sentence, actually a question. The example above reads as "Can I delete a Post?".

There are several other property aliases which allow constructing a readable question. And here is a guidance to help you do this:

* use the a (or an) alias when you check by Type

`html
...
`

use this alias when you check action on a particular instance. So, the question can be read as "Can I read this particular* post?"

`html
...
`

* use do and on if you are bored and don't want to make your code more readable :)

`html
...
...
`

#### Component vs reactive Ability

Let's consider PROS and CONS of both solutions in order to make the decision.

Reactive Ability:

PROS:
* easy to use
* declarative in template with v-if
* easy to pass as a prop to another component
* easy to use in complex boolean expressions (either in js or in template)

CONS:
* more expensive to check, conditions are re-evaluated on each re-render

Can Component:

PROS:
* declarative
* can cache permissions check results until props or ability changes (currently does not)

CONS:
* more expensive to create
* adds nesting in template
* harder to use in complex boolean expressions
* harder to pass permission check as a prop to another component

Despite the fact that reactive ability check is a bit more expensive, they are still very fast and it's recommended to use reactive ability instead of component.

TypeScript support

The package is written in TypeScript, so don't worry that you need to keep all the properties and aliases in mind. If you use TypeScript, your IDE will suggest you the correct usage and TypeScript will warn you if you make a mistake.

There are few ways to use TypeScript in a Vue app, depending on your preferences. But let's first define our AppAbility type:


`ts @{data-filename="AppAbility.ts"}
import { MongoAbility } from '@casl/ability';

type Actions = 'create' | 'read' | 'update' | 'delete';
type Subjects = 'Article' | 'User'

export type AppAbility = MongoAbility<[Actions, Subjects]>;
`

$3

There is no other way for TypeScript to know types of global properties without augmentation. To do this, let's add src/shims-ability.d.ts file with the next content:

`ts @{data-filename="shims-ability.d.ts"}
import { AppAbility } from './AppAbility'

declare module 'vue' {
interface ComponentCustomProperties {
$ability: AppAbility;
$can(this: this, ...args: Parameters): boolean;
}
}
`

$3

With composition API, we don't need to augment Vue types and can use useAbility hook:

`ts
import { useAbility } from '@casl/vue';
import { AppAbility } from './AppAbility';

export default {
setup(props) {
const { can } = useAbility();

return () => can('read', 'Post') ? 'Yes' : 'No';
}
}
`

Additionally, we can create a separate useAppAbility hook, so we don't need to import useAbility and AppAbility in every component we want to check permissions but instead just import a single hook:


`ts @{data-filename="hooks/useAppAbility.ts"}
import { useAbility } from '@casl/vue';
import { AppAbility } from '../AppAbility';

export const useAppAbility = () => useAbility();
`

$3

It's also possible to use @casl/vue and TypeScript with options API. By default, ABILITY_TOKEN is typed as InjectionKey, to cast it to InjectionKey, we need to use a separate variable:

`ts @{data-filename="AppAbility.ts"}
import { InjectionKey } from 'vue';
import { ABILITY_TOKEN } from '@casl/vue';

// previous content that defines AppAbility

export const TOKEN = ABILITY_TOKEN as InjectionKey;
`

and now, when we inject AppAbility instance, we will have the correct types:

`html

`

> Read Vue TypeScript for more details

Update Ability instance

Majority of applications that need permission checking support have something like AuthService or LoginService or Session service (name it as you wish) which is responsible for user login/logout functionality. Whenever user login (and logout), we need to update Ability instance with new rules. Usually you will do this in your LoginComponent.

Let's imagine that server returns user with a role on login:

`html @{data-filename="Login.vue"}



`

> See Define rules to get more information of how to define Ability`.

Want to help?

Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on guidelines for [contributing].

If you'd like to help us sustain our community and project, consider to become a financial contributor on Open Collective

> See Support CASL for details.

License

MIT License

[contributing]: https://github.com/stalniy/casl/blob/master/CONTRIBUTING.md
[Vue 3]: https://v3.vuejs.org/guide/introduction.html