Kazuki's Blog

ITは活用する道具である！

📚 目次 | Contents of Kazuki's Blog

Common
🕰 4年ぶりの更新です。ブログ、再始動します！

ブログ、再始動します！インクを新しく満たして、また書き始めました。

✨🕰 今後ブログで取り上げるトピックについて

具体的な発信内容について整理です。

🖥 PCの設定や活用方法
📱 ガジェットの設定や活用方法

🔍 ITを活用した情報収集や活用方法

  • 今後にご期待を

📓 ITとアナログの関係

🚀 チャレンジしていること



📅 最終更新: 2026年6月24日

Vue.js×Markdownブログを作ろう（番外編8：謎の巨大フォルダ「node_modules」の正体と、正しい付き合い方）

はじめに

ファイル構造を徹底解剖していく番外編シリーズ、プロジェクトのルート直下に鎮座する node_modules フォルダ です。

エディタで開こうとするとファイルが多すぎてフリーズしそうになったり、フォルダのプロパティを見ると数万個のファイルがあり、一体何が入っているの？という疑問を今回は解消していきたいと思います。

1. node_modules ディレクトリを一言で言うと？

node_modules は、一言で言えば 「世界中のエンジニアが作った外部ライブラリ（部品）の巨大な倉庫」 です。

私たちがブログを作る際、package.json に「Vue」や、Markdownを変換する「marked」といったライブラリを使いたいと記述しました。そして npm install というコマンドを実行しましたよね。

そのコマンドを叩いた瞬間に、インターネット上の共有スペース（npmレジストリ）から、必要なライブラリの本体データが自動的にダウンロードされ、この node_modules という倉庫の中にすべて詰め込まれたのです。

2. なぜこんなにファイル数が多くて重いの？

「使っているライブラリはVueとmarkedくらいなのに、なぜ数万個もファイルがあるの？」と不思議に思いますよね。

理由は、「ライブラリのライブラリ（依存関係）」にあります。

たとえば、私たちが導入した「marked」というライブラリも、実は別の誰かが作った小さな便利ツール（部品）を何個も組み合わせて作られています。そして、その小さな便利ツールも、さらに別の小さな部品を使っている…というように、Webの世界は無数の部品が数珠つなぎになって成り立っています。

npm install を実行すると、npmはそれらの「孫ライブラリ」や「ひ孫ライブラリ」までをすべて自動で計算し、1つのバグもなく動くように芋づる式でダウンロードしてくれます。その結果、気付けば node_modules の中は膨大なファイルで埋め尽くされ、数万ファイル、数百メガバイトという巨大な倉庫になるのです。

3. 開発者が絶対に知っておくべき「3つの掟」

この node_modules はシステムが自動管理する場所なので、私たちが中身のコードを書き換えることはありません。しかし、開発を進める上で絶対に破ってはいけない超重要なルールが3つあります。

掟①：絶対にGitHubにプッシュ（コミット）してはいけない！

これがおそらく、初心者の方が一番やってしまいがちな失敗です。 node_modules は重すぎるため、そのままGitHubにアップロードしようとすると、プッシュがいつまでも終わらなかったり、容量制限でエラーになったりします。

そのため、プロジェクト内にある .gitignore というファイルに、あらかじめ以下のような記述をして、Gitの監視対象から外しておくのが鉄則です。

# .gitignore の中身（Gitに無視させるリスト）
node_modules/
dist/

「GitHubに上げなかったら、Cloudflare Pagesや他の人がコードをダウンロードしたときに動かなくなるのでは？」と思うかもしれません。 でも大丈夫。手元にはお買い物リストである package.json と package-lock.json が残っています。これさえGitHubに上がっていれば、それを受け取った側が各自の環境で npm install（または npm ci）を叩くだけで、いつでも全く同じ node_modules 倉庫をその場で一瞬で再現できるからです。

掟②：中身を直接書き換えてはいけない！

「ライブラリの動きをちょっと変えたいから」と、node_modules/ の中にあるコードを直接手動で修正してはいけません。 なぜなら、次に npm install を実行したときや、Cloudflare Pagesで自動ビルドが走るときに、インターネットからダウンロードされたまっさらなデータで丸ごと上書きされ、あなたの修正は完全に消え去ってしまうからです。

掟③：調子が悪くなったら「フォルダごとゴミ箱へポイ」でOK！

開発を続けていると、たまにライブラリのバージョンが競合して「どうしてもビルドエラーが直らない！」という謎の不調に陥ることがあります。

