TypeScript アプリの拡張されたユーザーエクスペリエンス

このガイドでは、TypeScript を使用して YouTrack アプリを構築するための、実験的な拡張開発者エクスペリエンス ( 強化された DX) について説明します。拡張された DX では、標準のアプリツールに加えて、ファイルベースのルーティング、生成されたフロントエンド API 型、開発モードでのランタイム検証、およびより高速な開発ループが追加されます。

このガイドを使用して、実験的な TypeScript ツールチェーンでアプリを作成します。標準的な JavaScript アプリを作成するには、まずアプリクイックスタートガイドから始めます。

Enhanced DX を使用する場合でも、通常のアプリバンドルを YouTrack にアップロードします。ただし、バックエンドハンドラーは TypeScript で作成し、ツールチェーンにビルドさせます。

強化された DX のメリット

標準的なアプリのスキャフォールディングフローと比較して、拡張 DX ツールチェーンには以下の機能が追加されています。

標準アプリの scaffold	強化された DXscaffold
JavaScript バックエンドハンドラー	型チェック機能を備えた TypeScript バックエンドハンドラー
手動 HTTP ハンドラー接続	バックエンドエンドポイント向けのファイルベースルーティング
共有されるリクエストまたはレスポンス契約はありません	フロントエンド API 呼び出し用に生成された型
手動アップロードサイクル	ウォッチモードでの自動再構築とアップロード
ハンドラー、設定、プロパティの手動設定	一般的なタスクのための `npm run g` ジェネレーターコマンド
変更があるたびにフロントエンドを再構築してアップロードする	`npm run dev` に即座に反映されるフロントエンドの変更に対するオプションの Vite サポート (ホットモジュール交換)

前提条件

Enhanced DX ツールチェーンを使用して YouTrack アプリを作成するには、以下が必要です。

お使いのマシンに Node.js(英語) バージョン 18.20.4 以降がインストールされています
アプリをアップロードできる YouTrack インスタンスへのアクセス
プロジェクトの更新権限を持つ永久トークン

アプリパッケージを作成する

拡張 DX ツールチェーンを使用してアプリを作成するには、標準のアプリジェネレーターを使用し、TypeScript 開発アプローチを選択してください。

Enhanced DX を使用してアプリパッケージを作成するには:

アプリ用の空のディレクトリを準備します。
アプリジェネレーターを実行します。
npm create @jetbrains/youtrack-app
開発手法を選択するよう求められたら、TypeScript (ファイルベースルーティングによる DX 機能の強化) を選択してください。
生成されたアプリパッケージのディレクトリに移動します。
アプリパッケージのルートディレクトリに .env ファイルを作成します。
YOUTRACK_HOST=https://your-youtrack.example.com YOUTRACK_TOKEN=perm:your-permanent-token

その結果、ローカル開発用に構成され、.env ファイルに保存されている値を使用してアプリを YouTrack インスタンスにアップロードできるように設定されたアプリパッケージが生成されます。

ローカル開発を開始するには、次のコマンドを実行してください。これによりアプリがビルドされ、開発バージョンが YouTrack にアップロードされます。

npm run dev

アプリパッケージの操作

生成されたアプリパッケージには、フロントエンドとバックエンドの構築、ローカルでのアプリ開発、YouTrack へのアップロードを行うための個別のコマンドが含まれています。

ゴール	コマンド
ローカル環境で開発し、フロントエンドを即座に更新	`npm run dev`
ウォッチモードを再構築およびアップロードして実行します	`npm run watch`
バックエンドタイプのみを生成する	`npm run build:backend`
フロントエンドバンドルを構築する	`npm run build:frontend`
本番ビルドを作成する	`npm run build`
`.env` の認証情報を使用して、現在のビルドをアップロードしてください。	`npm run upload-local`
アプリをビルドしてアップロードする	`npm run update`

ビルドシーケンス

