update | 2026.08.19

Astro x microcms JAMSTACKブログ構築 - 環境設定

  • ホーム
  • Astro x microcms JAMSTACKブログ構築 - 環境設定
Astro x microcms JAMSTACKブログ構築 - 環境設定
目次

前回は「👈 Astro x microcms JAMSTACKブログ構築 - 方向性・デザイン」

環境ファイルを再確認

オフィシャルサイトを参考

参照元：https://blog.microcms.io/astro5-microcms-introduction
blog.microcms.io

このサイト用に変更を加えた部分の覚書き

  • tsconfig.json
  • .env
  • astro.config.mjs
  • env.d.ts

tsconfig.json

Astroにおける tsconfig.json は、一言で言うと「TypeScript（およびAstro独自のコンポーネントコード）を安全に、そして快適に開発するためのルールブック」です。

AstroはデフォルトでTypeScriptをサポートしているため、このファイルがあることでエディタ（VS Codeなど）がコードのバグを瞬時に教えてくれたり、便利な入力補完を提供してくれたりします。

具体的な主な役割は以下の3つです。

1.Astro特有のコード（.astroファイル）を認識させる

これが最も重要な役割の一つです。 通常、TypeScriptは .ts や .tsx という拡張子しか理解できません。しかし、tsconfig.json でAstro用の設定を読み込むことで、「.astro という特殊なファイルの中に書かれたTypeScriptや、コンポーネントのProps（型）も正しくチェックしてね」とエディタに伝えることができます。

これがないと、VS Codeで .astro ファイルを開いたときに、1行目から赤線（エラー）だらけになってしまいます。

2.インポートのパスをスッキリさせる（パスエイリアス）

// 😭 パスが長くて見づらい、階層が変わると壊れる
import Button from '../../../../components/ui/Button.astro';
"paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@layouts/*": ["src/layouts/*"],
      "@assets/*": ["src/assets/*"],
      "@scss/*": ["src/scss/*"]

これを設定しておくと、プロジェクト内のどこからでも以下のようにスッキリ記述できるようになります。

// 😎 どこから呼んでもこの1行でスマートに完結！
import Header from "@layouts/Header.astro";
import Footer from "@layouts/Footer.astro";

3.エディタのコードチェックの「厳しさ」を決める

「型のエラーをどれくらい厳密にチェックするか」の難易度を設定します。 例えば、"strict": true（厳格モード）に設定すると、「データが空（null）になる可能性を考慮していないコード」などに対してエディタが事前に警告を出してくれます。

これにより、「ローカルで開発しているときは動いていたのに、microCMSから予期せぬデータが届いて本番サイトがクラッシュした」というような事故を、ビルド前に未然に防ぐことができます。

{
  // Astro公式が推奨するTypeScriptの基本設定を丸ごと継承
  "extends": "astro/tsconfigs/strict", 
  
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"] // よく使われるsrcフォルダへのショートカット設定
    }
  }
}

.env

Astroにおける .env ファイルは、「外部に漏れてはいけない重要な秘密情報（APIキーなど）」や「開発環境と本番環境で切り替えたい設定」を、安全に管理するための隠し小箱です。

microCMSを使った開発では、絶対に手放せない超重要ファイルになります。

具体的な役割と、Astroならではの特徴を3つに分けて解説します。

1. 重要な認証情報を「隠す」（セキュリティ）

microCMSからデータを取得するには、X-MICROCMS-API-KEY というパスワードのようなもの（APIキー）が必要です。

もし、このキーをコード内に直接書いてしまうと、GitHubなどの共有リポジトリにそのままアップロードされ、世界中に公開されてしまう危険があります（最悪の場合、データを勝手に書き換えられたり消されたりします）。

.env に書いておけば、その情報はローカル（自分のパソコン）の中にだけ保存され、コード上には残りません。

MICROCMS_SERVICE_DOMAIN=your-space-domain
MICROCMS_API_KEY=abcdefg1234567890

⚠️ 超重要: .env ファイルはGitHubにアップロードされないよう、必ず .gitignore ファイルに登録して除外してください。

2.フロントエンド（ブラウザ）に漏洩するのを自動で防ぐ

Astroはセキュリティに非常に厳しく、デフォルトでは .env に書いた値はブラウザ側（JavaScript）からは一切見えないようになっています（サーバーサイドのビルド時のみ読み込める）。

もし「検索窓の機能（Pagefindなど）で、どうしてもブラウザ側からもAPIキーや特定の変数にアクセスしたい！」という場合は、変数の頭に PUBLIC_ をつけるというルールがあります。

