設定方法

次のリファレンスはAstroでサポートされているすべての設定項目をカバーしています。Astroの設定についてもっと知りたい場合は、Astroの設定の解説を確認してください。

astro.config.mjs

import { defineConfig } from 'astro/config'

export default defineConfig({
  // 設定項目をここに追加します
})

トップレベルのオプション

root

データ型: string
CLI: --root
デフォルト値: "." (現在の作業ディレクトリ)

このオプションはプロジェクトルート以外のディレクトリでastroのCLIコマンドを実行するときにのみ指定する必要があります。Astroは設定ファイルを見つける前にプロジェクトルートを知る必要があるため、通常このオプションは Astroの設定ファイルではなくCLI経由で指定されます。

--root: './my-project'のように相対パスを渡した場合、Astroは現在の作業ディレクトリを起点として相対パスを解決します。

例

{
  root: './my-project-directory'
}

$ astro build --root ./my-project-directory

srcDir

データ型: string
デフォルト値: "./src"

Astroがサイトを読み込むディレクトリを設定します。

ファイルシステムの絶対パスかプロジェクトルートからの相対パスのどちらかを指定します。

{
  srcDir: './www'
}

publicDir

データ型: string
デフォルト値: "./public"

静的アセットを置くディレクトリを設定します。このディレクトリのファイルは開発環境では/で配信され、ビルド時にはビルド用のディレクトリにコピーされます。これらのファイルは変換、バンドルされることはなく、常にそのままの状態で配信、コピーされます。

ファイルシステムの絶対パスかプロジェクトルートからの相対パスのどちらかを指定します。

{
  publicDir: './my-custom-publicDir-directory'
}

outDir

データ型: string
デフォルト値: "./dist"

astro buildコマンドがビルドの最終成果物を出力するディレクトリを設定します。

ファイルシステムの絶対パスかプロジェクトルートからの相対パスのどちらかを指定します。

{
  outDir: './my-custom-build-directory'
}

cacheDir

データ型: string
デフォルト値: "./node_modules/.astro"

ビルド成果物をキャッシュするディレクトリを設定します。このディレクトリのファイルは、ビルド時間を短縮するために以降のビルドで使用されます。

ファイルシステムの絶対パスかプロジェクトルートからの相対パスのどちらかを指定します。

{
  cacheDir: './my-custom-cache-directory'
}

redirects

データ型: Record.<string, RedirectConfig>
デフォルト値: {}

追加： astro@2.9.0

リダイレクトのマッピングを指定します。マッチするルートをキーに、リダイレクト先のパスを値にします。

動的ルートと静的ルートの両方をリダイレクトできますが、同じ種類のルートにのみリダイレクトできます。たとえば、'/article': '/blog/[...slug]' のようなリダイレクトはできません。

{
  redirects: {
    '/old': '/new',
    '/blog/[...slug]': '/articles/[...slug]',
  }
}

アダプターをインストールせずに静的に生成されたサイトでは、<meta http-equiv="refresh">タグによるクライアントリダイレクトを生成し、ステータスコードはサポートされません。

SSRの使用時か、output: staticモードで静的アダプターを使用している場合は、ステータスコードがサポートされます。AstroはリダイレクトされるGETリクエストにはステータスコード301を、その他のリクエストメソッドにはステータスコード308を使用します。

リダイレクトのステータスコードは、リダイレクトの設定でオブジェクトを使用してカスタマイズできます。

{
  redirects: {
    '/other': {
      status: 302,
      destination: '/place',
    },
  }
}

site

データ型: string

最終的にデプロイされるURLです。Astroはビルドの最後にサイトマップとcanonicalタグのURLを生成するためにこの完全なURLを使用します。Astroを最大限活用するためにこの値を設定することを強く推奨します。

{
  site: 'https://www.my-site.dev'
}

compressHTML

データ型: boolean
デフォルト値: true

HTML出力をミニファイし、HTMLファイルのサイズを小さくするためのオプションです。デフォルトでは、Astroは.astroコンポーネントのHTMLから改行を含む空白を削除します。これは開発モードと最終ビルドの両方で発生します。HTMLの圧縮を無効にするには、compressHTMLフラグをfalseに設定します。

{
  compressHTML: false
}

base

データ型: string

デプロイ先のベースパスです。Astroは、開発時と本番ビルドの両方で、このパスをページとアセットのルートとして使用します。

以下の例では、astro devコマンドは/docsでサーバーを起動します。

{
  base: '/docs'
}

