🙌

フロントエンド開発の推しライブラリ紹介(mise / TypeDoc / tsd 編)

に公開
TypeScript
開発環境
frontend
OSS
library
tech

みなさん、こんにちは！

季節の変わり目に風邪をひきがちな、フロントエンドエンジニアの @nyaomaru です！ 😿

今回は僕が推しているライブラリの “毎日触る土台” に効く 3 つ：

  • mise（ツール管理＆タスク実行）
  • TypeDoc（API ドキュメント）
  • tsd（型のテスト）

をまとめて紹介していきます。

ほな、一緒に見ていこな～！

mise： 言語/ツールのバージョンとタスクを一元管理

https://github.com/jdx/mise

まず、README がオシャやなぁ～。ロゴもええし、デモも見やすい。

Docs もええ感じやなぁ！以下を見れば、インストールまでわかるで！OS 毎に違うから、自分の利用している OS のガイドラインに沿って入れていこな～。

https://mise.jdx.dev/getting-started.html

ちなみに「ミーズ（mise）」って呼ぶらしいで！

mise (pronounced "meez") or "mise-en-place"
https://mise.jdx.dev/about.html

🎁 これでやれること

PJ 毎の環境設定がめちゃ楽になる。

  • Node / pnpm / Bun / Deno / Python…のバージョン固定＆自動切替
  • .tool-versions 互換。既存 nvm 派生の運用からの移行もラク
  • タスクランナー内蔵（make 代替にも）

個人的な感想としては nvm + makefile + α って感じやな。諸々がオールインワンで提供されているのがステキなポイントや！

🔎 どうやってつかうん？

最小セットアップ（mise.toml）

title=mise.toml
# mise.toml
[tools]
# 各 tool の version を指定することで、mise install 実行時に環境が整う
node = "22.6.0"
pnpm = "9"
bun = "1"

[env]
# 共通の環境変数をここで集中管理
NODE_ENV = "development"

# package json で登録されている script を実行できる
[tasks.setup]
# `mise setup` のように叩ける
description = "Install dependencies via pnpm"
run = "pnpm install"

[tasks.dev]
# `mise dev` のように叩ける
description = "Boot application via pnpm"
run = "pnpm dev"

[tasks.lint]
# `mise lint` のように叩ける
description = "Boot application via pnpm"
run = "pnpm lint"

これを PJ のトップディレクトリに配置するだけ～

🎯 なぜ推す？

環境の統合が楽ちんなのと、

  • チーム全員の Node/pnpm を秒で揃えられる
  • タスクも一箇所に寄せるので、CI も手元も同じコマンドで回る
  • 日々の開発者の 2~3 秒を節約できる

つまり、チーム開発でめちゃ威力発揮するで！

唯一めんどくさいのが、最初にこのリポジトリ信用してもええ？って聞かれることくらいやな。

mise-confirmation

でも、Yes 押したらもう後は言うことなし文句なし。超便利やからガンガン使っていきたいなぁ～！

TypeDoc：型から“嘘のない” API ドキュメント

「コメントがそのままドキュメントになる」って最高やない？
そんな夢を叶えてくれるのが TypeDoc やで！

まずはドキュメントサイトを見てほしい。

https://typedoc.org/

これが TypeDoc の自動生成で出てくる画面やねんけど、オシャやな～。これが OSS として利用できるなんて、感謝やで～ 🙏

https://github.com/TypeStrong/typedoc

README みると簡単に導入できるで～！

🎁 これでやれること

swagger-docs にように、型と実装に関するドキュメントが自動で生成される優れもんやな

  • エクスポート実体から自動生成されるので、ドキュメントと実装の乖離が起きにくい
  • モノレポの packages モードで複数パッケージを一つのサイトに統合可能

特に、実装から作成されるところが、いい点よな。ドキュメントってすぐ腐っていくやん？やからこそ、実装を正としたドキュメントやと、リファクタもしやすいよな～

🔎 どうやってつかうん？

pnpm add -D typedoc

最小セットアップ（typedoc.json）

title=typedoc.json
{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "tsconfig": "tsconfig.json",
  "excludePrivate": true,
  "excludeInternal": true
}

package.json の script に追加しておくと、CI もやりやすいで～

title=package.json
{
  "scripts": {
    "docs": "typedoc"
  }
}

ちなみに、コメントも反映されるから、コメント書くとええ感じなるで～

title=is-kit/define.ts
/**
 * ユーザー定義関数を「型付き述語」としてラップするユーティリティ。
 *
 * 注意：述語の正しさは呼び出し側の責任です。
 * 結果は `!!` によって真偽値に変換され、常に一貫したガード動作を保証します。
 *
 * @param fn 判定対象の値が型条件を満たす場合に truthy を返す関数。
 * @returns 関数が true を返すとき、その値を意図した型に絞り込む Predicate。
 */
