@astrojs/ netlify

このアダプターを使用すると、Astroでオンデマンドでレンダリングされたルートと機能をNetlifyにデプロイできます。これには、サーバーアイランド、アクション、セッションが含まれます。

Astroを静的サイトビルダーとして使用している場合、このアダプターが必要になるのは、サーバーを必要とする追加のNetlifyサービス（Netlify Image CDNなど）を使用している場合のみです。それ以外の場合、静的サイトをデプロイするためにアダプターは必要ありません。

Netlifyデプロイガイド (EN)でAstroサイトをデプロイする方法を学びましょう。

Astro Netlifyを選ぶ理由

Netlifyは、GitHubリポジトリに直接接続してサイトをホストできるデプロイメントプラットフォームです。このアダプターは、Astroのビルドプロセスを強化し、Netlifyを介したデプロイメントのためにプロジェクトを準備します。

インストール

Astroには、公式インテグレーションのセットアップを自動化するためのastro addコマンドが含まれています。もしよろしければ、手動でインテグレーションをインストールすることもできます。

astro addコマンドでNetlifyアダプターを追加して、Astroプロジェクトでオンデマンドレンダリングを有効にします。これにより、@astrojs/netlifyがインストールされ、astro.config.mjsファイルに適切な変更が一度に行われます。

npm

npx astro add netlify

pnpm

pnpm astro add netlify

Yarn

yarn astro add netlify

これで、ページごとにオンデマンドレンダリングを有効にするか、ビルド出力設定をoutput: 'server'に設定してデフォルトですべてのページをサーバーレンダリングすることができます。

手動インストール

まず、お好みのパッケージマネージャーを使用して、Netlifyアダプターをプロジェクトの依存関係にインストールします。

npm

npm install @astrojs/netlify

pnpm

pnpm add @astrojs/netlify

Yarn

yarn add @astrojs/netlify

次に、アダプターをastro.config.*ファイルに追加します。

 import { defineConfig } from 'astro/config';
 import netlify from '@astrojs/netlify';

 export default defineConfig({
    // ...
    adapter: netlify(),
 });

使い方

デプロイガイドはこちらでご覧いただけます。 (EN)

指示に従ってサイトをローカルでビルド (EN)します。ビルド後、.netlify/フォルダーが作成され、その中には.netlify/functions-internal/フォルダーにNetlify Functionsが、.netlify/edge-functions/フォルダーにNetlify Edge Functionsが含まれます。

サイトをデプロイするには、Netlify CLIをインストールして実行します。

netlify deploy

Astroに関するNetlifyブログ投稿とNetlifyドキュメントには、このインテグレーションを使用してNetlifyにデプロイする方法に関する詳細情報が記載されています。

Netlify Edge FunctionsでAstroミドルウェアを実行する

Astroミドルウェアは、ビルド時に事前レンダリングされたページに、実行時にオンデマンドでレンダリングされたページに適用されます。

事前レンダリングされたページのリダイレクト、アクセス制御、またはカスタムレスポンスヘッダーを実装するには、middlewareModeオプション (EN)を有効にして、Netlify Edge Functionsでミドルウェアを実行します。

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    edgeMiddleware: true,
  }),
});

edgeMiddlewareが有効になっている場合、Edge functionsは、静的アセット、事前レンダリングされたページ、オンデマンドでレンダリングされたページを含むすべてのリクエストに対してミドルウェアコードを実行します。

オンデマンドでレンダリングされたページの場合、context.localsオブジェクトはJSONを使用してシリアル化され、レンダリングを実行するサーバーレス関数にヘッダーで送信されます。セキュリティ対策として、サーバーレス関数は、生成されたEdge functionsからのリクエストでない限り、403 Forbiddenレスポンスでリクエストを拒否します。

サイトからEdge Contextにアクセスする

Netlify Edge Functionsは、ユーザーのIP、地理位置情報データ、Cookieなどのリクエストに関するメタデータを含むコンテキストオブジェクトを提供します。

これはAstro.locals.netlify.contextオブジェクトを介してアクセスできます。

---
const {
  geo: { city },
} = Astro.locals.netlify.context;
---

<h1>{city}から来たフレンドリーな訪問者さん、こんにちは！</h1>

TypeScriptを使用している場合は、src/env.d.tsを更新してNetlifyLocalsを使用することで、適切な型指定を取得 (EN)できます。

type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals

declare namespace App {
  interface Locals extends NetlifyLocals {
    // ...
  }
}

これは事前レンダリングされたページでは利用できません。

Netlify Image CDNのサポート

