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

> @auth0/actions NPM パッケージを使用して、プロジェクトの Actions を実装します。

# Actions NPM

[**`@auth0/actions`** NPM パッケージ](https://www.npmjs.com/package/@auth0/actions) は、**Auth0 Actions の TypeScript 定義**を利用するための**公式 Actions ライブラリ**です。これにより、外部エディターや IDE でプロジェクトの Actions を実装してテストできます。

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  [**`@auth0/actions`** 公開リポジトリ](https://github.com/auth0/auth0-actions) では、この NPM パッケージの基盤となるコードを確認できます。
</Callout>

<div id="benefits">
  ### 利点
</div>

このライブラリは、次のユースケースに対応します。

* **IDE / コードエディターの支援**: このライブラリを参照すると、IDE やコードエディターで **自動補完**、**オブジェクトや関数の定義表示**、**エラーチェック**が利用でき、開発時の支援が向上します。
* **TypeScript 開発**: Actions は引き続き Node.js CommonJS で記述・実行されますが、このライブラリを使用すると、外部プロジェクトで **TypeScript** を使って Actions を開発し、その後 CommonJS としてビルドして Auth0 テナントにデプロイできます。
* **ユニットテストの改善**: 外部プロジェクトで TypeScript 開発を行えるようになることで、このライブラリを使えば、開発者はベストプラクティスに従い、TypeScript の定義に基づいて**ユニットテストを改善**できます。
* **AI による Actions 生成**: このライブラリによって、AI がより正確な Action の例を生成できるようになることに一歩近づきます。

***

<div id="how-it-works">
  ### 動作の仕組み
</div>

<div id="installation">
  #### インストール
</div>

以下のいずれかのパッケージマネージャーを使用して、このパッケージを**開発依存関係**としてインストールします。

> このパッケージは、開発ツールを補完するため、開発依存関係として使用する必要があります。

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

***

<div id="import">
  #### インポート
</div>

このライブラリの**構造**は次のとおりです。

```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>

<div id="examples">
  ### 例
</div>

以下の Actions の例は、JavaScript と TypeScript を並べて直接比較できるよう、あえて両方で示しています。

<div id="configuration">
  #### 設定
</div>

<Tabs>
  <Tab title="JavaScript">
    Action の作成時に IntelliSense の補完を利用できるように、`package.json` で開発時の依存関係を定義します。

    ```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">
    Action の作成時に IntelliSense の補完を利用できるように、`package.json` で開発時の依存関係を定義します。

    ```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"
      }
    }
    ```

    Action の作成時に IntelliSense の補完を利用できるように、`tsconfig.json` を定義します。

    ```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>

<div id="post-login-access-control-and-id-token-custom-claims">
  ### Post-Login のアクセス制御と IDトークン のカスタムクレーム
</div>

次の Action の例は、Post-Login フロー中に実行されます。ユーザーにロールが割り当てられているかどうかを確認し、ロールが見つからない場合は `api.access.deny()` を呼び出します。ロールが存在する場合は、IDトークン にカスタムクレームを設定します。

`import` 文は、コード内で外部型を利用できることを宣言するものです。これにより、エディターは `event` オブジェクトと `api` オブジェクトの構造を認識できます。

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

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

    /**
    * PostLogin フローの実行中に呼び出されるハンドラー。
    *
    * @param {Event} event - ユーザーの詳細情報と、そのユーザーがログインしているコンテキスト。
    * @param {PostLoginAPI} api - ログインの動作を変更するためのメソッドを提供するインターフェース。
    */
    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';

    /**
    * PostLogin フローの実行中に呼び出されるハンドラー。
    *
    * @param {Event} event - ユーザーの詳細情報と、そのユーザーがログインしているコンテキスト。
    * @param {PostLoginAPI} api - ログインの動作を変更するためのメソッドを提供するインターフェース。
    */
    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>

@auth0/actions の詳細については、[https://www.npmjs.com/package/@auth0/actions](https://www.npmjs.com/package/@auth0/actions) を参照してください。

`@auth0/actions` の実装コードの詳細については、[Auth0 Actions repository](https://github.com/auth0/auth0-actions) を参照してください。

Actions の作成方法の詳細については、[Write Your First Action](/ja/docs/customize/actions/write-your-first-action) を参照してください。