@astrojs/ netlify

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

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

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

Astro Netlifyを選ぶ理由

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

インストール

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

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

npx astro add netlify

pnpm astro add netlify

yarn astro add netlify

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

手動インストール

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

npm install @astrojs/netlify

pnpm add @astrojs/netlify

yarn add @astrojs/netlify

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

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

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

使い方

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

指示に従ってサイトをローカルでビルドします。ビルド後、.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ミドルウェアは、ビルド時に事前レンダリングされたページに、実行時にオンデマンドでレンダリングされたページに適用されます。

事前レンダリングされたページのリダイレクト、アクセス制御、またはカスタムレスポンスヘッダーを実装するには、edgeMiddlewareオプションを有効にして、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を使用することで、適切な型指定を取得できます。

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

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

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

Netlify Image CDNのサポート

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

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

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

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

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

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

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

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

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は、本番環境でページを適切にルーティングするためにそれを使用します。

セッション

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

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

ページのキャッシュ

動的コンテンツのないオンデマンドでレンダリングされたページは、パフォーマンスを向上させ、リソース使用量を削減するためにキャッシュできます。アダプターで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 Functionsからのファイルのインクルードまたは除外

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

`includeFiles`

Type: string[]
Default: []

追加： astro@5.3.0

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

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

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

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からの相対ファイルパスを持つ除外する特定のファイルの配列を指定します。絶対パスは期待どおりに機能しない場合があります。

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パターンがサポートされています。

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'
    ]
  }),
});

実験的な機能

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

`experimentalStaticHeaders`

Type: boolean
Default: false

追加： @astrojs/netlify@6.4.0

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

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

たとえば、実験的なコンテンツセキュリティポリシー (EN)が有効な場合、experimentalStaticHeadersを使用して、<meta>要素を作成する代わりにCSP headersをNetlify設定に追加できます。

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

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