> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging-automated-sdk-version-update.mintlify.site/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.

<Steps titleSize="h3">
  <Step title="Installer le paquet">
    Utilisez l’un des gestionnaires de paquets suivants pour installer le paquet :

    <Tabs>
      <Tab title="NPM">
        <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
          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.
        </Callout>

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

      <Tab title="Yarn">
        <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
          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.
        </Callout>

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

      <Tab title="Pnpm">
        <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
          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.
        </Callout>

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

  <Step title="Importer les définitions de types">
    Utilisez l’une des options suivantes pour importer les définitions TypeScript dans vos Actions, selon votre technologie :

    <Tabs>
      <Tab title="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
        }
        ```
      </Tab>

      <Tab title="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
        };
        ```
      </Tab>

      <Tab title="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
        };
        ```
      </Tab>
    </Tabs>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      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`
    </Callout>

    <Accordion title="Structure de la bibliothèque">
      <Tree>
        <Tree.Folder name="@auth0/actions" defaultOpen>
          <Tree.Folder name="credentials-exchange" defaultOpen>
            <Tree.Folder name="v1" />

            <Tree.Folder name="v2" />
          </Tree.Folder>

          <Tree.Folder name="custom-email-provider" defaultOpen>
            <Tree.Folder name="v1" />
          </Tree.Folder>

          <Tree.Folder name="custom-phone-provider" defaultOpen>
            <Tree.Folder name="v1" />
          </Tree.Folder>

          <Tree.Folder name="custom-token-exchange" defaultOpen>
            <Tree.Folder name="v1" />
          </Tree.Folder>

          <Tree.Folder name="event-stream" defaultOpen>
            <Tree.Folder name="v1" />
          </Tree.Folder>

          <Tree.Folder name="password-reset-post-challenge" defaultOpen>
            <Tree.Folder name="v1" />
          </Tree.Folder>

          <Tree.Folder name="post-change-password" defaultOpen>
            <Tree.Folder name="v1" />

            <Tree.Folder name="v2" />
          </Tree.Folder>

          <Tree.Folder name="post-login" defaultOpen>
            <Tree.Folder name="v1" />

            <Tree.Folder name="v2" />

            <Tree.Folder name="v3" />
          </Tree.Folder>

          <Tree.Folder name="post-user-registration" defaultOpen>
            <Tree.Folder name="v1" />

            <Tree.Folder name="v2" />
          </Tree.Folder>

          <Tree.Folder name="pre-user-registration" defaultOpen>
            <Tree.Folder name="v1" />

            <Tree.Folder name="v2" />
          </Tree.Folder>

          <Tree.Folder name="send-phone-message" defaultOpen>
            <Tree.Folder name="v1" />

            <Tree.Folder name="v2" />
          </Tree.Folder>
        </Tree.Folder>
      </Tree>
    </Accordion>
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="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"]
        }

        ```
      </Tab>

      <Tab title="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
          }
        }

        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="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`.

    <Tabs>
      <Tab title="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);
        }
        ```
      </Tab>

      <Tab title="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.
        </Warning>
      </Tab>
    </Tabs>
  </Step>
</Steps>

<Check>
  **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.
</Check>