@astrojs/ netlify

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

Si estás usando Astro como un generador de sitios estáticos, solo necesitas este adaptador si estás utilizando servicios adicionales de Netlify que requieren un servidor (por ejemplo, Netlify Image CDN). De lo contrario, no necesitas un adaptador para desplegar tu sitio estático.

Aprende cómo desplegar tu sitio de Astro en nuestra guía de despliegue en Netlify.

Por qué Astro Netlify

Netlify es una plataforma de despliegue que te permite alojar tu sitio conectándose directamente a tu repositorio de GitHub. Este adaptador mejora el proceso de compilación de Astro para preparar tu proyecto para el despliegue a través de Netlify.

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 Netlify para habilitar el renderizado bajo demanda en tu proyecto de Astro con el comando astro add. Esto instalará @astrojs/netlify y realizará los cambios apropiados en tu archivo astro.config.mjs en un solo paso.

npm

npx astro add netlify

pnpm

pnpm astro add netlify

Yarn

yarn astro add netlify

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, instala el adaptador de Netlify en las dependencias de tu proyecto usando tu gestor de paquetes preferido:

npm

npm install @astrojs/netlify

pnpm

pnpm add @astrojs/netlify

Yarn

yarn add @astrojs/netlify

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

astro.config.mjs

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

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

Uso

Lee la guía de despliegue completa aquí.

Sigue las instrucciones para compilar tu sitio localmente. Después de compilar, tendrás una carpeta .netlify/ que contiene tanto Netlify Functions en la carpeta .netlify/functions-internal/ como Netlify Edge Functions en la carpeta .netlify/edge-functions/.

Para desplegar tu sitio, instala la Netlify CLI y ejecuta:

netlify deploy

La publicación del blog de Netlify sobre Astro y la documentación de Netlify proporcionan más información sobre cómo usar esta integración para desplegar en Netlify.

Ejecutar middleware de Astro en Netlify Edge Functions

Por defecto, el middleware de Astro se aplica a las páginas prerenderizadas en el momento de la compilación y a las páginas renderizadas bajo demanda en el tiempo de ejecución.

Para implementar redirecciones, control de acceso o cabeceras de respuesta personalizadas para páginas prerenderizadas, ejecuta tu middleware en Netlify Edge Functions configurando la opción middlewareMode en edge:

astro.config.mjs

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

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

Cuando middlewareMode se establece en 'edge', una función de borde (edge function) ejecutará tu código de middleware para todas las solicitudes, incluidos los archivos estáticos, las páginas prerenderizadas y las páginas renderizadas bajo demanda.

Para las páginas renderizadas bajo demanda, el objeto context.locals se serializa utilizando JSON y se envía en una cabecera para la función serverless, que realiza el renderizado. Como medida de seguridad, la función serverless se negará a atender solicitudes con una respuesta 403 Forbidden a menos que provengan de la función de borde generada.

Acceder al contexto del borde desde tu sitio

Netlify Edge Functions proporciona un objeto context que incluye metadatos sobre la solicitud, como la IP del usuario, datos de geolocalización y cookies.

Se puede acceder a esto a través del objeto Astro.locals.netlify.context:

---
const {
  geo: { city },
} = Astro.locals.netlify.context;
---

<h1>Hello there, friendly visitor from {city}!</h1>

Si estás usando TypeScript, puedes obtener tipados adecuados actualizando src/env.d.ts para usar NetlifyLocals:

src/env.d.ts

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

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

Esto no está disponible en páginas prerenderizadas.

Soporte para la CDN de imágenes de Netlify

Este adaptador utiliza por defecto la CDN de imágenes de Netlify para transformar imágenes sobre la marcha sin afectar los tiempos de compilación. Está implementado utilizando un Servicio de imágenes de Astro bajo el capó.

Para optar por no utilizar la optimización de imágenes remotas de Netlify Image CDN, utiliza la opción imageCDN:

astro.config.mjs

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

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

Si estás utilizando imágenes alojadas en otro dominio, debes autorizar el dominio o los patrones de URL utilizando las opciones de configuración image.domains o image.remotePatterns:

astro.config.mjs

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

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

Para obtener más información, consulta la guía para autorizar imágenes remotas. Esto no es necesario para imágenes alojadas en el mismo dominio que tu sitio.

Sitios estáticos con el adaptador de Netlify

Para sitios estáticos (output: 'static') alojados en Netlify, normalmente no necesitas un adaptador. Sin embargo, algunas características de despliegue solo están disponibles a través de un adaptador.

Los sitios estáticos necesitarán instalar este adaptador para usar y configurar el servicio de imágenes de Netlify.

Si utilizas la configuración de redirecciones en tu configuración de Astro, el adaptador de Netlify se puede utilizar para traducir esto al formato _redirects adecuado.

astro.config.mjs

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

export default defineConfig({
  // ...
  adapter: netlify(),
  redirects: {
    '/blog/old-post': '/blog/new-post',
  },
});

Una vez que ejecutes astro build, habrá un archivo dist/_redirects. Netlify lo usará para enrutar correctamente las páginas en producción.

Nota

Aún puedes incluir un archivo public/_redirects para redirecciones manuales. Cualquier redirección que especifiques en la configuración de redirecciones se añadirá al final de las tuyas.

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 configura automáticamente Netlify Blobs para el almacenamiento de sesiones cuando se utiliza el adaptador de Netlify. 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.

Caché de páginas

Las páginas renderizadas bajo demanda sin ningún contenido dinámico se pueden almacenar en caché para mejorar el rendimiento y reducir el uso de recursos. Habilitar la opción cacheOnDemandPages en el adaptador almacenará en caché todas las páginas renderizadas en el servidor por hasta un año:

astro.config.mjs

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

Esto se puede cambiar página por página añadiendo cabeceras de caché a tu respuesta:

pages/index.astro

---
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>

Con un control de caché detallado, Netlify admite cabeceras de caché estándar como CDN-Cache-Control o Vary. Consulta la documentación para aprender sobre la implementación de, por ejemplo, el tiempo de vida (TTL) o el almacenamiento en caché stale-while-revalidate (SWR): https://docs.netlify.com/platform/caching

Protección contra desajustes de versión

Agregado en: @astrojs/netlify@6.6.0

La protección contra desajustes de Netlify garantiza que los usuarios que acceden a tu sitio durante un despliegue continúen recibiendo contenido de la misma versión de despliegue. El adaptador de Netlify configura automáticamente la protección contra desajustes para las características de Astro como acciones, islas de servidor, transiciones de vista y solicitudes de prebúsqueda al inyectar el ID de despliegue actual en las solicitudes internas. Esto evita desajustes de versión entre el cliente y el servidor durante los despliegues activos.

Aunque Astro agrega automáticamente la cabecera de protección contra desajustes para sus características integradas, si estás realizando tus propias solicitudes de tipo fetch a tu sitio, puedes incluir la cabecera manualmente utilizando la variable de entorno DEPLOY_ID:

const response = await fetch('/api/endpoint', {
  headers: {
    'X-Netlify-Deploy-ID': import.meta.env.DEPLOY_ID,
  },
});

Incluir o excluir archivos de Netlify Functions

Al desplegar un sitio de Astro con renderizado bajo demanda en Netlify, las funciones generadas rastrean e incluyen automáticamente las dependencias del servidor. Sin embargo, es posible que necesites personalizar qué archivos se incluyen en tus Netlify Functions.

includeFiles

Type: string[]
Default: []

Agregado en: astro@5.3.0

La propiedad includeFiles te permite especificar explícitamente archivos adicionales que deben empaquetarse con tu función. Esto es útil para archivos que no se detectan automáticamente como dependencias, como:

• Archivos de datos cargados mediante operaciones de fs
• Archivos de configuración
• Archivos de plantilla

Proporciona un array de archivos adicionales a incluir con rutas de archivo relativas a la raíz (root) de tu proyecto. Es posible que las rutas absolutas no funcionen como se espera.

astro.config.mjs

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

export default defineConfig({
  // ...
  adapter: netlify({
    includeFiles: ['./my-data.json'], // relative to `root`
  }),
});

