🦁

テンプレートは「配った後」が本番だった。TS7テンプレートの更新問題と、わたしがCopierを選んだ理由

に公開

先日、TypeScript 7の開発環境をテンプレートにして ts7-template としてGitHubに公開しました。NixのdevShellを使ってNode.js 26とpnpm 12を固定し、型チェック・lint・フォーマットをすべてネイティブ製のツール(TypeScript 7のネイティブ版 tsc、oxlint、oxfmt)で揃えました。テストにはVitest 5を採用した、個人的最新こだわりの構成です。

ですが、まだ提供されたばかりのTypeScript環境において「ある重大な事実」に気づいていました。それは、一度このテンプレートからプロジェクトを作ってしまうと、その後テンプレート側をどれだけ改良しても、作成済みのプロジェクトには一切変更が反映されないということです。

テンプレートを作って公開すると、なんだか達成感があって満足してしまいますよ。でも、本当の勝負はここからです。

この記事では、この「更新されない問題」を Copier を使って copier-ts7 へと至ったかについて紹介します。

結論からお伝えしてしまうと、更新機能を持つ候補の中で現在も継続的に開発され、今回のNixベースの運用条件にも適合したのがCopierだった、というのが最大の理由です。

TypeScript 7 時代だからこそ、一度きりのコピーでは終われない

「テンプレートなんて、そんなに頻繁に直すだろうか」とお思いでしょう。もし環境が枯れきっていて変更の機会が少ないなら、一度コピーして終わりでまったく困らないでしょう。

わたしが困っていた理由は、TypeScript 7を取り巻くツールチェインが激動の最中だからです。

  • フォーマッターのoxfmtはまだ0.x系で、設定や挙動がこれから変わりうる状態です。
  • TypeScript 7.0にはプログラムから使うAPIがなく、7.1で新しいAPIが入る予定になっています(リリース告知)。APIが追加されれば、lintの選択肢や最適な設定も変わる可能性があります。
  • Node.jsのメジャーバージョンが上がれば、当然 flake.nix と flake.lock を更新したくなるでしょう。

テンプレートを少し直すたびに、作成済みのすべてのプロジェクトへ手作業で同じ修正を入れて回ることは、想像しただけで心が折れます。そこで「テンプレートを更新したら、作成済みのプロジェクトにもスムーズに取り込めること」を絶対条件として、いくつかの手段を比較してみることにしました。

比較検討:コピー専用ツールやnpmパッケージ化が抱える限界

最初に検討したのは、手軽に使えるおなじみの手段たちです。しかし、どれも今回の要件を満たしてくれません。

手段 変数の埋め込み 作成後の更新
GitHub Template repository なし できない
Nix flake の templates なし できない
degit / tiged / giget なし できない
自作の create-* パッケージ 自分で実装 できない

ts7-templateで使っていた「GitHub Template repository」は、公式ドキュメントにも「作られたリポジトリはテンプレートとunrelated historiesになり、PRとmergeができない」と明記されています。Nixのflake templatesはNixだけで完結するので相性は最高なのですが、変数を埋め込む機能すらなく、要望のissueも2020年から開いたままです。プロジェクト名すら差し込めないのでは、少し寂しいですよね。

それなら、ファイルをごっそりコピーするのではなく「設定をnpmパッケージにして、各プロジェクトから参照(extends)させる」アプローチはどうでしょうか。これなら設定の更新はパッケージのバージョンアップで届きます。

実際に同じバージョンのツールで試してみたら、TS 7.0.2の tsconfig.json はnpmパッケージを継承できたので問題ありませんでした。しかし、他のツールで壁にぶつかります。

  • oxlint: .oxlintrc.json の extends はファイルパスしか受け付けません。パッケージから読むには実験的な oxlint.config.ts が必要になります。
  • oxfmt: .oxfmtrc.json に extends を書いてみたところ、エラーにもならず、ただ静かに無視されてしまいました。
  • Vitest: mergeConfig は配列を連結する仕様のため、利用側で柔軟に include などを置き換えるのが困難でした。

設定を共有するためだけにJSONをTSに書き換え、npmへの公開まで管理するのは、今の規模感では手間に見合いません。それに、この方法では flake.nix やCIのGitHub Actionsワークフローといった「npmパッケージでは配れないファイル」の更新問題が残ったままになってしまいます。

Copier を採用した決め手と、「誰のファイルか」を分ける設計

「プロジェクト作成時に質問で値を埋め込めて、作成後にも更新を届けられる」。この厳しい条件をクリアする道具は、探してみると実は2つしか見つかりませんでした。

1つは cruft(cookiecutterに更新機能を足したもの)ですが、2024年12月を最後にリリースが止まっており、長く使う土台にするには不安が残ります。

