> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

> Installez le paquet NPM officiel @auth0/actions comme dépendance de développement afin d'ajouter les définitions de types TypeScript, IntelliSense et la vérification des erreurs lors de l'écriture et des tests unitaires des Auth0 Actions par trigger et par version dans des éditeurs externes.

# Écrire votre Action à l'aide de votre éditeur de code

Utilisez le paquet NPM [`@auth0/actions`](https://www.npmjs.com/package/@auth0/actions) pour écrire et soumettre vos Actions à des tests unitaires dans votre propre éditeur de code ou IDE, avec toutes les fonctions d'IntelliSense, de vérification des types et de détection des erreurs.

### 1. Installer le paquet

Utilisez l’un des gestionnaires de paquets suivants pour installer le paquet :

**NPM**

Utilisez `--save-dev` lors de l’installation du paquet pour indiquer qu’il s’agit d’une dépendance de développement venant compléter vos outils de développement.

```bash title="install-npm.sh" theme={null}
npm install @auth0/actions --save-dev
```

**Yarn**

Utilisez `--dev` lors de l’installation du paquet pour indiquer qu’il s’agit d’une dépendance de développement venant compléter vos outils de développement.

```bash title="install-yarn.sh" theme={null}
yarn add @auth0/actions --dev
```

**Pnpm**

Utilisez `--save-dev` lors de l’installation du paquet pour indiquer qu’il s’agit d’une dépendance de développement venant compléter vos outils de développement.

```bash title="install-pnpm.sh" theme={null}
pnpm add @auth0/actions --save-dev
```

### 2. Importer les définitions de types

Utilisez l’une des options suivantes pour importer les définitions TypeScript dans vos Actions, selon votre technologie :

**JSDocs @import**

Choisissez cette option si vous voulez profiter d’IntelliSense sans modifier la structure de votre code JavaScript existant :

```js title="jsdocs-import.js" theme={null}
/** @import {Event, PostLoginAPI} from "@auth0/actions/post-login/v3" */

/**
* Gestionnaire qui sera appelé lors de l'exécution d'un flux PostLogin.
*
* @param {Event} event - Détails sur l'utilisateur et sur le contexte dans lequel il se connecte.
* @param {PostLoginAPI} api - Interface dont les méthodes permettent de modifier le comportement de la connexion.
*/
exports.onExecutePostLogin = async (event, api) => {
  // Votre code
}
```

**JSDocs @param**

Choisissez cette option pour assurer la sûreté de typage dans les fichiers JavaScript au moyen d’instructions d’importation placées dans les commentaires JSDoc :

```js title="jsdocs-param.js" theme={null}
/**
* Gestionnaire qui sera appelé lors de l'exécution d'un flux PostLogin.
*
* @param {import('@auth0/actions/post-login/v3').Event} event - Détails sur l'utilisateur et le contexte dans lequel il se connecte.
* @param {import('@auth0/actions/post-login/v3').PostLoginAPI} api - Interface dont les méthodes permettent de modifier le comportement de la connexion.
*/
exports.onExecutePostLogin = async (event, api) => {
    // Votre code
};
```

**TS types import**

Choisissez cette option si vous développez avec TypeScript, pour une vérification de types complète et une syntaxe moderne :

```ts title="types-import.ts" theme={null}
import type { Event, PostLoginAPI } from '@auth0/actions/post-login/v3';

/**
* Gestionnaire qui sera appelé lors de l'exécution d'un flux PostLogin.
*
* @param {Event} event - Détails sur l'utilisateur et le contexte dans lequel il se connecte.
* @param {PostLoginAPI} api - Interface dont les méthodes permettent de modifier le comportement de la connexion.
*/
exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
  // Votre code
};
```

L’instruction d’importation doit reposer sur le **nom du trigger** et le **numéro de version**, en tenant compte de la [structure de la bibliothèque](#library-structure).

**Suivez ce modèle** : `@auth0/actions/[trigger_name]/[trigger_version]`

**Par exemple** : `@auth0/actions/post-login/v3`

> **Structure de la bibliothèque**
>
> **@auth0/actions**
>
> **credentials-exchange**
>
> **v1**
>
> **v2**
>
> **custom-email-provider**
>
> **v1**
>
> **custom-phone-provider**
>
> **v1**
>
> **custom-token-exchange**
>
> **v1**
>
> **event-stream**
>
> **v1**
>
> **password-reset-post-challenge**
>
> **v1**
>
> **post-change-password**
>
> **v1**
>
> **v2**
>
> **post-login**
>
> **v1**
>
> **v2**
>
> **v3**
>
> **post-user-registration**
>
> **v1**
>
> **v2**
>
> **pre-user-registration**
>
> **v1**
>
> **v2**
>
> **send-phone-message**
>
> **v1**
>
> **v2**

### 3. Configurer votre projet

Les exemples de configuration suivants sont volontairement présentés en JavaScript et en TypeScript, afin d’offrir une comparaison directe, côte à côte.

**JavaScript**

Dans votre `package.json`, définissez les dépendances de développement afin de bénéficier de l’aide d’IntelliSense pendant la rédaction de votre Action :

```json title="package.json" theme={null}
{
  "name": "actions-npm-example-js",
  "version": "1.0.0",
  "description": "Auth0 Actions npm dependency example using JavaScript",
  "main": "example.js",
  "author": "Auth0",
  "license": "MIT",
  "devDependencies": {
    "@auth0/actions": "^0.33.0"
  }
}
```

Dans votre `jsconfig.json`, définissez les dépendances de développement afin de bénéficier de l’aide d’IntelliSense pendant la rédaction de votre Action.

```json title="jsconfig.json" theme={null}
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "checkJs": false,
    "baseUrl": ".",
    "paths": {
      "actions:*": ["src/*"]
    }
  },
  "include": ["src/**/*.js"]
}

```

**TypeScript**

Dans votre `package.json`, définissez les dépendances de développement afin de bénéficier de l’aide d’IntelliSense pendant la rédaction de votre Action.

```json title="package.json" theme={null}
{
  "name": "actions-npm-example-ts",
  "version": "1.0.0",
  "description": "Auth0 Actions npm dependency example using TypeScript",
  "main": "example.ts",
  "author": "Auth0",
  "license": "MIT",
  "devDependencies": {
    "@auth0/actions": "^0.33.0",
    "@types/node": "22.14.0",
    "typescript": "^5.9.2"
  }
}
```

Dans votre `tsconfig.json`, définissez les dépendances de développement afin de bénéficier de l’aide d’IntelliSense pendant la rédaction de votre Action.

```json title="tsconfig.json" theme={null}
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "nodenext",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "outDir": "dist",
    "declaration": true,
    "sourceMap": true,
    "allowJs": true,
    "checkJs": false,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "noEmit": true,
    "paths": {
      "actions:*": ["./src/*"]
    }
  },
  "exclude": [
    "node_modules",
    "dist"
  ],
  "include": [
    "**/*.ts"
  ],
  "ts-node": {
    "transpileOnly": true
  }
}

```

### 4. Rédiger le code de votre Action

L’exemple d’Action suivant s’exécuterait pendant le flux Post-Login. Il vérifie si des rôles sont attribués à l’utilisateur et appelle `api.access.deny()` si aucun rôle n’est trouvé. Si des rôles sont présents, il définit ensuite la demande personnalisée dans le jeton d’ID.

L’instruction d’importation rend les types externes accessibles à votre code. L’éditeur connaît ainsi la structure des objets `event` et `api`.

**JavaScript**

```js title="example.js" theme={null}
/** @import {Event, PostLoginAPI} from "@auth0/actions/post-login/v3" */

const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';

/**
* Gestionnaire appelé lors de l'exécution d'un flux PostLogin.
*
* @param {Event} event - Détails sur l'utilisateur et le contexte dans lequel il se connecte.
* @param {PostLoginAPI} api - Interface dont les méthodes permettent de modifier le comportement de la connexion.
*/
exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles;

  if (roles === undefined || roles.length === 0) {
    api.access.deny('Restricted');
    return;
  }

  api.idToken.setCustomClaim(`${CUSTOM_CLAIM_NAMESPACE}/roles`, roles);
}
```

**TypeScript**

```ts title="example.ts" theme={null}
import type { Event, PostLoginAPI } from '@auth0/actions/post-login/v3';

const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';

/**
* Gestionnaire appelé lors de l'exécution d'un flux PostLogin.
*
* @param {Event} event - Détails sur l'utilisateur et le contexte dans lequel il se connecte.
* @param {PostLoginAPI} api - Interface dont les méthodes permettent de modifier le comportement de la connexion.
*/
exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
  const roles = event.authorization?.roles;

  if (roles === undefined || roles.length === 0) {
    api.access.deny('Restricted');
    return;
  }

  api.idToken.setCustomClaim(`${CUSTOM_CLAIM_NAMESPACE}/roles`, roles);
};
```

> [!WARNING]
>
> Si vous utilisez TypeScript, vous devez compiler votre code en JavaScript avant de le déployer dans Auth0. L’environnement d’exécution d’Auth0 Actions n’exécute que du JavaScript. Utilisez le compilateur TypeScript (`tsc`) pour transpiler vos fichiers `.ts` en fichiers `.js` avant de pouvoir les déployer. Vous devez aussi inclure des commentaires JSDoc pour activer IntelliSense dans le Dashboard.

> [!TIP]
>
> **Point de contrôle**
>
> Vous devriez maintenant disposer d’une Action fonctionnelle, rédigée et validée sur le plan des types dans votre propre éditeur de code, prête à être déployée dans Auth0.