Astro入門：Windowsでの導入手順（pnpm/Biome/Playwright対応）【2025】

2025年版：Astroとは？—Windows＋VS Codeで最速の静的サイト環境を1時間で構築する手順コーディング
この記事は約9分で読めます。

みなさんこんにちは。古の時代からWeb制作をしているのですが、最近は自分でエンジニアとしてなにかを作ったりすることもすっかりなくなり、どちらかというとディレクションとかマーケティング方面ばかりです。

もとはWebデザイナー（というかFlashというものでアニメやゲームを作りまくってた）、フロントエンドエンジニア、テクニカルディレクターときたのですが、ディレクター歴が長くなってしまってすっかりエンジニア方面は他のエンジニアの方々に任せっぱなしになってしまっていました。

ちょっとはずかしいので、勉強しなおしています。

というわけで、手始めに最近よく聞くような気がするAstroってなに？とか開発環境を整えるところまでやってみました。

Astroってなに？

Astroは“静的HTMLをベースに必要な箇所だけJSを動かす”設計のサイト向けフレームワークです。ページはまず静的HTMLとして出力し、必要な場所だけ後からJavaScriptを読み込む設計（Islands Architecture）。そのおかげで、配信するJSが最小限になり、表示速度とSEOに強くなります。
Astro Docs+1

  • 静的ファースト：ほとんどをHTMLで配信（JSゼロでも表示可能）。
    Getting started | Docs
  • 必要な箇所だけ動かす：React/Vue/Svelteなどを“島”として部分的に動かす思想。
    Front-end frameworks | Docs
  • ブログ／企業サイト／ドキュメントに最適（もちろんSSR運用も可能）。
    Getting started | Docs

「SPA全体で高度な状態管理が必要」など“アプリ寄り”は Next.js/Remix の方が素直なことも。Astroの強みはサイト側です。

この記事のゴール（今回やったこと）

  • Windows＋VS Code（PowerShell）でAstroのプロジェクトを新規作成
  • pnpmで依存管理し、開発サーバーを起動
  • Biome（整形＆軽いLint）を導入
  • PlaywrightのE2Eテストを1本通して、環境を“壊れていない”状態で固定

実作業パス：C:\Users\ユーザー名\Documents\engineer_study

前提（準備するもの）

  • Node.js LTS（v22系）：Windowsなら winget で入れると簡単。
    Node.js
    Winget.run
  • pnpm：高速・省容量なパッケージマネージャ。
    pnpm
  • VS Code：言わずもがなのレベルであるエディタ。
    入れておく拡張機能は以下
    Astro / Biome / Playwright Test / PowerShell / GitLens（任意）
  • ブラウザ：Chrome系（Lighthouse計測用にも）

手順1：Node.js LTS を入れる（winget）

ターミナル：

winget install OpenJS.NodeJS.LTS
node -v     # v22.x と表示されればOK

※公式のLTSダウンロードページからの導入でもOK。
Node.js
Winget.run

手順2：pnpm を導入（権限エラーを避ける方法）

Corepackでの有効化は Program Files への書き込みでEPERMになることがあります。今回はユーザー領域に入れました。

ターミナル：

npm i -g pnpm
pnpm -v

（うまくいかない場合）

winget install pnpm.pnpm

pnpm

手順3：Astro プロジェクト作成 → 起動

ターミナル：

cd $HOME\Documents\engineer_study
pnpm create astro@latest astro-blog　
# 質問されたらデフォルトを選択してOK

ターミナル：

cd astro-blog
pnpm install
pnpm dev

ブラウザで http://localhost:4321 を開く → 初期ページが見えたらOK。

Astroの公式ガイドでも同様の手順が案内されています。
Astro Docs

手順4：Biome（整形＆軽Lint）を入れる

ターミナル：

pnpm add -D @biomejs/biome
pnpm dlx @biomejs/biome init

package.json の scripts に整形コマンドを追加：

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro",
    "lint": "biome check --write .",
    "test:e2e": "playwright test"
  }
}

ターミナル：整形の実行（保存時整形と合わせて運用）

pnpm run lint

Biomeはフォーマッタ＋リンタを一体で提供する高速ツールです。
Biome+1

手順5：Playwright（E2E）を導入 → テスト1本通す

ターミナル：

