> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging-actions-triggers-prototype.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Code your project's Actions using @auth0/actions NPM package.

# Actions NPM

The [**`@auth0/actions`** NPM package](https://www.npmjs.com/package/@auth0/actions) is the **official Actions library** that facilitates the **Auth0 Actions TypeScript definitions**. This helps you code and test your project’s Actions in external editors and IDEs.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  The [**`@auth0/actions`** public repository](https://github.com/auth0/auth0-actions) provides access to the code behind the NPM package.
</Callout>

### Benefits

This library helps you with the following use cases:

* **IDE / Code Editor Assistance**: By referencing this library, IDEs and code editors can help developers coding with **autocompletion**, **object and function definitions**, and **error checking**.
* **TypeScript Development**: Although Actions are still coded and work using Node.js CommonJS, this library enables Actions development on external projects using **TypeScript** which then can be built and deployed as Common JS to the Auth0 Tenant.
* **Unit Testing Improvements**: By enabling TypeScript development on external projects, this library allows developers to follow best practices and to **improve their Unit Testing** based on the TypeScript definitions.
* **AI Actions Generation**: This library gets us one step closer for AI to be able to generate more accurate Action examples.

***

### How It Works

#### Installation

Use one of the following package managers to install the package as a **development dependency**:

> The package must be used as a development dependency to supplement your development tools.

* **NPM**: `npm install @auth0/actions --save-dev`
* **Yarn**: `yarn add @auth0/actions --dev`
* **Pnpm**: `pnpm add @auth0/actions --save-dev`

***

#### Import

The library has the following **structure**:

```bash theme={null}
@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
    └───v2
```

The import statement should be based on each **trigger name** and **version number** considering the previous library structure.

**Follow the pattern**: `@auth0/actions/[trigger_name]/[trigger_version]`

**For example**: `@auth0/actions/post-login/v3`

Use one of the following alternatives to import the TypeScript definitions into your Actions depending on your technology:

Use this alternative when you want IntelliSense without changing your existing JavaScript code structure:

<Tabs>
  <Tab title="JSDoc @import">
    Use this alternative when you want IntelliSense without changing your existing JavaScript code structure:

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

    /**
    * Handler that will be called during the execution of a PostLogin flow.
    *
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
    */
    exports.onExecutePostLogin = async (event, api) => {
      // Your code
    }
    ```
  </Tab>

  <Tab title="JSDoc @param">
    Use this alternative for type safety in JavaScript files using import statements in JSDoc comments:

    ```javascript theme={null}
    /**
    * Handler that will be called during the execution of a PostLogin flow.
    *
    * @param {import('@auth0/actions/post-login/v3').Event} event - Details about the user and the context in which they are logging in.
    * @param {import('@auth0/actions/post-login/v3').PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
    */
    exports.onExecutePostLogin = async (event, api) => {
      // Your code
    };
    ```
  </Tab>

  <Tab title="TypeScript import">
    Use this alternative when developing with TypeScript for full type checking and modern syntax:

    ```javascript theme={null}
    import type { Event, PostLoginAPI } from '@auth0/actions/post-login/v3';

    /**
    * Handler that will be called during the execution of a PostLogin flow.
    *
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
    */
    exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
      // Your code
    };
    ```
  </Tab>
</Tabs>

<Warning>
  When using TypeScript, you must compile your code to JavaScript before deploying to Auth0. The Auth0 Actions runtime only executes JavaScript.Use the TypeScript compiler (`tsc`) to transpile your `.ts` files to `.js` files, before it can be deployed. You must also include JSDoc comments to enable IntelliSense in the Dashboard.
</Warning>

### Examples

The following Actions examples are intentionally presented in both JavaScript and TypeScript to provide a direct, side-by-side comparison.

#### Configuration

<Tabs>
  <Tab title="JavaScript">
    In your `package.json`, define any development dependencies to have intelliSense help when writing your Action:

    ```javascript theme={null}
    {
      "name": "actions-js",
      "version": "1.0.0",
      "description": "Actions JS",
      "main": "example.js",
      "author": "John Doe",
      "license": "ISC",
      "devDependencies": {
        "@auth0/actions": "^0.7.1"
      }
    }
    ```
  </Tab>

  <Tab title="TypeScript">
    In your `package.json`, define any development dependencies to have intelliSense help when writing your Action.

    ```typescript theme={null}
    {
      "name": "actions-ts",
      "version": "1.0.0",
      "description": "Actions TS",
      "main": "example.ts",
      "author": "John Doe",
      "license": "ISC",
      "devDependencies": {
        "@auth0/actions": "^0.7.1",
        "@types/node": "22.14.0",
        "typescript": "^5.9.2"
      }
    }
    ```

    In your `tsconfig.json`, define any development dependencies to have intelliSense help when writing your Action.

    ```typescript 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
      },
      "include": [
        "**/*.ts"
      ],
      "exclude": [
        "node_modules",
        "dist"
      ]
    }
    ```
  </Tab>
</Tabs>

### Post-Login access control and ID token custom claims

The following example Action would execute during the Post-Login flow. It checks if the user has roles assigned, and calls `api.access.deny()` if none are found. If roles are present, it proceeds to set the custom claim on the ID token.

The import statement declares the availability of external types to your code. This allows the editor to know the structure of the `event` and `api` objects.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    /** @import {Event, PostLoginAPI} from "@auth0/actions/post-login/v3" */

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

    /**
    * Handler that will be called during the execution of a PostLogin flow.
    *
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
    */
    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">
    ```typescript theme={null}
    import type { Event, PostLoginAPI } from '@auth0/actions/post-login/v3';

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

    /**
    * Handler that will be called during the execution of a PostLogin flow.
    *
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
    */
    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);
    };
    ```
  </Tab>
</Tabs>

To learn more about @auth0/actions, visit: [https://www.npmjs.com/package/@auth0/actions](https://www.npmjs.com/package/@auth0/actions).

To learn more about the code behind `@auth0/actions`, visit the [Auth0 Actions repository](https://github.com/auth0/auth0-actions).

To learn more about writing Actions, see [Write Your First Action](/docs/customize/actions/write-your-first-action).