Visual Studioで既存のASP.NET CoreアプリにTypeScriptを追加するなら、結論はシンプルです。Microsoft.TypeScript.MSBuildをNuGetで追加し、tsconfig.jsonでTypeScriptの入力元をscripts、出力先をwwwroot/jsに分け、Razor側で生成後のJavaScriptを読み込むのが基本です。
2026年4月のMicrosoft公式リポジトリ履歴では、4月24日にドキュメント管理系の更新が入り、その後4月27日にtsconfig.jsonとサンプルコードの実質的な見直しが確認できます。現場で重要なのは、「Visual Studio上でTypeScriptを少しだけASP.NET Core MVCに足す手順」が、より安全で整理された形になった点です。特にrootDirの追加と、DOM要素のnullチェックは、既存アプリへTypeScriptを段階導入するチームにとって見逃せません。(GitHub)
Visual Studioの最新動向: Add TypeScript to an ASP.NET Core appで何が変わったか
Microsoft Learnの「Add TypeScript to an existing ASP.NET Core app in Visual Studio」は、ASP.NET Core MVCアプリにTypeScriptを追加し、ビルド、実行、デバッグ、サードパーティライブラリの型定義追加までを扱うチュートリアルです。前提として、Visual Studioと「ASP.NET と Web 開発」ワークロードが必要で、プロジェクト作成時は.NET 8.0 or laterを選ぶ流れになっています。(Microsoft Learn)
今回の2026年4月更新ポイントを実務目線で整理すると、単なる手順紹介ではなく、既存のASP.NET CoreアプリにTypeScriptを安全に組み込むための構成整理と見てよいでしょう。
| 更新・注目ポイント | 何が重要か | 現場で取るべき対応 |
|---|---|---|
Microsoft.TypeScript.MSBuildを使う流れが中心 | Visual Studio、MSBuild、dotnet build/dotnet publishとの相性がよい | ASP.NET Core MVCやRazor中心の既存アプリではNuGet導入を基本にする |
tsconfig.jsonにrootDir: "./scripts"が入った | TypeScriptの入力元と生成JavaScriptの出力先を明確に分けられる | scriptsに.ts、wwwroot/jsに生成物という構成を標準化する |
wwwrootとnode_modulesをexclude | 生成済みJSや依存パッケージを再コンパイル対象にしない | ビルドの重複、意図しないファイル監視、出力ループを避ける |
DOM要素取得後にnullチェックを入れるサンプルへ | 要素が存在しない場合の実行時エラーを避けられる | 本番コードではDOM取得後の存在確認を徹底する |
| Angular/Vue利用時はSPAテンプレート推奨 | MVCに小さくTypeScriptを足すケースと、本格SPAは別物 | フロントエンド規模に応じて導入方式を選ぶ |
このチュートリアルが向いているケース、向いていないケース
Visual StudioでTypeScriptを扱う方法は複数あります。今回のMicrosoft Learn記事は、既存のASP.NET Core MVCアプリに、部分的にTypeScriptを追加するケースに向いています。
| ケース | おすすめ度 | 判断基準 |
|---|---|---|
| 既存のASP.NET Core MVC/Razor Pagesアプリに少量の画面制御を追加したい | 高い | フロントエンドは補助的で、サーバーサイドレンダリングが中心 |
dotnet buildやdotnet publishでTypeScriptも一緒にビルドしたい | 高い | DevOpsやCI/CDでMSBuild統合を重視する |
| jQueryなど既存ライブラリに型定義を追加して保守性を上げたい | 高い | レガシー寄りの画面を段階的に改善したい |
| React、Angular、Vueで本格的なSPAを作りたい | 低い | SPAテンプレートやnpm/Viteなどのフロントエンドビルド基盤を使うべき |
JavaScript Project Systemや.esprojベースのプロジェクト | 低い | Microsoftの別記事では、JSPSや.esprojではNuGetではなくnpmパッケージ利用が案内されている |
Microsoft Learnでも、Visual Studio 2022以降でASP.NET CoreとAngularまたはVueを使う場合は、ASP.NET Core SPAテンプレートの利用が推奨されています。つまり、今回の手順は「SPA開発の標準手順」ではなく、ASP.NET Core MVCにTypeScriptを追加する軽量な導入手順として理解するのが正解です。(Microsoft Learn)
Visual StudioでASP.NET CoreアプリにTypeScriptを追加する基本手順
実務で迷わないように、Microsoft Learnの流れを現場向けに整理します。
前提条件を確認する
まず、Visual Studioに「ASP.NET と Web 開発」ワークロードが入っているか確認します。入っていない場合は、Visual Studio Installerから追加します。
ASP.NET Core MVCテンプレートが表示されない場合、原因の多くはこのワークロード不足です。テンプレート名や検索語を疑う前に、インストール済みワークロードを確認してください。
ASP.NET Core MVCプロジェクトを用意する
新規作成する場合は、Visual Studioの「新しいプロジェクトの作成」から、C#のASP.NET Core Web App (Model-View-Controller)を選びます。追加情報では.NET 8.0 or laterを選択する流れです。既存アプリに追加する場合も、MVCまたはRazorを中心にした構成であれば同じ考え方で導入できます。(Microsoft Learn)
TypeScriptサポート用のNuGetパッケージを追加する
プロジェクトを右クリックし、「NuGet パッケージの管理」からMicrosoft.TypeScript.MSBuildを検索してインストールします。
このパッケージを使う理由は、単にVisual StudioでTypeScriptを書けるようにするためだけではありません。ASP.NET Coreプロジェクトでは、TypeScriptのコンパイルを.NET Core CLIやMSBuildに統合しやすくなります。Microsoftの関連ドキュメントでも、Visual Studio 2019以降はTypeScript SDKではなくNuGetパッケージの利用が推奨され、.NETシナリオではdotnet buildやdotnet publishでTypeScriptコンパイルを有効にする方法として案内されています。(Microsoft Learn)
DevOpsエンジニアやPlatform Teamにとっては、ここが重要です。ローカルのVisual Studioだけで動く構成ではなく、CI/CDでも再現できる構成にしやすいからです。
2026年4月更新で注目すべきtsconfig.jsonの考え方
今回の更新で特に実務的なのが、tsconfig.jsonの構成です。ポイントは、入力元と出力先を分けることです。
{
"compileOnSave": true,
"compilerOptions": {
"noImplicitAny": false,
"noEmitOnError": true,
"removeComments": false,
"sourceMap": true,
"target": "ES6",
"rootDir": "./scripts",
"outDir": "wwwroot/js"
},
"include": [
"scripts/**/*"
],
"exclude": [
"node_modules",
"wwwroot"
]
}この構成では、TypeScriptファイルはscripts配下に置き、生成されたJavaScriptはwwwroot/jsへ出力されます。outDirは生成後のJavaScriptファイルの出力先を示し、sourceMapはデバッグに必要なソースマップ生成に関係します。Microsoft Learnでも、ビルド後にapp.jsとapp.js.mapが生成され、ソースマップはデバッグに必要と説明されています。(Microsoft Learn)
rootDirを指定する意味
rootDir: "./scripts"を指定すると、TypeScriptコンパイラがどこをソースの起点として扱うかが明確になります。
これを指定しない場合でも小さなサンプルでは動くことがありますが、ファイルが増えたときに出力構造が読みづらくなったり、どこまでをTypeScriptの入力として扱うべきかが曖昧になったりします。
実務では、次のように役割を分けると保守しやすくなります。
/scripts
app.ts
form-validation.ts
dashboard.ts
/wwwroot/js
app.js
app.js.map
form-validation.js
form-validation.js.map
dashboard.js
dashboard.js.mapwwwroot/jsに.tsファイルを直接置かないことがポイントです。wwwrootはブラウザーへ配信する静的ファイルの場所です。TypeScriptのソースコード置き場ではなく、生成物の出力先として扱うと、開発者にもCIにも分かりやすい構成になります。
excludeでwwwrootを外す理由
excludeにwwwrootを入れるのは、生成されたJavaScriptやソースマップを再びTypeScriptコンパイル対象にしないためです。
特に、チーム開発で次のような問題が起きる場合は、includeとexcludeの設定を見直してください。
| 症状 | よくある原因 | 対応 |
|---|---|---|
| ビルド対象ファイルが増えすぎる | includeが広すぎる | scripts/**/*のように入力元を限定する |
| 生成物まで監視・処理される | wwwrootを除外していない | excludeにwwwrootを入れる |
| npm依存まで処理される | node_modulesを除外していない | excludeにnode_modulesを入れる |
| 出力先が分かりにくい | outDirだけで入力元が曖昧 | rootDirも指定する |
DOM操作サンプルの改善: nullチェックは本番コードでも必須
2026年4月の差分では、app.tsのサンプルも改善されています。以前のようにdocument.getElementById()の戻り値へ直接アクセスするのではなく、取得した要素が存在するか確認してから処理する形です。GitHub上の差分でも、const element = document.getElementById("ts-example");で要素を受け取り、存在する場合のみinnerHTMLを更新するコードに変更されています。(GitHub)
実務では、さらに次のように書くと安全です。
function showGreeting(): void {
const element = document.getElementById("ts-example");
if (!element) {
return;
}
element.textContent = "Hello from TypeScript";
}ここでtextContentを使っているのは、単純な文字列表示ならinnerHTMLより安全だからです。innerHTMLはHTMLを挿入したい場合には便利ですが、外部入力やユーザー入力をそのまま入れるとXSSの原因になります。
判断基準は次の通りです。
| 目的 | 使うプロパティ | 理由 |
|---|---|---|
| 文字列を表示するだけ | textContent | HTMLとして解釈されないため安全 |
| HTML断片を意図的に描画する | innerHTML | タグを反映できるが、入力値の扱いに注意が必要 |
| 属性やクラスを操作する | setAttribute、classList | 目的が明確で保守しやすい |
TypeScriptを入れるメリットは、型注釈やIntelliSenseだけではありません。こうしたDOM操作の危険な箇所を、コードレビューで発見しやすくなることも大きな利点です。
Razor側では生成後のJavaScriptを読み込む
TypeScriptファイルそのものをブラウザーで読み込むのではなく、コンパイル後のJavaScriptを読み込みます。
Microsoft Learnの流れでは、_Layout.cshtmlで次のようにwwwroot/js配下の生成物を参照します。(Microsoft Learn)
<script src="~/js/app.js"></script>ここで注意したいのは、読み込み位置です。ページ固有の要素を操作するスクリプトを共通レイアウトで読み込む場合、その要素が存在しないページでもスクリプトが実行される可能性があります。
そのため、本番では次のいずれかを選びます。
| 方法 | 向いているケース | 注意点 |
|---|---|---|
_Layout.cshtmlで共通読み込み | 全ページで使う共通スクリプト | ページ固有要素に直接依存しない |
各ViewのScriptsセクションで読み込み | 特定ページだけで使うスクリプト | 読み忘れを防ぐルールが必要 |
| バンドル・ビルドツールでまとめる | ファイル数が多い | npm/Vite/Webpackなどの運用が必要 |
小規模な導入なら_Layout.cshtmlで十分です。ただし、画面ごとにTypeScriptファイルが増えるなら、ページ単位で読み込むか、フロントエンドのビルド基盤を別途検討した方が管理しやすくなります。
ビルドとデバッグで確認すべきポイント
Visual Studioではアプリ実行時にビルドされますが、導入直後は必ず「Build > Build Solution」を実行して、TypeScriptの出力を確認しましょう。
確認すべきファイルは次の2つです。
wwwroot/js/app.js
wwwroot/js/app.js.mapapp.jsはブラウザーが実行するJavaScriptです。app.js.mapはTypeScriptソースと生成後JavaScriptを対応付けるソースマップで、デバッグに使われます。Microsoft Learnでも、TypeScriptコンパイラがこれらを生成し、ソースマップはデバッグに必要と説明されています。(Microsoft Learn)
ChromeまたはEdgeでクライアント側スクリプトをデバッグする
Visual StudioからF5で実行し、TypeScript側の関数にブレークポイントを設定すると、ブラウザー操作をきっかけにブレークできます。Microsoft Learnでは、クライアント側スクリプトのデバッグにはChromeまたはEdgeが必要とされています。(Microsoft Learn)
デバッグできない場合は、次の順に確認してください。
| 確認項目 | 見る場所 | 対応 |
|---|---|---|
.mapファイルが生成されているか | wwwroot/js | sourceMap: trueを確認する |
| 読み込んでいるJSパスが正しいか | ブラウザーの開発者ツール | 404になっていないか確認する |
| ブレークポイントがバインドされているか | Visual Studio | 空洞の赤丸になっていないか見る |
| ブラウザーが対応しているか | 実行ブラウザー | ChromeまたはEdgeで試す |
| 古いJSがキャッシュされていないか | DevTools Network | キャッシュ無効化またはハードリロードする |
サードパーティライブラリを使う場合は型定義を入れる
チュートリアルでは、jQueryの型定義として@types/jqueryを追加する例も紹介されています。型定義を入れると、jQueryオブジェクトに対してIntelliSenseが効き、メソッド名の補完や型チェックの恩恵を受けられます。(Microsoft Learn)
例として、package.jsonに次のようなdevDependenciesを追加します。
{
"devDependencies": {
"@types/jquery": "3.5.1"
}
}ただし、ここで混同しやすい点があります。@types/jqueryは、jQuery本体ではなくTypeScript向けの型定義です。MVCテンプレートではjQuery本体がwwwroot/libに含まれる場合がありますが、別のテンプレートや独自構成では、jQuery本体も別途追加する必要があります。
| パッケージ | 役割 | 本番で必要か |
|---|---|---|
jquery | ブラウザーで動くライブラリ本体 | 使うなら必要 |
@types/jquery | TypeScriptの補完・型チェック用 | 開発時に必要 |
Microsoft.TypeScript.MSBuild | TypeScriptをMSBuildで扱うためのNuGet | ビルド構成として必要 |
既存のレガシー画面でjQueryを使っているチームにとって、@types/*の導入は移行の第一歩として有効です。いきなりReactやVueへ置き換えるより、まず型定義を入れて誤用を減らす方が、短期的には効果が出やすい場合があります。
DevOps・Platform Team向け: CI/CDで失敗しない設計ポイント
Visual Studio上で動いたとしても、CI/CDで失敗する構成では実務投入しにくくなります。TypeScript導入時は、ローカル開発者だけでなく、ビルドサーバーやリリースパイプラインも含めて設計しましょう。
dotnet buildでTypeScriptも通るか確認する
NuGetのMicrosoft.TypeScript.MSBuildを使う利点は、MSBuildや.NET Core CLIとの統合です。Microsoftの関連ドキュメントでも、ASP.NET CoreプロジェクトではNuGetパッケージが.NETシナリオの推奨オプションであり、dotnet buildやdotnet publishでTypeScriptコンパイルを有効にする方法として説明されています。(Microsoft Learn)
CIで最低限確認したいコマンドは次の通りです。
dotnet restore
dotnet build --configuration Release
dotnet publish --configuration Releaseビルドサーバーでだけ失敗する場合は、Node.jsやVisual Studio Build Tools、NuGetパッケージ復元、作業ディレクトリの差異を確認します。
生成JSをGit管理するか決める
wwwroot/jsに生成される.jsや.js.mapをGitに含めるかは、チームの運用で決める必要があります。
| 方針 | メリット | デメリット | 向いているケース |
|---|---|---|---|
| 生成JSをコミットする | デプロイ時にビルド不要でも動く | 差分が増え、ソースと生成物のズレが起きやすい | シンプルな手動デプロイ |
| 生成JSをコミットしない | ソース管理がきれい | CI/CDで必ずビルドが必要 | 自動ビルド・自動デプロイ |
本番では.mapを出さない | ソース漏えいリスクを下げられる | 本番デバッグがしにくい | セキュリティ要件が強い環境 |
おすすめは、CI/CDが整っているならTypeScriptソースを正とし、生成物はビルドで作る方針です。ただし、静的ファイルだけを単純コピーする運用が残っている場合は、生成JSの扱いを事前に決めておかないと、本番でスクリプトが見つからない事故につながります。
Source Mapの公開範囲を考える
sourceMap: trueは開発とデバッグには便利です。一方で、本番環境に.mapファイルを公開すると、TypeScriptの元コード構造が見えやすくなります。
機密ロジックをフロントエンドに置くべきではありませんが、それでも社内用画面や管理画面では、ソースマップの公開範囲を確認してください。
実務では次のように分けると安全です。
| 環境 | sourceMap | 理由 |
|---|---|---|
| ローカル開発 | true | Visual Studioでのデバッグに必要 |
| 検証環境 | trueまたは制限付き | 障害調査を優先する場合に有効 |
| 本番環境 | 要件次第 | 公開リスクと調査効率のバランスで判断 |
よくある失敗と対処法
TypeScriptファイルをwwwrootに置いてしまう
wwwrootは公開される静的ファイルの置き場です。TypeScriptのソースを置く場所ではありません。
誤ってwwwroot/js/app.tsのように配置すると、出力先と入力元が混ざり、チーム内で「どれが編集対象か」が分かりにくくなります。基本はscriptsに.ts、wwwroot/jsに生成された.jsです。
生成されたJSではなくTSをRazorから読もうとする
ブラウザーが実行するのはTypeScriptではなくJavaScriptです。RazorやHTMLからは、生成後の~/js/app.jsを読み込みます。
<script src="~/js/app.js"></script>~/scripts/app.tsのように参照しても、通常のブラウザーではそのまま実行できません。
DOM要素が存在しないページでエラーになる
共通レイアウトでスクリプトを読み込むと、全ページで同じJavaScriptが実行されます。特定ページにしか存在しない要素を操作するなら、必ず存在確認を入れます。
const button = document.getElementById("save-button");
if (!button) {
return;
}このチェックは、TypeScript初心者ほど省略しがちです。最初からチームのコーディング規約に入れておくと、レビューコストを下げられます。
npmパッケージの状態がVisual Studio上で同期しない
Microsoft Learnでは、package.jsonとソリューションエクスプローラー上のnpmパッケージ表示が同期していないように見えるケースにも触れています。多くの場合、Visual Studioの再起動やpackage.jsonの再追加で表示が更新されることがあります。(Microsoft Learn)
CIではVisual Studioの表示ではなく、実際にnpm installやdotnet buildが成功するかを基準に判断しましょう。
既存ASP.NET CoreアプリにTypeScriptを入れる判断基準
TypeScript導入は「流行っているから入れる」ではなく、次の条件に当てはまるときに効果が出やすいです。
| 導入した方がよい状況 | 理由 |
|---|---|
| JavaScriptの画面ロジックが増えてきた | 型チェックと補完で保守しやすくなる |
| 複数人で同じJSを編集している | 引数や戻り値の誤解を減らせる |
| jQueryや既存ライブラリの誤用が多い | @types/*で補完と型チェックを使える |
| CI/CDでビルドを標準化したい | NuGet/MSBuild統合で再現性を高めやすい |
| 将来的にフロントエンド刷新を考えている | 段階的移行の準備になる |
一方で、すでにReactやVueを本格採用している場合、ASP.NET Core MVCに直接TypeScriptを足すより、専用のフロントエンドプロジェクトやSPAテンプレートを使った方が自然です。
実務でのおすすめ構成
小〜中規模のASP.NET Core MVCアプリなら、次の構成が扱いやすいです。
/MyAspNetCoreApp
/Controllers
/Models
/Views
/scripts
app.ts
validation.ts
/wwwroot
/js
app.js
app.js.map
validation.js
validation.js.map
/css
/lib
tsconfig.json
package.json
MyAspNetCoreApp.csprojこの構成のメリットは、役割が明確なことです。
scriptsは開発者が編集するTypeScriptの置き場です。wwwroot/jsはブラウザーに配信するJavaScriptの置き場です。tsconfig.jsonはその変換ルールを管理します。
Platform Teamが社内テンプレートを整備するなら、このディレクトリ構成とtsconfig.jsonを標準化しておくと、チームごとの差異を減らせます。
まとめ: 2026年4月更新で押さえるべき次の一手
Visual Studioの「Add TypeScript to an ASP.NET Core app」は、既存のASP.NET Core MVCアプリにTypeScriptを段階導入するための実用的な手順です。2026年4月の公式リポジトリ履歴を見ると、4月24日の管理系更新に加え、4月27日にtsconfig.jsonとサンプルコードの改善が入っており、実務では次の3点を押さえるべきです。(GitHub)
まず、TypeScriptサポートはMicrosoft.TypeScript.MSBuildで追加し、Visual Studioだけでなくdotnet buildやdotnet publishでも再現できる構成にします。次に、rootDir: "./scripts"とoutDir: "wwwroot/js"で、ソースと生成物を明確に分けます。最後に、DOM操作ではgetElementById()の戻り値を必ず確認し、ページによって要素が存在しないケースでも壊れないコードにします。
次に取るべき行動は、既存プロジェクトでscriptsとwwwroot/jsの分離ができているか、tsconfig.jsonにrootDirとexcludeが入っているか、CIでdotnet buildが通るかを確認することです。ここまで整えれば、ASP.NET CoreアプリへTypeScriptを安全に追加し、チーム開発でも保守しやすい構成にできます。
コメント