vacl

A Lightweight Typescript ACL directives library for Vue 3

Usage no npm install needed!

<script type="module">
  import vacl from 'https://cdn.skypack.dev/vacl';
</script>

README

Statements Branches Functions Lines
Statements Branches Functions Lines

Vacl

A lightweight, strictly-typed, Vue 3 ACL directives library.
Report Bug ยท Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Advanced Configuration
  5. Roadmap
  6. Contributing
  7. License
  8. Contact
  9. Acknowledgements

About The Project

Vacl is a small, fast and strictly typed ACL for Vue3. It offers simple on-load configuration for permissions and roles, with helpful template directives like v-can, v-cannot, etc.

It is not a full ACL system, like CASL, rather an easy-to-start js accompaniment to the likes of the Spatie Laravel Permissions package.

Vacl is designed to get you set up with frontend authorisation as fast as possible, so you can move on to other things in your SPA.

<!---If the delete permission is matched-->
<button v-can="'delete'">Delete</button>

<!---If the staff role is matched-->
<button v-has="'staff'">Delete</button>

Built With

Getting Started

Prerequisites

This library is for Vue3 only. If you need ACL for Vue2 please consider one of the following:

Installation

  1. Install:

    npm install vacl

    or

    yarn add vacl

  2. Configure:

    import VACL from 'vacl';
 
createApp(App)
.use(VACL, {
  permissions: ['view products', 'edit products'],
  roles: ['staff', 'editor']
})
.mount('#app');

    We are manually passing a config object as an example. In reality the roles and permissions would be generated on the server and passed to the frontend.

    Just ensure the config passed to VACL takes the following shape:

    {
  permissions: string[];
  roles: roles[];
}

    Please note: This is a collective of the roles/permissions that the user has, if a match is unsuccessful it is assumed the user does not have that role/permission.

Usage

Directives

To show or remove an element based on permissions:

<!---If the delete permission is matched-->
<button v-can="'delete'">Delete</button>

<!---If either the delete or archive permission is matched-->
<button v-can:any="'delete,archive'">Delete</button>

<!---If both delete and archive permission is matched-->
<button v-can:all="'delete,archive'">Delete</button>

Roles work exactly same, using the has directive:

<!---If the staff role is matched-->
<button v-has="'staff'">Delete</button>

<!---If either the staff or editor role is matched-->
<button v-has:any="'staff,editor'">Delete</button>

<!---If both staff and editor role is matched-->
<button v-has:all="'staff,editor'">Delete</button>

There are also inverse directives, should you need them:

<!---If the delete permission is missing-->
<button v-cannot="'delete'">Contact an Admin</button>

<!---If either the delete or archive permission is missing-->
<button v-cannot:any="'delete,archive'">Contact an Admin</button>

<!---If both delete and archive permission are missing-->
<button v-cannot:all="'delete,archive'">Contact an Admin</button>

For roles:

<!---If the staff role is missing-->
<button v-hasnt="'staff'">Contact an Admin</button>

<!---If either the staff or editor role is missing-->
<button v-hasnt:any="'staff,editor'">Contact an Admin</button>

<!---If both staff and editor role are missing-->
<button v-hasnt:all="'staff,editor'">Contact an Admin</button>

Direct Invocation

If you need something more complex you can access the Vacl instance directly:

<button v-if="$vacl.can('delete') || $vacl.has('admin')">Delete</button>

There are also a number of methods you can leverage on the $vacl instance:

Method Argument Description
can() string[]
string		 Shorthand accessor for hasAllPermissions().
hasAllPermissions() string[]
string		 Assert the store has all of the passed permission(s).
hasAnyPermissions() string[]
string		 Assert the store has any of the passed permission(s).
missingAllPermissions() string[]
string		 Assert the store is missing all of the passed permission(s).
missingAnyPermissions() string[]
string		 Assert the store is missing at least 1 of the passed permission(s).
has() string[]
string		 Shorthand accessor for hasAllRoles().
hasAllRoles() string[]
string		 Assert the store has all of the passed role(s).
hasAnyRoles() string[]
string		 Assert the store has any of the passed role(s).
missingAllRoles() string[]
string		 Assert the store is missing all of the passed role(s).
missingAnyRoles() string[]
string		 Assert the store is missing at least 1 of the passed role(s).
getRoles() - Gets the array of currently stored roles.
getPermissions() - Gets the array of currently stored permissions.
setRoles() string[] Overwrites the role store with the passed array.
setPermissions() string[] Overwrites the permission store with the passed array.
addRoles() string[]
string		 Adds the given role(s) to the role store.
addPermissions() string
string[]		 Adds the given permission(s) to the permission store.
clearRoles() - Clears the currently stored roles.
clearPermissions() - Clears the currently stored permissions.
clear() - Clears both the role and permission store.

Advanced Configuration

When initialising (app.use(Vacl, config)) there are additional properties you can set:

Property Default Description
permissions [ ] Array of permission strings that the user has, eg: ['view jobs', 'edit posts']
roles [ ] Array of role strings that the user has, eg: ['admin', 'sales']
forceRemove false By default a directive that fails a check, like v-can, will set the element to display: hidden. If forceRemove is set to true then the element will be removed from the DOM entirely. This might be especially desirable when using on active components, but carries the cost of removing the element from the Vue reactivity watchers.

Reactivity

There are some limitations regarding the reactivity in Vue. For instance once an element is removed via a custom directive (pretty much anything other than v-if) it is not currently possible to re-insert it should the user gain the necessary role/permission - a page refresh is required. This is an issue with all Vue acl-directive packages, but we are currently investigating work-arounds.

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Twitter - @FullStackFool

NPM - https://www.npmjs.com/package/vacl

Acknowledgements

Below is a list of those who have helped with excellent peer review and feedback during development.