このオプションを使用する場合、静的アセットのインポートとURLには、指定したベースをプレフィックスとして追加する必要があります。この値はimport.meta.env.BASE_URLでアクセスできます。

import.meta.env.BASE_URLの値は、trailingSlashの設定に従います。明示的にスラッシュを含めるか、trailingSlash: "always"が設定されている場合は、末尾にスラッシュが含まれます。trailingSlash: "never"が設定されている場合は、baseにスラッシュが含まれていても、BASE_URLには末尾のスラッシュが含まれません。

trailingSlash

データ型: 'always' | 'never' | 'ignore'
デフォルト値: 'ignore'

開発サーバーのルーティングをマッチさせる動作の設定をします。次のオプションから選択してください。

• 'always' - 末尾にスラッシュを含むURLにのみマッチします。（例: “/foo/“）
• 'never' - 末尾にスラッシュを含むURLにはマッチしない。（例: “/foo”）
• 'ignore' - URLの末尾に”/“があるかどうかに関係なくマッチします。

本番用ホストが末尾のスラッシュの有無を厳格に扱う場合に、この設定項目を使用してください。

開発中に末尾のスラッシュの有無によりURLが動作しないようにしたい場合にも、このオプションを設定できます。

{
  // 例: 開発時に末尾のスラッシュを必須にする
  trailingSlash: 'always'
}

以下も参照:

• buildOptions.pageUrlFormat

scopedStyleStrategy

データ型: 'where' | 'class' | 'attribute'
デフォルト値: 'attribute'

追加： astro@2.4

Astroコンポーネント内のスタイルをスコープするための戦略を指定します。次のオプションから選択してください。

• 'where' - :whereセレクターを使用し、詳細度（specificity）は増加しません。
• 'class' - クラスベースのセレクターを使用し、詳細度は1だけ増加します。
• 'attribute' - data-属性を使用し、詳細度は増加しません。

'class'を使用すると、Astroコンポーネント内の要素セレクターが（たとえばグローバルスタイルシートの）グローバルスタイルのデフォルトを上書きすることを保証できます。'where'を使用すると、詳細度をより細かく制御できますが、より高い詳細度のセレクター、レイヤー、その他のツールを使用して、適用されるセレクターを制御する必要があります。'attribute'を使用すると、要素のclass属性を操作し、自分のスタイルロジックとAstroの適用するスタイルとの間の競合を回避する必要がある場合に便利です。

adapter

データ型: AstroIntegration

ビルドアダプターにより、好みのサーバー、サーバーレス、エッジのホストにデプロイできます。NetlifyやVercelなどのファーストパーティーのアダプターをインポートし、AstroのSSRを活用しましょう。

SSRについて詳しくはサーバーサイドレンダリングのガイドを、ホストの完全な一覧はデプロイのガイドを確認してください。

import netlify from '@astrojs/netlify/functions';
{
  // 例: Netlifyのサーバーレスデプロイのためにビルドする
  adapter: netlify(),
}

以下も参照:

• output

output

データ型: 'static' | 'server' | 'hybrid'
デフォルト値: 'static'

ビルドの出力対象を指定します。

• 'static' - 静的ホストにデプロイするための静的サイトをビルドします。
• 'server' - SSR (サーバーサイドレンダリング) をサポートするホストにデプロイするためのアプリをビルドします。
• 'hybrid' - サーバーサイドレンダリングするページを一部含んだ静的サイトをビルドします。

import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static'
})

以下も参照:

• adapter

ビルドのオプション

build.format

データ型: ('file' | 'directory')
デフォルト値: 'directory'

各ページの出力ファイルの形式を制御します。

• 'file'が指定された場合、Astroは”/foo.html”のように、各ページに対応するHTMLファイルを生成します。
• 'directory'が指定された場合、Astroは”/foo/index.html”のように、ディレクトリを生成しページに対応するindex.htmlファイルをネストします。

{
  build: {
    // 例: ビルド時に`page/index.html`ではなく`page.html`を生成します。
    format: 'file'
  }
}

Astro.urlへの影響

build.formatの値によって、ビルド時にAstro.urlに設定される値が変わります。

• directoryの場合 - Astro.url.pathnameは、フォルダの挙動を模倣するために、/foo/のように末尾にスラッシュを含みます。
• fileの場合 - Astro.url.pathnameは、/foo.htmlのように.htmlを含みます。

これにより、new URL('./relative', Astro.url)を使用して相対URLを作成すると、開発時とビルド時で一貫した動作となります。

