Astroの設定

プロジェクトにastro.config.mjsファイルを追加することで、Astroの動作をカスタマイズできます。これはAstroプロジェクトではよく使われるファイルで、公式のサンプルテンプレートやテーマはすべて、デフォルトでこのファイルを含んでいます。

📚 サポートされているすべてのオプションの概要については、AstroのAPI設定リファレンスをお読みください。

有効なAstro設定ファイルは、defaultエクスポートを使用して、設定をエクスポートします。defineConfigヘルパーを用いるのがおすすめです。

import { defineConfig } from 'astro/config'

export default defineConfig({
  // オプションをここに書きます...
  // https://docs.astro.build/ja/reference/configuration-reference/
})

defineConfig()を使うと、IDEで自動的にタイプヒントを表示できるのでおすすめですが、これはオプションです。最低限必要で、有効な設定ファイルは次のようなものです。

// 例: 最低限必要な空の設定ファイル
export default {}

Astroは、JavaScriptの設定ファイルとして、astro.config.js、astro.config.mjs、astro.config.cjs、astro.config.tsという複数のファイル形式をサポートしています。多くの場合は.mjsを、設定ファイルをTypeScriptで記述する場合は.tsを使用することをおすすめします。

TypeScriptの設定ファイルの読み込みは、tsmを使って処理され、プロジェクトのtsconfigのオプションを尊重します。

Astroは、プロジェクトルート内にあるastro.config.mjsという名前の設定ファイルを自動的に使用しようとします。プロジェクトルートに設定ファイルがない場合、Astroのデフォルトのオプションが使用されます。

# 例: ./astro.config.mjs から設定を読み込みます。 
astro build

--configフラグを使用して、使用する設定ファイルを明示的に設定できます。このCLIフラグは、常にastroコマンドを実行した現在の作業ディレクトリから相対パスで指定されます。

# 例: このファイルから設定を読み込みます。
astro build --config my-config-file.js

Astroでは、設定ファイルにdefineConfig()ヘルパーを使用することをおすすめします。defineConfig()はIDEに自動的にインテリセンスを提供します。VSCodeのようなエディタは、設定ファイルがTypeScriptで書かれていなくても、AstroのTypeScriptの型定義を読み込んで、自動的にjsdocの型ヒントを提供してくれます。

import { defineConfig } from 'astro/config'

export default defineConfig({
  // オプションをここに書きます...
  // https://docs.astro.build/ja/reference/configuration-reference/
})

また、以下のJSDoc記法を用いてVSCodeに手動で型定義を提供できます。

export default /** @type {import('astro').AstroUserConfig} */ {
  // オプションをここに書きます...
  // https://docs.astro.build/ja/reference/configuration-reference/
}

rootまたは--rootフラグで相対パスを指定すると、astroコマンドを実行した現在の作業ディレクトリを起点として、指定した相対パスを解決します。

import { defineConfig } from 'astro/config'

export default defineConfig({
  // 現在の作業ディレクトリにある "./foo"ディレクトリを指します。
  root: 'foo'
})

Astroは、他のすべての相対ファイルおよび相対ディレクトリを、プロジェクトルートからの相対パスとして解決します。

import { defineConfig } from 'astro/config'

export default defineConfig({
  // 現在の作業ディレクトリにある "./foo"ディレクトリを指します。
  root: 'foo',
  // 現在の作業ディレクトリの "./foo/public" ディレクトリを指します。
  publicDir: 'public',
})

設定ファイルから相対的にファイルやディレクトリを参照するには、import.meta.urlを使用します（common.jsのastro.config.cjsファイルを記述する場合を除きます）。

import { defineConfig } from 'astro/config'

export default defineConfig({
  // この設定ファイルからの相対パスで、"./foo"ディレクトリを指します。
  root: new URL("./foo", import.meta.url),
  // この設定ファイルから相対パスで、"./public "ディレクトリを指します。
  publicDir: new URL("./public", import.meta.url),
})

インポートしたJavaScriptやCSSファイルなど、Astroが処理するコードについては、astro.config.*ファイルのvite.build.rollupOptionsでentryFileNames、chunkFileNames、assetFileNamesを用いて出力するファイル名をカスタマイズできます。

import { defineConfig } from 'astro/config'

export default defineConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          entryFileNames: 'entry.[hash].js',
          chunkFileNames: 'chunks/chunk.[hash].js',
          assetFileNames: 'assets/asset.[hash][extname]',
        },
      },
    },
  },
})

これは、広告ブロッカーの影響を受ける可能性のある名前のスクリプト（たとえばads.jsやgoogle-tag-manager.js）がある場合に役に立ちます。

Astroは他のファイルをロードする前に設定ファイルを評価します。そのため、import.meta.envは使えず、また.envファイルによってセットされた環境変数の取得もできません。

設定ファイルの中でprocess.envを使用して、CLIによりセットされたものなど、その他の環境変数の取得は可能です。

📚 サポートされているすべての設定オプションの概要については、AstroのAPI設定リファレンスを参照してください。