dist/ の中身は何なのか — ビルドツールとVite

ビルドツールとVite。コードの書類と梱包されたファイル、変換を表す歯車。

※本記事はアフィリエイト広告(PR)を含みます。

npm run build を打つと dist/ に見覚えのないファイルができる。あれは何なのか。

前回: node_modulesは消してよい — npmとパッケージ管理 この記事で第3段階(プログラミング)は最後です。

自分が書いたのは main.js と style.css と index.html の3つだけのはずなのに、出てきたのは index-a1b2c3d4.js みたいな、意味の分からない名前のファイルでした。開いてみたら改行がなくて、変数名は t とか n とか1文字になっていて、自分が書いた覚えのないコードまで混ざっている。

「動いたからいいや」で先に進みました。 そして数日後、本番だけ画面が真っ白になったときに、何も出来ませんでした。

エラーは出ています。でもエラーが指している場所は index-a1b2c3d4.js の 1行目 4823文字目。自分のコードのどこなのか、まったく分かりません。

中で何が起きているか分からないまま使うと、壊れたときに何も出来ない。 これはビルドツールに限った話ではないのですが、ビルドツールは特にそうです。普段は完全に透明で、壊れたときだけ突然出てくるからです。

この記事は「Vite の使い方」ではありません。「そもそも、なぜビルドという工程が要るのか」を分解する記事です。動かすのは、分解した話を目で確認するためです。

対象レベル: 初級 / 区分: 必修

目次

この記事でわかること

  • ビルドは1つの作業ではなく、4つの別々の作業の総称だということ(トランスパイル・バンドル・minify・tree shaking)
  • 「バンドルは必須ではなくなった」こと。ブラウザは今 import を理解できる。それでも本番でまとめるのには別の理由がある
  • Vite の開発サーバーが速いのは、最適化が上手いからではなく「まとめていないから」だということ
  • dist/ に出るファイル名のハッシュは飾りではなく、キャッシュ対策という明確な仕事をしていること
  • ビルド成果物はただの静的ファイルなので、nginx が返すだけで公開できること

この記事でやること

  1. なぜビルドが要るのかを4つに分解して理解する(ここが本題)
  2. VMの中の Ubuntu で npm create vite@latest を実行し、Vanilla(フレームワークなし)のプロジェクトを作る
  3. npm run dev -- --host 0.0.0.0 で開発サーバーを起動し、ホストのブラウザから見る。HMR を体験する
  4. npm run build して dist/ の中身を ls -la で実際に見る
  5. dist/ を nginx で配って、ビルド成果物がただの静的ファイルであることを確認する

作業する場所を毎回書きます。コマンドは全部 VMの中の Ubuntu(VS Code のリモートターミナルでも、SSH でも同じ)、確認はホストの Windows のブラウザです。

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
ビルド自分が書いたコードを、そのままブラウザに配れる形に作り直す工程。中身は下の4つの作業の総称
トランスパイルブラウザが理解できない書き方を、理解できる JavaScript に書き直すこと
バンドル分かれている複数のファイルを1つにまとめること。通信の回数を減らすのが目的
minify(ミニファイ)空白・改行・コメントを削り、変数名を短くしてファイルを小さくすること。動きは変わらない
tree shakingどこからも呼ばれていないコードを捨てること。使っていない機能まで配らずに済む
Vite上の作業をまとめて引き受けるビルドツールのひとつ。開発中と本番で別々のやり方を使い分けるのが特徴

そもそも、なぜビルドが要るのか

ここが本題です。ビルドという単語が指しているのは、実は4つの別々の作業です。まとめて「ビルド」と呼ばれているせいで、1個の魔法に見えてしまいます。

分解すると、こうなります。

#作業何をしているか無いと何が困るか
1トランスパイルブラウザが読めない書き方を、読める形に書き直すそもそも動かない
2バンドルたくさんのファイルを1つにまとめる通信回数が増えて遅い
3minify空白・改行・変数名を削って小さくするファイルが重い
4tree shaking使っていないコードを捨てる使わないコードまで配ってしまう

この4つは、それぞれ別々の困りごとに対する別々の答えです。 順番に見ます。

1. ブラウザが理解できない書き方を、理解できる形に直す=トランスパイル

一番わかりやすいのがこれです。

人間が書きたい書き方と、ブラウザが読める書き方は、一致していません。

たとえば TypeScript。

function greet(name: string): string {
  return `こんにちは、${name}さん`;
}

: string の部分は TypeScript の書き方です。ブラウザにそのまま渡すと構文エラーで止まります。 ブラウザは JavaScript しか知らないからです。

だから、こう書き直してから渡します。

function greet(name) {
  return `こんにちは、${name}さん`;
}

型の情報を消しただけです。 この「別の言語・別の書き方から、ブラウザが読める JavaScript に書き直す」作業をトランスパイルと呼びます。

同じことが、React の JSX でも起きます。

const el = <h1>こんにちは</h1>;

JavaScript に <h1> をそのまま書く文法は存在しません。 これも書き直しが要ります。

そしてもう1つ、見落としやすいけれど大事なケースがあります。新しい構文と、古いブラウザです。

const name = user?.profile?.name ?? "名無し";

?.(オプショナルチェーン)と ??(Null 合体演算子)は、比較的新しい書き方です。今の Chrome なら動きます。でも数年前のブラウザや、古い Android の WebView では構文エラーになります。

トランスパイラは、これを古いブラウザでも動く形に書き直します。

var _a, _b;
var name = (_b = user === null || user === void 0
  ? void 0
  : (_a = user.profile) === null || _a === void 0
    ? void 0
    : _a.name) !== null && _b !== void 0
  ? _b
  : "名無し";

読みたくない見た目です。でも、これが「動く形」です。

ここがビルドの本質の1つです。 人間が読みやすい書き方と、機械が確実に動かせる書き方は、違います。ビルドツールはその間を機械的に翻訳しているだけです。 前者を人間が書き、後者をブラウザが読む。両方を人間が書こうとしていたのが、ビルドが無かった時代です。

2. たくさんのファイルを、まとめて減らす=バンドル