excludeFiles

Type: string[]
Default: []

Agregado en: astro@5.3.0

Puedes utilizar la propiedad excludeFiles para evitar que se empaqueten archivos específicos que de otro modo se incluirían. Esto es útil para:

• Reducir el tamaño del paquete
• Excluir binarios grandes
• Evitar que se desplieguen archivos no deseados

Proporciona un array de archivos específicos a excluir con rutas de archivo relativas a la raíz (root) de tu proyecto. Es posible que las rutas absolutas no funcionen como se espera.

astro.config.mjs

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

export default defineConfig({
  // ...
  adapter: netlify({
    excludeFiles: ['./src/some_big_file.jpg'], // relative to `root`
  }),
});

Usar patrones glob

Tanto includeFiles como excludeFiles admiten patrones glob para hacer coincidir múltiples archivos:

astro.config.mjs

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

Características de desarrollo local

Al ejecutar astro dev, el adaptador habilita varias características de la plataforma Netlify para garantizar que el entorno coincida lo más estrechamente posible con el de producción. Estas incluyen:

• Un servidor local de Netlify Image CDN. Esto se usa para images por defecto.
• Un servidor local de Netlify Blobs. Esto se usa para sessions por defecto.
• Redirecciones, reescrituras y cabeceras de tu configuración de Netlify.
• Acceso al Netlify Edge Context en páginas bajo demanda.
• Variables de entorno de tu sitio de Netlify.

Esto funciona mejor cuando tu sitio local está vinculado a un sitio de Netlify usando netlify link.

Puedes habilitar o deshabilitar algunas de estas características usando la opción devFeatures en la configuración de tu adaptador. Por defecto, todas las características están habilitadas excepto las variables de entorno.

devFeatures

Type: boolean | object
Default: { images: true, environmentVariables: false }

Añadido en: @astrojs/netlify@6.5.1

La opción devFeatures puede ser un booleano para habilitar o deshabilitar todas las características, o un objeto para habilitar características específicas.

astro.config.mjs

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

export default defineConfig({
  // ...
  adapter: netlify({
    devFeatures: {
      // Enable Netlify Image CDN support in dev. Defaults to true.
      images: false,
      // Inject Netlify environment variables in dev. Defaults to false.
      environmentVariables: true,
    },
  }),
});

devFeatures.images

Type: boolean
Default: true

Añadido en: @astrojs/netlify@6.5.1

Habilita el soporte para la versión local de Netlify Image CDN en desarrollo.

Esto utiliza una versión local de Netlify Image CDN, en lugar del servicio de imágenes predeterminado de Astro.

devFeatures.environmentVariables

Type: boolean
Default: false

Añadido en: @astrojs/netlify@6.5.1

Inyecta variables de entorno de tu sitio de Netlify en el entorno de desarrollo.

Esto te permite usar los mismos valores en desarrollo que usarías en producción. Consulta la documentación de Netlify sobre variables de entorno para obtener más información, incluyendo cómo usar variables diferentes para diferentes entornos.

staticHeaders

Type: boolean
Default: false

Agregado en: @astrojs/netlify@7.0.0

Permite especificar cabeceras personalizadas para páginas prerenderizadas en la configuración de Netlify.

Si está habilitado, el adaptador guardará las cabeceras estáticas en el archivo de configuración de Framework API cuando las proporcionen características de Astro, como la Content Security Policy.

Por ejemplo, cuando la Content Security Policy está habilitada, staticHeaders se puede utilizar para agregar las cabeceras de CSP a tu configuración de Netlify, en lugar de crear un elemento <meta>:

astro.config.mjs

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

export default defineConfig({
  security: {
    csp: true
  },
  adapter: netlify({
    staticHeaders: true
  })
});

Ejemplos

• El Astro Netlify Edge Starter proporciona un ejemplo y una guía en el archivo README.

• Explora proyectos de Astro Netlify en GitHub ¡para ver más ejemplos!

Más integraciones

Frameworks de front-end

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

Adaptadores

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

Otras integraciones

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap