@astrojs/ node

v11.0.0 GitHub npm Registro de cambios

Este adaptador permite que Astro despliegue tus rutas y características renderizadas bajo demanda a objetivos Node, incluyendo islas de servidor, acciones y sesiones.

Si estás usando Astro como un generador de sitios estáticos, no necesitas un adaptador.

Por qué Astro Node.js

Node.js es un entorno de ejecución de JavaScript para código del lado del servidor. @astrojs/node se puede utilizar tanto en modo independiente (standalone) como de middleware para otros servidores HTTP, como Express.

Instalación

Astro incluye un comando astro add para automatizar la configuración de las integraciones oficiales. Si lo prefieres, puedes instalar las integraciones manualmente en su lugar.

Añade el adaptador de Node para habilitar el renderizado bajo demanda en tu proyecto de Astro con el comando astro add. Esto instalará @astrojs/node y realizará los cambios apropiados en tu archivo astro.config.* en un solo paso.

npx astro add node

pnpm astro add node

yarn astro add node

Ahora, puedes habilitar el renderizado bajo demanda por página, o establecer la configuración de salida de tu compilación en output: 'server' para renderizar todas tus páginas en el servidor por defecto.

Instalación manual

Primero, añade el adaptador de Node a las dependencias de tu proyecto usando tu gestor de paquetes preferido.

npm install @astrojs/node

pnpm add @astrojs/node

yarn add @astrojs/node

Luego, añade el adaptador a tu archivo astro.config.*:

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

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

Configuración

@astrojs/node se puede configurar pasando opciones a la función del adaptador. Las siguientes opciones están disponibles:

`mode`

Type: 'middleware' | 'standalone'

Controla si el adaptador compila en modo middleware o independiente.

El modo middleware permite utilizar el resultado de la compilación como middleware para otro servidor de Node.js, como Express.js o Fastify.
El modo independiente compila un servidor que se inicia automáticamente cuando se ejecuta el módulo de entrada. Esto te permite desplegar más fácilmente tu compilación en un servidor de alojamiento sin necesidad de código adicional.

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

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

`staticHeaders`

Type: boolean
Default: false

Agregado en: @astrojs/node@10.0.0

Si está habilitado, el adaptador servirá las cabeceras de las páginas prerenderizadas utilizando el objeto Response cuando las proporcionen características de Astro, como la Content Security Policy.

Por ejemplo, cuando la Content Security Policy está habilitada, se puede usar staticHeaders para agregar las cabeceras de CSP al objeto Response en lugar de crear un elemento <meta>:

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

export default defineConfig({
  security: {
    csp: true
  },
  adapter: node({
    mode: 'standalone',
    staticHeaders: true,
  })
});

`experimentalDisableStreaming`

Type: boolean
Default: false

Agregado en: @astrojs/node@9.3.0

Deshabilita la transmisión de HTML predeterminada de Astro para páginas renderizadas bajo demanda.

La transmisión de HTML ayuda con el rendimiento y generalmente brinda una mejor experiencia al visitante. En la mayoría de los casos, no se recomienda deshabilitar la transmisión.

Sin embargo, cuando necesites deshabilitar la transmisión de HTML (por ejemplo, si tu proveedor de alojamiento solo admite el almacenamiento en caché de HTML no transmitido a nivel de CDN), puedes optar por no usar el comportamiento por defecto:

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

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

`bodySizeLimit`

Tipo: number
Predeterminado: 1073741824 (1 GB)

Agregado en: @astrojs/node@10.0.0

Establece el tamaño máximo permitido del cuerpo de la solicitud en bytes. Cuando el cuerpo de una solicitud entrante supera este límite, se lanzará un error al consumir el cuerpo.

Establécelo en Infinity o 0 para deshabilitar el límite por completo. Esto puede ser útil si necesitas aceptar cuerpos de solicitud muy grandes, como para subidas de vídeo.

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

export default defineConfig({
  adapter: node({
    mode: 'standalone',
    bodySizeLimit: 5 * 1024 * 1024 * 1024, // 5 GB
  }),
});

Uso