コードを整理していくと、ファイルは自然に増えます。

src/
├── main.js
├── utils/
│   ├── format.js
│   ├── validate.js
│   └── api.js
├── components/
│   ├── header.js
│   ├── footer.js
│   └── modal.js
└── style.css

人間にとっては、分かれているほうが圧倒的に読みやすい。 これは間違いなくそうです。

でもブラウザにとっては、分かれているほど不利です。

DNS・HTTP・HTTPS の回 で、1ページを表示するのに何回通信が発生しているかを開発者ツールで数えました。画像1枚、CSS 1枚、JS 1本、それぞれが別々のリクエストでした。

ファイルが8個あれば、リクエストは8回です。1回のリクエストには、

  • DNS の名前解決(キャッシュされていなければ)
  • TCP の接続確立
  • TLS のハンドシェイク(HTTPS なら)
  • リクエスト送信 → レスポンス待ち

という往復がぶら下がっています。ファイルの中身が小さくても、往復の時間はほぼ固定でかかります。

これを1つにまとめれば、リクエストは1回で済みます。これがバンドルです。

dist/
└── assets/
    └── index-a1b2c3d4.js   ← 8個ぜんぶ入っている

HTTP/2 で改善したのでは? という指摘は正しいです。HTTP/2 以降は1本の接続の中で複数のファイルを並行して送れるので、昔ほど「ファイル数=致命傷」ではなくなりました。 ただしゼロにはなりません。 ファイルごとにヘッダーの往復はあるし、そのファイルが必要だと分かるのは、それを参照している別のファイルを読み終えた後です。main.js を読んで初めて utils/api.js が要ると分かる、というのが連鎖すると、待ち時間が積み上がります。

3. 小さくする=minify

自分が書いたコードは、こうなっているはずです。

function calculateTotalPrice(items, taxRate) {
  // 合計金額を計算する
  let total = 0;

  for (const item of items) {
    total = total + item.price * item.quantity;
  }

  return Math.round(total * (1 + taxRate));
}

改行・インデント・コメント・意味のある変数名。 全部、人間が読むためのものです。ブラウザは1つも必要としていません。

minify は、これを削ります。

function c(t,a){let e=0;for(const n of t)e=e+n.price*n.quantity;return Math.round(e*(1+a))}

やっていることは3つです。

削るもの例
空白・改行・インデント全部詰める
コメント丸ごと削除
変数名・関数名calculateTotalPrice → c、total → e

動作は1ミリも変わりません。 変わるのはサイズだけです。これで数十パーセント小さくなります。

そして、これがデバッグを不可能にしている犯人でもあります。冒頭で書いた「エラーの場所が index-a1b2c3d4.js の 1行目 4823文字目」というのは、改行を全部消したから全部が1行目になっているというだけの話です。この解決策が後で出てくるソースマップです。

変数名を短くするのは、なぜ安全なのか。 関数の中でしか使われていない変数は、外から名前で呼ばれることがないからです。だから名前は何でもいい。 逆に、外から名前で呼ばれるもの(window.myFunc とか、オブジェクトのプロパティ名)は、迂闊にリネームすると壊れます。ここはツールが判別してやってくれますが、「文字列でプロパティ名を組み立てる」ような書き方をすると判別に失敗することがあります。 minify したときだけ壊れるバグは、だいたいこれです。

4. 使っていないコードを落とす=tree shaking

ライブラリを入れると、使っていない機能まで全部ついてきます。

たとえば、日付を扱うライブラリを入れて、使ったのは「今日の日付を YYYY-MM-DD にする」1つだけ。でもライブラリ本体には、タイムゾーン変換も、相対時間表示も、各国語の月名も入っています。

そのまま配ると、使っていない99%も一緒に配ることになります。

tree shaking は、「どこからも呼ばれていないコード」を辿って捨てる作業です。

// utils.js
export function used()   { return "使う"; }
export function unused() { return "使わない"; }
// main.js
import { used } from "./utils.js";
console.log(used());

この場合、unused() はどこからも呼ばれていないので、dist/ には入りません。

木を揺すって、枯れた葉(使われていないコード)を落とす。だから tree shaking です。

なぜ「木を揺する」で済むのか。 import { used } from "./utils.js" という書き方が、「何を使うか」をコードを実行する前に静的に読み取れる形だからです。 これは後で出てくる ES モジュールの性質です。昔の require() は実行時に決まるので、何が使われるか事前に分からず、tree shaking ができません。 ここは繋がっています。


ビルドが要らなかった時代に、何が困っていたか

「ビルドが要る理由」を4つ見ました。逆側からも見ておきます。ビルドが無かった頃、どう書いていたのか。

こうです。

<script src="jquery.js"></script>
<script src="utils.js"></script>
<script src="validate.js"></script>
<script src="main.js"></script>

<script> タグを、必要な順番に並べる。 それだけです。ビルドツールもコンパイルも要りません。

これは分かりやすいです。分かりやすいのですが、規模が大きくなると3つの問題が出ます。

問題1: グローバル汚染

昔のスクリプトには、「このファイルの中だけ」という仕切りがありませんでした。

// utils.js
var config = { debug: true };
// main.js
var config = { apiUrl: "https://example.com" };

後から読まれたほうが勝ちます。 utils.js の config は、main.js に上書きされて消えます。

エラーは出ません。静かに壊れます。 そして「なぜか debug が効かない」という調査に半日溶けます。

ファイルが4個なら気をつけられます。40個になると無理です。

問題2: 読み込み順

上の例で <script src="main.js"> を utils.js より先に書いたら、main.js が utils.js の関数を呼ぶ瞬間に「そんな関数はない」で落ちます。

つまり、依存関係を人間が手で順番に並べて管理していたわけです。

  • A は B に依存している
  • B は C に依存している
  • C は A の一部の関数を使っている(循環している)

この順番を、ファイルが増えても手で正しく保ち続ける。 現実的ではありません。

問題3: 依存の管理

jquery.js というファイルがリポジトリに置いてあるだけでは、バージョンも入手元も分かりません。 更新は公式サイトから手でダウンロードして置き換える。そのライブラリがさらに別のライブラリに依存していたら、それも手で入れる。

