eduvia/nuxt-can
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: translate readme for release

Browse Source
This commit is contained in:
stanig2106
2025-11-14 06:18:04 +01:00
parent f12bc0ce85
commit 1d3ef7cb2b
1 changed files with 89 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
README.md
View File

@@ -5,29 +5,30 @@
[![License][license-src]][license-href] [![License][license-src]][license-href]
[![Nuxt][nuxt-src]][nuxt-href] [![Nuxt][nuxt-src]][nuxt-href]
`nuxt-can` apporte deux directives Vue (`v-can`, `v-cannot`) pour écrire des permissions ultra lisibles dans les templates Nuxt. Les directives sont transformées à la compilation en appels à une fonction `__can__` fournie par l’application hôte tout en restant 100 % tree-shake friendly et parfaitement typées côté TypeScript. `nuxt-can` ships two Vue directives (`v-can`, `v-cannot`) so you can encode permissions directly in Nuxt templates. Each directive is transformed at build time into a composable `__can__` call provided by your app, keeping the runtime lean, tree-shake friendly, and fully typed.
- [✨  Release Notes](/CHANGELOG.md) - [✨ Release Notes](/CHANGELOG.md)
## Features ## Highlights
- ✅ Directives `v-can` / `v-cannot` transformées en `v-if` / `!v-if` - ✅ Cleanly adds permissions to existing templates without rewriting your business `v-if`s
- ✅ Merge automatique avec des `v-if` existants (pas de runtime inutile) - ✅ Compile-time transform of `v-can` / `v-cannot` into `v-if` guards
- ✅ Proxy global `can` + types générés selon votre configuration de permissions - ✅ Smart merge with existing `v-if` conditions (no extra wrappers)
- ✅ Import configurable de la fonction `__can__` (store, API, …) - ✅ Auto-generated `can` proxy with types derived from your permissions map
- ✅ Erreurs compile-time claires (cas interdits détectés avant build) - ✅ Pluggable import of the host `__can__` function (stores, APIs, etc.)
- ✅ Helpful DX errors for unsupported directive shapes
## Quick Setup ## Quick Start
Installez le module dans votre application Nuxt : Install the module in your Nuxt app:
```bash ```bash
npm install nuxt-can npm install nuxt-can
# ou # or
npx nuxi module add nuxt-can npx nuxi module add nuxt-can
``` ```
Déclarez ensuite le module et configurez vos permissions : Enable it inside `nuxt.config.ts` and describe the permissions tree:
```ts ```ts
// nuxt.config.ts // nuxt.config.ts
@@ -40,12 +41,12 @@ export default defineNuxtConfig({
employee: ['view', 'edit'], employee: ['view', 'edit'],
contract: ['create'], contract: ['create'],
}, },
canFunctionImport: '~/permissions/can', // chemin vers votre implémentation __can__ canFunctionImport: '~/permissions/can', // path to your __can__ implementation
}, },
}) })
``` ```
Implémentez la fonction `__can__` dans le fichier ciblé (`~/permissions/can` dans l’exemple) : Provide the `__can__` implementation referenced above:
```ts ```ts
// permissions/can.ts // permissions/can.ts
@@ -56,88 +57,107 @@ export function __can__(path: string[]) {
} }
``` ```
Le module génère automatiquement un proxy `can` typé : Now you can write directives that stay type-safe:
```vue ```vue
<template> <template>
<button v-can="can.employee.view">Voir le dossier</button> <button v-can="can.employee.view">View profile</button>
<button v-if="isReady" v-can="can.employee.edit"> <button v-if="isReady" v-can="can.employee.edit">
Modifier Edit profile
</button> </button>
<p v-cannot>Accès refusé</p> <p v-cannot>Access denied</p>
</template> </template>
``` ```
Résultat compilé : …and the compiler rewrites them into plain conditionals:
```vue ```vue
<button v-if="__can__(['employee', 'view'])">Voir le dossier</button> <button v-if="__can__(['employee', 'view'])">View profile</button>
<button v-if="(isReady) && __can__(['employee', 'edit'])">Modifier</button> <button v-if="(isReady) && __can__(['employee', 'edit'])">Edit profile</button>
<p v-if="!(__can__(['employee', 'edit']))">Accès refusé</p> <p v-if="!(__can__(['employee', 'edit']))">Access denied</p>
``` ```
### Règles et erreurs surveillées ## Usage Rules & Errors
- `v-cannot` doit suivre immédiatement un `v-can` (aucun autre composant entre les deux). The transformer validates every template and throws descriptive errors when:
- Un `v-can` ne peut pas cohabiter avec `v-else` / `v-else-if`.
- `v-cannot` n’accepte ni expression, ni argument, ni `v-if`.
- Un seul `v-cannot` par `v-can`.
- Les expressions doivent suivre le pattern `can.x.y` (au moins deux niveaux après `can`).
Toute violation produit une erreur compile-time lisible. - `v-cannot` does not immediately follow its matching `v-can`.
- `v-can` appears on an element already using `v-else` / `v-else-if`.
- `v-cannot` uses an argument, modifiers, or a `v-if` condition.
- Multiple `v-cannot` blocks exist for the same `v-can`.
- The expression is not a static dotted path like `can.resource.action`.
### Types générés ## Generated Types
À partir de la clé `permissions`, le module génère un fichier `.d.ts` qui expose : The `permissions` map feeds a generated `types/nuxt-can.d.ts` declaration that augments:
- `can` / `$can` sur `ComponentCustomProperties` - `ComponentCustomProperties` with `can`, `$can`, and `__can__`.
- `__can__` sur les templates/scripts Nuxt - `NuxtApp` with `$can` and `$__can__`.
- `NuxtApp.$can` et `NuxtApp.$__can__` - Runtime typings for the `#build/nuxt-can/can-import.mjs` bridge.
La DX template + TypeScript reste donc impeccable sans configuration additionnelle. No extra setup is required for editors or strict TypeScript projects.
## Why `v-can`?
## Contribution Retrofitting authorization into an existing codebase often means revisiting every `v-if` to sprinkle permission checks alongside business logic. That makes templates harder to read, increases the risk of regressions, and couples security rules with UI state management. `v-can` and `v-cannot` isolate the permission layer: you keep your original conditions untouched while the transformer injects the `__can__` guards for you. As a result, business logic stays readable, authorization lives in one place, and code reviews can focus on either concern without stepping on each other.
<details> ## Playground
<summary>Local development</summary>
Run `npm run dev` to explore the playground app located in `/playground`. It demonstrates:
- Stacked `v-can` / `v-cannot` pairs.
- Interaction with existing `v-if`s and `v-for`s.
- Template blocks that share the same permission guard.
- A live permission summary powered by the injected `__can__` function.
Feel free to wire your own `~/playground/permissions/__can__.ts` to mimic a real backend.
## Local Development
```bash ```bash
# Install dependencies # Install dependencies
npm install npm install
# Generate type stubs # Prepare type stubs and the playground
npm run dev:prepare npm run dev:prepare
# Develop with the playground # Playground dev server
npm run dev npm run dev
# Build the playground # Build the playground
npm run dev:build npm run dev:build
# Run ESLint # Lint & tests
npm run lint npm run lint
# Run Vitest
npm run test npm run test
npm run test:watch npm run test:watch
# Release new version # Type checks (module + playground)
npm run test:types
# Release pipeline
npm run release npm run release
``` ```
</details> ## Contributing
1. Fork & clone the repo.
2. Run `npm run dev:prepare` once to scaffold stubs.
3. Use the playground (`npm run dev`) to reproduce issues.
4. Add tests under `test/` and fixtures under `test/fixtures/*`.
5. Open a PR following Conventional Commits (e.g. `feat:`, `fix:`).
---
<!-- Badges --> <!-- Badges -->
[npm-version-src]: https://img.shields.io/npm/v/my-module/latest.svg?style=flat&colorA=020420&colorB=00DC82 [npm-version-src]: https://img.shields.io/npm/v/nuxt-can/latest.svg?style=flat&colorA=020420&colorB=00DC82
[npm-version-href]: https://npmjs.com/package/my-module [npm-version-href]: https://npmjs.com/package/nuxt-can
[npm-downloads-src]: https://img.shields.io/npm/dm/my-module.svg?style=flat&colorA=020420&colorB=00DC82 [npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-can.svg?style=flat&colorA=020420&colorB=00DC82
[npm-downloads-href]: https://npm.chart.dev/my-module [npm-downloads-href]: https://npm.chart.dev/nuxt-can
[license-src]: https://img.shields.io/npm/l/my-module.svg?style=flat&colorA=020420&colorB=00DC82 [license-src]: https://img.shields.io/npm/l/nuxt-can.svg?style=flat&colorA=020420&colorB=00DC82
[license-href]: https://npmjs.com/package/my-module [license-href]: https://npmjs.com/package/nuxt-can
[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js [nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
[nuxt-href]: https://nuxt.com [nuxt-href]: https://nuxt.com