開発時の末尾のスラッシュの挙動を一貫させるために、ビルドフォーマットに応じてtrailingSlashオプションを'always'または'never'に制限できます。

• directoryの場合 - trailingSlash: 'always'を設定する
• fileの場合 - trailingSlash: 'never'を設定する

build.client

データ型: string
デフォルト値: './dist/client'

output: 'server'またはoutput: 'hybrid'の場合にのみ、クライアントサイドのCSSとJavaScriptの出力ディレクトリを制御します。outDirはコードがビルドされる場所を制御します。

outDirに対する相対パスを指定します。

{
  output: 'server', // または'hybrid'
  build: {
    client: './client'
  }
}

build.server

データ型: string
デフォルト値: './dist/server'

SSRのビルド時にサーバーJavaScriptの出力ディレクトリを制御します。

outDirに対する相対パスを指定します。

{
  build: {
    server: './server'
  }
}

build.assets

データ型: string
デフォルト値: '_astro'

追加： astro@2.0.0

バンドルされたJSやCSSなどのAstroが生成したアセットが、ビルド出力先のどのディレクトリに配置されるかを指定します。

{
  build: {
    assets: '_custom'
  }
}

以下も参照:

• outDir

build.assetsPrefix

データ型: string
デフォルト値: undefined

追加： astro@2.2.0

Astroが生成したアセットへのリンクのプレフィックスを指定します。アセットが現在のサイトとは異なるドメインから提供されている場合に使用できます。

たとえばこの値をhttps://cdn.example.comに設定すると、アセットは（baseオプションに関係なく）https://cdn.example.com/_astro/...から取得されます。アセットを配信するには、./dist/_astro/のファイルをhttps://cdn.example.com/_astro/にアップロードする必要があります。この手順はサードパーティのドメインがどのようにホストされているかによって異なります。_astroパスの名前を変更するには、build.assetsに新しいディレクトリを指定します。

{
  build: {
    assetsPrefix: 'https://cdn.example.com'
  }
}

build.serverEntry

データ型: string
デフォルト値: 'entry.mjs'

SSRのビルド時のサーバーエントリーポイントのファイル名を指定します。このエントリーポイントは、デプロイ先のホストに通常依存し、アダプターが自動的に設定します。

ランタイムがファイルをJavaScriptモジュールとして認識できるように、このファイルの拡張子は.mjsとすることをおすすめします。

{
  build: {
    serverEntry: 'main.mjs'
  }
}

build.redirects

データ型: boolean
デフォルト値: true

追加： astro@2.6.0

リダイレクトがビルド時にHTMLに出力されるかどうかを指定します。このオプションはoutput: 'static'モードでのみ適用されます。SSRでは、リダイレクトは他のレスポンスと同じように扱われます。

このオプションは、リダイレクト用の特別な設定ファイルをもち、HTMLベースのリダイレクトを必要としない・望まないアダプターによって使用されることを想定しています。

{
  build: {
    redirects: false
  }
}

build.inlineStylesheets

データ型: 'always' | 'auto' | 'never'
デフォルト値: auto

追加： astro@2.6.0

プロジェクトのスタイルがcssファイルとしてブラウザに送信されるか、<style>タグとしてインラインで送信されるかを制御します。次のオプションから選択します。

• 'always' - プロジェクトのスタイルは<style>タグにインライン化されます。
• 'auto' - ViteConfig.build.assetsInlineLimit（デフォルト: 4kb）より小さいスタイルシートのみがインライン化されます。それ以外の場合、プロジェクトのスタイルは外部のスタイルシートとして送信されます。
• 'never' - プロジェクトのスタイルは外部のスタイルシートとして送信されます。

{
  build: {
    inlineStylesheets: `never`,
  },
}

build.split

非推奨

バージョン3.0で非推奨となりました。

データ型: boolean
デフォルト値: false

ビルドの設定オプションbuild.splitは、アダプターの設定オプションfunctionPerRoute (EN)に置き換えられました。

使用しているSSRアダプターのドキュメントを参照して、functionPerRouteによりSSRコードをどのようにバンドルするかを定義してください。

build.excludeMiddleware

非推奨

バージョン3.0で非推奨となりました。

データ型: boolean
デフォルト値: false

ビルドの設定オプションbuild.excludeMiddlewareは、アダプターの設定オプションedgeMiddleware (EN)に置き換えられました。

使用しているSSRアダプターのドキュメントを参照して、edgeMiddlewareによりSSRのミドルウェアコードをビルド時にバンドルするかどうかを定義してください。

サーバーのオプション

astro devとastro previewの両方で使用される、Astroの開発サーバーをカスタマイズします。

{
  server: { port: 1234, host: true }
}

実行するコマンド（“dev”、“preview”）に応じて設定を変えるために、この設定項目に関数を渡すこともできます。

{
  // 例: コマンドに応じてカスタマイズするためには関数の構文を使用します
  server: (command) => ({ port: command === 'dev' ? 4321 : 4000 })
}

server.host

データ型: string | boolean
デフォルト値: false

追加： astro@0.24.0

localhost以外のIPなど、サーバーがリッスンするネットワークIPアドレスを設定します。

• false - ネットワークIPアドレスを公開しません。
• true - LANやパブリックなアドレスを含むすべてのアドレスでリッスンします。
• [カスタムアドレス] - 192.168.0.1などの[カスタムアドレス]のネットワークIPアドレスを公開します。

server.port

データ型: number
デフォルト値: 4321

サーバーがリッスンするポートを設定します。

設定したポートが使用されていた場合、Astroは自動的に利用可能な次のポート番号を使用しようと試みます。

{
  server: { port: 8080 }
}

server.headers

データ型: OutgoingHttpHeaders
デフォルト値: {}

追加： astro@1.7.0

astro devとastro previewで送信されるカスタムHTTPレスポンスヘッダーを設定します。

画像のオプション

image.endpoint

データ型: string
デフォルト値: undefined

追加： astro@3.1.0

画像最適化に使用するエンドポイントを設定します。undefinedを設定すると、デフォルトのエンドポイントが使用されます。

エンドポイントは常に/_imageに挿入されます。

{
  image: {
    // 例: カスタム画像エンドポイントを使用する
    endpoint: './src/image-endpoint.ts',
  },
}

image.service

データ型: Object
デフォルト値: {entrypoint: 'astro/assets/services/sharp', config?: {}}

追加： astro@2.1.0

どの画像サービスをAstroのアセットサポートで使用するかを設定します。

画像サービスが使用するエントリーポイントを含むオブジェクトを指定する必要があります。オプションで、サービスに渡す設定用オブジェクトを含めることもできます。

サービスのエントリーポイントは、組み込みのサービスかサードパーティのパッケージのどちらかを指定できます。

{
  image: {
    // 例: Sharpをベースとした画像サービスを有効にする
    service: { entrypoint: 'astro/assets/services/sharp' },
  },
}

image.domains

データ型: Array.<string>
デフォルト値: {domains: []}

追加： astro@2.10.10

リモート画像の最適化を許可する画像ソースドメインのリストを定義します。Astroは、その他のリモート画像を最適化しません。

このオプションにはドメイン名の文字列の配列を指定します。ワイルドカードは許可されません。許可されたソースURLパターンのリストを定義するにはimage.remotePatternsを使用してください。

astro.config.mjs

{
  image: {
    // 例: リモート画像の最適化を単一のドメインに対して許可する
    domains: ['astro.build'],
  },
}

image.remotePatterns

データ型: Array.<RemotePattern>
デフォルト値: {remotePatterns: []}

追加： astro@2.10.10

リモート画像の最適化を許可する画像ソースURLパターンのリストを定義します。

remotePatternsは4つのプロパティで設定します。

1. プロトコル（protocol）
2. ホスト名（hostname）
3. ポート（port）
4. パス名（pathname）

{
  image: {
    // 例: s3バケットのすべての画像に対して処理を許可する
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.amazonaws.com',
    }],
  },
}

以下のように、許可されたhostnameとpathnameの値を定義するためにワイルドカードを使用できます。それ以外の場合、指定された値のみがそのまま設定されます。 hostname:

• すべてのサブドメインを許可するには、’**.’で始めます（‘endsWith’を使う）。
• 1つの階層のサブドメインのみを許可するには、’*.’で始めます。

pathname:

