Astroの始め方 — 最初のページを作ってビルドする入門ガイド

ひよこ

自己紹介やブログを作りたいんだけど、Astroって何が便利なの？

ペンギン先生

Astroは記事や紹介文など、コンテンツ中心のWebサイトを作るフレームワークだよ。まずHTMLとして届け、必要な部分に動きを加えられる。今回は見出しとリストだけの1ページから始めよう。

ひよこ

JavaScriptがゼロって聞いたけど、本当？

ペンギン先生

UIフレームワークのコンポーネントは、標準ではブラウザ用の実行コードを付けずにHTMLへ描画されるよ。ただし、自分でscriptを書いたりclient:ディレクティブを指定したりすればJavaScriptも配信される。サイト全体で必ずゼロ、という意味ではないんだ。

ひよこ

始める前に必要なものは？

ペンギン先生

Node.js、エディタ、ターミナルを用意しよう。確認時点の公式要件はNode.js 22.12.0以上で、奇数メジャー版は対象外だよ。対応しているLTS系列の更新版を選び、node --versionとnpm --versionを確認してね。

ひよこ

プロジェクトを作ったら、どのファイルを触るの？

ペンギン先生

最小テンプレートを選んで作成し、src/pages/index.astroを編集するよ。pagesの中のファイルがURLに対応するんだ。開発サーバーに表示されたアドレスを開いて、見出しが変わるか確かめよう。

ひよこ

ファイルの上にある---は何？

ペンギン先生

その中はページを生成するときに動くJavaScriptやTypeScriptの準備部分だよ。下のHTMLテンプレートから変数を使える。静的ビルドならビルド時、オンデマンド描画ならサーバーでリクエストを処理するときに実行されるんだ。

ひよこ

検索欄やボタンも作れる？

ペンギン先生

できるよ。単純な動きならscriptを使えるし、ReactなどのUIコンポーネントなら対応するインテグレーションを追加できる。client:visibleなどでブラウザ側の処理を読み込む時機を指定した部分が、クライアントの島になるよ。

ひよこ

記事が増えたら、Markdownを置くだけでいいの？

ペンギン先生

pages内のMarkdownはページになるけれど、まとめて管理するContent Collectionsは別の設定だよ。現在の方法ではsrc/content.config.tsでloaderやschemaを定義する。最初のページができてから、公式のブログチュートリアルへ進むと分かりやすいよ。

ひよこ

公開前には何を確かめればいい？

ペンギン先生

npm run buildで成果物を作り、npm run previewでその結果を見よう。この例は静的出力なのでdistが成果物だよ。ログイン利用者別の内容を返すなど、オンデマンド描画を使う場合は公開先に合うアダプターと実行環境も必要になるね。

最初のゴール：好きなものを紹介する1ページ

まず見出しとリストを自分の言葉へ変えてみましょう。Reactやデータベースは、この練習では使いません。

1. Node.jsを確認してプロジェクトを作る

確認時点の要件は Node.js 22.12.0以上。奇数メジャー版はサポートされないため、公式が対応するLTS系列の更新版を選びます。以下の最初の2つが使えない場合は、先にNode.js公式のダウンロード案内で準備してください。

node --version
npm --version
npm create astro@latest my-astro-site

対話では最小構成のテンプレートを選びます。依存関係のインストールを選んだ場合は作成中に実行されます。Gitの初期化は任意です。完了したら移動します。

cd my-astro-site
npm install
npm run dev

ターミナルに表示されたローカルURLを開きます。通常は http://localhost:4321 ですが、使用中のポートなどで変わるため表示を確認しましょう。止めるときは、そのターミナルでCtrl+Cを押します。

2. src/pages/index.astroを編集する

ファイルの内容を次へ置き換えて保存します。

---
const title = "ひよこのおすすめ";
const items = ["読書", "散歩", "プログラミング"];
---
<!doctype html>
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{title}</title>
  </head>
  <body>
    <h1>{title}</h1>
    <ul>
      {items.map((item) => <li>{item}</li>)}
    </ul>
  </body>
</html>

<style>
  h1 { color: #24629b; }
</style>

「ひよこのおすすめ」と3項目が表示されたら成功です。配列の中身を変えてみましょう。このファイルにはブラウザで動く script がなく、配列からリストを作る処理はページの生成側で行われます。

3. 開発画面と公開用の出力を分ける

開発サーバーを止めてから、次を実行します。

npm run build
npm run preview

成功すれば dist に静的成果物ができ、プレビューのURLでも同じ見出しとリストを確認できます。previewは成果物をローカルで確かめるコマンドです。本番公開は、利用するホスティングのAstro向け手順に従います。

つまずいたときと、次に進む道

• Node.jsの要件エラー：node --version と公式の必要条件を照合し、別の古いNode.jsがPATHで選ばれていないか確認します。
• Missing script: dev：今いるフォルダに、このプロジェクトの package.json があるか確認します。
• Reactを置いたのにクリックへ反応しない：インテグレーションと client: の指定を確認します。HTMLを表示するだけなら、クライアントのハイドレーションは不要です。

記事管理へ進むなら公式ブログチュートリアルへ。Content Collectionsはフォルダを作るだけで設定が完了する機能ではありません。loaderとschemaを定義してから使います。サイト選びを整理したい場合はAstroとNext.jsの比較も確認できます。

参考資料

• Astro — Install Astro
• Astro — Islands architecture
• Astro — Content collections