そんなときの最強の裏技が、「node_modules フォルダを丸ごと削除して、もう一度 npm install し直す」 という方法です。 前述の通り、このフォルダはいつでもレシピ（package.json）から完全復元できるため、いつ消しても問題ありません。一度倉庫を空っぽにして、一から綺麗にダウンロードし直すことで、嘘のようにエラーが解決することはよくあります。

4. プロジェクト全体の流れの「完全な総まとめ」

これで、ブログプロジェクト内にある主要な登場人物（ファイル・フォルダ）の解説がすべて出揃いました！ これまでバラバラだった知識を、1つの綺麗なストーリーとして繋げてみましょう。

  1. package.json に「Vueやmarkedが欲しい」と希望を書く。
  2. npm install を叩くと、世界中から部品が集まり node_modules（巨大倉庫）が作られる。
  3. tsconfig や env.d.ts のルールに従って、TypeScriptが安全にコードを監視する。
  4. 私たちが src/App.vue に魂を込め、src/assets/content/ に記事（Markdown）を書く。
  5. vite.config.ts の設定を元にViteが倉庫（node_modules）と私たちのコードを最高にブレンドする。
  6. npm run build を叩くと、超軽量な本番用成果物 dist ディレクトリが出力される。
  7. Cloudflare Pages が dist の中身だけを世界中に配信する。

おわりに

最初はフォルダを開くだけで圧倒されていた無数のファイル群も、こうして1つずつの「役割」と「全体の繋がり」が分かれば、すべてが必然的にそこに存在していることが見えてきたはずです。

Vue.js×Markdownブログを作ろう（番外編7：最終成果物「dist」ディレクトリの正体とビルドの裏側）

はじめに

日々の開発では src/ フォルダの中身ばかりを触っていますが、私たちが npm run build というコマンドを叩いたとき、プロジェクトのルート直下に突如として現れるのがこの dist フォルダです。

「ビルドすると作られるフォルダだとは知っているけれど、中身はどうなっているの？」「なぜわざわざこれを作る必要があるの？」という疑問を、今回は解消していきましょう。私たちが書いたコードが世界中に配信される「最後の仕組み」がここに詰まっています。

1. dist ディレクトリを一言で言うと？

dist は 「Distribution（配布・配信）」 の略で、一言で言えば 「本番環境にそのまま配れる完成済みのWebサイトパッケージ」 です。

私たちが開発中に書いているコード（VueのSFCやTypeScript、生のMarkdownファイル）は、実はブラウザ（ChromeやSafariなど）が直接読んでも理解できません。

ブラウザが100%理解できる言語は、標準的な 「HTML」「CSS」「JavaScript」 の3つだけです。 そのため、開発用のソースコードをブラウザが読める形へと「翻訳・最適化」し、1つのパッケージとしてまとめた出力先が dist フォルダなのです。

2. dist ディレクトリの中身をのぞいてみよう

ビルドが成功した後の dist フォルダの構造は、驚くほどシンプルになっています。

vue-md-site/dist/
├── index.html             # 完全に翻訳された唯一のHTML
├── favicon.ico            # サイトのアイコン
├── images/                # 画像などの静的ファイル
└── assets/                # 軽量化されたCSSとJavaScriptの塊
    ├── index-BBEYnoMf.css
    ├── index-Dtf6P7_P.js
    ├── Vue3入門-wCZpJ_e-.js
    └── コーヒー淹れ方-Ciwv9eb-.js

① 1枚の index.html

ルートにあった index.html とは異なり、ビルド後の index.html は、最適化されたCSSやJavaScriptを読み込むための正しいリンクが自動で埋め込まれた「本番専用のHTML」にアップデートされています。

② assets/ フォルダ（暗号のようなファイル名）

中を見ると、index-BBEYnoMf.css や Vue3入門-wCZpJ_e-.js のように、ファイル名の後ろにランダムな英数字（ハッシュ値）がついています。

これはViteが施してくれた非常に賢い仕組み（キャッシュ対策）です。 もしブログを更新して再ビルドすると、この英数字が別のものに変わります。これにより、ブラウザが「あ、古いファイル（キャッシュ）じゃなくて、新しいファイルを読み込まなきゃ！」と自動で判断してくれるため、訪問者に常に最新の記事を届けることができます。

3. ビルドの裏側でViteがやってくれていること