フロントエンドは、バックエンドのビルド時に生成される API 型定義に依存しています。そのため、アプリパッケージを初めて使用する際は、フロントエンドをビルドする前にバックエンドをビルドする必要があります。

                npm run build:backend
                npm run build:frontend
            

src/api/ で生成されるファイルは、バックエンドのビルド時に上書きされます。手動で編集しないでください。

地域開発

npm run dev を実行すると、アプリパッケージは以下のようにローカル開発用に準備されます。

以前に生成された API ファイルは削除されます
バックエンドが構築され、API 型定義が生成されます。
アプリの開発版が YouTrack にアップロードされます
ローカル開発サーバーがポート 9000 で起動されます。
バックエンドファイルの変更により、必要に応じて再構築と新規アップロードがトリガーされます。
フロントエンドファイルの変更は開発中に即座に反映されます

ローカル開発サーバーを起動したくない場合は、npm run watch を使用してください。このモードでは、フロントエンドの変更は即座に反映されるのではなく、通常の再構築とアップロードをトリガーします。

パッケージ構造

生成されたアプリパッケージには、以下のディレクトリとファイルが含まれています。src/api/ 内の一部のファイルは、バックエンドをビルドした後にのみ生成されます。

            src/
            |- api/
            |  |- index.ts
            |  |- youtrack-types.d.ts
            |  |- api.d.ts                 # generated by the backend build
            |  |- api.zod.ts               # generated by the backend build
            |  |- app.d.ts                 # generated by the backend build
            |  `- extended-entities.d.ts   # generated by the backend build
            |- backend/
            |  |- router/
            |  |  |- global/
            |  |  |- project/
            |  |  |- issue/
            |  |- types/
            |  |  |- backend.global.d.ts
            |  |  `- utility.d.ts
            |  `- requirements.ts
            |- common/
            |  `- utils/
            |     `- logger.ts
            |- widgets/
            `- app-id.ts
        

src/api/ に生成されるファイルは、バックエンドハンドラー、設定、拡張プロパティから派生したものです。src/backend/router/ のファイルは、アプリの HTTP エンドポイントを定義します。

初期アプリパッケージには、global、project、issue スコープ用のサンプルハンドラーが含まれています。article および user スコープ用のハンドラーを追加することもできます。

ファイルベースルーティング

ファイルベースルーティングでは、バックエンドハンドラーファイルの場所と名前によって、提供されるエンドポイントが決まります。個別の設定でエンドポイントを手動で宣言する代わりに、各ハンドラーを特定のディレクトリに配置し、サポートされている HTTP メソッドに応じてファイル名を付けます。

拡張 DX では、バックエンドハンドラーは次のパスパターンを使用します。

src/backend/router/{scope}/{path}/{METHOD}.ts

サポートされているスコープは global、project、issue、article、user です。ルートパスはネストすることができ、ハイフンで区切られたセグメントを含めることができます。

ハンドラーフォーマット

各ハンドラーファイルは、リクエストタイプ、レスポンスタイプ、デフォルトハンドラー、タイプ生成用の Handle エイリアスをエクスポートします。

                /**
                 * @zod-to-schema
                 */
                export type ProjectSettingsReq = {
                  projectId: string;
                };

                /**
                 * @zod-to-schema
                 */
                export type ProjectSettingsRes = {
                  name: string;
                  shortName: string;
                };

                export default function handle(ctx: CtxGet<ProjectSettingsRes, ProjectSettingsReq, "project">): void {
                  ctx.response.json({
                    name: ctx.project.name,
                    shortName: ctx.project.shortName,
                  });
                }

                export type Handle = typeof handle;
            

生成される API 契約および実行時検証では、@zod-to-schema でアノテーションが付けられた型のみが対象となります。

コンテキストの種類

各ハンドラーは、リクエスト、レスポンス、現在のユーザー、アプリ設定、スコープ固有の YouTrack エンティティへのアクセスを提供するコンテキストオブジェクトを受け取ります。