# サーバー（Astro）しか読めない（microCMSのキーなどに使う） 
MICROCMS_API_KEY=secret_abc123
# ブラウザ側からもアクセスできる
PUBLIC_ANALYTICS_ID=ga_98765

このように、名前の付け方ひとつで誤って機密情報がブラウザに漏れるのを防いでくれる仕組みになっています。

3.Astroのコード内で呼び出す方法

.env に書いた値は、Astro（Vite）の仕組みを使ってコード内で以下のように呼び出します。

---
// src/pages/index.astro などのフロントマター（--- の中）で呼び出す場合
const apiKey = import.meta.env.MICROCMS_API_KEY;
const domain = import.meta.env.MICROCMS_SERVICE_DOMAIN;

// これを使ってmicroCMSのSDKを初期化したり、fetchを叩いたりする
---

昔のNode.jsでよく使われていた process.env.XXX ではなく、import.meta.env.XXX を使うのがAstro（Vite）の標準スタイルです。

astro.config.mjs

Astroにおける astro.config.mjs は、一言で言うと「プロジェクト全体の挙動や機能をカスタマイズする、最高権限を持ったコントロールパネル（司令塔）」です。

先ほど復習したように、ベースURLの変更やSassの設定、拡張機能（プラグイン）の導入などはすべてここで行います。

1. プロジェクトの「基本ルール」を決める

Webサイトをどのようにビルド（出力）するか、URLの形をどうするかといった、サイトの根本的な挙動を設定します。

  • URLの末尾：/about にするか、常に /about/ に統一するか（trailingSlash）
  • 出力形式：静的なHTMLファイルとして書き出すか、サーバーで動的に動かすか（SSG / SSR の切り替え）
  • 配置場所：サイトをドメインの直下に置くか、サブディレクトリに置くか（base）

これらを1箇所で一元管理するのがメインの役割です。

2. 外部機能（インテグレーション）を合体させる

Astroは標準状態だと非常にシンプルですが、astro.config.mjs の integrations という項目を使うことで、強力な機能をボタン一つで追加するように合体（インテグレーション）させることができます。

  • icon()アイコンを簡単に扱えるようにする
  • preact()React系のコンポーネントをAstroで動かせるようにする
  • pagefind()サイト内に爆速の検索機能を埋め込む

他にも、サイトマップを自動生成する機能（@astrojs/sitemap）や、Tailwind CSSを使えるようにする機能なども、すべてこのファイルに1行追記するだけで有効化されます。

他にも、サイトマップを自動生成する機能（@astrojs/sitemap）や、Tailwind CSSを使えるようにする機能なども、すべてこのファイルに1行追記するだけで有効化されます。

3. 裏方ツール（Vite）のチューニング

Astroは内部で Vite（バイト） という超高速なビルドツールを使って、JavaScriptやCSS、画像を処理しています。

astro.config.mjs の中に vite: { ... } という項目を書くことで、Astroを通じてViteに直接指示を出すことができます。

  • 「CSSに自動でベンダープレフィックスをつけて！」（Autoprefixer）
  • 「すべてのコンポーネントで、共通のSassのmixinを使えるように自動で読み込んどいて！」（additionalData）

といった高度なアセット（素材）の最適化設定は、すべてこの役割のおかげで実現しています。


最終的なコード