npm run build を叩いたとき、ビルドツール（Vite）は単にファイルをコピーしているわけではありません。裏側で以下のような「超高度な最適化」を一瞬で行っています。

① コンパイル（翻訳）

.vue のファイルを分解し、TypeScriptを純粋なJavaScriptへ、MarkdownをHTML文字列へと、ブラウザが理解できる標準言語へ完璧に翻訳します。

② バンドル（荷まとめ）

開発中は細かく分かれていた何十個ものプログラムファイルや、node_modules から読み込んだ外部ライブラリ（Vue本体やmarkedなど）を、ブラウザが効率よく読み込めるように数個のファイルへと綺麗にまとめ上げます。

③ ミニファイ（軽量化）

人間が読みやすいために空けていた「改行」や「スペース」、「コメントアウト」をすべて削除し、変数名を a や b のように極限まで短く書き換えます。中身をギチギチに詰め込んでファイルサイズを最小限にすることで、スマホなどの弱い回線でもブログが一瞬で開くようになります。

4. Cloudflare Pagesとの関係

後編の記事で、Cloudflare Pagesの設定画面に以下のような入力をしました。

  • ビルドコマンド: npm run build
  • 出力ディレクトリ: dist

この設定の意図が、もう完全に繋がったのではないでしょうか？

Cloudflare Pagesは、GitHubからコードを受け取ったあと、内部で npm run build を実行してこの dist フォルダを自動生成します。そして、「この dist フォルダの中身だけ」を世界中のエッジサーバーに配置して公開しているのです。

そのため、開発用のファイル（src/）や設定ファイル（tsconfig等）は、本番のWebサイト上には1枚も公開されず、安全に守られています。

おわりに

普段何気なく実行している npm run build の裏側では、Viteが私たちの書いた大切な記事やコードを、世界中の読者が最も速く、最も綺麗に読める形へと職人技のように仕立て上げてくれていたのです。

  • package.json で材料を集め、
  • vite.config.ts と tsconfig でルールを教え、
  • App.vue で魂を込め、
  • dist という最高の料理を完成させて、Cloudflare Pages で世界に配る。

この一連の流れが理解できれば、あなたも立派なモダンフロントエンド開発者の仲間入りです。 土台の仕組みを完璧にマスターしたあなたのブログは、これからどんなカスタマイズにも耐えられる強いサイトになりました。次回からは、もっと新しい機能やデザインをどんどん追加していきましょう。

ブクログ書籍情報の特定カラム一括更新時の考慮事項

はじめに

皆さんはブクログで登録した書籍の「保管場所」や「整理用の分類」をどのように管理していますか？私は本棚の書籍が実際にどこに保管されているかを分かりやすく分類するために、ブクログの「タグ」機能を活用することにしました。

しかし、いざ整理を始めようとしたところ、タグがブランク（未設定）の書籍が大量にあることに気づきました。さらに不便なことに、ブクログのWeb版やアプリでは「タグがブランクの書籍のみを抽出する」というフィルター設定ができない仕様になっています。

そこで、タグがブランクの書籍に一括で "NA" という初期タグを付与し、後から管理しやすくしようと考えました。今回は、そのために行った「データのエクスポート → CSV編集 → 再インポート」による一括更新の手順と、その過程で見えてきた重要な考慮事項（落とし穴）についてまとめます。

1. 背景：やりたかったこととブクログの仕様

今回の目的は、タグが空欄の書籍データに対して一括で "NA" を書き込むことです。 ブクログにはCSVを用いたデータの「エクスポート」と「インポート（まとめて登録）」機能があるため、以下の手順で簡単に実現できると考えました。

  1. 現在の本棚データをCSVでエクスポートする
  2. Excelやテキストエディタで開き、タグが空欄の行に "NA" を入力する
  3. 編集したCSVを再度インポートする

しかし、ここでブクログの仕様による大きな壁にぶつかりました。

既存書籍は「上書き」されず「スキップ」される

ブクログのインポート機能は、同一の書籍（ISBNやアイテムIDが同じもの）がすでに本棚に存在する場合、二重登録を防ぐためにその行を自動的に「スキップ」する仕様になっています。

つまり、CSVを編集してそのままインポートしても、既存の書籍データが上書き更新されることはありません。情報を一括更新したい場合は、「一度本棚のデータを削除し、編集後のCSVで入れ替える」というステップが必要になります。

2. 特定カラムを一括更新するための正しい手順

上記の仕様を踏まえ、以下の手順で一括更新を進めました。

  1. 現在のデータのバックアップ（エクスポート） 万が一に備え、最新の本棚データをCSV形式でエクスポートし、手元に大切に保管します。
  2. CSVファイルの編集 エクスポートしたCSVファイルを編集します。今回はタグがブランクの列を見つけ、一括で "NA" を入力しました。
  3. ブクログ上のデータを削除 ブクログの「設定」＞「まとめて削除」から、更新対象の書籍（または本棚全体）をいったん削除します。※手元に編集済みのCSVが保存されていることを必ず確認してください。
  4. 編集したCSVのインポート 「設定」＞「まとめて登録」＞「CSV登録」から、編集済みのCSVファイルをアップロードします。

これで一発で綺麗に更新されるはずでしたが、インポート時にいくつかのエラーに直面しました。

3. インポート時に発生したエラーと考慮事項

CSVをインポートした際、いくつかの行で「〇行目のアイテムが見つかりませんでした」というエラーが発生しました。一括更新を行う上で、以下の2点は特に注意すべき考慮事項です。

1. 洋書や古い書籍が「見つからない」エラーになる

ブクログのCSVインポートは、ファイル内の「ISBN」や「ASIN」を元に、Amazonなどの外部データベースへ情報を照会する仕組みです。 そのため、以下のようなアイテムはデータベース上でヒットせず、インポートエラーになります。

  • Amazon等での取り扱いが終了・ページが削除された古い書籍や限定版ソフト
  • 海外のデータベースにしか存在しない洋書、CD、教材

今回エラーになった行を抽出したところ、やはり洋書や海外の学習教材が多く含まれていました。これらはCSV一括インポートが使えないため、エラー行だけを別出しして後から手動で検索して登録し直す必要があります。

2. オリジナルアイテムは一括インポートできない

自分でタイトルや画像を設定して登録した「オリジナルアイテム」は、そもそもAmazonなどの外部データベースにデータが存在しません。そのため、CSVファイルを使ってオリジナルアイテムを一括インポート（復活）することはできないという仕様上の制限があります。

また、過去に登録したオリジナルアイテムのマスターデータがブクログ内に残っている場合でも、単純に編集画面を開いて「更新」ボタンを押すだけでは本棚に再登録（復活）できない挙動を確認しました。

オリジナルアイテムを本棚に復元する方法

もしオリジナルアイテムを本棚に戻したい場合は、以下のいずれかの手順を踏む必要があります。

  • 方法A（詳細ページから登録）: 「登録済みのアイテム」一覧からタイトルをクリックし、画面最上部のパンくずリストから「作品詳細ページ」に移動して、そこから改めて「本棚に登録」ボタン（読書状況の選択）を押す。
  • 方法B（作り直し）: 紐付けがおかしくなっている場合は、一度そのオリジナルアイテムのマスターデータを削除し、最初から手動で「オリジナルアイテム登録」をやり直す。

おわりに

今回はブクログの書籍情報（タグ）を一括更新する際の手順と、インポート時の制限についてご紹介しました。

CSVを使った一括更新は非常に強力ですが、「既存データの上書きはできない（削除が必要）」「洋書やオリジナルアイテムはインポートエラーになる」というトラップがあります。特にオリジナルアイテムや絶版の本を多く本棚に入れている方は、全削除を伴う一括更新を行う前に、手動でのリカバリにどれくらい手間がかかるかを事前に見積もっておくことを強くおすすめします（私の場合はエラーが29件だったため、手動コピペでリカバリできる範疇でした）。

本棚の整理やタグの一括管理を検討している方の参考になれば幸いです。

Google API(Books API)を作成し、ObsidianのBooks SearchコミュニティプラグインにAPIキーを設定する

はじめに

Obsidianを使って読書ノートや日々の記録を管理している方も多いのではないでしょうか。

Obsidianのコミュニティプラグインである「Book Search」は、本のタイトルやISBNを入力するだけで、著者名や出版、カバー画像などの書誌情報を自動で取得してくれる非常に便利なプラグインです。

デフォルトの状態でも検索は可能ですが、Google Books APIを独自に取得して設定することで、検索の安定性や速度が向上し、より快適に読書ノートを作成できるようになります。

今回は、Google Books APIの作成手順から、ObsidianのBook SearchプラグインにAPIキーを設定するまでの全手順を、画像の位置を交えながら分かりやすく解説します。

1. Google Books APIの取得方法

まずは、Google Cloud ConsoleからBooks APIを有効化し、APIキーを発行する手順を進めていきます。

