import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro' import Since from '/components/Since.astro';

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

Astroを静的サイトビルダーとして使用している場合、アダプターは必要ありません。

Astro Node.jsを選ぶ理由

Node.jsは、サーバーサイドコード用のJavaScriptランタイムです。@astrojs/nodeは、スタンドアロンモードまたはExpressなどの他のhttpサーバーのミドルウェアとして使用できます。

インストール

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

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

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

手動インストール

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

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

import { defineConfig } from 'astro/config';import node from '@astrojs/node';export default defineConfig({  adapter: node({    mode: 'standalone',  }),});

設定

@astrojs/nodeは、アダプター関数にオプションを渡すことで設定できます。次のオプションが利用可能です。

mode

アダプターがmiddlewareモードとstandaloneモードのどちらでビルドするかを制御します。

• middlewareモードでは、ビルドされた出力をExpress.jsやFastifyなどの別のNode.jsサーバーのミドルウェアとして使用できます。
• standaloneモードでは、エントリモジュールが実行されると自動的に起動するサーバーがビルドされます。これにより、追加のコードを必要とせずに、ビルドをホストに簡単にデプロイできます。

import { defineConfig } from 'astro/config';import node from '@astrojs/node';export default defineConfig({  adapter: node({    mode: 'middleware',  }),});

experimentalDisableStreaming

オンデマンドでレンダリングされるページの、AstroのデフォルトのHTMLストリーミングを無効にします。

HTMLストリーミングはパフォーマンスに役立ち、一般的にユーザーにより良い体験を提供します。ほとんどの場合、ストリーミングを無効にすることはお勧めできません。

ただし、HTMLストリーミングを無効にする必要がある場合（たとえば、ホストがCDNレベルでストリーミングされていないHTMLキャッシュのみをサポートしている場合）、デフォルトの動作をオプトアウトできます。

import { defineConfig } from 'astro/config';import node from '@astrojs/node';export default defineConfig({  adapter: node({    mode: 'standalone',    experimentalDisableStreaming: true,  }),});

experimentalStaticHeaders

有効にすると、アダプターは、コンテンツセキュリティポリシーなどのAstroの機能によって提供された場合、Responseオブジェクトを使用して事前レンダリングされたページのヘッダーを提供します。

たとえば、実験的なコンテンツセキュリティポリシーが有効になっている場合、experimentalStaticHeadersを使用して、<meta>要素を作成する代わりにCSPヘッダーをResponseオブジェクトに追加できます。

import { defineConfig } from 'astro/config';import node from '@astrojs/node';export default defineConfig({  experimental: {    csp: true  },  adapter: node({    mode: 'standalone',    experimentalStaticHeaders: true,  })});

使い方

まず、ビルドを実行します。選択したmode（上記参照）に応じて、以下の適切な手順に従ってください。

ミドルウェア

サーバーのエントリポイントは、デフォルトで./dist/server/entry.mjsにビルドされます。このモジュールは、Nodeのrequestおよびresponseオブジェクトをサポートする任意のフレームワークで使用できるhandler関数をエクスポートします。

たとえば、Expressでは次のようになります。

import express from 'express';import { handler as ssrHandler } from './dist/server/entry.mjs';const app = express();// これをastro.config.mjsの`base`オプションに基づいて変更します。// それらは一致する必要があります。デフォルト値は「/」です。const base = '/';app.use(base, express.static('dist/client/'));app.use(ssrHandler);app.listen(8080);

または、Fastify（>4）では次のようになります。

import Fastify from 'fastify';import fastifyMiddie from '@fastify/middie';import fastifyStatic from '@fastify/static';import { fileURLToPath } from 'node:url';import { handler as ssrHandler } from './dist/server/entry.mjs';const app = Fastify({ logger: true });await app  .register(fastifyStatic, {    root: fileURLToPath(new URL('./dist/client', import.meta.url)),  })  .register(fastifyMiddie);app.use(ssrHandler);app.listen({ port: 8080 });

さらに、Astro.localsまたはAstroミドルウェアでアクセスするオブジェクトを渡すこともできます。

import express from 'express';import { handler as ssrHandler } from './dist/server/entry.mjs';const app = express();app.use(express.static('dist/client/'));app.use((req, res, next) => {  const locals = {    title: 'New title',  };  ssrHandler(req, res, next, locals);});app.listen(8080);

ミドルウェアモードではファイルを提供しないことに注意してください。HTTPフレームワークを設定して、ファイルを提供するようにする必要があります。デフォルトでは、クライアントアセットは./dist/client/に書き込まれます。

スタンドアロン

スタンドアロンモードでは、サーバーのエントリポイントが実行されるとサーバーが起動します。デフォルトでは、./dist/server/entry.mjsにビルドされます。次のように実行できます。

node ./dist/server/entry.mjs

スタンドアロンモードの場合、サーバーはページとAPIルートに加えてファイルの提供を処理します。

カスタムホストとポート

実行時に環境変数として渡すことで、スタンドアロンサーバーが実行されるホストとポートを上書きできます。

HOST=0.0.0.0 PORT=4321 node ./dist/server/entry.mjs

HTTPS

デフォルトでは、スタンドアロンサーバーはHTTPを使用します。これは、HTTPSを実行するプロキシサーバーがその前にある場合にうまく機能します。スタンドアロンサーバー自体でHTTPSを実行する必要がある場合は、SSLキーと証明書を提供する必要があります。

環境変数SERVER_CERT_PATHおよびSERVER_KEY_PATHを介してキーと証明書へのパスを渡すことができます。bashでそれらを渡す方法は次のとおりです。

SERVER_KEY_PATH=./private/key.pem SERVER_CERT_PATH=./private/cert.pem node ./dist/server/entry.mjs

ランタイム環境変数

ビルドプロセスの実行時に環境変数を含む.envファイルが存在する場合、これらの値は、静的ウェブサイトを生成する場合と同様に、出力にハードコーディングされます。

ビルド中、ランタイム変数は.envファイルに存在していてはならず、実行時に期待されるすべての環境変数をAstroに提供する必要があります：VARIABLE_1=placeholder astro build。これは、ビルドされたアプリケーションが実行されるときに実際の値が利用可能になることをAstroに示します。プレースホルダーの値はビルドプロセスによって無視され、Astroは実行時に提供された値を使用します。

複数のランタイム変数の場合は、.envとは別のファイル（例：.env.runtime）に保存します。次のコマンドでビルドを開始します。

export $(cat .env.runtime) && astro build

アセット

スタンドアロンモードでは、dist/client/フォルダー内のアセットはスタンドアロンサーバーを介して提供されます。これらのアセットをCDNにデプロイしている場合があり、その場合、サーバーは実際にはそれらを提供しません。しかし、イントラネットサイトなどの場合によっては、アプリケーションサーバーから直接静的アセットを提供しても問題ありません。

dist/client/_astro/フォルダー内のアセットは、Astroがビルドしたものです。これらのアセットはすべてハッシュで名前が付けられているため、長いキャッシュヘッダーを付けることができます。内部的に、アダプターはこれらのアセットにこのヘッダーを追加します。

セッション

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

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