Astroサイト運用での npm run コマンド操作について

Mar 4, 2026

Netplan Matsuyama

Developer

このプロジェクトでは、コード品質を維持するために複数のコマンドを運用しています。PR 作成前やローカル開発時に、これらのコマンドを理解することは重要です。本記事では各コマンドの説明と使用方法をまとめています。

注記 本記事はAstro利用者による確認ガイドです。各コマンドの実行順序は、一般的なベストプラクティス（軽い処理から重い処理へ）に基づいていますが、Astro公式で明確に推奨されているものではありません。

全体像

ローカル開発時およびCI環境で実行するコマンドの概要：

# LOCAL: コード品質チェック例
npm run format         # コード自動整形
npm run type-check     # TypeScript型チェック
npm run test          # テスト実行

# GITHUB: PR 作成
gh pr create

# CI: 自動実行
# - npm run format:check (フォーマット確認のみ)
# - npm run type-check
# - npm run test

---

npm run format:check

目的

Prettier によるコードフォーマットが統一されているか確認します。

実施内容

• スキャン対象：全リポジトリファイル（**/*.{js,ts,tsx,astro,md,mdx,mjs,cjs,json,yml,yaml}）
• チェック項目：
  • インデント（スペース数）
  • 行の最大長（80-100 文字）
  • 末尾のセミコロン
  • クォート形式（シングル vs ダブル）
  • 改行・スペースの統一
• 修正なし：チェックのみ実行（ファイルは変更されない）

実行例

npm run format:check

成功時の出力

Checking formatting...
All matched files use Prettier code style!

失敗時の出力例

Checking formatting...
[warn] src/components/Example.astro
[warn] src/pages/index.astro
Code style issues found in 2 files. Run Prettier with --write to fix.

失敗時の対応

自動修正を実行してから再チェック：

npm run format      # Prettier で自動修正
npm run format:check  # 再度チェック

修正対象ファイルの確認：

npm run format:check 2>&1 | grep -E "^\[warn\]"

CI での役割

• PR がコード基本的なフォーマット基準を満たしているか確認
• merge 前の品質ゲート機能として機能
• 開発者間でのコード統一性を確保

注意点

• .prettierrc に設定を記述（親プロジェクトで一元管理）
• 括弧・改行の自動調整は Prettier に任せて、手動調整は不要

---

npm run type-check

目的

TypeScript の型エラーを検出します。Astro 専用（通常の tsc ではなく）

なぜ Astro 専用？

Astro は仮想モジュール（virtual modules）を多用します：

• astro:content：コンテンツコレクション定義
• virtual:starlight/*：Starlight UI コンポーネント
• @astrojs/starlight/loaders：ローダー関数

通常の TypeScript コンパイラー（tsc）ではこれらの仮想モジュールが解決できないため、Astro 専用の astro check を使用します。

実施内容

astro check

• .ts, .tsx, .astro ファイルをスキャン
• 型定義エラーをレポート
• 警告（warning）やヒント（hint）も出力
• 仮想モジュールにも対応

実行例

npm run type-check

成功時の出力

Result (19 files):
- 0 errors
- 0 warnings
- 5 hints

失敗時の出力例

src/components/Header.astro:12:5 - error ts(2322): Object literal may only specify known properties, and 'unknownProp' does not exist in type 'Props'.

エラー情報の読み方

src/components/Header.astro:12:5
├─ ファイルパス: src/components/Header.astro
├─ 行: 12
├─ 列: 5
└─ エラーコード: ts(2322)

失敗時の対応

1. エラー箇所を特定（ファイル:行:列）
2. 期待される型と実際の型を確認
3. 型定義ミスを修正
4. 再度実行

例：

// ❌ 誤り：unknownProp は Props に定義されていない
<Header unknownProp="value" />

// ✅ 正解：Props で定義されたプロパティのみ使用
<Header title="My Title" />

Warnings と Hints について

レベル	内容	対応
error	コンパイル不可	必須：修正が必要
warning	潜在的な問題	任意：修正推奨
hint	最適化提案	無視可

推奨： errors のみ修正し、warnings・hints は無視して OK

CI での役割

• ビルド時にコンパイル可能かどうかを確認
• 型安全性を担保（実行時エラーを削減）
• IDE の補完機能と一貫性をチェック

注意点

• coverage/ ディレクトリの警告は無視（生成ファイルのため）
• 仮想モジュールエラーが出た場合は tsconfig.json を確認
• Node module の型定義が無い場合は @types/ パッケージをインストール

---

npm run test

目的

Jest による自動テスト実行。144 個のテストが定義されています。

テストスイート構成

src/__tests__/
├── 404-redirect.test.ts          (29 tests)
│   └─ 404ページのリダイレクト機能
├── cookie-banner.test.ts         (32 tests)
│   └─ Cookieバナーの表示・操作
├── astro-config.test.ts          (54 tests)
│   └─ astro.config.mjs の構造検証
├── content-config.test.ts        (25 tests)
│   └─ コンテンツコレクション定義
└── project-structure.test.ts     (4 tests)
    └─ プロジェクト構造の一貫性

実施内容

• jsdom 環境でテスト実行（ブラウザ API をシミュレート）
• Node.js 実験的オプション使用：--experimental-vm-modules
• 各テストは独立して実行
• エラー発生時は失敗テストを報告

実行例

npm run test

成功時の出力

 PASS  src/__tests__/404-redirect.test.ts
 PASS  src/__tests__/cookie-banner.test.ts
 PASS  src/__tests__/astro-config.test.ts
 PASS  src/__tests__/content-config.test.ts
 PASS  src/__tests__/project-structure.test.ts

Test Suites: 5 passed, 5 total
Tests:       144 passed, 144 total
Snapshots:   0 total
Time:        0.727 s

失敗時の出力例

 FAIL  src/__tests__/content-config.test.ts

  ● Content Configuration › should define required collections

    expect(received).toBe(expected)
    Expected: true
    Received: false

      173 |       const hasDocsCollection = /docs\s*:/.test(configContent);
          |                                 ^
      175 |       expect(hasDocsCollection).toBe(true);

テスト失敗時の対応

1. 失敗したテストを特定：ファイルと describe/it 名を確認
2. テストの期待値を理解：テストファイルを開いて条件を確認
3. 実装を修正：ソースコードを修正
4. テスト再実行：npm run test で検証

例：

// テスト：docs コレクションが定義されていることを確認
it('should define required collections', () => {
  const hasDocsCollection = /docs\s*:/.test(configContent);
  expect(hasDocsCollection).toBe(true); // ← 失敗
});

対応：

// src/content.config.ts を確認
export const collections = {
  docs: defineCollection({
    // ← docs が定義されているか確認
    loader: docsLoader(),
    schema: docsSchema({
      extend: (context) => blogSchema(context),
    }),
  }),
};

特定テストのみ実行

# cookie-banner テストのみ実行
npm run test -- cookie-banner

# 特定の describe ブロック
npm run test -- --testNamePattern="CookieBanner"

ウォッチモード（開発時）

npm run test -- --watch

変更を検出して自動的にテストを再実行します。

CI での役割

• 全テストスイートが通過することを確認
• 機能的な品質ゲート
• 既存機能の破壊（リグレッション）を防止

注意点

• テストスイートが失敗した場合、commit 禁止
• CI で再び失敗すると merge ブロック
• テストカバレッジは全機能をカバー

---

一括実行

PR 作成前の完全なチェック：

npm run format && npm run type-check && npm run test

実行順序の重要性

1. format：フォーマットを修正

npm run format

2. type-check：型エラーをチェック

npm run type-check

3. test：機能テストを実行

npm run test

理由：フォーマットエラーがあるとコードが変わり、その後の型チェックやテストに影響する可能性があるため。

---

まとめ

コマンド	対象	修正	失敗時	CI
format:check	全ファイル	×（チェックのみ）	npm run format で修正	✓
type-check	.ts/.tsx/.astro	×（チェックのみ）	ソース修正	✓
test	テストコード	×（実行のみ）	ソース修正	✓

これらのコマンドは 開発の品質を保証する重要なツールです。PR 作成前に必ず実行し、CI で自動的に再検証することで、安定したコードベースを維持しています。

Local環境のmailpitについて