1-1. プロジェクトの作成

  1. Google Cloud Console にアクセスします。
  2. 画面上部にある「プロジェクト選択ツール」**を開きます。
  3. ポップアップ画面の右上にある「新しいプロジェクト」をクリックします。

  4. 任意のプロジェクト名を入力し、**「作成」ボタンをクリックします。

    1-2. Books APIの有効化

  5. 先ほど作成したプロジェクトを選択して切り替えます。

  6. 左メニューまたはダッシュボードから「APIとサービス」＞「ライブラリ」**を選択します。
  7. 検索窓に「Books API」と入力して検索します。
  8. 検索結果に表示された**「Books API」をクリックします。
  9. 「有効にする」ボタンをクリックします。しばらく待つとAPIが有効化されます。

1-3. APIキーの生成

  1. APIの詳細画面、または左メニューから「認証情報」**の画面を開きます。
  2. 画面上部の「＋認証情報を作成」をクリックし、メニューから「APIキー」を選択します。
  3. Books APIで使用するためのAPIキーを生成します。
  4. 発行された**APIキーをコピーし、メモ帳などに控えておきます。

    ※注意: APIキーは他人に知られないよう、取り扱いに注意してください。

2. ObsidianのBook Searchプラグインへの設定

Google sideでの設定が完了したら、最後にObsidian側への紐付けを行います。

  1. Obsidianを開き、「設定」＞「コミュニティプラグイン」＞「Book Search」の設定画面を開きます。
  2. 「Google API Settings」の項目にある「API Key」の入力欄に、先ほど控えたAPIキーを貼り付けます。 これで、すべての設定が完了です！

おわりに

Google Books APIを経由した書籍検索が可能になりました。

APIキーを設定したことで、これまで以上にサクサクと書籍データがヒットするようになり、読書ノートの作成効率が劇的にアップするはずです。読んだ本をその場でObsidianにストックしていく感覚は、一度慣れると手放せなくなります。

「最近本の検索がうまくヒットしないな」と感じていた方や、これから本格的にObsidianで読書管理を始めたい方は、ぜひ試してみてください。

Vue.js×Markdownブログを作ろう（番外編6：「vite.config.ts」と「env.d.ts」の役割を徹底解説）

はじめに

これまでに、画面を司る App.vue や、TypeScriptのルールを決める tsconfig ファミリーについて解説してきました。

今回は、後編のデプロイ自動化編でエラーを解決するために大活躍した2つのファイル、vite.config.ts と env.d.ts にスポットを当てます。

あのとき、なぜこの2つを書き換えるだけで複雑なビルドエラーが一発で解決したのか。その仕組みと、この2つのファイルが担っている重要な役割について、分かりやすく解説していきます。

1. 2つのファイルの役割を「料理」に例えると？

今回もイメージしやすいように、「料理（アプリ開発）」に例えてみましょう。

  • vite.config.ts は、厨房の 「高機能調理家電（Vite）のカスタム設定」 です。 「食材（ファイル）を調理するときは、このオプションを使ってね」「この特殊な食材（Markdown）は、プログラムじゃなくてただのテキスト（生野菜）として扱ってね」と調理器具の動きをカスタムします。
  • env.d.ts は、調理スタッフ（TypeScript）のための 「特製レシピ（型定義の補足メモ）」 です。 「普段扱わない特殊な食材（.vue ファイルや環境変数）が届くけど、これはこういう風に調理していい安全なものだよ」とスタッフに教えて安心させるメモです。

2. vite.config.ts（Viteのカスタム設定）の役割

vite.config.ts は、超高速なビルド工具である「Vite」の動きをカスタマイズするためのファイルです。

実際のコード（初期状態）

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue() // 👈 Vueファイルを処理できるようにするプラグイン
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)) // 👈 「@」でsrcフォルダを指せるようにする設定
    }
  }
})

ここがポイント

  • plugins: Viteは標準だとシンプルなJavaScriptしか扱えません。そこに vue() プラグインを差し込むことで、「.vue という特殊なファイルもパース（解析）してWebページに変換できるようにする」という能力を追加しています。
  • resolve.alias（エイリアス）: コードを書くときに ../../components/Button.vue のように上の階層を何度も遡って書くのは大変ですよね。ここで @ を src/ のショートカットとして登録しておくことで、いつでも @/components/Button.vue とシンプルに記述できるようになります。

3. env.d.ts（環境型定義ファイル）の役割

続いて、プロジェクトのルートにある env.d.ts です。末尾の .d.ts は「Declaration（宣言）ファイル」を意味し、TypeScript専用の型定義を書く場所です。

後編で私たちが追加したコード

/// <reference types="vite/client" />

declare module '*.vue' {
  import type { DefineComponent } from 'vue'
  const component: DefineComponent<{}, {}, any>
  export default component
}

なぜこれが必要だったのか？

TypeScriptは非常に優秀なチェック機構ですが、標準状態では「JavaScript（.ts や .js）」のことしか知りません。そのため、突然 import App from './App.vue' と書かれると、「何だこの .vue ってファイルは！型が分からないからエラーにするぞ！（TS7016）」と怒ってしまいます。

そこで、env.d.ts の出番です。 declare module '*.vue'（拡張子が .vue のファイルすべてを対象とする） と宣言し、「それはVueのコンポーネントだから安心して読み込んでいいよ」とTypeScriptに教えてあげることで、ビルド時の型チェック（vue-tsc）を無事に通過させることができるのです。

また、1行目の /// <reference types="vite/client" /> があるおかげで、Viteが提供する便利な機能（画像インポートや環境変数の読み込み）の型もTypeScriptが理解できるようになっています。

4. トラブルシューティングの伏線回収

後編の記事で、Markdownのパースエラーが起きた際、私たちは App.vue のインポート処理を以下のように修正しました。

// 修正後
const markdownFiles = import.meta.glob('./assets/content/**/*.md', { query: '?raw', import: 'default' })

この { query: '?raw' } という指定は、「Vite（vite.config.ts で動いている仕組み）に対して、このファイルをプログラムコードとしてではなく、ただの生の文字列（raw text）として読み込んでね！」という合図です。

これによって、Viteの設定（調理家電）が「よし、これはプログラムじゃないから文法チェックはスルーして、そのままテキストとして届けよう」と正しく判断し、エラーが消え去ったわけです。

vite.config.ts の仕様（クエリの扱い方）と、env.d.ts によるVite用型定義のサポートが組み合わさることで、私たちのMarkdownブログは完璧に動作しています。

おわりに

一見すると難しそうな英語の設定ファイルばかりですが、

  • vite.config.ts でファイルの調理方法（ビルド）をカスタムし、
  • env.d.ts でTypeScriptにファイルの正体を教えてあげる。

それぞれの役割が分かると、エラーログが出たときも「あ、これはViteの読み込みの設定だな」「これはTypeScriptへの教え込みが足りないな」と、自分で解決する力がグッと身につきます。

プロジェクトの土台の仕組みをマスターしたところで、次回からはまた楽しい新機能の追加や、デザインのカスタマイズを進めていきましょう。

Vue.js×Markdownブログを作ろう（番外編5：なぜ3つもある？「tsconfig」ファミリーの役割を徹底解説）

はじめに

これまで、App.vue の構造や package.json の役割など、プロジェクトを支える様々なファイルの裏側を紐解いてきました。

今回は、エディタのフォルダを開いたときに「…ん？ なんで似たような名前のファイルが3つもあるんだ？」と誰もが一度は疑問に思う、TypeScriptの設定ファイル群 tsconfig.json、tsconfig.app.json、tsconfig.node.json にスポットを当てます。

「TypeScriptの設定は1つのファイルにまとめてくれればいいのに」と思うかもしれません。しかし、これらが3つに分かれているのには、Vue 3 ＋ Viteというモダンな開発環境ならではの理由があります。それぞれの役割と関係性を整理していきたいと思います。

1. 3つのファイルの役割を「会社」に例えると？

この3つの関係性は、「会社の組織図（親会社と2つの専門部署）」に例えると非常に分かりやすいです。

  • tsconfig.json（親会社 / 全体統括部） すべてのベースとなる共通の社内ルール（TypeScriptの基本設定）を決める場所です。実務は子会社（下の2つ）に丸投げしています。
  • tsconfig.app.json（子会社A / フロントエンド開発部） ブラウザ上で動く「ブログの画面（Vueやメインプログラム）」を担当する部署。ブラウザ特有の仕組み（DOMなど）を理解する設定になっています。
  • tsconfig.node.json（子会社B / バックエンド・インフラ部） パソコンやサーバー上で動く「Viteの設定ファイル（vite.config.ts）」などを担当する部署。Node.jsの仕組みを理解する設定になっています。

2. なぜファイルを分ける必要があるのか？

最大の理由は、「ブラウザで動くコード」と「サーバー（パソコン）で動くコード」では、使える機能やルールが全く違うからです。

違いの具体例

  • 画面用のコード（src/ 配下）： ブラウザで動くため、window や document といった画面操作の言葉（DOM）を理解する必要があります。
  • 設定用のコード（vite.config.ts など）： パソコン（Node.js環境）でビルドするときに動くため、ファイルシステムを操作する path や fs といったサーバー側の言葉を理解する必要があります。

もしこれを1つの tsconfig.json だけで管理しようとすると、「画面用のコードなのにサーバー用の命令が混ざってしまっている」「設定ファイルなのにブラウザ用の設定が適用されてエラーになる」といった、型チェックの混乱（汚染）が起きてしまいます。

そのため、それぞれのファイルが担当する「範囲（インクルードする場所）」を明確に分けているのです。

3. それぞれのファイルの中身を解剖

① tsconfig.json（共通ルールの定義と割り振り）

このファイル自体は、細かいルールをあまり書きません。他の2つの設定ファイルを「参照（references）」し、プロジェクト全体へ割り振る司令塔の役割をしています。

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ]
}

② tsconfig.app.json（画面・Vueアプリ専用）

私たちが書く src/ 配下のコード（VueやTypeScript）をチェックするためのルールが書かれています。

{
  "extends": "@vue/tsconfig/tsconfig.dom.json", // 👈 ブラウザ(DOM)用の設定をベースにする
  "include": ["env.d.ts", "src/**/*", "src/**/*.vue"], // 👈 対象はsrcフォルダの中身だけ！
  "compilerOptions": {
    "composite": true,
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo"
  }
}

include を見ることで、「この設定は src/ の中身と env.d.ts だけを見張るんだな」ということが分かります。

③ tsconfig.node.json（ビルド設定ファイル専用）

Viteの設定ファイルなど、開発ツール自体を動かすためのルールが書かれています。

{
  "extends": "@tsconfig/node22/tsconfig.json", // 👈 Node.js用の設定をベースにする
  "include": ["vite.config.ts"], // 👈 対象はvite.config.tsだけ！
  "compilerOptions": {
    "composite": true,
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "types": ["node"] // 👈 Node.jsの型定義を使う
  }
}

こちらの対象（include）は vite.config.ts に限定されており、Node.jsの機能を使って動作するようにカスタマイズされています。

4. 開発者が知っておくべきこと

日常の個人開発において、これらのファイルを直接手動で書き換える機会はそれほど多くありません。しかし、以下の仕組みを知っておくとトラブル時に役立ちます。

  • 型チェックコマンドの裏側 後編の記事でビルドした際、vue-tsc --build というコマンドを実行して型チェックを行いました。この --build というオプションこそが、「tsconfig.json の指示に従って、複数の子設定ファイル（app と node）を順番にまとめて賢くチェックしてね」という命令の正体です。
  • 設定を変更したいとき もし「ブログ画面（src/）のコードで、もっと厳格に型をチェックしたい」と思ったら、直すべきターゲットは全体の tsconfig.json ではなく、tsconfig.app.json の方になります。

おわりに

今回は、名前がそっくりで混乱しやすい「tsconfig」ファミリーの正体について解説しました。

一見複雑に見える3分割の構成は、「ブラウザ用（画面）」と「Node.js用（ツール設定）」の型チェックルールが混ざらないように隔離し、安全かつ高速にビルドを行うためのモダンな知恵が詰まった設計だったのです。

ブラックボックスになりがちな「設定ファイルの意図」が分かると、エラーが起きたときも「これは画面側の問題だな」「これはViteの設定側の問題だな」とアタリをつけやすくなります。

Vue.js×Markdownブログを作ろう（番外編4：「package.json」と「package-lock.json」の違いと役割を徹底解説）

はじめに

こんにちは。前回までの番外編シリーズでは、index.html や App.vue といった画面に直接関わるコードの仕組みを解剖してきました。

今回は、プロジェクトのルート直下に置かれている、一見地味だけれど超重要な2つのファイル、package.json と package-lock.json にスポットを当てます。

「どちらもライブラリの管理用ファイルだということは知っているけれど、なぜ2つもあるの？」「中身はどう違うの？」という疑問を持つ方は多いはずです。 この2つのファイルが果たす役割と、なぜモダンなWeb開発に両方が必要なのか、その理由を分かりやすく紐解いていきます！

1. 2つのファイルの役割を「料理」に例えると？

2つのファイルの違いをシンプルに理解するために、「料理（アプリ開発）」に例えてみましょう。

  • package.json は、大まかな 「お買い物リスト（またはレシピの材料欄）」 です。 「Vueのバージョン3系と、markedというライブラリが必要です」という大枠の希望が書かれています。
  • package-lock.json は、実際に購入した 「レシート（購入履歴の完全な明細）」 です。 「〇年〇月〇日、〇〇スーパーで、シリアル番号〇〇のVueバージョン3.5.15を確かに購入しました」という、寸分の狂いもない正確な記録が書かれています。

2. package.json（お買い物リスト）の中身と役割

まずは package.json です。私たちが npm install marked などのコマンドを叩いたとき、ここに自動でライブラリ名が追記されます。

主な記述内容

{
  "name": "vue-md-site",
  "version": "0.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  },
  "dependencies": {
    "marked": "^11.0.0",
    "vue": "^3.4.0"
  }
}

ここがポイント：チルダ（~）やキャレット（^）

ライブラリのバージョンの前に ^（キャレット） がついていますね。これは「バージョン3.4.0以上、4.0.0未満の範囲なら、最新のものを自動で入れていいよ」という「大まかな指定」を意味しています。

これにより、開発者が一からプロジェクトを立ち上げる際、自動的にバグが修正された最新のパッチバージョンが手に入るというメリットがあります。

3. なぜ package-lock.json（レシート）が必要なのか？

「大まかな指定で最新版が入るなら、package.json だけで十分では？」と思うかもしれません。しかし、ここに落とし穴があります。

もし package.json しかなかった場合、以下のような悲劇（通称：自分の環境では動くのに問題）が起こる可能性があります。

  1. Aさん（あなた）がブログを作った時、Vueの最新版は 3.4.0 だった（正常に動く）。
  2. 半年後、Cloudflare Pages（サーバー）がビルドする時、Vueの最新版が 3.4.99 にアップデートされていた。
  3. 3.4.99 にわずかな仕様変更があり、ブログのコードと干渉してビルドエラーになってしまった！

このように、**「タイミングによってインストールされるバージョンがズレる」のを完全に防ぐために生まれたのが package-lock.json** です。

package-lock.json には、あなたがインストールしたその瞬間の「全く同一のバージョン」や「ダウンロード元のURL」、「ファイルが改ざんされていないかを証明するハッシュ値」が、関連するすべての依存ライブラリ（何百個もの孫ライブラリまで）にわたって完璧にロック（固定）されて記録されています。

Cloudflare Pagesや他の開発メンバーは、この package-lock.json のレシート通りにライブラリを復元するため、いつでも、どこでも、誰の環境でも、完全に同じ状態でアプリが動くことが保証されるのです。

4. 開発者が守るべきルール

この2つのファイルの仕組みが分かると、日々のGit管理やコマンドの使い方が変わってきます。開発者が覚えておくべきルールは以下の3つです。

① package-lock.json は手動で絶対に編集しない

このファイルは、npm コマンドが自動で書き換えるものです。人間が手動で書き換えると整合性が崩れ、ビルドが通らなくなる原因になります。

② 2つのファイルは必ずセットでGitHubにプッシュする

「ロックファイルは自動生成だからGit管理から外そう」というのは大きな間違いです。Cloudflare Pagesに正確なバージョンを伝えるため、変更があったら必ず2つ同時にコミットしてプッシュしてください。

③ 本番環境やクローン直後は npm ci を使う

通常、ローカルでのライブラリ追加には npm install を使いますが、Cloudflare PagesなどのCI/CD環境では、自動的に npm clean-install（npm ci） というコマンドが内部で走っています。 これは「package.json のおまかせ指定を無視して、package-lock.json のレシート通りに100%厳密にインストールする」というデプロイ専用の安全なコマンドです。

おわりに

今回は、package.json と package-lock.json のコンビについて解説しました。

  • package.json で楽にライブラリの希望を伝え、
  • package-lock.json で厳密に足並みをそろえる。

後編の記事で、Cloudflare Pagesが迷うことなく一発でビルドを成功させられたのも、GitHub経由でこの2つのファイルが正しくCloudflareに引き渡されていたからです。

エラーログなどで見かけることが多いファイルですが、意味が分かると怖くありません。ぜひ裏方の仕組みも味方につけて、日々の開発を楽しんでいきましょう。