これは npm の回 で見た package.json が解決した問題そのものです。

まとめると、ビルドツールが登場した理由はこうです。 ファイルを分けたい(人間の都合)が、分けると壊れる・遅くなる(機械の都合)。 その両方を成立させるために、「書くときは分ける、配るときはまとめる」という工程を挟んだ。 それがビルドです。


ES モジュール — import と export

グローバル汚染と読み込み順の問題に、言語そのものが出した答えが ES モジュールです。

// utils.js
export function formatDate(d) {
  return d.toISOString().slice(0, 10);
}
// main.js
import { formatDate } from "./utils.js";

console.log(formatDate(new Date()));

これで3つが同時に解決します。

昔の問題ES モジュールでどうなるか
グローバル汚染export したものだけが外に出る。 それ以外はファイルの中に閉じる
読み込み順import に書いてある=依存関係が宣言されている。 順番はツールが解決する
何を使っているか不明ファイルの先頭を見れば依存が全部分かる

「このファイルは何に依存しているか」がコードに書いてある。 これが決定的です。人間が <script> の順番で暗黙に表現していたものが、明示的なデータになりました。

ブラウザも今は理解できる

ここが、この記事で一番ひっくり返るところです。

import / export は、今のブラウザがそのまま理解できます。

<script type="module" src="/main.js"></script>

type="module" を付けるだけです。これだけで、ブラウザは main.js の中の import を読んで、必要なファイルを自分で取りに行きます。

試せます。VMの中の Ubuntu で、適当なディレクトリを作って。

bash
$ mkdir -p ~/esm-test && cd ~/esm-test
bash
$ cat > utils.js <<'EOF'
  export function hello(name) {
    return `こんにちは、${name}さん`;
  }
  EOF
bash
$ cat > main.js <<'EOF'
  import { hello } from "./utils.js";
  document.body.textContent = hello("obmes");
  EOF
bash
$ cat > index.html <<'EOF'
  <!doctype html>
  <html lang="ja">
  <head><meta charset="utf-8"><title>ESM test</title></head>
  <body>
  <script type="module" src="/main.js"></script>
  </body>
  </html>
  EOF

配ります。

bash
$ python3 -m http.server 8000 --bind 0.0.0.0

ホストの Windows のブラウザで http://<VMのIP>:8000/ を開くと、「こんにちは、obmesさん」と出ます。

ビルドツールは1つも使っていません。 import をブラウザが解釈して、utils.js を自分で取りに行っています。