Primero, realiza una compilación. Dependiendo del mode seleccionado (ver arriba), sigue los pasos correspondientes a continuación:

Middleware

El punto de entrada del servidor se compila en ./dist/server/entry.mjs por defecto. Este módulo exporta una función handler que se puede usar con cualquier framework que admita los objetos de request y response de Node.

Por ejemplo, con Express:

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

const app = express();
// Change this based on your astro.config.mjs, `base` option.
// They should match. The default value is "/".
const base = '/';
app.use(base, express.static('dist/client/'));
app.use(ssrHandler);

app.listen(8080);

O, con 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 });

Además, también puedes pasar un objeto al que se pueda acceder con Astro.locals o en el middleware de 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);

Ten en cuenta que el modo middleware no realiza el servicio de archivos. Deberás configurar tu framework HTTP para que lo haga por ti. Por defecto, los archivos estáticos del cliente se escriben en ./dist/client/.

Independiente

En el modo independiente, el servidor se inicia cuando se ejecuta el punto de entrada del servidor. Por defecto se compila en ./dist/server/entry.mjs. Puedes ejecutarlo con:

node ./dist/server/entry.mjs

Para el modo independiente, el servidor maneja el servicio de archivos además de las rutas de página y de la API.

Host y puerto personalizados

Puedes invalidar el host y el puerto en los que se ejecuta el servidor independiente pasándolos como variables de entorno en el tiempo de ejecución:

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

HTTPS

Por defecto, el servidor independiente utiliza HTTP. Esto funciona bien si tienes un servidor proxy delante que maneje HTTPS. Si necesitas que el propio servidor independiente ejecute HTTPS, debes proporcionar tu clave y certificado SSL.

Puedes pasar la ruta a tu clave y certificado a través de las variables de entorno SERVER_CERT_PATH y SERVER_KEY_PATH. Así es como podrías pasarlas en bash:

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

Archivos estáticos

En el modo independiente, los archivos estáticos de tu carpeta dist/client/ se sirven a través del servidor independiente. Es posible que estés desplegando estos recursos en una CDN, en cuyo caso el servidor nunca los servirá realmente. Pero en algunos casos, como los sitios de intranet, está bien servir recursos estáticos directamente desde el servidor de aplicaciones.

Los recursos de la carpeta dist/client/_astro/ son los que Astro ha compilado. Todos estos recursos se nombran con un hash y, por lo tanto, se les pueden asignar cabeceras de caché de larga duración. Internamente, el adaptador añade esta cabecera para estos recursos:

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

Sesiones

La API de Sesiones de Astro te permite almacenar fácilmente datos de usuario entre solicitudes. Esto se puede usar para cosas como datos y preferencias de usuario, carritos de compras y credenciales de autenticación. A diferencia del almacenamiento en cookies, no hay límites de tamaño en los datos y se pueden restaurar en diferentes dispositivos.

Astro utiliza el sistema de archivos local para el almacenamiento de sesiones cuando se utiliza el adaptador de Node. Si prefieres utilizar un controlador de almacenamiento de sesiones diferente, puedes especificarlo en tu configuración de Astro. Consulta la referencia de configuración de session para obtener más detalles.

Variables de entorno

Al utilizar los secretos de astro:env o process.env en tiempo de ejecución, ni Astro ni el adaptador cargan variables de entorno por ti.

Algunos proveedores de alojamiento pueden exponer las variables de entorno que configures a través de su panel de control durante la compilación y en el tiempo de ejecución. Consulta la documentación de tu proveedor de alojamiento para configurar y utilizar variables de entorno dentro de la plataforma específica.

Al autoalojarse, puedes cargar variables de entorno a través de comandos de la CLI o archivos de configuración según corresponda:

DB_HOST=... DB_PASSWORD=... node ./dist/server/entry.mjs

npx @dotenvx/dotenvx run -- node ./dist/server/entry.mjs

FROM node:lts AS runtime
WORKDIR /app

COPY . .

RUN npm install
RUN npm run build

ENV DB_HOST=...
ENV DB_PASSWORD=...
CMD node ./dist/server/entry.mjs