このアダプターは、デフォルトでNetlify Image CDNを使用して、ビルド時間に影響を与えることなく画像をオンザフライで変換します。これは、内部でAstro Image Service (EN)を使用して実装されています。

NetlifyのImage CDNのリモート画像最適化をオプトアウトするには、imageCDNオプションを使用します。

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    imageCDN: false,
  }),
});

別のドメインでホストされている画像を使用している場合は、image.domains (EN)またはimage.remotePatterns (EN)設定オプションを使用して、ドメインまたはURLパターンを承認する必要があります。

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
    // ...
    adapter: netlify(),
    image: {
      domains: ['example.com'],
    },
});

詳細については、リモート画像の承認ガイド (EN)を参照してください。これは、サイトと同じドメインでホストされている画像には必要ありません。

Netlifyアダプターを使用した静的サイト

Netlifyでホストされている静的サイト（output: 'static'）の場合、通常はアダプターは必要ありません。ただし、一部のデプロイ機能はアダプターを介してのみ利用できます。

静的サイトでは、Netlifyの画像サービスを使用して設定するために、このアダプターをインストールする必要があります。

Astro設定でredirects設定を使用する場合、Netlifyアダプターを使用してこれを適切な_redirects形式に変換できます。

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify(),
  redirects: {
    '/blog/old-post': '/blog/new-post',
  },
});

astro buildを実行すると、dist/_redirectsファイルが作成されます。Netlifyは、本番環境でページを適切にルーティングするためにそれを使用します。

:::note手動リダイレクト用にpublic/_redirectsファイルをまだ含めることができます。リダイレクト設定で指定したリダイレクトは、独自のリダイレクトの末尾に追加されます。:::

セッション

Astro Sessions APIを使用すると、リクエスト間でユーザーデータを簡単に保存できます。これは、ユーザーデータや設定、ショッピングカート、認証情報などに使用できます。Cookieストレージとは異なり、データにサイズ制限はなく、別のデバイスで復元できます。

Astroは、Netlifyアダプターを使用する場合、セッションストレージ用にNetlify Blobsを自動的に設定します。別のセッションストレージドライバーを使用したい場合は、Astro設定で指定できます。詳細については、 session設定リファレンス (EN)を参照してください。

ページのキャッシュ

動的コンテンツのないオンデマンドでレンダリングされたページは、パフォーマンスを向上させ、リソース使用量を削減するためにキャッシュできます。アダプターでcacheOnDemandPagesオプションを有効にすると、すべてのサーバーでレンダリングされたページが最大1年間キャッシュされます。

export default defineConfig({
  // ...
  adapter: netlify({
    cacheOnDemandPages: true,
  }),
});

これは、レスポンスにキャッシュヘッダーを追加することで、ページごとに変更できます。

---
import Layout from '../components/Layout.astro';

Astro.response.headers.set('CDN-Cache-Control', 'public, max-age=45, must-revalidate');
---

<Layout title="Astro on Netlify">
  {new Date()}
</Layout>

きめ細かなキャッシュ制御により、NetlifyはCDN-Cache-ControlやVaryなどの標準的なキャッシュヘッダーをサポートしています。TTL（Time to Live）やSWR（Stale While Revalidate）キャッシングの実装方法については、ドキュメントを参照してください：https://docs.netlify.com/platform/caching

スキュー保護

Netlifyのスキュー保護は、デプロイ中にサイトにアクセスしたユーザーが同じデプロイバージョンのコンテンツを引き続き受け取れるようにします。Netlifyアダプターは、現在のデプロイIDを内部リクエストに注入することで、アクション、サーバーアイランド、ビュートランジション、プリフェッチリクエストなどAstroの各機能に対してスキュー保護を自動的に設定します。これにより、デプロイ中のクライアントとサーバー間のバージョン不一致を防ぎます。

Astroは組み込み機能に対してスキュー保護ヘッダーを自動的に追加しますが、サイトへの独自のfetchリクエストをおこなう場合は、DEPLOY_ID環境変数を使用してヘッダーを手動で含められます。

const response = await fetch('/api/endpoint', {
  headers: {
    'X-Netlify-Deploy-ID': import.meta.env.DEPLOY_ID,
  },
});

Netlify Functionsからのファイルのインクルードまたは除外

オンデマンドレンダリングでAstroサイトをNetlifyにデプロイする場合、生成された関数はサーバーの依存関係を自動的にトレースしてインクルードします。ただし、Netlify Functionsにインクルードするファイルをカスタマイズする必要がある場合があります。

includeFiles

Type: string[]
Default: []

追加： astro@5.3.0

