設定方法

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

import { defineConfig } from 'astro/config'

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

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

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

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

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

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

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

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

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

{
  srcDir: './www'
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

動的ルートと静的ルートの両方をリダイレクトできますが、同じ種類のルートにのみリダイレクトできます。たとえば、'/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',
    },
  }
}

データ型: string

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

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

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

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

{
  compressHTML: false
}

データ型: 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には末尾のスラッシュが含まれません。

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

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

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

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

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

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

以下も参照:

• buildOptions.pageUrlFormat

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

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

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

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

データ型: AstroIntegration

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

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

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

以下も参照:

• output

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

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

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

import { defineConfig } from 'astro/config';

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

以下も参照:

• adapter

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

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

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

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

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'を設定する

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

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

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

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

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

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

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

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

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

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

{
  build: {
    assets: '_custom'
  }
}

以下も参照:

• outDir

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

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'
  }
}

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

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

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

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

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

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

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

{
  build: {
    redirects: false
  }
}

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

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

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

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

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

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

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

データ型: 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 })
}

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

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

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

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

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

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

{
  server: { port: 8080 }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

リモート画像の最適化を許可する画像ソース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つの階層のサブルートのみを許可するには、’/*‘で終わります。

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

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

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

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

データ型: Partial<ShikiConfig>

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

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

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

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

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

データ型: RemarkPlugins

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

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

データ型: RehypePlugins

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

import rehypeMinifyHtml from 'rehype-minify';
{
  markdown: {
    rehypePlugins: [rehypeMinifyHtml]
  }
}

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

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

{
  markdown: {
    gfm: false,
  }
}

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

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

{
  markdown: {
    smartypants: false,
  }
}

データ型: 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に追加の設定項目を渡します。Astroがサポートしていない高度な設定が必要になった場合に有用です。

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

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

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

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

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

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

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

{
  experimental: {
    optimizeHoistedScript: true,
  },
}