@astrojs/node: standalone y middleware

@astrojs/node es el adapter para ejecutar Astro sobre un servidor Node que gobiernas tú. A diferencia de las plataformas serverless, aquí no hay ningún proveedor entre tu proceso y la máquina: posees el servidor, el puerto y el ciclo de vida. El adapter ofrece dos modos que responden a dos filosofías. En standalone construye un servidor completo, autosuficiente, que arrancas con node y que sirve tanto los estáticos como las rutas dinámicas. En middleware produce un manejador que injertas en un servidor Express, Fastify o Connect que ya tenías: Astro pasa a ser una pieza más de tu cadena, y tú sigues al mando de todo lo demás.

standalone: un servidor completo listo para correr

El modo standalone es el más directo: le pides a Astro que construya un servidor web entero, con su bucle de escucha ya incluido. El build deja un punto de entrada ejecutable, y arrancarlo es una sola orden.

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

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

npm run build
# el build produce dist/server/entry.mjs
node ./dist/server/entry.mjs
# el servidor escucha y sirve estaticos mas rutas dinamicas

Ese servidor no depende de nada externo: sirve por sí mismo los assets del cliente y ejecuta las rutas bajo demanda. Su comportamiento se ajusta por variables de entorno —HOST para la interfaz de escucha y PORT para el puerto (8080 por defecto)—, de modo que el mismo artefacto se despliega en distintos entornos sin recompilar. Esa portabilidad lo hace el candidato natural para un contenedor.

# Dockerfile para el modo standalone
FROM node:lts-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
ENV HOST=0.0.0.0
ENV PORT=8080
EXPOSE 8080
CMD ["node", "./dist/server/entry.mjs"]

middleware: Astro como una pieza de tu servidor

A veces no quieres que Astro sea el servidor, sino que viva dentro de uno tuyo —porque ya tienes rutas de API, autenticación, sockets o lógica que no es de Astro—. Para eso está el modo middleware: el build no arranca nada, sino que exporta un handler que tú montas donde quieras.

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

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

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

const app = express();
app.use(express.static('dist/client/')); // sirve tu los estaticos
app.use(ssrHandler);                     // y delega el resto en Astro
app.listen(8080);

Aquí tú posees la cadena: registras tus rutas antes o después de Astro, decides quién sirve los estáticos y cómo se ordenan las capas. El handler acepta incluso un cuarto argumento para inyectar locals, de forma que tu servidor puede pasar datos —un usuario autenticado, un identificador de petición— al contexto que verán tus páginas.

app.use((req, res, next) => {
  const locals = { usuario: req.session?.usuario };
  ssrHandler(req, res, next, locals); // los locals llegan a Astro.locals
});

Detrás de un proxy inverso y varios núcleos

Un proceso Node en producción rara vez se expone desnudo a internet. Lo habitual es ponerle delante un proxy inverso —nginx, Caddy— que termina el TLS, comprime respuestas, cachea estáticos y reparte carga. El proceso de Astro escucha en un puerto local, y el proxy es la cara pública que atiende el mundo.

Node ejecuta un único hilo por proceso, así que para aprovechar varios núcleos se lanzan varias instancias —con un gestor como PM2, con systemd, o con el cluster del propio Node— y el proxy balancea entre ellas. Ese patrón, un servidor de aplicación replicado tras un balanceador, es el mismo que rige cualquier backend Node clásico, y hereda sus mismas responsabilidades: vigilar la salud de cada proceso, reiniciarlo si cae y drenar conexiones al desplegar una versión nueva.

flowchart LR
C[cliente] --> PX[proxy inverso nginx o caddy]
PX --> N1[proceso node uno]
PX --> N2[proceso node dos]
N1 --> APP[servidor de Astro]
N2 --> APP
style PX fill:#89b4fa,color:#11111b
style APP fill:#a6e3a1,color:#11111b