vue-access-guard

Permission-aware helpers for Vue 3 + Quasar applications. This library centralizes how dynamic routes and UI fragments are enabled according to the permissions delivered by your backend so you can share the same rules across teams.

• Multi-format bundles: ESModule, CommonJS and UMD (with sourcemaps & types)
• Router guard that lazily fetches module permissions and injects routes on demand
• <PermissionWrapper> component to toggle template fragments without scattered checks
• Minimal API surface designed to integrate with existing stores, Axios clients or custom fetchers

Installation

npm install vue-access-guard
# or
pnpm add vue-access-guard

In peer environments you must already depend on vue@^3.3.0, vue-router@^4.2.0 and (optionally) quasar@^2.

Quick start

The library only requires two steps:

1. Configure how permissions are retrieved (once, when your app boots).
2. Attach the router guard and optionally wrap view fragments.

// main.ts
import { createApp } from "vue";
import App from "./App.vue";
import router from "./router";
import { init, routerWarder } from "vue-access-guard";
import apiClient from "./services/apiClient";
import { appRoutes } from "./router/routes";

init({
  moduleEndpoint: "/backoffice/apps/functionalities/module",
  axios: apiClient, // anything exposing a POST method will work
});

routerWarder(router, appRoutes, {
  moduleUrl: ({ to }) =>
    (to.meta as { moduleUrl?: string })?.moduleUrl ?? to.path,
  cachePermissions: true,
});

createApp(App).use(router).mount("#app");

<!-- PermissionWrapper.vue -->
<template>
  <PermissionWrapper functionality="dashboard">
    <DashboardPanel />

    <template #fallback>
      <NoAccessMessage />
    </template>
  </PermissionWrapper>
</template>

<script setup lang="ts">
import { PermissionWrapper } from "vue-access-guard";
import DashboardPanel from "@/components/DashboardPanel.vue";
import NoAccessMessage from "@/components/NoAccessMessage.vue";
</script>

When the user navigates, routerWarder resolves the active module, fetches its permissions (using the strategy you configured via init) and injects the routes returned by filterRoutesByPermissions. The <PermissionWrapper> component handles any slot structure and only renders fragments that match active permissions.

API overview

| Export | Purpose | | --------------------------------------------------- | ------------------------------------------------------------------------------- | | init(config) / getConfig() | Register global dependencies (Axios client, custom stores, endpoints). | | routerWarder(router, routes, options) | Attach the navigation guard that fetches and caches module permissions. | | filterRoutesByPermissions(routes, options) | Filter route records before adding them to the router. | | setPermissions, getPermissions, getPermission | Manage the in-memory permission cache manually. | | PermissionWrapper | Vue component that conditionally renders its slots based on functionality keys. | | types.ts exports | Reusable TypeScript definitions for route and permission records. |

See the inline JSDoc across src/ for additional behavioural details.

Development scripts

• pnpm run dev – Vite dev server to iterate on the library playground or test harness.
• pnpm run lint – ESLint flat config focused on TypeScript sources.
• pnpm run typecheck – tsc --noEmit to validate type safety without emitting files.
• pnpm run test – Vitest suite covering the module configuration & permission store helpers.
• pnpm run build – Generates the production bundles (dist/) along with declaration files.
• pnpm run prepublishOnly – End-to-end sanity check executed automatically before publishing.

Publishing to npm

1. Bump the version following SemVer. For your first public release move to 1.0.0 once the API is stable.
2. Make sure pnpm run prepublishOnly finishes without errors. This runs linting, type checks, tests and the production build.
3. Confirm the package contents with pnpm pack – only the dist/, README.md and LICENSE files are shipped thanks to the "files" whitelist.
4. Publish from a clean git state: npm publish --access public.

You can use npm publish --dry-run to verify the archive before shipping it to the registry.

Contributing

1. Fork the repository and create a topic branch.
2. Install dependencies with pnpm install.
3. Add or update tests when fixing bugs or shipping new features.
4. Run the full quality gate (pnpm run lint && pnpm run typecheck && pnpm run test).
5. Open a pull request describing the change and the motivation behind it.

Bug reports and feature suggestions are very welcome – please use the GitHub issues tracker linked in package.json.

License

Released under the MIT License – see LICENSE for the full text. Feel free to use this package in commercial and open-source projects.