Saltearse al contenido

@astrojs/ netlify

v4.0.1 GitHub npm Changelog

Este adaptador permite a Astro desplegar tu sitio renderizado en modo hybrid o server en Netlify.

Aprende como desplegar tu sitio Astro en nuestra guía de despliegue en Netlify.

¿Por qué Astro Netlify?

Sección titulada ¿Por qué Astro Netlify?

Si estás usando Astro como un generador de sitios estáticos—su comportamiento es fuera de serie—no necesitas un adaptador.

Si deseas usar el renderizado bajo demanda, también conocido como renderizado del lado del servidor (SSR), Astro requiere un adaptador que coincida con tu entorno de despliegue.

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

Instalación

Sección titulada Instalación

Agrega el adaptador de Netlify con el comando astro add. Esto instalará el adaptador y hará los cambios apropiados en tu archivo astro.config.mjs en un solo paso.

Terminal window
# Usando NPM
npx astro add netlify
# Usando Yarn
yarn astro add netlify
# Usando PNPM
pnpm astro add netlify

Añadir dependencias manualmente

Sección titulada Añadir dependencias manualmente

Si prefieres instalar el adaptador manualmente, completa los siguientes dos pasos:

  1. Instala el adaptador de Netlify en las dependencias de tu proyecto usando tu gestor de paquetes preferido. Si estás usando npm o no estás seguro, ejecuta esto en la terminal:
Terminal window
  npm install @astrojs/netlify
  1. Agrega dos nuevas líneas a tu archivo de configuración astro.config.mjs:
astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';


export default defineConfig({
  output: 'server',
  adapter: netlify(),
});

Uso

Sección titulada Uso

Lee la guía completa de despliegue aquí.

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

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

Terminal window
netlify deploy

El artículo 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.

Acceder al contexto edge desde tu sitio

Sección titulada Acceder al contexto edge desde tu sitio

Las Funciones Edge de Netlify proporcionan un objeto de contexto que incluye metadatos sobre la solicitud, como la IP de un usuario, datos de geolocalización y cookies.

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

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


<h1>Hola, amable visitante de {city}!</h1>

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

src/env.d.ts
/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />


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


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

Esto no está disponible en las páginas prerenderizadas.

Ejecutar el middleware de Astro en Funciones Edge

Sección titulada Ejecutar el middleware de Astro en Funciones Edge

Cualquier middleware de Astro se aplica a las páginas prerenderizadas en tiempo de construcción y a las páginas renderizadas bajo demanda en tiempo de ejecución. Si estás usando el adaptador de Netlify Edge, puedes ejecutar el middleware de Astro en las Funciones Edge de Netlify para que se aplique a las páginas prerenderizadas y renderizadas bajo demanda.

Para implementar redirecciones, control de acceso o encabezados de respuesta personalizados para las páginas prerenderizadas, ejecuta tu middleware en las Funciones Edge de Netlify habilitando la opción edgeMiddleware:

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


export default defineConfig({
  output: 'server',
  adapter: netlify({
   edgeMiddleware: true,
  }),
});

Para sitios estáticos, generalmente no necesitas un adaptador. Sin embargo, si utilizas la configuración de redirects en tu archivo de configuración de Astro, puedes utilizar el adaptador de Netlify para traducirlo al formato adecuado de _redirects.

astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify/static';
export default defineConfig({
  adapter: netlify(),
  redirects: {
    '/blog/old-post': '/blog/new-post',
  }
});

Configurar edgeMiddleware: true desplegará tu middleware como una Función Edge y lo ejecutará en todas las rutas, incluidas las páginas prerenderizadas. Sin embargo, los locales especificados en el middleware no estarán disponibles para ninguna página prerenderizada, ya que ya se han renderizado completamente en tiempo de construcción.

Soporte para Netlify Image CDN

Sección titulada Soporte para Netlify Image CDN

Este adaptador utiliza el CDN de imágenes de Netlify para transformar imágenes sobre la marcha sin afectar a los tiempos de construcción. Es implementado usando un Servicio de Imágenes Astro bajo el capó.

Sitios estáticos y redirecciones

Sección titulada Sitios estáticos y redirecciones

Para sitios estáticos, generalmente no necesitas un adaptador. Sin embargo, si utilizas la configuración de redirects en tu archivo de configuración de Astro, puedes utilizar el adaptador de Netlify para traducirlo al formato adecuado de _redirects.

astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify/static';
export default defineConfig({
  adapter: netlify(),
  redirects: {
    '/blog/old-post': '/blog/new-post',
  },
});

Una vez que ejecutes astro build, se generará un archivo dist/_redirects. Netlify utilizará ese archivo para enrutamiento adecuado de las páginas en producción.

Caché de páginas

Sección titulada Caché de páginas

Las páginas renderizadas bajo demanda sin ningún contenido dinámico pueden ser almacenadas 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 bajo demanda durante un año:

astro.config.mjs
export default defineConfig({
  output: 'server',
  adapter: netlify({
    cacheOnDemandPages: true,
  }),
});

Esto se puede cambiar en cada página agregando encabezados de caché a tu respuesta:

src/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 control de caché de granularidad fina, Netlify soporta encabdezados de caché estándar como CDN-Cache-Control o Vary.

Refiérete a la documentación para aprender a implementar, por ejemplo, el tiempo de vida (TTL) o el almacenamiento en caché obsoleto mientras se vuelve a validar (SWR): https://docs.netlify.com/platform/caching

Ejemplos

Sección titulada Ejemplos

Solución de problemas

Sección titulada Solución de problemas

Para obtener ayuda, revisa el canal #support en Discord. ¡Nuestros amigables miembros del Escuadrón de Soporte están aquí para ayudarte!

Puedes revisar nuestra Documentación de Integración de Astro para más información sobre integraciones.

Contribuyendo

Sección titulada Contribuyendo

Este paquete es mantenido por el equipo central de Astro. ¡Estás invitado a enviar un problema o PR!

Changelog

Sección titulada Changelog

Consulta el CHANGELOG.md para un historial de cambios en esta integración.

Otros

Frameworks UI

Adaptadores SSR

Otros