export default defineConfig({
  // 💡 サイトのベースとなるパス（ルート相対パス）。通常はデフォルトの "/" でOK。
  // もしGitHub Pagesなどで「username.github.io/my-blog/」のようにサブディレクトリで運用する場合は、ここを "/my-blog/" に変更。
  base: "/",

  trailingSlash: "always", // URL末尾に常にスラッシュを付与する（例: /about/）

  build: {
    //format: "file",
    format: "directory", // ディレクトリ形式でビルドする（例: about.astro -> about/index.html を生成）
    inlineStylesheets: "always", // 💡 CSSをHTML内に自動でインライン化（埋め込み）し、レンダリングブロックを解消する
  },

  // 💡 Astroに組み込む拡張機能（プラグイン）の配列
  // icon: アイコン（SVG等）の最適化・共通化
  // preact: 軽量なUIライブラリ「Preact」コンポーネントをAstro内で動かすための機能
  // pagefind: 爆速で動く静的サイト向けの全文検索エンジン（ビルド時にインデックスを自動生成）
  integrations: [icon(), preact(), pagefind()],

  // 開発ツールバーを無効化（ローカル開発時に画面下に表示されるAstroのメニューバーを非表示にする）
  devToolbar: {
    enabled: false,
  },

  // 💡 Astroの裏側で動いているビルドツール「Vite（バイト）」のカスタマイズ設定
  vite: {
    build: {
      // 💡 アセット（画像やフォントなど）をBase64文字列としてHTML/CSSに埋め込む上限サイズ（バイト数）。
      // ここを 0 にすることで、小さな画像であってもインライン化せず、必ず独立したファイルとして出力させます（キャッシュの効率化などに有効）。
      assetsInlineLimit: 0,
    },
    css: {
      postcss: {
        // 💡 CSSのベンダープレフィックス（-webkit- や -moz- など）を、ターゲットブラウザに合わせて自動付与する設定
        plugins: [autoprefixer()],
      },
      preprocessorOptions: {
        scss: {
          // 💡 すべての .scss / .astro 内の <style lang="scss"> に対して、自動的に指定のSassファイルを読み込ませる設定。
          // これにより、各コンポーネントで毎回 `@use "..."` を書かなくても、共通の変数や mixin、共通クラス（c-list）がどこでも使えるようになります。
          // `fileURLToPath` を使うことで、OS（Windows/Mac等）によるパス表記の違いによるエラーを防いでいます。
          additionalData: `
            @use "${fileURLToPath(new URL("./src/scss/_mixin.scss", import.meta.url))}" as mixin;
            @use "${fileURLToPath(new URL("./src/scss/_c-list.scss", import.meta.url))}" as c-list;
          `,
        },
      },
    },
  },
});
  1. inlineStylesheets: "always" と assetsInlineLimit: 0 のバランス - この構成では、「CSSはHTML内に全部埋め込んで一瞬で画面を表示させる（FCPの最適化）」一方で、「画像やアイコンなどのアセットは一切HTMLに埋め込まずに別ファイルにしてブラウザキャッシュを効かせる」という、メリハリの利いたパフォーマンスが取られている。
  2. additionalData の恩恵 - このSassの自動インポート設定があるおかげで、コンポーネント側のコードは相対パスだらけにならずにクリーンな状態を保てている。

env.d.ts

Astroにおける env.d.ts は、一言で言うと「.env に書いた秘密の変数（環境変数）を、TypeScriptに『こういう名前のデータがあるよ』と教えてあげるための通訳（型定義ファイル）」です。

末尾の .d.ts の「d」は Declaration（宣言） の略で、プログラムの実体ではなく「型（データの中身のルール）」だけを宣言するTypeScript専用のファイルになります。

このファイルがなぜ必要なのか、2つの重要な役割は以下の通り。

1. import.meta.env.XXXX の入力補完（サジェスト）を効かせる

Astroで .env に定義した変数（例：MICROCMS_API_KEY）をコード内で使おうとして、import.meta.env. まで打ち込んだとき、エディタが自動で候補を出してくれる。

env.d.ts にその変数の名前と型（string など）を登録しておくことで、VS Codeなどのエディタが完全に理解し、タイポ（打ち間違い）をゼロにしてくれます。

// 💡 ここに .env で使う環境変数の「型」を定義する
interface ImportMetaEnv {
  readonly MICROCMS_SERVICE_DOMAIN: string;
  readonly MICROCMS_API_KEY: string;
  readonly PUBLIC_ANALYTICS_ID?: string; // ? をつけると「無いかもしれない」というオプショナルな意味に
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

これを書いておくと、コード内で import.meta.env.MIC... と打った時点で、エディタが MICROCMS_API_KEY をピタッと予測候補に出してくれるようになります。

最初の1行目にある /// <reference types="astro/client" />

stroプロジェクトを作ると、最初から env.d.ts の先頭にこの不思議な1行が書かれています。これはめちゃくちゃ重要な記述です。

これがあるおかげで、Astro特有の便利な機能（画像をインポートしたときの型や、Client-sideの機能など）がTypeScript全体に認識されます。この1行は絶対に消さないように注意してください。

設定ファイル・関係性まとめ

  1. .env 「APIキーは abcdefg... 」（データを隠して保持）
  2. env.d.ts 「TypeScript、MICROCMS_API_KEY は文字（string）データである」（型を教える）
  3. tsconfig.json 「了解。env.d.ts のルール通りにエディタで入力補完を出す」（エディタのルール設定）
  4. astro.config.mjs （この裏でViteを動かし、すべてのファイルを合体させて本番用にビルドする）

次回は「Astro x microcms JAMSTACKブログ構築 - 環境設定 👉」