@astrojs/ node

v9.2.2 GitHub npm Journal des modifications

Cet adaptateur permet à Astro de déployer vos routes et fonctionnalités rendues à la demande vers des cibles Node, y compris les îlots de serveurs, les actions et les sessions.

Si vous utilisez Astro comme générateur de site statique, vous n’avez pas besoin d’adaptateur.

Pourquoi Astro Node.js

Node.js est un environnement d’exécution JavaScript pour le code côté serveur. @astrojs/node peut être utilisé soit en mode standalone, soit comme middleware pour d’autres serveurs http, tels que Express.

Installation

Astro inclut une commande astro add pour automatiser l’installation des intégrations officielles. Si vous préférez, vous pouvez installer les intégrations manuellement à la place.

Ajoutez l’adaptateur Node pour activer le rendu à la demande dans votre projet Astro avec la commande astro add. Cela installera @astrojs/node et apportera les changements appropriés à votre fichier astro.config.* en une seule étape.

npx astro add node

pnpm astro add node

yarn astro add node

Désormais, vous pouvez activer le rendu à la demande par page ou définir la configuration de sortie de votre compilation sur output: 'server' pour restituer toutes vos pages par défaut sur le serveur.

Installation manuelle

Tout d’abord, ajoutez l’adaptateur Node aux dépendances de votre projet en utilisant votre gestionnaire de paquets préféré.

npm install @astrojs/node

pnpm add @astrojs/node

yarn add @astrojs/node

Ensuite, ajoutez l’adaptateur à votre fichier astro.config.* :

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

export default defineConfig({
  adapter: node({
    mode: 'standalone',
  }),
});

Configuration

@astrojs/node peut être configuré en passant des options dans la fonction de l’adaptateur. Les options suivantes sont disponibles :

`mode`

Type : 'middleware' | 'standalone'

Contrôle si l’adaptateur se construit en mode middleware ou standalone.

Le mode middleware permet à la sortie de compilation d’être utilisée comme middleware pour un autre serveur Node.js, comme Express.js ou Fastify.
Le mode standalone crée un serveur qui démarre automatiquement lorsque le module d’entrée est exécuté. Cela vous permet de déployer plus facilement votre compilation sur un hôte sans avoir besoin de code supplémentaire.

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

export default defineConfig({
  adapter: node({
    mode: 'middleware',
  }),
});

Utilisation

Tout d’abord, effectuer une compilation. En fonction du mode sélectionné (voir ci-dessus), suivez les étapes appropriées ci-dessous :

Middleware

Le point d’entrée du serveur est compilé dans ./dist/server/entry.mjs par défaut. Ce module exporte une fonction handler qui peut être utilisée avec n’importe quel framework qui supporte les objets Node request et response.

Par exemple, avec Express :

import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';

const app = express();
// Changez ceci en fonction de votre option `base` dans astro.config.mjs.
// Ils doivent correspondre. La valeur par défaut est "/".
const base = '/';
app.use(base, express.static('dist/client/'));
app.use(ssrHandler);

app.listen(8080);

Ou, avec 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 });

De plus, vous pouvez également passer un objet qui sera accessible avec Astro.locals ou dans le middleware 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: 'Nouveau titre',
  };

  ssrHandler(req, res, next, locals);
});

app.listen(8080);

Notez que le mode middleware ne permet pas de servir des fichiers. Vous devrez configurer votre framework HTTP pour qu’il le fasse pour vous. Par défaut, les ressources du client sont écrites dans ./dist/client/.

Standalone

En mode standalone, un serveur démarre lorsque le point d’entrée du serveur est exécuté. Par défaut, il est compilé dans ./dist/server/entry.mjs. Vous pouvez le lancer avec :

node ./dist/server/entry.mjs

En mode standalone, le serveur gère le service de fichiers en plus des routes de pages et d’API.

Hôte et port personnalisés

Vous pouvez modifier l’hôte et le port sur lesquels le serveur standalone s’exécute en les passant comme variables d’environnement au moment de l’exécution :

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

HTTPS

Par défaut, le serveur standalone utilise le protocole HTTP. Cela fonctionne bien si vous avez un serveur proxy en face de lui qui utilise HTTPS. Si vous avez besoin que le serveur standalone utilise HTTPS lui-même, vous devez fournir votre clé et votre certificat SSL.

Vous pouvez passer le chemin vers votre clé et votre certificat via les variables d’environnement SERVER_CERT_PATH et SERVER_KEY_PATH. Voici comment vous pouvez les transmettre avec Bash :

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

Variables de l’environnement d’exécution

Si un fichier .env contenant des variables d’environnement est présent lors de l’exécution du processus de compilation, ces valeurs seront codées en dur dans la sortie, tout comme lors de la génération d’un site web statique.

Pendant la compilation, les variables d’exécution doivent être absentes du fichier .env, et vous devez fournir à Astro toutes les variables d’environnement attendues au moment de l’exécution : VARIABLE_1=valeur-fictive astro build. Ceci signale à Astro que la valeur réelle sera disponible lors de l’exécution de l’application compilée. La valeur fictive sera ignorée par le processus de compilation, et Astro utilisera la valeur fournie à l’exécution.

Dans le cas de multiples variables d’environnement, stockez-les dans un fichier séparé (par exemple .env.runtime) de .env. Lancez la compilation avec la commande suivante :

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

Ressources

En mode standalone, les ressources de votre dossier dist/client/ sont servies par le serveur standalone. Vous pouvez déployer ces ressources sur un CDN, auquel cas le serveur ne les servira jamais. Mais dans certains cas, comme les sites intranet, il est possible de servir les ressources statiques directement depuis le serveur d’application.

Les ressources dans le dossier dist/client/_astro/ sont celles générées par Astro. Celles-ci sont toutes nommées avec un hachage et peuvent donc recevoir de longs en-têtes de cache. En interne, l’adaptateur ajoute cet en-tête pour ces ressources :

Cache-Control: public, max-age=31536000, immutable

Sessions

L’API Sessions d’Astro vous permet de stocker facilement les données utilisateur entre chaque requête. Ceci peut être utilisé pour des éléments tels que les données et préférences utilisateur, les paniers d’achat et les identifiants d’authentification. Contrairement au stockage des cookies, la taille des données est illimitée et elles peuvent être restaurées sur différents appareils.

Astro utilise le système de fichiers local pour le stockage des sessions avec l’adaptateur Node. Si vous préférez utiliser un autre pilote de stockage de session, vous pouvez le spécifier dans votre configuration Astro. Consultez la référence de configuration session pour plus de détails.