includeFilesプロパティを使用すると、関数にバンドルする必要がある追加のファイルを明示的に指定できます。これは、次のような依存関係として自動的に検出されないファイルに役立ちます。

• fs操作を使用してロードされたデータファイル
• 設定ファイル
• テンプレートファイル

プロジェクトのroot (EN)からの相対ファイルパスを持つ追加ファイルの配列を指定します。絶対パスは期待どおりに機能しない場合があります。

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    includeFiles: ['./my-data.json'], // `root`からの相対パス
  }),
});

excludeFiles

Type: string[]
Default: []

追加： astro@5.3.0

excludeFilesプロパティを使用して、通常はインクルードされる特定のファイルがバンドルされないようにすることができます。これは、次の場合に役立ちます。

• バンドルサイズの削減
• 大きなバイナリの除外
• 不要なファイルがデプロイされないようにする

プロジェクトのroot (EN)からの相対ファイルパスを持つ除外する特定のファイルの配列を指定します。絶対パスは期待どおりに機能しない場合があります。

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    excludeFiles: ['./src/some_big_file.jpg'], // `root`からの相対パス
  }),
});

globパターンの使用

includeFilesとexcludeFilesの両方で、複数のファイルを照合するためのglobパターン (EN)がサポートされています。

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  adapter: netlify({
    includeFiles: [
      './data/**/*.json'
    ],
    excludeFiles: [
      './node_modules/package/**/*',
      './src/**/*.test.js'
    ]
  }),
});

ローカル開発機能

astro devを実行すると、アダプターはいくつかのNetlifyプラットフォーム機能を有効にし、開発環境を本番環境にできるだけ近づけます。これには以下が含まれます。

• ローカルのNetlify Image CDNサーバー。デフォルトで画像に使用されます。
• ローカルのNetlify Blobsサーバー。デフォルトでセッションに使用されます。
• Netlify設定のリダイレクト、リライトおよびヘッダー。
• オンデマンドページでのNetlify Edge Contextへのアクセス。
• Netlifyサイトの環境変数。

これらの機能は、netlify linkを使用してローカルサイトをNetlifyサイトにリンクしている場合に最も効果的に動作します。

これらの機能の一部は、アダプター設定のdevFeaturesオプションで有効または無効にできます。デフォルトでは、環境変数を除くすべての機能が有効になっています。

devFeatures

Type: boolean | object
Default: { images: true, environmentVariables: false }

追加： @astrojs/netlify@6.5.1

devFeaturesオプションには、すべての機能を有効または無効にする真偽値か、特定の機能を有効にするオブジェクトを指定できます。

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    devFeatures: {
      // 開発時にNetlify Image CDNサポートを有効にします。デフォルトはtrueです。
      images: false,
      // 開発時にNetlifyの環境変数を注入します。デフォルトはfalseです。
      environmentVariables: true,
    },
  }),
});

devFeatures.images

Type: boolean
Default: true

追加： @astrojs/netlify@6.5.1

開発時にローカルのNetlify Image CDNサポートを有効にします。

デフォルトのAstro画像サービスの代わりに、ローカルバージョンのNetlify Image CDNを使用します。

devFeatures.environmentVariables

Type: boolean
Default: false

追加： @astrojs/netlify@6.5.1

Netlifyサイトの環境変数を開発環境に注入します。

これにより、本番環境と同じ値を開発時に使用できます。環境ごとに異なる変数を使用する方法など、詳細についてはNetlifyの環境変数に関するドキュメントを参照してください。

実験的な機能

以下の機能も利用可能ですが、将来のアップデートで破壊的な変更が加えられる可能性があります。この機能をプロジェクトで使用している場合は、@astrojs/netlify CHANGELOGで更新情報を確認してください。

experimentalStaticHeaders

Type: boolean
Default: false

追加： @astrojs/netlify@6.4.0

Netlifyの設定で事前レンダリングされたページのカスタムヘッダーを指定できるようにします。

有効にすると、アダプターはコンテンツセキュリティポリシーなどのAstroの機能によって提供された静的ヘッダーをフレームワークAPI設定ファイルに保存します。

たとえば、CSP設定 (EN)を有効にしている場合、experimentalStaticHeadersを使用して、<meta>要素を作成する代わりにCSP headersをNetlify設定に追加できます。

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  security: {
    csp: true
  },
  adapter: netlify({
    experimentalStaticHeaders: true
  })
});

例

• Astro Netlify Edge Starterには、例とREADMEのガイドが記載されています。

• その他の例については、GitHubでAstro Netlifyプロジェクトを閲覧してください！

他のインテグレーション

UIフレームワーク

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSRアダプター

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

その他

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap