「routopia」でURLのパラメータ書き忘れが型エラーになった | routopia

どんなアプリか

routopia は、先に書いておいたルートの定義をもとに、型安全に URL を組み立てる TypeScript のライブラリです。npm から入れて使います。

routopia focuses on declaratively and simply getting type-safe URLs.

yKicchan さん、GitHub の README「Why routopia?」

パスパラメータは [id] のように角かっこで囲んで定義し、型を指定します。README の例では、定義と違う型の値を渡したり、必須のパスパラメータを省いたりすると型のエラーになります。

クエリパラメータは queries の中に定義します。ベース URL や、Next.js の Catch-all Segments と同じ形の可変長のパラメータにも対応しています。

クエリパラメータは並べ替えて出力されるため、SWR のように URL をキーにするキャッシュの仕組みと合わせやすい、と README は説明しています。ライブラリは軽量で、依存パッケージはありません。

README は向いている場面として、SDK の無い外部サイトやサードパーティの API のエンドポイントへのリンク、myapp:// のような独自スキームの URL、Next.js の Route Handlers を挙げています。

名前	型	仕掛け	対応	料金
routopia	URL の組み立て	ルートの定義から型安全に URL を組み立てる	TypeScript ライブラリ（npm）	無料（MIT）
cc-hooks-ts	フックの定義	Claude Code のフックを TypeScript で型安全に定義する	npm ライブラリ	無料（OSS, MIT）
gqlkit	スキーマの構築	TypeScript の型定義と関数から GraphQL Schema を構築する	TypeScript ライブラリ	無料（OSS, MIT）
byethrow	エラー処理	例外を投げずにエラーを扱う軽量な Result 型	npm ライブラリ	無料（OSS, MIT）

自動生成や正規表現のような高度な機能が必要なら、ほかのライブラリのほうが合う場合がある、と README に書かれています。

戻り値はテンプレートリテラル型で細かく推論されます。string 型で受け取りたいときは型注釈を付けるよう案内されています。

テスト用に型の制約をゆるめた mock メソッドがあります。ただし URL エンコードを省くので、本番のアプリのコードでは使わないよう注意書きがあります。

複数のルート定義を一つにまとめることもできますが、その場合は TreeShaking がうまく効かないと README に書かれています。