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

> 公式の @auth0/actions NPM パッケージを開発依存関係としてインストールすれば、外部エディターでトリガーとバージョンごとに Auth0 Actions を記述・ユニットテストする際に、TypeScript の型定義、IntelliSense、エラーチェックを利用できます。

# コードエディターを使ってActionを記述する

[`@auth0/actions`](https://www.npmjs.com/package/@auth0/actions) NPM パッケージを使用すると、お好みのコードエディターや IDE で、IntelliSense、型チェック、エラーチェックをフルに活用しながら Actions の記述とユニットテストを行えます。

<Steps titleSize="h3">
  <Step title="パッケージをインストールする">
    次のいずれかのパッケージマネージャーを使用してパッケージをインストールします。

    <Tabs>
      <Tab title="NPM">
        <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
          パッケージのインストール時に `--save-dev` を指定すると、開発ツールを補完する開発依存関係であることを示せます。
        </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">
          パッケージのインストール時に `--dev` を指定すると、開発ツールを補完する開発依存関係であることを示せます。
        </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">
          パッケージのインストール時に `--save-dev` を指定すると、開発ツールを補完する開発依存関係であることを示せます。
        </Callout>

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

  <Step title="型定義をインポートする">
    ご利用の技術に応じて、次のいずれかの方法でTypeScriptの型定義をActionsにインポートします。

    <Tabs>
      <Tab title="JSDocs @import">
        既存のJavaScriptコードの構造を変えずにIntelliSenseを利用したい場合は、この方法を使用します。

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

        /**
        * PostLogin フローの実行中に呼び出される Handler です。
        *
        * @param {Event} event - ユーザーと、そのユーザーが login を行うコンテキストに関する詳細情報。
        * @param {PostLoginAPI} api - login の動作を変更するためのメソッドを備えたインターフェイス。
        */
        exports.onExecutePostLogin = async (event, api) => {
          // ここにコードを記述します
        }
        ```
      </Tab>

      <Tab title="JSDocs @param">
        JSDocコメント内でimport文を使用してJavaScriptファイルの型安全性を確保したい場合は、この方法を使用します。

        ```js title="jsdocs-param.js" theme={null}
        /**
        * PostLogin フローの実行中に呼び出される Handler です。
        *
        * @param {import('@auth0/actions/post-login/v3').Event} event - ユーザー情報と、そのユーザーが login する際のコンテキストに関する詳細。
        * @param {import('@auth0/actions/post-login/v3').PostLoginAPI} api - login の動作を変更するためのメソッドを提供するインターフェイス。
        */
        exports.onExecutePostLogin = async (event, api) => {
            // ここにコードを記述します
        };
        ```
      </Tab>

      <Tab title="TS types import">
        TypeScriptで開発し、完全な型チェックと最新の構文を利用したい場合は、この方法を使用します。

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

        /**
        * PostLogin フローの実行中に呼び出される Handler です。
        *
        * @param {Event} event - ユーザーと、ログインが行われるコンテキストに関する Details (詳細)。
        * @param {PostLoginAPI} api - ログインの動作を変更するメソッドを提供するインターフェース。
        */
        exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
          // ここにコードを記述します
        };
        ```
      </Tab>
    </Tabs>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      import文は、[ライブラリ構造](#library-structure)を踏まえて、各**トリガー名**と**バージョン番号**に基づいて記述する必要があります。

      **次のパターンに従ってください**: `@auth0/actions/[trigger_name]/[trigger_version]`

      **例**: `@auth0/actions/post-login/v3`
    </Callout>

    <Accordion title="ライブラリ構造">
      <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="プロジェクトを構成する">
    以下の構成例は、並べて比較できるように、意図的にJavaScriptとTypeScriptの両方で示しています。

    <Tabs>
      <Tab title="JavaScript">
        `package.json` で開発依存関係を定義し、Actionの作成時にIntelliSenseの支援を受けられるようにします。

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

        `jsconfig.json` で開発依存関係を定義し、Actionの作成時にIntelliSenseの支援を受けられるようにします。

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

        ```
      </Tab>

      <Tab title="TypeScript">
        `package.json` で開発依存関係を定義し、Actionの作成時にIntelliSenseの支援を受けられるようにします。

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

        `tsconfig.json` で開発依存関係を定義し、Actionの作成時にIntelliSenseの支援を受けられるようにします。

        ```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="Actionのコードを書く">
    次のAction例は、Post-Loginフロー中に実行されます。ユーザーにロールが割り当てられているかを確認し、割り当てがなければ `api.access.deny()` を呼び出します。ロールがある場合は、続けてIDトークンにカスタムクレームを設定します。

    import文は、外部の型がコードで利用できることを宣言するものです。これにより、エディターが `event` オブジェクトと `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';

        /**
        * PostLogin フローの実行中に呼び出される Handler です。
        *
        * @param {Event} event - ユーザーと、そのユーザーが login する際のコンテキストに関する Details（詳細）。
        * @param {PostLoginAPI} api - 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">
        ```ts title="example.ts" 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);
        };
        ```

        <Warning>
          TypeScriptを使用する場合は、Auth0に導入する前にコードをJavaScriptにコンパイルする必要があります。Auth0 Actionsのランタイムが実行できるのはJavaScriptのみです。導入する前に、TypeScriptコンパイラー (`tsc`) で `.ts` ファイルを `.js` ファイルにトランスパイルしてください。また、DashboardでIntelliSenseを有効にするために、JSDocコメントも含める必要があります。
        </Warning>
      </Tab>
    </Tabs>
  </Step>
</Steps>

<Check>
  **チェックポイント**

  これで、ご自身のコードエディターで作成し型チェックまで済ませた、Auth0に導入する準備が整ったActionが完成しました。
</Check>