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
For Vue 2.x:
npm install @casl/[email protected] @casl/ability
# or
yarn add @casl/[email protected] @casl/ability
# or
pnpm add @casl/[email protected] @casl/ability
For Vue 3.x:
npm install @casl/vue @casl/ability
# or
yarn add @casl/vue @casl/ability
# or
pnpm add @casl/vue @casl/ability
Getting started
This package provides a Vue plugin, several hooks for new Vue Composition API and Can
component.
The plugin
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:
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:
<template>
<div v-if="$can('create', 'Post')">
<a @click="createPost">Add Post</a>
</div>
</template>
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
:
createApp()
.use(abilitiesPlugin, ability)
.mount('#app');
And to inject an Ability
instance in a component, we can use ABILITY_TOKEN
:
<template>
<div>
<div v-if="$ability.can('create', 'Post')">
<a @click="createPost">Add Post</a>
</div>
</div>
</template>
<script>
import { ABILITY_TOKEN } from '@casl/vue';
export default {
inject: {
$ability: { from: ABILITY_TOKEN }
}
}
</script>
This is a bit more verbose but allows us to be explicit. This works especially good with new Composition API:
<template>
<div>
<div v-if="can('create', 'Post')">
<a @click="createPost">Add Post</a>
</div>
</div>
</template>
<script>
import { useAbility } from '@casl/vue';
export default {
setup() {
// some code
const { can } = useAbility();
return {
// other props
can
};
}
}
</script>
provideAbility hook
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:
<template>
<!-- a template -->
</template>
<script>
import { provideAbility } from '@casl/vue';
import { defineAbility } from '@casl/ability';
export default {
setup() {
const myCustomAbility = defineAbility((can) => {
// ...
});
provideAbility(myCustomAbility)
}
}
</script>
See CASL guide to learn how to define
Ability
instance.
Can component
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):
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:
<template>
<Can I="create" a="Post">
<a @click="createPost">Add Post</a>
</Can>
</template>
It accepts default slot and 5 properties:
-
do
- name of the action (e.g.,read
,update
). Has an aliasI
-
on
- checked subject. Hasa
,an
,this
aliases -
field
- checked field<template> <Can I="read" :this="post" field="title"> Yes, you can do this! ;) </Can> </template>
-
not
- inverts ability check and show UI if user cannot do some action:<template> <Can not I="create" a="Post"> You are not allowed to create a post </Can> </template>
-
passThrough
- renders children in spite of whatability.can
returns. This is useful for creating custom components based onCan
. For example, if you need to disable button based on user permissions:<template> <div> <Can I="delete" a="Post" passThrough v-slot="{ allowed }"> <button :disabled="!allowed">Delete post</button> </Can> </div> </template>
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
(oran
) alias when you check by Type<Can I="read" a="Post">...</Can>
-
use
this
alias when you check action on a particular instance. So, the question can be read as "Can I read this particular post?"<Can I="read" :this="post">...</Can>
-
use
do
andon
if you are bored and don't want to make your code more readable :)<Can do="read" :on="post">...</Can> <Can do="read" :on="post" field="title">...</Can>
Component vs reactive Ability
Let's consider PROS and CONS of both solutions in order to make the decision.
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
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
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 <Can>
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:
import { Ability, AbilityClass } from '@casl/ability';
type Actions = 'create' | 'read' | 'update' | 'delete';
type Subjects = 'Article' | 'User'
export type AppAbility = Ability<[Actions, Subjects]>;
export const AppAbility = Ability as AbilityClass<AppAbility>;
Augment Vue types
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:
import { AppAbility } from './AppAbility'
declare module 'vue' {
interface ComponentCustomProperties {
$ability: AppAbility;
$can(this: this, ...args: Parameters<this['$ability']['can']>): boolean;
}
}
Composition API
With composition API, we don't need to augment Vue types and can use useAbility
hook:
import { useAbility } from '@casl/vue';
import { AppAbility } from './AppAbility';
export default {
setup(props) {
const { can } = useAbility<AppAbility>();
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:
import { useAbility } from '@casl/vue';
import { AppAbility } from '../AppAbility';
export const useAppAbility = () => useAbility<AppAbility>();
Options API
It's also possible to use @casl/vue
and TypeScript with options API. By default, ABILITY_TOKEN
is typed as InjectionKey<Ability>
, to cast it to InjectionKey<AppAbility>
, we need to use a separate variable:
import { InjectionKey } from 'vue';
import { ABILITY_TOKEN } from '@casl/vue';
// previous content that defines `AppAbility`
export const TOKEN = ABILITY_TOKEN as InjectionKey<AppAbility>;
and now, when we inject AppAbility
instance, we will have the correct types:
<script lang="ts">
import { defineComponent } from 'vue';
import { TOKEN } from './AppAbility';
export default defineComponent({
inject: {
ability: { from: TOKEN }
},
created() {
this.ability // AppAbility
}
});
</script>
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:
<template>
<form @submit.prevent="login">
<input type="email" v-model="email" />
<input type="password" v-model="password" />
<button type="submit">Login</button>
</form>
</template>
<script>
import { AbilityBuilder, Ability } from '@casl/ability';
import { ABILITY_TOKEN } from '@casl/vue';
export default {
name: 'LoginForm',
inject: {
$ability: { from: ABILITY_TOKEN }
},
data: () => ({
email: '',
password: ''
}),
methods: {
login() {
const { email, password } = this;
const params = { method: 'POST', body: JSON.stringify({ email, password }) };
return fetch('path/to/api/login', params)
.then(response => response.json())
.then(({ user }) => this.updateAbility(user));
},
updateAbility(user) {
const { can, rules } = new AbilityBuilder(Ability);
if (user.role === 'admin') {
can('manage', 'all');
} else {
can('read', 'all');
}
this.$ability.update(rules);
}
}
};
</script>
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