そしてもう1つが、今回わたしが選んだ Copier です。2026年9月にもアップデートがリリースされるなど開発が活発で、Nixpkgsにも入っているため nix run nixpkgs#copier でサクッと動きます。Pythonの環境をわざわざ用意しなくて済むのは、Nixを前提にした今回のテンプレートと丁度良い。

Copierの素晴らしいところは、copier update の仕組みです。最新のテンプレートからプロジェクトを裏でいったん作り直し、それまでに利用者がプロジェクト側で加えた変更を差分として当て直す、いわゆる「3-way merge」をしてくれます。どのバージョンのテンプレートから作ったかは .copier-answers.yml に記録されているので、更新時にもう一度質問へ答える必要もありません。

設計の中心:「どのファイルが誰のものか」を決める

Copierの恩恵を受けるには、すべてのファイルを「テンプレートのもの」と「プロジェクト(利用者)のもの」に明確に分けることです。利用者がいじるファイルにテンプレートが毎回手を出してしまうと、更新のたびに競合(コンフリクト)祭りが発生します。

そこでCopierの _skip_if_exists 機能を使い、以下の4つを「プロジェクトのもの(初回のみ生成し、以後は触らない)」と定義しました。

  • README.md
  • LICENSE
  • CLAUDE.md
  • docs/decisions.md(設計判断の記録)

これに合わせて、ファイルの構成も工夫しています。

  • 判断ログの分割: ts7-templateでは docs/decisions.md に設計判断を書いていましたが、これを docs/template-decisions.md に移して「編集しないこと」と明記しました。利用者用の docs/decisions.md は空で渡します。
  • CLAUDE.md のインポート化: 利用者向けに渡す CLAUDE.md は1行のimport文のみにして、中身は @docs/template-claude.md へと逃がしました。これで、テンプレート側の規約は更新しつつ、利用者は自分の指示を自由に足せるようになります。
  • pnpm-lock.yaml は配らない: 依存関係を1つ足しただけで、以後の更新でロックファイルが毎回競合してしまうからです。これは初回の pnpm install で利用者(わたし)に作ってもらうことにしました。

逆に flake.lock は「テンプレートのもの」として扱い、Node.jsやpnpmの更新もテンプレートのタグとして受け取る設計にしました。ツール群のバージョン組み合わせが確実に動くことを、こちらで検証してから配るためです。

作成は5行、更新は1行。テストで守られたテンプレート構成

これらの工夫を詰め込んで完成したのが copier-ts7 です。使い勝手にはとことんこだわりました。

プロジェクトの作成は、Nixとdirenvがあれば以下の5行で終わります。

nix run nixpkgs#copier -- copy gh:sho7650/copier-ts7 my-app
cd my-app && direnv allow
pnpm install          # pnpm-lock.yaml ができるのでコミットする
git init -b main && git add -A && git commit -m "chore: initial commit from copier-ts7"
pnpm run check        # typecheck → lint → format:check → test:coverage

そして、テンプレートがバージョンアップした際の更新コマンドは、たったの1行です。

nix run .#update

copier自体をdevShellに入れると約1.6GiBのクロージャを毎回ダウンロードする羽目になるため、flakeのappとして定義し、更新のときだけ取得されるように絞り込みました。

テンプレート自体が壊れていないことを保証するために、Bash用のテストフレームワークbats-coreでテストを書いて、CIを毎回、回すようにしました。このテストで、「oxfmtが package.json のキーを勝手に並べ替えてしまい、生成直後の format:check が落ちる」という、テンプレートとしてヤバイ不具合もリリース前に見つけて修正できました。

配った後も面倒を見られる、生きたテンプレートを育てよう

これまでの手段を比較して、わたしがCopierを選んだ理由は次の3つに集約されます。

  1. 作成後の更新を届けられる: テンプレートを何度も直すことになるTS7環境では、ここが絶対に外せませんでした。
  2. 設定以外のファイルもまとめて扱える: npmパッケージでは配れない flake.nix やCIのワークフローも含めて、プロジェクト全体を管理できます。
  3. 開発が続いていて、Nix から直接使える: Python環境を意識せずに済むのは大きなメリットです。

利用者はツールのバージョン組み合わせに悩むことなく、たまに nix run .#update を叩いて、もし競合が出たらそこだけ直せばいい。そんな体験を作ることができました。

テンプレートは、ただ作って配って終わりではありません。配った後に直せて、利用者の手元でも一緒に進化していけるようになって、はじめて「使える道具」として育っていくのだと実感しています。

TypeScript 7.1が出たときに、この3-way mergeの仕組みがどこまでスムーズに機能するか、今から少し心配しつつも楽しみにしています。もしTypeScriptの新しい開発環境を探しているなら、ぜひ copier-ts7 を試してみてくださいませ。

Discussion