export function define<T>(fn: (value: unknown) => value is T): Predicate<T>;
export function define<T>(fn: (value: unknown) => boolean): Predicate<T>;
export function define<T>(
  fn: ((value: unknown) => value is T) | ((value: unknown) => boolean)
): Predicate<T> {
  return (value: unknown): value is T => !!fn(value);
}

✨ typedoc でドキュメントを生成すると、この JSDoc コメントがそのまま API ドキュメントとして出力され、オーバーロード定義と説明がきれいに表示されるで。まさに「型が真実」のドキュメントやな～！

コメントの書き方については、以前書いた記事を参考にしてみてや～！

https://zenn.dev/nyaomaru/articles/why-should-i-write-comment

https://zenn.dev/nyaomaru/articles/how-can-i-write-comment

🎯 なぜ推す？

自動で生成されて管理が楽ちんやからやな～

他にも

  • 導入がすごく楽。実装がちゃんとしてたら、基本入れるだけで動くはず！
  • Github Pages で公開すると、Public ですぐに共有できる document として利用可能
  • 設定は typedoc.json / package.json / tsconfig.json のいずれでも記述可。扱いやすい場所にまとめるのが吉。

つまり、チームで仕様を共有するのに役に立つで！

注意点としては、ドキュメント生成には Node.js の環境が必要やで～。これも mise で設定してたら、mise run docs で楽ちんや～！

tsd：.test-d.ts で型のふるまいを検証

https://github.com/tsdjs/tsd

型専用のテストツールやな。ライブラリや OSS 開発とかに向いてて、業務では使うのちょっと難しいかもしれんけど、おもろいから入れてみるのありなんちゃうかな？

🎁 これでやれること

型専用テストができるで～

  • *.test-d.ts を実行して expectType / expectError / expectAssignable などでコンパイル時に保証
  • 実行時 error の検知ではなく、型のテストができる

特に、型のテストを書くことで利用する型がどのように使用される想定の型なのか？ がわかるサンプルになるのが、ええポイントやな

🔎 どうやってつかうん？

pnpm add -D tsd

最小セットアップ（package.json）

以下を追記する。

title=package.json
"tsd": {
  "directory": "tests-d",
  "compilerOptions": {
    "baseUrl": "."
  }
}

test ディレクトリとして、tests-d を作成し、tsconfig.jsonを配置する

title=tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noEmit": true,
    "baseUrl": "..",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["./**/*.ts"],
  "exclude": ["../node_modules", "../dist"]
}

そして、以下のような test を実装する。(サンプル)

title=define.test-d.ts
import { expectType } from 'tsd';
import { define } from '../../src/core/define';
import type { Predicate } from '../../src/types';

// =============================================
// describe: define (types)
// =============================================
// it: returns a Predicate<T> regardless of input predicate flavor
expectType<Predicate<string>>(define<string>(() => true));
expectType<Predicate<number>>(define<number>((x) => typeof x === 'number'));

実装は 軽量・依存なしで、型安全な isXXX を簡単に構築できる is-kit を参照してみてな～！🚀

https://github.com/nyaomaru/is-kit

🎯 なぜ推す？

型のテストっていう発想がおもろいのと、

  • なおざりになりがちな型の安全性を担保できる
  • テストを書くことで、想定の実装かどうかを検査できる

がええなぁ～って思うポイントや！

まとめ

最近のフロントエンド開発における「プロジェクトの基本設定で用いるオススメのライブラリ」を取り上げてみたで～！

  • mise
  • TypeDoc
  • tsd

ところで、みんなはどんなオススメのライブラリがある？

ワイ「こんなん知ってるで～、ワイルドだろぉ～！？」

ってやりたかったというより、

ワイ「みんなのオススメも知りたいねん、教えてーや。いや、ホンマに。教えてください！お願いしますよごめんなさい！！！」

って気持ちやねんな。

せやから、もしよかったらコメントでオススメの library 書いてみて！それか、参考にしてるオススメの記事とか、今読んでる本とか、全然関係ない推しとか、なんでもええから教えてなぁ～！

おまけ

最後に、今回紹介した基盤ツールと相性の良い型安全ユーティリティも紹介しとくで！
わいが作ったやつやけど、めっちゃ軽量で使いやすいからぜひ見てってな〜！

https://github.com/nyaomaru/is-kit

https://zenn.dev/nyaomaru/articles/introduce-is-kit

Discussion