pnpm add -D @playwright/test
pnpm dlx playwright install

tests/smoke.spec.ts を新規作成：

import { test, expect } from '@playwright/test';

test('トップページが開ける', async ({ page }) => {
  const res = await page.goto('http://localhost:4321/');
  expect(res?.ok()).toBeTruthy();
  await expect(page.locator('main')).toBeVisible();
});

実行：

ターミナルA（起動しっぱなし）：

pnpm dev

ターミナルB（別にターミナルを立ち上げる）：

pnpm run test:e2e   # => 1 passed になれば成功

Playwright Test は test/expect で読みやすいE2Eが書けます。
Playwright+1

VS Codeのおすすめ拡張（任意）

  • Astro（構文ハイライト／補完）
  • Biome（整形・Lint統合）
  • Playwright Test（テスト実行UI）
  • Tailwind CSS IntelliSense（今後UIを足す場合）
  • PowerShell／GitLens（作業効率UP）

設定 → Format On Save をONにすると、保存時にBiomeで自動整形されて快適です。

よくあるつまずき（今回の実録ベース）

Q1. pnpm は認識されません
A. npm i -g pnpm でユーザー領域に導入 → 端末を再起動 → pnpm -v で確認。
Installation | pnpm

Q2. EPERM: ... open 'C:\Program Files\nodejs\pnpm'
A. CorepackがProgram Filesに書き込もうとして失敗。管理者で実行またはnpmグローバルで回避。

Q3. ERR_PNPM_NO_PKG_MANIFEST
A. package.json がない階層で実行しているだけ。cdでプロジェクト直下に移動。

Q4. Missing script: test:e2e
A. package.json の scripts に "test:e2e": "playwright test" を追加（直で実行するなら pnpm exec playwright test）。

Q5. Unable to read ... package.json / not valid JSON
A. JSONにコメントや末尾カンマが混入。正しいJSONに直す。

Q6. BOMが原因でJSONエラー
A. VS Code右下のエンコードを**UTF-8（BOMなし）**で保存し直す。

最終確認用：今回の package.json（正常版・コピペ可）

{
  "name": "astro-blog",
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro",
    "lint": "biome check --write .",
    "test:e2e": "playwright test"
  },
  "dependencies": {
    "astro": "^5.12.9"
  },
  "devDependencies": {
    "@biomejs/biome": "^1.9.4",
    "@playwright/test": "^1.48.0"
  }
}

次のステップ

ざくざく進めてみましたが最低限、Astroの立ち上げまでは滞りなく進めることができました。
次はこの環境をベースに速度パフォーマンスの観察やUIの実装、アクセシビリティ周りといろいろやっていきたいと思います。

  • 速度の見える化：pnpm build && pnpm preview → ChromeのLighthouseで計測。特に INP と CLS を観察しましょう（Core Web Vitalsの主要指標）。
    web.dev
    Google ヘルプ
  • UIを一歩前へ：コンテナクエリ/:has() を使ったカードUI実装（JSなしでも“気持ちよく”崩れるレイアウトに）。
  • A11yの基礎：フォーカス可視・タップ領域・ドラッグ操作の代替などをチェックリスト化。

参考リンク（公式中心・コピペ用）

Astro 公式ドキュメント（入門）: https://docs.astro.build/en/getting-started/
Astro Islands Architecture: https://docs.astro.build/en/concepts/islands/
Astro サポートフレームワーク: https://docs.astro.build/en/guides/framework-components/

pnpm インストールガイド: https://pnpm.io/installation
pnpm install の説明: https://pnpm.io/cli/install

Biome 公式サイト（日本語トップ）: https://biomejs.dev/ja/
Biome はじめる（日本語）: https://biomejs.dev/ja/guides/getting-started/

Playwright Test（APIリファレンス）: https://playwright.dev/docs/api/class-test
Playwright でテストを書く: https://playwright.dev/docs/writing-tests

Node.js ダウンロード（LTS）: https://nodejs.org/en/download
winget で Node.js LTS: https://winget.run/pkg/OpenJS/NodeJS.LTS

Core Web Vitals（web.dev）: https://web.dev/articles/vitals
Core Web Vitals レポート（Search Console ヘルプ）: https://support.google.com/webmasters/answer/9205520
タイトルとURLをコピーしました