シリーズ目次 ／ 前章: 01. Astroとは何か：コンテンツ中心という選択 ／ 次章: 03. .astroコンポーネントの基本
Table of contents
Open Table of contents
この章のねらい
Astroプロジェクトを実際に作って、開発サーバーが立ち上がるところまで進めます。生成されたディレクトリが何のためにあるのかも見ておきます。ここを飛ばすと、以降の章でファイルの置き場所に毎回迷います。
動作要件
Astroを動かすにはNode.jsが必要です。公式ドキュメントの要件は次のとおりです。
- Node.js v22.12.0 以上
- 奇数バージョン（v23、v25など）は非対応
用語: Node.jsは、ブラウザの外でJavaScriptを実行するための環境です。Astroはビルド時にNode.js上で動作し、HTMLを生成します。
Node.jsの奇数バージョンは開発版という位置づけで長期サポートの対象外のため、Astroもサポート対象から外しています。手元のバージョンは次のコマンドで確認できます。
node -v動くバージョンと動かないバージョンを並べると、次のとおりです。
パッケージマネージャーは npm、pnpm、Yarn のいずれでも構いません。この章では npm を例に説明します。
プロジェクトを作成する
対話式のセットアップウィザードを使うのが最も簡単です。
npm create astro@latest実行すると、プロジェクト名、テンプレートの選択、TypeScriptの設定、依存関係のインストール、Gitリポジトリの初期化などを順に尋ねられます。迷ったら、提示される既定値を選んでおけば問題ありません。
テンプレートを指定して作成する
ウィザードを介さず、テンプレートを直接指定することもできます。
# 公式サンプルから作成する
npm create astro@latest -- --template blog
# GitHubリポジトリをテンプレートにする
npm create astro@latest -- --template <your-org>/<your-repo>作成時にインテグレーション（拡張機能）を同時に追加することも可能です。
npm create astro@latest -- --add react --add partytownインテグレーションについては12. Astroのビルドとデプロイで改めて触れます。
標準的なディレクトリ構成
作成されたプロジェクトは、おおむね次のような構成になっています。
| 場所 | 役割 |
|---|---|
src/ | Astroが処理・最適化する対象のソースコード全般 |
src/pages/ | 必須。ここに置いたファイルがそのままページとURLになる |
src/components/ | 再利用するコンポーネントを置く慣例的な場所 |
src/layouts/ | 複数ページで共有する外枠（ヘッダー、フッターなど）を置く |
src/styles/ | CSSやSassをまとめる慣例的な場所 |
public/ | 加工せずそのまま配信するファイル（favicon.ico、robots.txt、フォントなど） |
astro.config.mjs | Astroの設定ファイル |
package.json | 依存パッケージとnpmスクリプト |
tsconfig.json | TypeScriptの設定 |
特別扱いされるのは src/pages/ だけです。公式ドキュメントも、これがなければサイトにページもルートも存在しないと書いています。逆に言えば src/pages/ 以外のディレクトリ名はただの慣例なので、好きに組み替えて構いません。
src/ と public/ の違い
この2つの使い分けで、最初はたいていつまずきます。
src/に置いたファイルは、Astroのビルド処理で扱えます。たとえば、インポートしたCSSはバンドルされ、画像は<Image />や<Picture />などを使うことで圧縮・フォーマット変換の対象になります。単にsrc/に置くだけで、すべてのファイルが自動的に最適化されるわけではありません。public/に置いたファイルは、一切加工されずそのままの名前で配信されます。
違いはひとつ、ファイルがビルド処理を通るかどうかだけです。
URLを固定したいファイルとAstroに触られたくないファイルは public/、最適化してほしいファイルは src/。これで大きく外しません。画像の扱いは11. Astroの画像最適化とView Transitionsで詳しく扱います。
開発サーバーを起動する
プロジェクトのディレクトリで次を実行します。
npm run dev既定ではポート4321で起動し、http://localhost:4321/ にアクセスすると画面を確認できます。ファイルを保存すると、その変更が自動的に反映されます（HMR、ホットモジュールリプレースメント）。
主なフラグは次のとおりです。
| フラグ | 意味 |
|---|---|
--port <number> | ポート番号を変更する（既定は4321） |
--host | 同一ネットワークの別端末からアクセスできるようにする |
--open | 起動と同時にブラウザを開く |
--verbose | 詳細なログを出力する |
バックグラウンド起動（Astro 7以降）
Astro 7では、開発サーバーをバックグラウンドプロセスとして起動できるようになりました。ターミナルを1枚占有せずに済むため、他の作業と並行しやすくなります。
# バックグラウンドで起動
astro dev --background
# 状態を確認
astro dev status
# ログを見る（--follow で追従）
astro dev logs --follow
# 停止
astro dev stop通常起動との違いは次のとおりです。
覚えておきたいCLIコマンド
日常的に使うのは次のあたりです。
| コマンド | 用途 |
|---|---|
astro dev | 開発サーバーを起動する |
astro build | 本番用にサイトをビルドする |
astro preview | ビルド結果をローカルで確認する |
astro check | 型チェックなどの診断を実行する |
astro sync | astro:content などの型定義を生成する |
astro add <name> | インテグレーションを追加し、設定ファイルも更新する |
astro info | 実行環境の情報を表示する |
astro docs | 公式ドキュメントを開く |
package.json の scripts に登録されているため、通常は npm run dev や npm run build の形で呼び出します。
astro check は、.astro ファイル内の型エラーやコンテンツコレクションのスキーマ違反を検出してくれます。ビルド前に実行する習慣をつけておくと、デプロイしてから気づく不具合を減らせます。
設定ファイルの最小構成
astro.config.mjs（TypeScriptなら astro.config.ts）は、次のような形をしています。
import { defineConfig } from "astro/config";
export default defineConfig({
site: "https://example.com",
});defineConfig で包むことで、エディタの補完と型チェックが効くようになります。設定項目は多岐にわたりますが、最初のうちは site（公開URL）だけ埋めておけば十分です。主要なオプションは12. Astroのビルドとデプロイで扱います。
要点
- Astroの動作にはNode.js v22.12.0以上が必要で、奇数バージョンは非対応である。
npm create astro@latestの対話ウィザードでプロジェクトを作成できる。src/pages/だけが特別で、ここに置いたファイルがページとURLになる。それ以外のディレクトリ名は慣例である。src/は最適化される、public/はそのまま配信されるという違いを押さえる。- Astro 7では
astro dev --backgroundで開発サーバーをバックグラウンド起動できる。
参考資料
- Install and Set up Astro — Astro Docs
- Project Structure — Astro Docs
- CLI Reference — Astro Docs
- Configuration Reference — Astro Docs
シリーズ目次 ／ 前章: 01. Astroとは何か：コンテンツ中心という選択 ／ 次章: 03. .astroコンポーネントの基本