02. AstroPaperのインストールと開発サーバーの起動

シリーズ目次 前章: 01. AstroPaperとは何か：最小限で始めるブログテーマ 次章: 03. AstroPaperのディレクトリ構成を読み解く

Table of contents

この章のねらい

手元のパソコンでAstroPaperを動かすところまで進めます。コマンドを打つだけの作業に見えますが、それぞれが何をしているかを知らないと、転んだときに原因を切り分けられません。

事前に必要なもの

Node.js

AstroPaperはNode.js上で動きます。テンプレートの package.json には次の指定が入っています。

{
  "engines": {
    "node": ">=22.12.0"
  }
}package.json

engines は、このプロジェクトが想定しているNode.jsのバージョンを宣言する項目です。22.12.0以上が要ります。古ければ更新してください。

現在のバージョンは次のコマンドで確認できます。

node -v

複数のバージョンを切り替えたい場合は、nvm、fnm、Volta といったバージョン管理ツールを使うと便利です。テンプレートには .node-version ファイルが含まれており、対応するツールを使っていれば自動で適切なバージョンに切り替わります。

パッケージマネージャー

パッケージマネージャーは、必要なライブラリをまとめて取得・管理するツールです。Node.jsに付属する npm のほか、pnpm、yarn、bun が使えます。

AstroPaperのリポジトリには pnpm-lock.yaml が含まれているため、pnpm を使うのがもっとも素直です。pnpm が未導入なら、次のコマンドで有効化できます。

corepack enable pnpm

corepack はNode.jsに同梱されている仕組みで、プロジェクトが指定したパッケージマネージャーを用意してくれます。

プロジェクトを作成する

好きなディレクトリで次のコマンドを実行します。

pnpm create astro@latest --template satnaing/astro-paper

Astroのプロジェクト作成ツールを取ってきて、AstroPaperのテンプレートを土台にプロジェクトを作る、という意味のコマンドです。実行すると、プロジェクト名、依存関係を入れるか、Gitリポジトリを初期化するかを順に聞かれます。

他のパッケージマネージャーを使う場合は次のとおりです。

# npm
npm create astro@latest -- --template satnaing/astro-paper

# yarn
yarn create astro --template satnaing/astro-paper

# bun
bun create astro@latest -- --template satnaing/astro-paper

npm と bun では、コマンド名の後に -- を挟みます。ここから先のオプションは呼び出し先のツールへ渡す、という区切り記号です。

4つを並べてみると、やっていることは同じで、違うのは区切り記号の有無だけだと分かります。

作成が終わったら、そのディレクトリへ移動します。

cd <作成したプロジェクト名>

依存関係をインストールする

プロジェクト作成時にインストールを行わなかった場合は、ここで実行します。

pnpm install

package.json に書かれたライブラリを node_modules/ ディレクトリへ展開する作業です。回線状況にもよりますが、初回は数十秒から数分かかります。

開発サーバーを起動する

pnpm dev

成功すると、ターミナルに次のようなURLが表示されます。

astro  v7.x.x ready in 500 ms
┃ Local    http://localhost:4321/

ブラウザで http://localhost:4321/ を開くと、AstroPaperのトップページが表示されます。この状態でMarkdownファイルや設定ファイルを保存すると、ブラウザが自動的に更新されます。この仕組みをホットリロードと呼びます。

停止するときはターミナルで Ctrl + C を押します。

起動できないときの確認ポイント

やみくもに試すと時間を溶かします。Node.jsのバージョン、pnpmの有無、ポートの空き。この順で潰してください。

用意されているコマンド

テンプレートの package.json には次のスクリプトが定義されています。

pnpm build が特別な理由

AstroPaperの build には、4つの処理がつながっています。

{
  "scripts": {
    "build": "astro check && astro build && pagefind --site dist && cp -r dist/pagefind public/"
  }
}package.json

1. astro check：TypeScriptの型やフロントマターの記述に誤りがないか検査する
2. astro build：dist/ ディレクトリへHTMLなどを書き出す
3. pagefind --site dist：書き出したHTMLを読んで検索用の索引を作る
4. cp -r dist/pagefind public/：作った索引を public/ へコピーする

4番目のコピーは、次回以降の開発時にも検索機能を試せるようにするためのものです。検索の仕組みは第9章で詳しく扱います。

4つは && でつながっているため、前の段が失敗するとその先は実行されません。

preview と dev の違い

pnpm dev は開発用の仕組みが動いているため、実際に公開されるHTMLとは細部が異なります。pnpm preview は pnpm build で書き出した本番用のファイルをそのまま配信するので、公開後の姿を確認したいときはこちらを使います。

pnpm build
pnpm preview

検索機能を確認したい場合も、必ず一度 pnpm build を通す必要があります。開発サーバーだけでは索引が存在しないため、検索欄に警告が表示されます。

最初に変更する場所

動作確認ができたら、まずは次の2つを自分用に書き換えます。

1. astro-paper.config.ts のサイト名・URL・説明文・著者名
2. src/content/posts/ に入っているサンプル記事

設定ファイルの各項目は第4章、記事の書き方は第5章で扱います。その前に次章で、どこに何があるのかを頭に入れておいてください。

要点

• AstroPaperはNode.js 22.12.0以上を必要とし、pnpm-lock.yaml が同梱されているためpnpmでの運用が素直である。
• create astro --template satnaing/astro-paper でテンプレートを取得し、pnpm install → pnpm dev で localhost:4321 に起動する。
• pnpm build は型チェック・ビルド・Pagefind索引生成・索引コピーの4段階を連結したコマンドである。
• 公開後の姿や検索機能を確認するには、pnpm dev ではなく pnpm build と pnpm preview を使う。
• 起動できないときは、Node.jsのバージョン、pnpmの有無、ポートの空き状況の順に切り分ける。

参考資料

• AstroPaper リポジトリ README — 作成コマンドとスクリプト一覧
• Astro: Install and Setup — 動作要件とプロジェクト作成
• Astro: CLI Reference — astro dev / build / preview / check / sync
• Node.js Corepack ドキュメント — パッケージマネージャーの有効化
• Pagefind 公式サイト — 索引生成コマンド

シリーズ目次 前章: 01. AstroPaperとは何か：最小限で始めるブログテーマ 次章: 03. AstroPaperのディレクトリ構成を読み解く