• すべてのサブルートを許可するには、’/**‘で終わります（‘startsWith’を使う）。
• 1つの階層のサブルートのみを許可するには、’/*‘で終わります。

マークダウンのオプション

markdown.drafts

Deprecated

バージョン3.0で非推奨となりました。コンテンツコレクションを使用してください。

データ型: boolean
デフォルト値: false

マークダウンのドラフトページがビルドに含まれるかを制御します。

マークダウンページがフロントマターにdraft: trueを含む場合、ドラフトとみなされます。ドラフトページは開発環境（astro dev）では常に含まれ、閲覧できますが、デフォルトでは最終的なビルドに含まれません。

{
  markdown: {
    // 例: 最終的なビルドにドラフトをすべて含む
    drafts: true,
  }
}

markdown.shikiConfig

データ型: Partial<ShikiConfig>

Shiki の設定項目です。使い方はマークダウンの設定のドキュメントを確認してください。

markdown.syntaxHighlight

データ型: 'shiki' | 'prism' | false
デフォルト値: shiki

使用するシンタックスハイライトを設定します。

• shiki - Shikiのハイライトを使用します。
• prism - Prismのハイライトを使用します。
• false - シンタックスハイライトを使用しません。

{
  markdown: {
    // 例: マークダウンでprismのシンタックスハイライトを使用するよう変更する
    syntaxHighlight: 'prism',
  }
}

markdown.remarkPlugins

データ型: RemarkPlugins

マークダウンのビルドの仕方をカスタマイズするためにRemarkのプラグインを渡します。プラグインの関数をインポートして適用する（推奨）か、プラグインの名前を文字列として渡します。

import remarkToc from 'remark-toc';
{
  markdown: {
    remarkPlugins: [remarkToc]
  }
}

markdown.rehypePlugins

データ型: RehypePlugins

マークダウンのビルドの仕方をカスタマイズするためにRehypeのプラグインを渡します。プラグインの関数をインポートして適用する（推奨）か、プラグインの名前を文字列として渡します。

import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
{
  markdown: {
    rehypePlugins: [rehypeAccessibleEmojis]
  }
}

markdown.gfm

データ型: boolean
デフォルト値: true

追加： astro@2.0.0

AstroはGitHub風のマークダウンをデフォルトで使用します。これを無効にするには、gfmフラグをfalseに設定します。

{
  markdown: {
    gfm: false,
  }
}

markdown.smartypants

データ型: boolean
デフォルト値: true

追加： astro@2.0.0

AstroはSmartyPantsのフォーマッターをデフォルトで使用します。これを無効にするには、smartypantsフラグをfalseに設定します。

{
  markdown: {
    smartypants: false,
  }
}

markdown.remarkRehype

データ型: RemarkRehype

remark-rehypeにオプションを渡します。

{
  markdown: {
    // 例: 脚注のテキストを別の言語に翻訳します。ここではデフォルトの英語の値を示します。
    remarkRehype: { footnoteLabel: "Footnotes", footnoteBackLabel: "Back to content"},
  },
};

インテグレーション

カスタムインテグレーションでAstroを拡張します。インテグレーションは、Solid.jsなどのフレームワークのサポート、サイトマップなどの新しい機能、PartytownやTurbolinksなど新しいライブラリの追加を一手に担います。

Astro のインテグレーションを使い始めるためにはインテグレーションガイドを確認してください。

import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
{
  // 例: Astro にReactとTailwindのサポートを追加
  integrations: [react(), tailwind()]
}

Vite

Viteに追加の設定項目を渡します。Astroがサポートしていない高度な設定が必要になった場合に有用です。

viteに設定するオブジェクトの完全なドキュメントはvitejs.devを確認してください。

例

{
  vite: {
    ssr: {
      // 例: 必要な場合、壊れたパッケージがSSRの処理を行うのをスキップさせます
      external: ['broken-npm-package'],
    }
  }
}

{
  vite: {
    // 例: Astroプロジェクトにカスタムのviteプラグインを直接追加する
    plugins: [myPlugin()],
  }
}

レガシーなフラグ

Astroのバージョン間の移行を支援するために、legacyフラグを導入することがあります。これらのフラグを使用すると、最新バージョンのAstroでも非推奨または古い動作を有効化できるため、Astroの新しいリリースにアップグレードして引き続き利用できます。

実験的なフラグ

Astroは、ユーザーが新しい機能に早期にアクセスできるように、実験的なフラグを提供しています。これらのフラグは安定しているとは限りません。

experimental.optimizeHoistedScript

データ型: boolean
デフォルト値: false

追加： astro@2.10.4

使用されていないコンポーネントのスクリプトが予期せずページに含まれるのを防ぎます。この最適化はベストエフォートであり、逆に使用されているスクリプトが含まれなくなる可能性もあります。ページを公開する前にビルドされた内容をしっかり確認してください。巻き上げられた（hoisted）スクリプトの解析の最適化を有効にするには、以下の実験的なフラグを追加します。

{
  experimental: {
    optimizeHoistedScript: true,
  },
}