Vue Access Control List (Vue 2)

Common errors

• TypeError: Cannot read properties of undefined (reading 'check')

  cause The `$acl` instance was not properly injected into the Vue application context.
  fix Verify that `acl` is passed to the root Vue instance: `new Vue({ ..., acl, ... }).$mount('#app')`, and that `Vue.use(AclInstaller)` was called.

• Rule 'myRule' not found or not applying correctly in route meta.

  cause An `AclRule` instance was not correctly created or generated for the route meta, or a `globalRule` name was misspelled.
  fix For direct `AclRule` instances in `meta.rule`, ensure it's `new AclRule('permission').generate()`. For `globalRules`, ensure the string name matches exactly, e.g., `meta: { rule: 'isAdmin' }`.

• Navigation fails or redirects unexpectedly when changing routes.

  cause The `notfound` property in `AclCreate` might be misconfigured, or the `middleware` is prematurely calling `acl.change()` with an incorrect permission.
  fix Check the `notfound` path and `forwardQueryParams` setting. Debug the `middleware` function to ensure `acl.change()` is called with the intended permission only after successful authentication or role determination.

Warnings

• breaking This package is explicitly designed for Vue.js 2.x. It is not compatible with Vue 3.x due to significant changes in Vue's plugin API and reactivity system (e.g., `Vue.use` vs `app.use`). Attempting to use it in a Vue 3 project will result in runtime errors.
  Fix: For Vue 3 projects, consider alternatives like `vue-simple-acl` or `vacl`, or implement ACL logic natively using Vue 3's composition API.
• gotcha Forgetting to call `.generate()` on `AclRule` instances when defining rules (e.g., in `globalRules` or `meta.rule`) will lead to rules not being properly compiled and applied, resulting in unexpected permission checks.
  Fix: Always append `.generate()` when creating a new `AclRule` instance: `new AclRule('permission').generate()`.
• gotcha The `middleware` function in `AclCreate` is an asynchronous method that executes on every route change. Long-running or inefficient operations within this middleware can significantly impact navigation performance.
  Fix: Optimize API calls and data processing within the `middleware` to be as fast as possible. Consider caching results if appropriate.
• gotcha The `$acl.check()` and `$acl.not.check()` methods in templates rely on the `acl` instance being correctly injected into the root Vue instance. If `acl` is not passed to `new Vue({})`, these methods will be undefined.
  Fix: Ensure `new Vue({ router, acl, ... })` includes your `acl` instance after calling `Vue.use(AclInstaller)` and instantiating `AclCreate`.

Install

• npm install vue-acl npm
• yarn add vue-acl yarn
• pnpm add vue-acl pnpm

Imports

• AclInstaller
  wrong:

  const AclInstaller = require('vue-acl').AclInstaller

  correct:

  import { AclInstaller } from 'vue-acl'

  Used with `Vue.use(AclInstaller)` to register the plugin.
• AclCreate
  wrong:

  import AclCreate from 'vue-acl'

  correct:

  import { AclCreate } from 'vue-acl'

  The primary class for configuring the ACL instance; named import is required.
• AclRule
  wrong:

  import { Rule } from 'vue-acl'

  correct:

  import { AclRule } from 'vue-acl'

  Used to construct individual access rules, often chained with `.or()`, `.and()`, and ending with `.generate()`.

Quickstart

This quickstart demonstrates the core setup of vue-acl, including installation, defining global rules, integrating with Vue Router for route protection, and passing the ACL instance to the root Vue instance. It also shows a basic `middleware` for dynamic permission changes and how to use `$acl.check()` within a component template.

import Vue from 'vue';
import Router from 'vue-router';
import App from './App.vue';
import { AclInstaller, AclCreate, AclRule } from 'vue-acl';

// 1. Define your Vue Router instance
Vue.use(Router);
const router = new Router({
  routes: [
    {
      path: '/',
      name: 'public',
      component: { template: '<div>Public Page <button v-if="$acl.check(\'admin\')">Admin Button</button></div>' },
      meta: { rule: 'isPublic' }
    },
    {
      path: '/admin',
      name: 'admin',
      component: { template: '<div>Admin Page <button v-if="$acl.not.check(\'public\')">Only Admin Button</button></div>' },
      meta: { rule: new AclRule('admin').generate() }
    },
    {
      path: '/error',
      name: 'notfound',
      component: { template: '<div>404 Not Found</div>' },
      meta: { rule: '*' }
    }
  ]
});

// 2. Install vue-acl plugin
Vue.use(AclInstaller);

// 3. Create your Acl instance
const acl = new AclCreate({
  initial: 'public',
  notfound: {
    path: '/error',
    forwardQueryParams: true
  },
  router,
  acceptLocalRules: true,
  globalRules: {
    isAdmin: new AclRule('admin').generate(),
    isPublic: new AclRule('public').or('admin').generate()
  },
  middleware: async acl => {
    // Simulate API call for user permissions
    await new Promise(resolve => setTimeout(resolve, 500));
    // In a real app, you'd fetch user roles from an API
    const userRole = process.env.VUE_APP_USER_ROLE ?? 'public'; // Example: 'admin' or 'public'
    acl.change(userRole);
  }
});

// 4. Mount your Vue app with router and acl
Vue.config.productionTip = false;

new Vue({
  router,
  acl,
  render: h => h(App)
}).$mount('#app');

// App.vue (minimal for demonstration)
// <template><div><router-link to="/">Public</router-link> | <router-link to="/admin">Admin</router-link><router-view /></div></template>
// <script>export default { name: 'App' }</script>