なぜ python3 -m http.server が要るのか。 index.html をファイルとしてダブルクリックで開く(file://)と、モジュールの読み込みは CORS エラーで失敗します。 ES モジュールは http:// か https:// 経由でしか読めない決まりです。 「ローカルで開いたら動かない」の大半はこれです。

止めるときは Ctrl+C。片付けは rm -rf ~/esm-test です。

[スクリーンショット: 01_esmodule_network.png] ホストのブラウザで開いた状態で F12 → Network タブを開いて再読み込みし、main.js と utils.js が別々のリクエストとして2本並んでいるところを撮ってください。開発者ツールの回 で見た画面です。バンドルしていないと通信が増える、というのがそのまま見えます。

だから「バンドルは必須ではなくなった」

ブラウザが import を理解するなら、バンドルしなくても動きます。 これは事実です。

それでも本番でまとめる理由は、残っています。

  1. 通信回数。上のスクリーンショットの通り、ファイルの数だけリクエストが飛びます。 ファイル200個のアプリなら200回です
  2. 依存の連鎖。ブラウザは main.js を読み終えて初めて utils.js が必要だと知ります。その utils.js がさらに import していたら、また往復します。深さの分だけ待ちます
  3. import "lodash" は動かない。ブラウザは ./utils.js のようなパスは辿れますが、lodash というパッケージ名だけでは node_modules を探しに行けません。この解決はツールの仕事です
  4. minify・tree shaking・トランスパイルは、どのみち要る。バンドルしないならしないで、残り3つの作業は消えません

整理すると、 ES モジュールは「なぜバンドルするのか」の理由の一部を消しました。「グローバル汚染を避けるため」「読み込み順を管理するため」はもう理由になりません。 残ったのは「配る効率のため」だけです。だから開発中はバンドルしない、本番だけバンドルするという選択が成り立ちます。それをやっているのが Vite です。


実際にやる — Vite でプロジェクトを作る

ここから VMの中の Ubuntu で作業します。

Node.js と npm は npm の回 で入れた前提です。確認します。

bash
$ node -v
$ npm -v
v22.11.0
10.9.0

バージョンが表示されれば OK です。出なければ npm の回に戻ってください。

その前に —— ここまでの ~/web/ はどうなるのか

第2段階から使ってきた ~/web/(index.html / style.css / script.js / data.json)は、消しません。

これから作る Vite のプロジェクトは別のディレクトリ(~/vite-demo/)に作ります。~/web/ はそのまま残しておいてください。

この2つは役割が違います。

~/web/~/vite-demo/
何か素のHTML/CSS/JS。ブラウザにそのまま渡しているビルドを通すプロジェクト
配り方python3 -m http.server でそのままnpm run build → dist/ を配る
役割仕組みを見るための最小構成道具が何をやっているかを見るための比較対象

~/web/ を Vite に載せ替えることもできますが、この回ではやりません。 載せ替えてしまうと「Vite が何を足したのか」の比較対象が消えるからです。素の状態を残したまま、隣に道具ありの状態を作って見比べます。

~/web/ を使うのは、第6段階の nginx の回が最後です。そこで「素のHTML」と「ビルド成果物」の両方を nginx に載せます。

npm create vite@latest

作業ディレクトリに移動して、

bash
$ cd ~
$ npm create vite@latest

対話が始まります。 聞かれる順に答えます。

? Project name: › vite-demo
? Select a framework: › Vanilla
? Select a variant: › JavaScript
質問答え理由
Project namevite-demoディレクトリ名になる
Select a frameworkVanillaフレームワークなし。 React などは第4段階で扱う
Select a variantJavaScriptTypeScript はまだ扱わない

必ず Vanilla を選んでください。 ここで React を選ぶと、ビルドの話とフレームワークの話が混ざって、何がどっちの機能なのか分からなくなります。 今日見たいのは「ビルドツールが何をしているか」だけです。

npm create は何をしているのか。 npm の回 の npx と同じで、create-vite を一時的にダウンロードして実行し、終わったら捨てています。 @latest を付けないと古いキャッシュが使われることがあります。

[スクリーンショット: 02_create_vite_対話.png] npm create vite@latest のフレームワーク選択画面(Vanilla にカーソルがある状態)を撮ってください。

npm install

作られたディレクトリに入って、

bash
$ cd vite-demo
$ ls -la
drwxr-xr-x  .
-rw-r--r--  .gitignore
-rw-r--r--  index.html
-rw-r--r--  package.json
drwxr-xr-x  public
drwxr-xr-x  src

node_modules/ はまだありません。 package.json に「何が必要か」が書いてあるだけです。

bash
$ cat package.json
{
  "name": "vite-demo",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "devDependencies": {
    "vite": "^7.0.0"
  }
}

見るところが3つあります。

  • "type": "module" … このプロジェクトは ES モジュールで書く、という宣言
  • scripts … npm run dev / npm run build / npm run preview の中身。この3行が全部です
  • devDependencies … Vite は開発時にだけ必要なので dependencies ではなくこちら。ビルド成果物には入りません

入れます。

bash
$ npm install

確認: ls node_modules | wc -l で数百のディレクトリが出れば成功です。 戻し方: rm -rf node_modules package-lock.json で消して、npm install をやり直せます。

先に 5173番を開ける

新しいポートを使うので、また ufw に穴を開けます。(HTMLの回からずっと同じ手順です)

bash
$ sudo ufw allow 5173/tcp
$ sudo ufw status

5173/tcp の行が出れば準備完了です。開けずに進むと、次の起動は成功するのにブラウザは読み込み中のまま終わります。

npm run dev — --host を付けないと見えない

起動します。ここが一番つまずくところです。

bash
$ npm run dev -- --host 0.0.0.0
  VITE v7.0.0  ready in 312 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.226.50:5173/

--host 0.0.0.0 を付けないと、ホストのブラウザから見えません。

理由は Linux のネットワークの回 と nginx の回 で見た話と同じです。Vite の開発サーバーは、デフォルトで 127.0.0.1(自分自身)にだけ待ち受けます。 VM の中からしか繋がりません。

0.0.0.0 にすると全部のネットワークインターフェースで待ち受けるので、ホストの Windows から届きます。

確認します。VMの中で、

bash
$ ss -tlnp | grep 5173
LISTEN 0 511 0.0.0.0:5173 0.0.0.0:* users:(("node",pid=4821,fd=21))

0.0.0.0:5173 になっていれば外向きです。ここが 127.0.0.1:5173 なら --host が効いていません。

-- は何なのか。 npm run dev -- --host 0.0.0.0 の真ん中の -- は、「ここから先は npm ではなく、実行されるコマンド(vite)への引数だ」という区切りです。 付け忘れると --host を npm が食べてしまって、Vite に届きません。--host を書いたのに 127.0.0.1 のまま、という時はこれです。

ホストの Windows のブラウザで、表示された Network の URL(http://192.168.226.50:5173/)を開きます。Vite のロゴとカウンターボタンのページが出れば成功です。

繋がらないときの確認順は nginx の回と同じで、内側から1段ずつです。

  1. VMの中で curl -I http://localhost:5173/ → 200 が返るか(サーバー自体が動いているか)
  2. VMの中で ss -tlnp | grep 5173 → 0.0.0.0 か 127.0.0.1 か
  3. ホストで ping <VMのIP> → ネットワークが繋がっているか
  4. VMの中で sudo ufw status → ファイアウォールが塞いでいないか(塞いでいれば sudo ufw allow 5173/tcp)

止め方: ターミナルで Ctrl+C。

[スクリーンショット: 03_vite_dev起動.png] 左に VM のターミナル(Local/Network の2行が見えている状態)、右にホストのブラウザで開いた Vite の初期ページを並べて撮ってください。--host を付けた結果 Network 行に VM の IP が出ているのが分かる形で。


開発サーバーが速い理由

npm run dev の起動が 300ミリ秒くらいだったはずです。これは偶然ではありません。

昔のビルドツール(webpack など)の開発サーバーは、こうでした。

起動 → 全ファイルを読む → 依存を解決する → 全部まとめる → 変換する
→ メモリ上に完成品を置く → やっとブラウザに配れる

「配る前に、全部作る」です。ファイルが1000個あれば、1000個分の作業が終わるまで待ちます。大きなプロジェクトで起動に30秒〜数分というのは、これが理由です。

Vite は違います。

起動 → 待ち受けるだけ(何も作らない)
→ ブラウザが index.html を要求 → 返す
→ ブラウザが main.js を要求 → その1本だけ変換して返す
→ ブラウザが style.css を要求 → その1本だけ変換して返す

ブラウザが要求したファイルだけ、その場で変換して返す。

これができるのは、さっき確認した「ブラウザが import を理解できる」という前提があるからです。まとめて渡さなくても、ブラウザが必要なものを自分で順番に取りに来てくれる。 だからサーバー側で先に全部作っておく必要がない。

昔のやり方Vite の開発サーバー
起動時にやること全ファイルをバンドルほぼ何もしない
ブラウザに返すもの完成した1つの塊要求された1ファイルずつ
起動時間ファイル数に比例して増えるほぼ一定
1ファイル直したとき影響範囲を作り直すそのファイルだけ変換し直す

これを Network タブで確認できます。

ホストのブラウザで F12 → Network → JS で絞って再読み込みすると、main.js、counter.js、vite/client … といったファイルが個別に並びます。 バンドルされた1本ではありません。

注意: これは開発中だけの姿です。 「本番でもファイルが200個飛ぶのか」と心配になりますが、npm run build した本番用はちゃんとまとまります。 Vite は開発と本番で別々の仕組みを使い分けています。 開発は「速さ優先=まとめない」、本番は「配る効率優先=まとめる」。この使い分けが Vite の設計そのものです。

node_modules はどうしているのか。 ライブラリだけは例外で、初回起動時にまとめて事前変換(依存の事前バンドル)されます。 node_modules/.vite/ に置かれます。 ライブラリは滅多に変わらないうえにファイル数が異常に多い(1パッケージで数百ファイルということがある)ので、ここだけは先にまとめたほうが速いからです。変わるもの=そのつど、変わらないもの=先にまとめる、という切り分けです。


HMR — 保存すると画面が即座に変わる

開発サーバーを起動したまま、VMの中でファイルを編集します。VS Code のリモート接続で開いてもいいですし、nano でも構いません。

bash
$ nano src/style.css

先に CSS で試します。 src/style.css の中の色をどれでもいいので変えて、保存します。たとえば body の background-color を #ff0000 にしてみてください。

ホストのブラウザを見てください。

再読み込みしていないのに、画面が変わっています。 Console にはこう出ます。

[vite] css hot updated: /src/style.css

これが HMR(Hot Module Replacement)です。日本語だと「モジュールの動的差し替え」。

やっていることは、こうです。

  1. Vite の開発サーバーが、ファイルの変更を監視している
  2. 変更を検知したら、そのファイルだけ変換し直す
  3. WebSocket でブラウザに「このモジュールが変わった」と通知する
  4. ブラウザ側が、そのモジュールだけ差し替える

ページ全体の再読み込みではありません。 ここが重要です。

なぜ再読み込みでは駄目なのか。 再読み込みすると、画面の状態が全部リセットされます。 フォームに10項目入力していた、モーダルを3階層開いていた、スクロールを一番下まで下げていた。保存するたびに全部消えて、また同じ操作をやり直す。 HMR は状態を保ったままコードだけ入れ替えるので、この往復が消えます。開発中の体感が一番変わるのはここです。

JS を変えると、同じにはならない

今度は src/main.js の文字列を変えて保存してください。

[vite] page reload src/main.js

hot updated ではなく page reload です。ページ全体が読み込み直されています。

差し替えではなく、再読み込みに落ちています。 理由は、この Vanilla テンプレートの main.js が「自分が差し替わったとき何をすればいいか」(import.meta.hot.accept)を書いていないからです。Vite はどう差し替えれば安全か分からないので、安全側に倒してページごと読み直します。

変えたファイルConsole状態
src/style.css[vite] css hot updated保たれる(本当のHMR)
src/main.js[vite] page reloadリセットされる

「HMR が効かない」の多くは、壊れているのではなくこれです。 React や Vue は「コンポーネント単位で差し替える」というルールが決まっているので、JSでもHMRがよく効きます。HMR の効きはフレームワーク次第、と覚えておいてください。

[スクリーンショット: 04_HMR.png] 左にエディタ(変更した style.css)、右にホストのブラウザ(色が変わった画面)を並べて撮ってください。ブラウザの Console に [vite] css hot updated: /src/style.css のログが出ている形にすると分かりやすいです。


npm run build — dist/ の中身を見る

ここが冒頭の疑問に対する答えです。

一度 Ctrl+C で開発サーバーを止めて、VMの中で、

bash
$ npm run build
vite v7.0.0 building for production...
✓ 9 modules transformed.
dist/index.html                0.46 kB │ gzip: 0.30 kB
dist/assets/index-DiwrgTda.css 1.24 kB │ gzip: 0.65 kB
dist/assets/index-C0sCkigK.js  1.86 kB │ gzip: 0.98 kB
✓ built in 284ms

見ます。

bash
$ ls -la dist/
$ ls -la dist/assets/
dist/
-rw-r--r--  index.html
drwxr-xr-x  assets
-rw-r--r--  vite.svg

dist/assets/
-rw-r--r--  index-C0sCkigK.js
-rw-r--r--  index-DiwrgTda.css
-rw-r--r--  javascript-CnrDzTsG.svg

src/ にあったファイルの名前が、1つも残っていません。

中を見ます。

bash
$ head -c 300 dist/assets/index-C0sCkigK.js
(function(){const t=document.createElement("link").relList;if(t&&t.supports&&t.supports("modulepreload"))return;for(const o of document.querySelectorAll('link[rel="modulepreload"]'))r(o);...

改行がありません。変数名が1文字です。 さっき見た minify そのものです。

index.html も見ます。

bash
$ cat dist/index.html
<!doctype html><html lang="ja"><head><meta charset="UTF-8"/><link rel="icon" type="image/svg+xml" href="/vite.svg"/><title>Vite App</title><script type="module" crossorigin src="/assets/index-C0sCkigK.js"></script><link rel="stylesheet" crossorigin href="/assets/index-DiwrgTda.css"></head><body><div id="app"></div></body></html>

元の index.html に書いてあった <script type="module" src="/src/main.js"> が、ビルド後のファイル名に書き換わっています。

これが npm run build の全体像です。

やったこと結果
トランスパイル新しい構文が、指定した対象ブラウザで動く形に
バンドルsrc/ の複数ファイルが assets/index-xxx.js 1本に
minify改行なし・変数名1文字
tree shaking使っていない export は入っていない
HTML の書き換え<script> の参照先が新しいファイル名に

[スクリーンショット: 05_dist_中身.png] ls -la dist/ dist/assets/ の出力と、npm run build のログ(ファイルサイズが並んでいるところ)が入るように撮ってください。ハッシュ付きのファイル名がはっきり読めるようにしてください。

戻し方: rm -rf dist で消せます。npm run build すればまた作られます。dist/ は「毎回作り直せる、捨てていいもの」です。この感覚が後の .gitignore の話に繋がります。

ファイル名のハッシュは何なのか

index-C0sCkigK.js の C0sCkigK の部分です。これは飾りではありません。

中身から計算された値です。中身が1バイトでも変われば、この文字列は変わります。

なぜそんなことをするのか。キャッシュ対策です。

ブラウザは、一度読んだファイルを保存して使い回します(キャッシュ)。速くていいのですが、更新したときに困ります。

ファイル名が main.js で固定だった場合:

1回目  main.js を取得 → キャッシュに保存
(あなたがバグを直して再デプロイ)
2回目  main.js → 「持ってるからそれでいいや」 → 古いコードのまま

これが「自分のブラウザでは直っているのに、ユーザーからは直っていないと言われる」の正体です。

ハッシュ付きの場合:

1回目  index-C0sCkigK.js を取得 → キャッシュに保存
(あなたがバグを直して再ビルド → 名前が index-Xy9pQr2m.js に変わる)
2回目  index.html が新しい名前を指している → 持っていない → 取りに行く

中身が変わればファイル名が変わるので、キャッシュが自動的に無効になります。

そして逆側も重要です。中身が変わらなければ名前も変わらないので、キャッシュがそのまま効き続けます。

だからサーバー側の設定はこうなります。 – index.html … キャッシュさせない(毎回取りに来させる。ここが新しいファイル名を教える入口だから) – assets/ の中身 … 思いっきりキャッシュさせる(名前が変われば別ファイル扱いなので、古いものが誤って使われることがない)

ハッシュ付きファイル名は、この設定を安全に成立させるための仕組みです。

確認してみます。VMの中で src/main.js を少しだけ書き換えて、

bash
$ npm run build && ls dist/assets/

JS のファイル名が変わっているはずです。CSS を触っていなければ、CSS の名前は変わっていません。 ここが確認できると、ハッシュが「中身から計算されている」ことが腑に落ちます。


npm run preview — 本番ビルドを確認する

dist/ ができたら、本番と同じ形で動くかを確認します。

このポートも開けます。

bash
$ sudo ufw allow 4173/tcp
bash
$ npm run preview -- --host 0.0.0.0
  ➜  Local:   http://localhost:4173/
  ➜  Network: http://192.168.226.50:4173/

ポートが 5173 ではなく 4173 です。開発サーバーと混同しないよう分けてあります。ここでも --host 0.0.0.0 は必須です。

ホストのブラウザで開いて、F12 → Network を見てください。

開発サーバーのときと違って、JS が1本しか来ていません。 バンドルされた結果です。

npm run dev で動くのに npm run preview で壊れる、はよくあります。 開発と本番で仕組みが違うからです。開発中は変換していなかったものが本番では変換される、開発中は使われていた import が tree shaking で落ちる、など。 「動いた」と言う前に、必ず npm run build → npm run preview まで通してください。 ここを飛ばして本番で気づく、というのが一番痛いパターンです。

止め方は Ctrl+C です。


dist/ は、ただの静的ファイル

ここで一番腑に落ちてほしいことがあります。

ビルド成果物は、ただの静的ファイルです。

HTML と CSS と JS と画像。それだけです。Node.js は要りません。Vite も要りません。Webサーバーが返すだけでいい。

証明します。Vite も npm も一切使わずに dist/ を配ってみます。使うのは、HTMLの回からずっと使っている Python の簡易サーバーです。VMの中で、

bash
$ cd ~/vite-demo/dist
$ python3 -m http.server 8000 --bind 0.0.0.0

ホストのブラウザで http://192.168.226.50:8000/ を開きます(IPは自分の値に)。Vite のページがそのまま出ます。

いま動いているのは Python です。 Node.js のプロセスは1つも起きていません。別のターミナルで確かめられます。

bash
$ ps aux | grep -c "[n]ode"
0

これが分かると、公開の話が急に簡単になります。 ビルド成果物は静的ファイルなので、nginx でも、S3 でも、GitHub Pages でも、Netlify でも、置けば動きます。 「フロントエンドのデプロイ」と言われると難しそうですが、やっているのは dist/ をどこかに置くことだけです。

確認できたら Ctrl+C で止めてください。

本物のWebサーバーで配るのは次の段階です。 Python の簡易サーバーは練習用で、本番では使いません(性能や安全性の面で本番向けではない、といった割り切りがあります)。 第6段階の nginx の回で、この dist/ をそのまま nginx に載せ替えます。 ~/vite-demo/ は消さずに残しておいてください。

1つだけ注意があります。 今回のような1ページだけのサイトなら問題ありませんが、ページ内でURLを切り替えるタイプのアプリ(SPA)を配ると、/about に直接アクセスしたときに 404 になります。サーバーは「about というファイルを探して、無い」と正しく答えているだけです。JS が中でURLを切り替えているだけで、そのファイルは実在しないからです。 対処は nginx なら try_files $uri $uri/ /index.html; で見つからなければ index.html を返すようにすること。第4段階で扱います。今は「そういう罠がある」とだけ覚えておいてください。


静的ファイルなので、置き場所は Vite の開発サーバーである必要はなく、普通のレンタルサーバーに置いても動きます。練習用に外から見える場所へ置くなら、スターレンタルサーバーのライトプランが 2026年11月時点で 3 ヶ月 495 円〜36 ヶ月 253 円(税込・月額換算、契約期間分の一括前払い)です。ライトは自動バックアップの対象外なので、dist/ をソースからいつでも作り直せる前提で使うのが向いています。

dist/ と node_modules/ は Git に入れない

Vite が作った .gitignore を見てください。VMの中で、

bash
$ cat .gitignore
node_modules
dist
dist-ssr
*.local
.vscode/*
!.vscode/extensions.json
.DS_Store

node_modules と dist が最初から入っています。

理由は同じで、どちらも「作り直せるもの」だからです。

作り直す方法Git に入れるとどうなるか
node_modules/npm install数万ファイル。 クローンが遅くなり、差分が読めなくなる
dist/npm run build毎回全部が差分になる。 minify されているので中身が読めない

Git に入れるのは「人間が書いた、作り直せないもの」だけです。

  • 入れる: src/、index.html、package.json、package-lock.json、設定ファイル
  • 入れない: node_modules/、dist/、.env(秘密情報)

package-lock.json は入れます。 npm の回 で見た通り、これは「実際に入ったバージョンの記録」です。これが無いと、別の人が npm install したときに違うバージョンが入り、「自分の環境では動く」が発生します。 生成物だけど入れる、という唯一の例外だと思ってください。

もし間違えて追加してしまった場合は、

bash
$ git rm -r --cached node_modules dist

--cached を付けると、Git の管理からだけ外れて、ファイル自体は消えません。 付け忘れると本当に消えます。ここは気をつけてください。


ソースマップ — ビルド後のコードをデバッグする地図

冒頭の話に戻ります。エラーが index-C0sCkigK.js の 1行目 4823文字目。これでは調べようがありません。

これを解決するのがソースマップです。

ソースマップは「ビルド後のこの位置は、元のファイルのこの行に対応する」という対応表です。

index-C0sCkigK.js の 1行目 4823文字目
        ↓ ソースマップを引くと
src/utils/format.js の 12行目 5文字目

元のコードの位置を教える地図、と考えれば正確です。

開発者ツールがこれを読むと、Sources タブに、ビルド前のファイルがそのまま表示されます。 src/main.js も src/counter.js も、自分が書いた形のまま出てきます。ブレークポイントも元のコードに置けます。

「minify したのに、なぜか開発者ツールで元のコードが見えている」のは、ソースマップが効いているからです。魔法ではありません。

Vite では、本番ビルドのソースマップはデフォルトでは出ません。VMの中で vite.config.js を作って有効にします。

bash
$ cat > vite.config.js <<'EOF'
  export default {
    build: {
      sourcemap: true
    }
  };
  EOF
bash
$ npm run build && ls -la dist/assets/
-rw-r--r--  index-C0sCkigK.js
-rw-r--r--  index-C0sCkigK.js.map     ← これ
-rw-r--r--  index-DiwrgTda.css

.map が増えています。 .js の末尾には、こう書かれます。

bash
$ tail -c 60 dist/assets/index-C0sCkigK.js
//# sourceMappingURL=index-C0sCkigK.js.map

「地図はここにあります」というメモです。開発者ツールはこれを見て .map を取りに行きます。

npm run preview -- --host 0.0.0.0 で確認して、ホストのブラウザの F12 → Sources タブを見てください。src/ のファイルが見えるようになっています。

戻し方: rm vite.config.js && npm run build でソースマップなしに戻せます。

本番にソースマップを置くべきか。賛否があります。 – 置く: エラー監視ツールが元の行番号を教えてくれる。障害対応が段違いに速い – 置かない: 元のコードが誰でも読める。コメントも変数名も全部

折衷案として、.map はビルドするが公開ディレクトリには置かず、エラー監視ツールにだけ渡すやり方が広く使われています。少なくとも「知らないうちに .map が公開されている」状態は避けてください。


ビルドツールの系譜 — webpack から Vite まで

調べていると名前が大量に出てきて混乱します。整理します。

ツール出た背景一言でいうと今の立ち位置
webpack2012〜何でもできる代わりに、設定が長い。 画像もCSSも全部モジュールとして扱う発想を作った既存プロジェクトで大量に現役。 新規で選ぶ理由は減った
Parcel2017〜設定ファイルなしで動く。 webpack の設定地獄への反動手軽。使われてはいるが主流ではない
Rollup2015〜ライブラリを作るための道具。 tree shaking を広めた立役者健在。Vite の本番ビルドが内部で使っている
esbuild2020〜Go で書かれていて、とにかく速い(10〜100倍)。機能は絞ってある健在。Vite の依存の事前バンドルが内部で使っている
Vite2020〜開発は「まとめない」、本番は Rollup でまとめる。 使い分けが設計思想今の事実上の標準
Turbopack2022〜Rust 製。webpack の作者が作っている次世代版Next.js 中心。 単独で選ぶ場面はまだ少ない

流れとしては、こうです。

  1. webpack が「何でもできる」を実現した。 代わりに設定ファイルが数百行になった
  2. Parcel が「設定なし」で反撃した。 でも細かい調整が効かない
  3. esbuild が「言語を変えれば速い」を証明した。 JavaScript で書かれたツールを JavaScript で動かしていたのが遅さの原因だった
  4. Vite が「そもそも開発中はまとめなくていい」と発想を変えた。 ES モジュールがブラウザで使えるようになったから成立した

今から始めるなら Vite

理由は3つです。

  1. 設定ファイルを書かずに始められる。 今回 vite.config.js を書いたのはソースマップの1箇所だけでした
  2. 開発サーバーが速い。 これは「快適」というより学習効率の問題です。保存から確認までが1秒なら試行錯誤の回数が桁で変わります
  3. 中身が既存の実績あるツール。 開発は esbuild、本番は Rollup。Vite は独自実装ではなく、良いものの組み合わせです

ただし「webpack を知らなくていい」わけではありません。 既存プロジェクトに入れば webpack.config.js が待っています。 でも最初に学ぶ道具としては Viteです。やっていること(4つの作業)は同じなので、Vite で仕組みを理解しておけば webpack の設定も「どの作業の設定なのか」として読めます。道具が変わっても、目的は変わりません。


つまずいたところ

自分が実際に詰まった箇所を残しておきます。

npm run dev は動くのに、ホストのブラウザから繋がらない → --host 0.0.0.0 の付け忘れです。9割これです。ss -tlnp | grep 5173 で 127.0.0.1 になっていないか見てください。

--host を付けたのに 127.0.0.1 のまま → -- の付け忘れです。npm run dev --host 0.0.0.0 ではなく npm run dev -- --host 0.0.0.0 です。

dist/index.html をダブルクリックで開いたら真っ白 → file:// では ES モジュールが CORS で読めません。npm run preview か nginx 経由で開いてください。

ビルドは通るのに npm run preview で真っ白、Console に 404 → サブディレクトリに置いたときに起きます。dist/index.html の中の src="/assets/..." がサイトのルートからの絶対パスだからです。サブディレクトリに置くなら vite.config.js に base: "/サブパス/" が要ります。

修正したのに、ブラウザで古い画面が出る → キャッシュです。Ctrl+Shift+R を試してください。それでも駄目ならnpm run build を打ち忘れて、古い dist/ を配っている可能性があります。

npm run build が「node_modules が無い」で失敗する → cd vite-demo を忘れて、1つ上のディレクトリで打っています。 pwd で確認してください。


後片づけ —— 開けたポートを閉じる

この記事で開けた 5173番と 4173番は、もう使いません。閉じます。

bash
$ sudo ufw delete allow 5173/tcp
$ sudo ufw delete allow 4173/tcp
$ sudo ufw status
Status: active

To                         Action      From
--                         ------      ----
22/tcp                     ALLOW       Anywhere
8000/tcp                   ALLOW       Anywhere

8000番はここで閉じても構いません。 次の第6段階では nginx が使う 80番に移るためです。素のHTMLをもう触らないなら、

bash
$ sudo ufw delete allow 8000/tcp

「使い終わったら閉じる」を習慣にしてください。 開けっぱなしのポートは、そこで何かが待ち受けていれば外から叩かれます。 第2段階から数えて、開けたのは 8000 / 8001 / 5173 / 4173 の4つでした。sudo ufw status に、いま自分が説明できない行が無いかを、ときどき見てください。

プロジェクトごと消したいときは:

bash
$ rm -rf ~/vite-demo

ただし次の nginx の回で dist/ を使うので、それまでは残しておくことをおすすめします。


まとめ

  • 「ビルド」は1つの作業ではなく、4つの別々の作業の総称。 トランスパイル・バンドル・minify・tree shaking。それぞれ別の困りごとに対する別の答え
  • トランスパイルは「人間が書きたい書き方」と「ブラウザが読める書き方」の翻訳。TypeScript も JSX も、新しい構文を古いブラウザ向けに直すのも、全部これ
  • バンドルは通信回数を減らすため。ファイルが8個ならリクエストは8回、という DNS・HTTPの回 で数えた話がそのまま理由になっている
  • minify は空白・改行・変数名を削るだけで動作は変わらない。そして、これがデバッグを不可能にしている犯人でもある
  • tree shaking が成立するのは、import が「何を使うか」を実行前に読み取れる形だから。ES モジュールの性質に乗っている
  • ビルドが無かった頃の困りごとは3つ。 グローバル汚染・読み込み順・依存の管理。ES モジュールが前の2つを、npm が3つ目を解決した
  • ブラウザは今 import を理解できる(<script type="module">)。だからバンドルは必須ではなくなった。 それでも本番でまとめるのは、通信回数・依存の連鎖・パッケージ名の解決という別の理由が残っているから
  • Vite の開発サーバーが速いのは、最適化が上手いからではなく「まとめていないから」。 ブラウザが要求したファイルだけ、その場で変換して返している
  • npm run dev は --host 0.0.0.0 を付けないと、VMの外から見えない。 さらに -- を忘れると npm が引数を食べる
  • dist/ のファイル名に付くハッシュはキャッシュ対策。 中身が変われば名前が変わるのでキャッシュが自動で切れ、変わらなければキャッシュが効き続ける
  • ビルド成果物はただの静的ファイル。 どこかに置いて配るだけで公開できる。Node.js も Vite も本番には要らない
  • node_modules/ と dist/ は Git に入れない。 どちらも作り直せるから。ただし package-lock.json は生成物だが入れる
  • ソースマップは「ビルド後のこの位置は、元のこの行」という対応表。 開発者ツールで元のコードが見えるのはこれのおかげで、魔法ではない
  • 今から始めるなら Vite。 設定なしで始まり、開発が速く、中身は実績のある esbuild と Rollup の組み合わせ

第3段階でできるようになったこと

これで第3段階(プログラミング)は終わりです。 振り返ります。

回できるようになったこと
JavaScript の基本変数・型・関数を書ける。== と === の罠を知っている
DOM 操作ページの中身を JavaScript から書き換えられる
非同期処理サーバーからデータを取ってきて表示できる。await の意味が分かる
npm とパッケージ管理他人が書いたコードを取り込める。package.json が読める
ビルドツール(この回)npm run build の中で何が起きているか説明できる

最初は「ボタンを押しても何も起きないページ」でした。 今は、データを取ってきて、画面を書き換えて、本番用にビルドして、Webサーバーで公開するところまで一本の線で繋がっています。

そして、ここまで一度もフレームワークを使っていません。 これは意図的です。フレームワークが何を代わりにやってくれているのかを判断するには、代わりにやってもらう前の姿を知っている必要があるからです。

第3段階でやったことの意味は、「動かせるようになった」ことより「壊れたときに、どこを見ればいいか分かるようになった」ことのほうが大きいと思っています。dist/ の中の1行しかないファイルを見ても、もう怖くありません。


参考リンク


この段階の確認

【第3段階】プログラミング は、ここで終わりです。 次に進む前に、答えを見ずに試してください。

読み終えた直後は、たいてい「分かった気」になっています。 手が動くかどうかは別です。

説明できますか

  1. "1" == 1 が true になるのはなぜか。ではどう書けばよいか
  2. 「1行目が書けない」ときに、最初にやることは何か。コードを書くことではありません
  3. AIが書いたコードが「動いた」ことは、何の証明になっていないのか

手が動きますか

  • 大きいお題を、日本語の擬似コード3行に割ってから書き始める
  • 書いた関数を、境界(0件・1件・ちょうど)で試す
  • 自分が書いたコードを読み返し、名前だけを直して動きが変わらないことを確かめる
  • DOM を書き換えて、画面を実際に変える

1つでも詰まったら、飛ばした回があります。 そこへ戻ってください。戻るのは後退ではありません。 戻り先の目安: JavaScriptの基本の回 / 問題の分け方の回 / 読めるコードの回 / AIの検算の回

全部答えられたなら、次の段階へ進んでください。


次に読む

この記事は 【第3段階】プログラミング の 7 / 7 本目です。

記事
← 前の記事fetchの結果が undefined — 非同期処理の基本
→ 次の記事手でDOMを書き換えるのをやめる — React・Vue・Svelte

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

Frontend›Build Tools
  • Module Bundlers(Vite / webpack)
  • Task Runners
  • Linters and Formatters の前提

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次