npm package: @juescobarcomodisimos/vue-access-guard
Description: Permission-based access control for Vue 3 + Quasar 2
Author: Juan A. Escobar
Latest version: 0.2.2

# 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

```bash
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.

```ts
// 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");
```

```vue
<!-- 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](https://semver.org). 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`](./LICENSE) for the full text. Feel free to use this package in commercial and open-source projects.