yarnプロジェクトにtypespecを導入する

この記事は何？

Typescript 風の記述から OpenAPI Schema を生成してくれる TypeSpec ですが、公式の GettingStarted に従うだけでは yarn プロジェクトが壊れてしまい少し躓いたので、解決までの手順をまとめました。

困った内容

まず、公式の getting startedは以下のような内容です。

公式手順

npm install -g @typespec/compiler

tsp init
> ここで質問に答えて'Generic REST API'を選択する

tsp compile .

これを、単純に yarn に読み替えて以下のようにしてもうまくいきません。

ダメな例

yarn global add @typespec/compiler
> インストールは可能

yarn tsp init
> .gitignore, .package.jsonが破壊され、package-lock.jsonが生成される

yarn compile .
> 何かが足りなくてエラー

ちゃんと動かないだけでなく .gitignore や package.json が破壊されたせいでどんな変更が入ったのかを追跡しづらく、というかそもそも global にインストールしたくありません。
git や devcontainer がある世界で良かった...

解決方法

私の試行錯誤の結果、以下の手順で実施すれば yarn プロジェクトで typespec を正しく動作できる環境になると思われます。

これから出てくる各ライブラリのバージョン値は執筆時時点（2025 年 12 月）の筆者の環境のものになりますので、適宜読み替えてください。

1. 作業前の状態を保存する

git commit でも git stash でも フォルダごとどこかにコピーを取っておくでもなんでも良いので必ず実施してください。

gitの場合

git add package.json yarn.lock .gitignore #特にこの3つが重要
git commit -m "typespec導入前時点の状態"

2. typespec をインストールする

devDependancies に入れたいので -D オプションを付けています。

yarn add -D @typespec/compiler

コマンド終了後、package.json が自動的に更新されます。

package.json

{
  "devDependencies": {
+ "@typespec/compiler": "^1.7.1",
  }
}

3. typespec の動作に必要なファイルを生成する

init しましょう。色々聞かれますが、以下のようにすべてデフォルトで OK です。

このコマンド実行後、package.json や.gitignore が破壊されます。次の手順で修正方法を説明します。

yarn tsp init
> warning: Folder /workspace is not empty.
>
> ✔ Initialize a new project here?: Yes
> ✔ Select a project template: Generic REST API
> ✔ Enter a project name: frontend
> ✔ What emitters do you want to use?: OpenAPI 3.1 document       [@typespec/openapi3]

ここで生成される main.tsp, tspconfig.yaml は重要ですので、消さないようにしてください。

4. .gitignore の変更を破棄する

前段の yarn tsp init によって破壊された .gitignore を元に戻しましょう。
人によってはあまり気にならないかもしれませんので、その場合はスキップしていただいて OK です。

git restore .gitignore

元に戻したうえで、以下を追加しておくとなお良いです。

.gitignore

+ tsp-output

5. package-lock.json を削除する

不要なので消します。

rm -f package-lock.json

5. package.json を良い感じに変更する

init 直後の package.json は以下のようになっています。たかが 1 つのパッケージの init で package.json をすべて書き換えてしまうなんてどういう了見なんでしょうか。

こちらも前段の .gitignore と同様に restore するのですが、 depandancies の 5 つは後で必要になりますのでメモっておいてください。

init直後のpackage.json

{
  "name": "frontend",
  "version": "0.1.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "@typespec/compiler": "latest",
    "@typespec/http": "latest",
    "@typespec/rest": "latest",
    "@typespec/openapi": "latest",
    "@typespec/openapi3": "latest"
  }
}

メモったら戻しましょう。

git restore package.json

戻したら、今度は手書きで 依存関係を追加します。先ほどメモった 5 つを書き入れましょう。
私の場合は例によって devDependancies に入れています。

package.json

{
  "devDependencies": {
+   "@typespec/compiler": "latest",
+   "@typespec/http": "latest",
+   "@typespec/rest": "latest",
+   "@typespec/openapi": "latest",
+   "@typespec/openapi3": "latest"
  }
}

7. tsp コマンドで yarn を参照するようにする。

もうひといきです！

このまま tsp コマンドを再度実行すると動きませんので、package.json に以下の 1 行を追加します。
こうすることで yarn tsp {サブコマンド} を実行したときに裏でも yarn が動いてくれるようになります。

package.json

{
+ "packageManager": "yarn@1.22.22",
}

8. tsp compile を実行

以下を実行して正常終了していればゴールです。お疲れさまでした！

yarn tsp compile .

> yarn run v1.22.22
> $ /workspace/node_modules/.bin/tsp compile .
> TypeSpec compiler v1.7.1
>
> ✔ Compiling
> ✔ @typespec/openapi3 14ms tsp-output/schema/
>
> Compilation completed successfully.
>
> Done in 0.40s.

さいごに

devcontainer がなければ泣いていました。ありがとう devcontainer。devcontainer はいいぞ。

参考資料

1. 【TSP 公式】Getting started - Installation
2. OpenAPI のスキーマ定義を、プログラム的に書ける TypeSpec を使ってみた

special thanks

• DevContainer