以下の TypeScript ヘルパータイプは、異なる HTTP メソッドを持つハンドラーのコンテキストオブジェクトを定義します。

                CtxGet<Res, Req?, Scope?>
                CtxDelete<Res, Req?, Scope?>
                CtxPost<Body, Res, Query?, Scope?>
                CtxPut<Body, Res, Query?, Scope?>
            

各コンテキストには必ず ctx.currentUser、ctx.settings、ctx.request、ctx.response が含まれます。ハンドラーディレクトリと汎用スコープが一致する場合、ctx.issue や ctx.project などのスコープ固有のプロパティが使用可能になります。

許可

ハンドラーへのアクセスに必要な権限を定義するには、Enhanced DX ランタイムパッケージの withPermissions ヘルパー関数を使用します。

                import { withPermissions } from '@jetbrains/youtrack-enhanced-dx-tools/runtime';

                function handle(ctx: CtxPost<Req, Res, "issue">): void {
                  ctx.response.json({ ok: true });
                }

                export default withPermissions(handle, ['read-issue', 'update-issue']);
                export type Handle = typeof handle;
            

アプリ要素を追加する

生成されたアプリには、npm run generate コマンドとその短縮エイリアスである npm run g が含まれています。これらのコマンドを使用して、ウィジェット、ハンドラー、拡張プロパティ、設定を追加できます。

ウィジェット

ジェネレーターを使用して、選択した拡張ポイント用のウィジェットを追加し、アプリの設定を自動的に更新します。

                    npm run g -- widget --key my-panel --extension-point ISSUE_BELOW_SUMMARY
                    npm run g -- widget --key admin-page --extension-point MAIN_MENU_ITEM --name "Admin Page"
                    npm run g -- widget --key project-tab --extension-point PROJECT_SETTINGS --permissions read-project
                

ハンドラー

ジェネレーターを使用して、適切な場所に、必要な型宣言を含むバックエンドハンドラーを作成します。

                    npm run g -- handler global/health
                    npm run g -- handler project/users --method POST
                    npm run g -- h issue/comments --method POST --permissions read-issue,update-issue
                

拡張プロパティ

ジェネレーターを使用して、YouTrack エンティティの拡張プロパティを宣言します。

                    npm run g -- property Issue.customStatus
                    npm run g -- property Issue.tags --type string --set
                    npm run g -- p Article.rating --type integer
                

バックエンドを再構築した後、生成された拡張プロパティは、ctx.issue.extensionProperties、ctx.project.extensionProperties、関連するスコープ付きエンティティを通じて利用可能になります。

アプリ設定

ジェネレーターを使用して設定スキーマを初期化し、プロパティを追加します。

                    npm run g -- settings init --title "My App Settings" --description "Admin configuration"
                    npm run g -- settings add --name apiKey --type string --write-only
                    npm run g -- settings add --name maxItems --type integer --min 1 --max 100
                

バックエンド要素を追加または変更した後は、バックエンドを再構築するか、npm run dev を稼働させ続けて、生成されたファイルとアップロードされたアプリバンドルが最新の状態に保たれるようにしてください。

生成された API クライアントを使用する

フロントエンドウィジェットは、生成された API クライアントを介してバックエンドハンドラーを呼び出すことができます。このクライアントは、src/backend/router/ 内のハンドラーファイルと、それらのファイルで宣言されているリクエストおよびレスポンスの型に基づいています。

バックエンドを構築すると、ツールチェーンは src/api/api.d.ts 内に ApiRouter 型を生成します。ウィジェットはこの型を createApi ヘルパー関数に渡して、各バックエンドルートに対応する型付きメソッドを取得します。

            import { createApi } from "@/api";
            import type { ApiRouter } from "@/api/api";

            const host = await YTApp.register();
            const api = createApi<ApiRouter>(host);

            const settings = await api.project.settings.GET({ projectId: "ABC" });
            const echo = await api.global.echo.POST({ message: "hello" });
            const details = await api.issue.details.GET({ issueId: "DEMO-1" });
        

