Zenn
😅

Astro最初のつまずきメモ

に公開
TypeScript
tech

初めに

備忘録なので役に立たない情報かもしれません
Astro を初めて使うと「ドキュメント通りに書いたはずなのに動かない…」とつまずきがちです。ここでは筆者自身が遭遇した“初段”のトラブル事例を3つピックアップし、原因とナイスハックをお届けします。

1. frontmatter（YAML ヘッダー）を忘れる

症状

[error] Could not parse frontmatter.

新規 .astro ファイルを追加しても画面が白紙のまま。ターミナルに上記エラー。

原因

Astro はページ冒頭に --- で囲んだ frontmatter が必須。内容が不要でも「空の frontmatter」がないと処理が中断します。

解決策＆ワンポイント

---
---
<html>
  <body>
    <h1>Hello, Astro!</h1>
  </body>
</html>
  • Tip: 最初から空 frontmatter を書いておけば、後からタイトルやレイアウト指定を追加しやすくなります。

2. コンポーネント import が解決できない

症状

[error] Failed to resolve import "../components/Header.astro"

ローカルでは動作したのに、CI や本番（Linux）でエラーになる。

原因

  1. ファイル名の大文字／小文字不一致
  2. 相対パスが深すぎて間違いやすい

解決策＆コツ

  1. ケースを正確に合わせる
    macOS では通っても、Linux 環境ではファイル名の大文字小文字がシビアです。

  2. パスエイリアスを導入
    tsconfig.json（または jsconfig.json）にエイリアスを設定すると、可読性が大幅アップ。

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@components/*": ["src/components/*"]
    }
  }
}

---
// src/pages/index.astro
import Header from "@components/Header.astro";
---
<Header />

3. TypeScript の型定義が効かない

症状

Property 'title' does not exist on type '{}' in Astro.props

渡した props が空のオブジェクトとして扱われ、型エラーが発生する。

原因

デフォルトでは Astro.props の型が {} に固定されています。

解決策＆おすすめ設定

  • Astro v3.4+ の defineProps を活用：
---ts
export interface Props { title: string; }
const { title } = Astro.props<Props>();
---
<h1>{title}</h1>
  • プロジェクト全体で型共有 したい場合は、global.d.ts にインターフェースを宣言：
// src/global.d.ts
declare namespace Astro {
  interface Props { title: string; }
}

このひと手間で .astro ファイル内の型補完がスムーズになります。

おわりに

ここまで紹介した3つは、Astro 入門時によくぶつかるトラップです。一度クリアすれば快適さを実感できるはず。今後は公式ドキュメントやコミュニティの記事も参照しながら、自分なりのベストプラクティスを構築しませう。

Discussion