TypeScript 7.1 Betaで.astroもtscで型チェック!astro buildが見逃していた24件
🙌 結論から
Astroのプロジェクトで型チェックをしていないなら、TypeScript 7.1 Betaのcontent mapperで一回だけでも回してみる価値はあります。
TypeScript 7.1 Betaから、.astro や .vue のようなTypeScript以外のファイルも tsc が直接型チェックできるようになりました。
このブログ(Astro 6.0.8・.astro ファイル44個)のリポジトリで試したところ、普段のビルドでは何も言われていなかったのに、エラーが24件出てきました(・_・;)
しかもそのうち10件は、コードの書き方ではなく、Cloudflare Workers用の型ファイルがブラウザ側の型を上書きしていたのが原因でした。
ただ、まだBetaなので、CIで必須にするのは安定版が出てからにします。
もう当たり前感あるけど、astro build は型をチェックしてくれないんですよね・・・!
💡 TypeScript 7.1 Betaで何が変わったのか
TypeScript 7.1 Betaは、2026年10月20日に公式ブログで発表されました。
7.0でGo製のネイティブコンパイラになって速くなった一方、ほかのツールから呼び出すためのAPIが入っていなかったので、VueやSvelte、Astroの型チェックは6系のままにするしかありませんでした。
7.1ではそのAPIが戻ってきたうえで、「content mapper」という仕組みが追加されています。
content mapperは、.astro のようなファイルをTypeScriptが読める形に変換して tsc に渡すプラグインです。
公式ブログでは、Astro・CSS Modules・Ember・MDX・Svelte・Vueで試作や実装が進んでいると紹介されていました👀
Astro用は @astrojs/ts-content-mapper というパッケージで、npmには0.2.0が出ています。
ここで1つ大事なのが、今まで使っていた astro check はTypeScript 7では動かないことです。
astro check が使う @astrojs/check 0.9.12は、対応するTypeScriptが ^5.0.0 || ^6.0.0 になっています。
なので、TypeScript 7系で .astro を型チェックしたいなら、content mapperに乗り換えることになります。
🔧 このブログで試した設定
やったことは3つだけです。
まず、Betaの typescript とAstro用のmapperを入れます。
npm i -D typescript@7.1.0-beta @astrojs/ts-content-mapper@0.2.0
npmの latest はまだ7.0.2なので、@7.1.0-beta を付けないと7.1は入りません(^^)
次に、tsconfig.json に contentMappers を足します。
{
"extends": "astro/tsconfigs/strict",
"include": [".astro/types.d.ts", "**/*"],
"exclude": ["dist", "worker-configuration.d.ts", "worker"],
"contentMappers": [
{
"package": "@astrojs/ts-content-mapper",
"extensions": [".astro"]
}
]
}
exclude に worker-configuration.d.ts と worker を入れている理由は、あとの「ハマった点」で書きます。
最後に、astro sync で型を作ってから --runExternalCode を付けて実行します。
npx astro sync
npx tsc --noEmit --runExternalCode
この --runExternalCode を付け忘れると、.astro は何もチェックされません。
実際に付けずに実行したら、次のエラーが出て止まりました。
error TS18068: Content mappers require the '--runExternalCode' command line flag to be enabled.
content mapperは node_modules の中のコードを実行するので、TypeScript側が「本当に動かしていい?」と明示的な許可を求める作りになっています🔒
VS Codeでも、ワークスペースの信頼とmapperの許可が必要で、js/ts.contentMappers.enabled の設定で止めることもできます。
👀 出てきたエラーは24件でした
結果を並べるとこんな感じです。
| 条件 | エラー件数 |
|---|---|
TypeScript 6.0.2で tsc --noEmit(.ts だけ) | 3件 |
7.1 Beta・mapperなし(.ts だけ) | 3件 |
7.1 Beta・mapperあり(.astro も) | 24件 |
| ↑からWorkersの型を外した後 | 14件 |
最初の3件は、.ts のファイルなのでTypeScript 6でも出ていたものです。
つまり、前からエラーがあるのに誰も気づいていなかったわけですね・・・笑
このブログは毎日ビルドして公開していますが、Astroのビルドは型エラーがあっても止まりません。
astro check をCIに入れていなかったので、ずっと素通りしていました(´・ω・`)
.astro 側で多かったのは、noImplicitAny(暗黙の any)と、コンポーネントに渡す variant の型が合っていないものでした。
残り1件は、Astro本体の node_modules/astro/components/Font.astro から出ていました。
これはAstroのGitHubのissue #18219で報告されていて、Astroの新しい版では修正済みです。
このブログはAstro 6系なので、まだ残っています( .. )
速さは、mapperありで44ファイルを全部見ても、この作業環境で約1秒でした。
別のプロジェクトのissueでは、astro check が約19秒、7.1のmapperで約2秒と報告されていたので、乗り換えたくなる気持ちはかなり分かります🔥
🤔 ハマった点とCloudflare Workersの型
一番時間を使ったのがここです。
BlogPost.astro の中で、目次やボタンを append() で足している部分が、次のようなエラーで6件まとめて引っかかりました。
Argument of type 'HTMLDivElement' is not assignable to parameter of type 'string | ReadableStream<any> | Response'.
普通の div を append() しているだけなのに、ReadableStream や Response を求められるのは変ですよね🤔
調べると、リポジトリの直下にある worker-configuration.d.ts が原因でした。
これはWranglerの wrangler types で作られる、Cloudflare Workers用の型ファイルです。
この中に interface Element が定義されていて、Workersの HTMLRewriter 用の before()・after()・append() の型になっています。
tsconfig.json の include に入っていたせいで、ブラウザ側の Element の型に混ざっていたというわけです。
exclude にこのファイルと worker フォルダを入れて回し直したら、24件が14件まで減りました🎉
append() の6件のほかに、after() の1件、fetch の結果が unknown 扱いになっていた3件も一緒に消えています。
Astroのサイトと「わかる」ボタン用のWorkerが同じリポジトリにあって、型ファイルも同じ tsconfig.json に入っていたのが原因なので、Workerは別の tsconfig.json に分けるのが正解かなと思っています。
Astro+Cloudflare Workersの構成の方は、ここは先に見ておくのがおすすめです!
✨ 今の時点での使い方
試してみて、私はこう分けることにしました。
- ローカルで時々回す:
package.jsonに"typecheck": "astro sync && tsc --noEmit --runExternalCode"のようなスクリプトを置いて、気になったときに実行 - CIではまだ必須にしない: Betaなので、失敗してもデプロイは止めない
- エディタは今のまま: 7.1の扱いはVS Code側の対応を待つ
公式ブログでは、RCはBetaの約1か月後、正式版はそのすぐ後という予定になっています。
7.1には、分配される条件型のチェックが厳しくなる変更や、DOMの型定義(lib.d.ts)の変更も入っていて、既存のコードで新しいエラーが出ることもあります。
なので、正式版が出るまでは「見つけたエラーを少しずつ直しておく期間」と割り切るのがちょうどいいと思います👍
🔗 関連記事と使い分け
- TypeScript 7.0でビルドが最大10倍速くなったので試してみた話…7.0のときは
.tsだけの話でした。今回の7.1で、.astroまでチェックできるようになったのが大きな違いです - Astro 6にアップグレードしてみた!…このブログをAstro 6に上げたときの記録です。Font.astroのエラーが残るのは、このバージョンを使っているからです
- Astroの静的サイトにCloudflare Workers KVで「わかる」ボタンを付けた話…今回の
worker-configuration.d.tsが入ったきっかけです。Workerを足すときは型ファイルの置き場所も一緒に決めておくと安心です
パパ系Webエンジニア〜愛用ガジェット一覧 🛍️
この記事を書いている作業環境のガジェットを楽天ROOMにまとめています ✨ 在宅エンジニアのデスク作りの参考にどうぞ 🙌
👍 まとめ
astro build が通っていても、型エラーがないとは限りません。
TypeScript 7.1 Betaのcontent mapperを使うと、tsc --noEmit --runExternalCode の1行で .astro までまとめてチェックできます。
このブログでは24件のエラーが出て、そのうち10件はCloudflare Workersの型が混ざっていたのが原因でした。
正直、最初に24件が出たときは「こんなにある・・・?」と少し引きましたが、原因を分けていくとかなりスッキリしました(^^)
まだBetaなので、正式版が出るまではローカルで時々回して、残り14件を少しずつ直していきます!
Astro+Cloudflareで作っている方は、一回だけでも回してみてください🙌
※ バージョン番号・料金・機能は今後も変わる可能性があります。最新情報は TypeScript公式ブログ と Astroのドキュメント をご確認ください👀