api オブジェクトの構造は、ファイルベースのルート構造に従います。例: src/backend/router/project/settings/GET.ts のハンドラーは api.project.settings.GET(...) として利用できます。

プロジェクトスコープおよび課題スコープのハンドラーの場合、リクエストデータに該当するエンティティ ID を含めてください。リクエストに projectId が含まれている場合、クライアントはプロジェクトエンドポイント経由で呼び出しをルーティングします。リクエストに issueId が含まれている場合、クライアントは課題エンドポイント経由で呼び出しをルーティングします。

生成された api オブジェクトにルートが欠落している場合は、バックエンドを再構築して src/api/api.d.ts をリフレッシュします。

エンティティフィールドを更新する

バックエンドハンドラーは、課題やプロジェクトなどの YouTrack エンティティの値を更新できます。値を更新する方法は、その値がアプリによって宣言された拡張プロパティか、通常の YouTrack フィールドかによって異なります。

YouTrack の変更を永続化する更新には、POST または PUT ハンドラーを使用してください。GET または DELETE ハンドラーでの変更は、実行時に失敗する可能性があります。

ハンドラーからフィールドの変更を永続化する必要がある場合は、以下の方法を使用してください。

フィールド	更新メソッド
アプリによって宣言された拡張プロパティ	`ctx.issue.extensionProperties` または対応するスコープ付きエンティティを介して値を直接割り当てます
通常の課題またはプロジェクトフィールド（カスタムフィールドを含む）	`@jetbrains/youtrack-enhanced-dx-tools/runtime` の `set()` ヘルパー関数を使用する

以下は、課題処理において両方のアプローチを使用した例です。

            import { set } from '@jetbrains/youtrack-enhanced-dx-tools/runtime';

            ctx.issue.extensionProperties.customNote = 'value';
            set(ctx.issue, 'summary', 'New title');
            set(ctx.issue, 'State', stateObject);
            set(ctx.issue, 'MyCustomField', 'value');
        

トラブルシューティング

生成されたアプリパッケージが YouTrack で想定どおりにビルド、アップロード、更新されない場合は、以下の注意事項を参照して、よくあるセットアップおよび開発上の課題を確認してください。

状態 - フロントエンドビルドは、./api/api が見つからないと報告します。

原因	ソリューション
API 型定義はまだ生成されていません。	`npm run build:backend` を実行して、`src/api/` 内のファイルを生成します。

条件 - アップロードの結果、401 Unauthorized が返されます。

原因	ソリューション
アップロードコマンドは YouTrack で認証できません。	`.env` の値を確認してください。`YOUTRACK_HOST` に `https://` が含まれ、`YOUTRACK_TOKEN` が `perm:` で始まることを確認してください。

状態 - ウォッチモードで変更がアップロードされません。

原因	ソリューション
変更されたファイルが監視対象のソースディレクトリの外にあるか、監視ツールが応答しなくなりました。	変更されたファイルが `src/` 内にあることを確認してください。ウォッチャーが停止した場合は、`npm run watch` を再起動してください。

状態 - ローカル開発モードでフロントエンドが空白になります。

原因	ソリューション
ローカル開発サーバーが実行されていないか、フロントエンドで実行時エラーが発生しています。	ローカル開発サーバーがポート 9000 で起動していることを確認し、ブラウザーのコンソールでフロントエンドのエラーを確認してください。

条件 - ts-to-zod が失敗したか、スキップされました。

原因	ソリューション
アプリパッケージに `ts-to-zod` パッケージが含まれていません。これは、依存関係が正しくインストールされていない場合、またはアプリパッケージが手動で変更された場合に発生する可能性があります。	`npm install` を実行してください。それでもパッケージが見つからない場合は、`npm install -D ts-to-zod` を使用して開発依存関係をインストールしてください。これがないと、ビルド自体は完了しても、ランタイム検証が無効になります。