API de Integración de Astro

Las Integraciones de Astro añaden nueva funcionalidad y comportamientos a tu proyecto con solo unas pocas líneas de código.

Esta página de referencia es para cualquiera que esté escribiendo su propia integración. Para aprender cómo usar una integración en tu proyecto, consulta nuestra guía de Uso de Integraciones en su lugar.

Ejemplos

Las integraciones oficiales de Astro pueden servir como referencia mientras construyes tus propias integraciones.

• Renderers: svelte, react, preact, vue, solid
• Libraries: partytown
• Features: sitemap

Referencia rápida de API

interface AstroIntegration {
  name: string;
  hooks: {
    'astro:config:setup'?: (options: {
      config: AstroConfig;
      command: 'dev' | 'build' | 'preview' | 'sync';
      isRestart: boolean;
      updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
      addRenderer: (renderer: AstroRenderer) => void;
      addWatchFile: (path: URL | string) => void;
      addClientDirective: (directive: ClientDirectiveConfig) => void;
      addMiddleware: (middleware: AstroIntegrationMiddleware) => void;
      addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void;
      injectScript: (stage: InjectedScriptStage, content: string) => void;
      injectRoute: (injectedRoute: InjectedRoute) => void;
      createCodegenDir: () => URL;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:route:setup'?: (options: {
      route: RouteOptions;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:routes:resolved'?: (options: {
      routes: IntegrationResolvedRoute[];
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:config:done'?: (options: {
      config: AstroConfig;
      setAdapter: (adapter: AstroAdapter) => void;
      injectTypes: (injectedType: InjectedType) => URL;
      logger: AstroIntegrationLogger;
      buildOutput: 'static' | 'server';
    }) => void | Promise<void>;
    'astro:server:setup'?: (options: {
      server: vite.ViteDevServer;
      logger: AstroIntegrationLogger;
      toolbar: ReturnType<typeof getToolbarServerCommunicationHelpers>;
      refreshContent?: (options: RefreshContentOptions) => Promise<void>;
    }) => void | Promise<void>;
    'astro:server:start'?: (options: {
      address: AddressInfo;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:server:done'?: (options: {
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:start'?: (options: {
      logger: AstroIntegrationLogger;
      setPrerenderer: (prerenderer: AstroPrerenderer | ((defaultPrerenderer: AstroPrerenderer) => AstroPrerenderer)) => void;
    }) => void | Promise<void>;
    'astro:build:setup'?: (options: {
      vite: vite.InlineConfig;
      pages: Map<string, PageBuildData>;
      updateConfig: (newConfig: vite.InlineConfig) => void;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:ssr'?: (options: {
      manifest: SerializedSSRManifest;
      middlewareEntryPoint: URL | undefined;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:generated'?: (options: {
      dir: URL;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:done'?: (options: {
      pages: { pathname: string }[];
      dir: URL;
      assets: Map<string, URL[]>;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;

    // ... any custom hooks from integrations
  };
}

Hooks

Astro proporciona hooks que las integraciones pueden implementar para ejecutarse durante ciertas partes del ciclo de vida de Astro. Los hooks de Astro están definidos en la interfaz IntegrationHooks, que es parte del namespace global Astro. Cada hook tiene una opción de logger que te permite usar el logger de Astro para escribir logs.

Los siguientes hooks están integrados en Astro:

astro:config:setup

Next hook: astro:route:setup

Cuándo: En la inicialización, antes de que tanto la configuración de Vite como la de Astro se hayan resuelto.

Por qué: Para extender la configuración del proyecto. Esto incluye actualizar la configuración de Astro, aplicar plugins de Vite, añadir renderers de componentes e inyectar scripts en la página.

'astro:config:setup'?: (options: {
  config: AstroConfig;
  command: 'dev' | 'build' | 'preview' | 'sync';
  isRestart: boolean;
  updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
  addRenderer: (renderer: AstroRenderer) => void;
  addClientDirective: (directive: ClientDirectiveConfig) => void;
  addMiddleware: (middleware: AstroIntegrationMiddleware) => void;
  addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void;
  addWatchFile: (path: URL | string) => void;
  injectScript: (stage: InjectedScriptStage, content: string) => void;
  injectRoute: (injectedRoute: InjectedRoute) => void;
  createCodegenDir: () => URL;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Opción config

Type: AstroConfig

Una copia de solo lectura de la configuración de Astro proporcionada por el usuario. Esto se resuelve antes de que cualquier otra integración se haya ejecutado. Si necesitas una copia de la configuración después de que todas las integraciones hayan completado sus actualizaciones de configuración, consulta el hook astro:config:done.

Opción command

Type: 'dev' | 'build' | 'preview' | 'sync'

• dev - El proyecto se ejecuta con astro dev
• build - El proyecto se ejecuta con astro build
• preview - El proyecto se ejecuta con astro preview
• sync - El proyecto se ejecuta con astro sync

Opción isRestart

Type: boolean

Añadido en: astro@1.5.0

false cuando el dev server inicia, true cuando se dispara una recarga. Útil para detectar cuando esta función se llama más de una vez.

Opción updateConfig()

Type: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;

Una función callback para actualizar la configuración de Astro proporcionada por el usuario. Cualquier configuración que proporciones se combinará con la configuración del usuario + otras actualizaciones de configuración de integraciones, ¡así que puedes omitir claves libremente!

Por ejemplo, supongamos que necesitas proporcionar un plugin de Vite al proyecto del usuario:

import bananaCSS from '@vitejs/official-banana-css-plugin';

export default {
  name: 'banana-css-integration',
  hooks: {
    'astro:config:setup': ({ updateConfig }) => {
      updateConfig({
        vite: {
          plugins: [bananaCSS()],
        }
      })
    }
  }
}

Opción addRenderer()

Type: (renderer: AstroRenderer) => void;
Examples: svelte, react, preact, vue, solid

Una función callback para añadir un renderer de framework de componentes (ej. React, Vue, Svelte, etc).

Opción addWatchFile()

Type: (path: URL | string) => void

Añadido en: astro@1.5.0

Si tu integración depende de algún archivo de configuración que Vite no observa y/o necesita un reinicio completo del dev server para que surta efecto, añádelo con addWatchFile(). Siempre que ese archivo cambie, el dev server de Astro se recargará (puedes comprobar cuándo ocurre una recarga con isRestart).

Ejemplo de uso:

// Must be an absolute path!
addWatchFile('/home/user/.../my-config.json');
addWatchFile(new URL('./ec.config.mjs', config.root));

Opción addClientDirective()

Type: (directive: ClientDirectiveConfig) => void;

Añadido en: astro@2.6.0

Añade una directiva de cliente personalizada para usar en archivos .astro.

Ten en cuenta que los entrypoints de las directivas solo se empaquetan a través de esbuild y deben mantenerse pequeños para no ralentizar la hidratación de componentes.

Ejemplo de uso:

astro.config.mjs

import { defineConfig } from 'astro/config';
import clickDirective from './astro-click-directive/register.js'

// https://astro.build/config
export default defineConfig({
  integrations: [
    clickDirective()
  ],
});

astro-click-directive/register.js

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "client:click",
  hooks: {
    "astro:config:setup": ({ addClientDirective }) => {
      addClientDirective({
        name: "click",
        entrypoint: "./astro-click-directive/click.js",
      });
    },
  },
});

astro-click-directive/click.js

/**
 * Hydrate on first click on the window
 * @type {import('astro').ClientDirective}
 */
export default (load, opts, el) => {
  window.addEventListener('click', async () => {
    const hydrate = await load()
    await hydrate()
  }, { once: true })
}

También puedes añadir tipos para las directivas en el archivo de definición de tipos de tu librería:

astro-click-directive/index.d.ts

import 'astro'
declare module 'astro' {
  interface AstroClientDirectives {
    'client:click'?: boolean
  }
}

Opción addDevToolbarApp()

Type: (entrypoint: DevToolbarAppEntry) => void;

Añadido en: astro@3.4.0

Añade una app personalizada de dev toolbar.

Ejemplo de uso:

astro.config.mjs

import { defineConfig } from 'astro/config';
import devToolbarIntegration from './astro-dev-toolbar-app/integration.js'

// https://astro.build/config
export default defineConfig({
  integrations: [
    devToolbarIntegration()
  ],
});

astro-dev-toolbar-app/integration.js

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "dev-toolbar-app",
  hooks: {
    "astro:config:setup": ({ addDevToolbarApp }) => {
      addDevToolbarApp({
        entrypoint: "./astro-dev-toolbar-app/plugin.js",
        id: "my-plugin",
        name: "My Plugin"
      });
    },
  },
});

astro-dev-toolbar-app/plugin.js

/**
 * @type {import('astro').DevToolbarApp}
 */
export default {
  id: "my-plugin",
  name: "My Plugin",
  icon: "<svg>...</svg>",
  init() {
    console.log("I'm a dev toolbar app!")
  },
};

Opción addMiddleware()

Type: (middleware: AstroIntegrationMiddleware) => void;

Añadido en: astro@3.5.0

Añade middleware para ejecutar en cada petición. Toma el módulo entrypoint que contiene el middleware, y un order para especificar si debe ejecutarse antes (pre) de otro middleware o después (post).

@my-package/integration.js

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "my-middleware-package",
  hooks: {
    "astro:config:setup": ({ addMiddleware }) => {
      addMiddleware({
        entrypoint: '@my-package/middleware',
        order: 'pre'
      });
    },
  },
});

El middleware se define en un paquete con una función onRequest(), al igual que el middleware definido por el usuario.

@my-package/middleware.js

import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => {
  if(context.url.pathname === '/some-test-path') {
    return Response.json({
      ok: true
    });
  }

  return next();
});

Añadido en: astro@5.0.0

La función también acepta una URL para el entrypoint:

@my-package/integration.js

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "my-middleware-package",
  hooks: {
    "astro:config:setup": ({ addMiddleware }) => {
      addMiddleware({
        entrypoint: new URL('./middleware.js', import.meta.url),
        order: 'pre'
      });
    },
  },
});

Opción injectRoute()

Type: ({ pattern: string; entrypoint: string | URL; prerender?: boolean }) => void;

Una función callback para inyectar rutas en un proyecto de Astro. Las rutas inyectadas pueden ser páginas .astro o route handlers de .js y .ts.

injectRoute() toma un objeto con un pattern y un entrypoint.

• pattern - dónde debería output la ruta en el navegador, por ejemplo /foo/bar. Un pattern puede usar la sintaxis de filepath de Astro para denotar rutas dinámicas, por ejemplo /foo/[bar] o /foo/[...bar]. Ten en cuenta que no se necesita una extensión de archivo en el pattern.
• entrypoint - un bare module specifier que apunta hacia la página .astro o el route handler .js/.ts que maneja la ruta denotada en el pattern.
• prerender - un booleano para establecer si Astro no puede detectar tu export prerender.

Ejemplo de uso

injectRoute({
  // Use Astro’s pattern syntax for dynamic routes.
  pattern: '/subfolder/[dynamic]',
  // Use relative path syntax for a local route.
  entrypoint: './src/dynamic-page.astro',
  // Use only if Astro can't detect your prerender export
  prerender: false
});

Para una integración diseñada para ser instalada en otros proyectos, usa su nombre de paquete para referirte al entrypoint de la ruta. El siguiente ejemplo muestra un paquete publicado en npm como @fancy/dashboard inyectando una ruta de dashboard:

injectRoute({
  pattern: '/fancy-dashboard',
  entrypoint: '@fancy/dashboard/dashboard.astro'
});

Al publicar tu paquete (@fancy/dashboard, en este caso) en npm, debes exportar dashboard.astro en tu package.json:

package.json

{
  "name": "@fancy/dashboard",
  // ...
  "exports": { "./dashboard.astro": "./dashboard.astro" }
}

Añadido en: astro@5.0.0

La función también acepta una URL para el entrypoint:

injectRoute({
  pattern: '/fancy-dashboard',
  entrypoint: new URL('./dashboard.astro', import.meta.url)
});

Opción injectScript()

Type: (stage: InjectedScriptStage, content: string) => void;

Una función callback para inyectar una cadena de contenido JavaScript en cada página.

El stage denota cómo este script (el content) debería insertarse. Algunos stages permiten insertar scripts sin modificación, mientras que otros permiten optimización durante el step de bundling de Vite:

• "head-inline": Inyectado en una etiqueta script en el <head> de cada página. No optimizado ni resuelto por Vite.

• "before-hydration": Importado del lado del cliente, antes de que se ejecute el script de hidratación. Optimizado y resuelto por Vite.

• "page": Similar a head-inline, excepto que el snippet inyectado es manejado por Vite y empaquetado con cualquier otra etiqueta <script> definida dentro de los componentes de Astro en la página. El script se cargará con un <script type="module"> en el output final de la página, optimizado y resuelto por Vite.

• "page-ssr": Importado como un módulo separado en el frontmatter de cada componente de página de Astro. Como este stage importa tu script, el global Astro no está disponible y tu script solo se ejecutará una vez cuando el import se evalúe por primera vez.

  El uso principal del stage page-ssr es inyectar un import de CSS en cada página para que sea optimizado y resuelto por Vite:

  injectScript('page-ssr', 'import "global-styles.css";');

createCodegenDir()

Type: () => URL;

Añadido en: astro@5.0.0

Una función que crea la carpeta <root>/.astro/integrations/<normalized_integration_name> y devuelve su ruta.

Te permite tener una carpeta dedicada, evitando conflictos con otra integración o con el propio Astro. Este directorio se crea al llamar a esta función, por lo que es seguro escribir archivos directamente en él:

my-integration.ts

import { writeFileSync } from 'node:fs'

const integration = {
  name: 'my-integration',
  hooks: {
    'astro:config:setup': ({ createCodegenDir }) => {
      const codegenDir = createCodegenDir()
      writeFileSync(new URL('cache.json', codegenDir), '{}', 'utf-8')
    }
  }
}

astro:route:setup

Añadido en: astro@4.14.0

Previous hook: astro:config:setup

Next hook: astro:routes:resolved

Cuándo: En astro build, antes de que comience el bundling. En astro dev, mientras se construye el module graph y en cada cambio a una ruta basada en archivos (añadida/eliminada/actualizada).

Por qué: Para establecer opciones para una ruta en tiempo de build o de petición, como habilitar el server rendering on-demand.

'astro:route:setup'?: (options: {
  route: RouteOptions;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Opción route

Type: { readonly component: string; prerender?: boolean; }

Un objeto con una propiedad component para identificar la ruta y los siguientes valores adicionales que te permiten configurar la ruta generada: prerender.

route.component

Type: string

Añadido en: astro@4.14.0

La propiedad component indica el entrypoint que se renderizará en la ruta. Puedes acceder a este valor antes de que las rutas se construyan para configurar el server rendering on-demand para esa página.

route.prerender

Type: boolean
Default: undefined

Añadido en: astro@4.14.0

La propiedad prerender se usa para configurar el server rendering on-demand para una ruta. Si el archivo de ruta contiene un valor export const prerender explícito, el valor se usará como predeterminado en lugar de undefined.

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [setPrerender()],
});

function setPrerender() {
  return {
    name: 'set-prerender',
    hooks: {
      'astro:route:setup': ({ route }) => {
        if (route.component.endsWith('/blog/[slug].astro')) {
          route.prerender = true;
        }
      },
    },
  };
}

Si el valor final después de ejecutar todos los hooks es undefined, la ruta recurrirá a un valor predeterminado de prerender basado en la opción output: prerenderizada para el modo static, y renderizada on-demand para el modo server.

astro:routes:resolved

Añadido en: astro@5.0.0

Previous hook: astro:route:setup

Siguiente hook: astro:config:done (solo durante el setup)

Cuándo: En astro dev, también se ejecuta en cada cambio a una ruta basada en archivos (añadida/eliminada/actualizada).

Por qué: Para acceder a las rutas y sus metadatos

'astro:routes:resolved'?: (options: {
  routes: IntegrationResolvedRoute[];
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Opción routes

Type: IntegrationResolvedRoute[]

Una lista de todas las rutas con sus metadatos asociados.

Ejemplo de uso:

my-integration.mjs

const integration = () => {
  return {
    name: 'my-integration',
    hooks: {
      'astro:routes:resolved': ({ routes }) => {
        const projectRoutes = routes.filter(r => r.origin === 'project').map(r => r.pattern)

        console.log(projectRoutes)
      },
    }
  }
}

astro:config:done

Previous hook: astro:routes:resolved

Siguiente hook: astro:server:setup cuando se ejecuta en modo “dev”, o astro:build:start durante los builds de producción

Cuándo: Después de que la configuración de Astro se haya resuelto y otras integraciones hayan ejecutado sus hooks de astro:config:setup.

Por qué: Para obtener la configuración final para usar en otros hooks.

'astro:config:done'?: (options: {
  config: AstroConfig;
  setAdapter: (adapter: AstroAdapter) => void;
  injectTypes: (injectedType: InjectedType) => URL;
  logger: AstroIntegrationLogger;
  buildOutput: 'static' | 'server';
}) => void | Promise<void>;

Opción config

Type: AstroConfig

Una copia de solo lectura de la configuración de Astro proporcionada por el usuario. Esto se resuelve después de que otras integraciones se hayan ejecutado.

Opción setAdapter()

Type: (adapter: AstroAdapter) => void;

Convierte la integración en un adapter. Lee más en la API de adapters.

Opción injectTypes()

Type: (injectedType: { filename: string; content: string }) => URL

Añadido en: astro@4.14.0

Te permite inyectar tipos en el proyecto de tu usuario añadiendo un nuevo archivo *.d.ts.

La propiedad filename se usará para generar un archivo en /.astro/integrations/<normalized_integration_name>/<normalized_filename>.d.ts y debe terminar con ".d.ts".

La propiedad content creará el cuerpo del archivo y debe ser TypeScript válido.

Adicionalmente, injectTypes() devuelve una URL a la ruta normalizada para que puedas sobrescribir su contenido más adelante, o manipularlo como quieras.

const path = injectTypes({
  filename: "types.d.ts",
  content: "declare module 'virtual:integration' {}"
})
console.log(path) // URL

Opción buildOutput

Type: 'static' | 'server'

Añadido en: astro@5.0.0

Te permite adaptar la lógica de tu integración dependiendo del output del proyecto del usuario.

astro:server:setup

Previous hook: astro:config:done

Next hook: astro:server:start

Cuándo: Justo después de que el servidor de Vite se cree en modo “dev”, pero antes de que se dispare el evento listen(). Consulta la API createServer de Vite para más información.

Por qué: Para actualizar las opciones y middleware del servidor de Vite, o habilitar el soporte para refrescar el content layer.

'astro:server:setup'?: (options: {
  server: vite.ViteDevServer;
  logger: AstroIntegrationLogger;
  toolbar: ReturnType<typeof getToolbarServerCommunicationHelpers>;
  refreshContent: (options: {
    loaders?: Array<string>;
    context?: Record<string, any>;
  }) => Promise<void>;
}) => void | Promise<void>;

Opción server

Type: ViteDevServer

Una instancia mutable del servidor de Vite usada en modo “dev”. Por ejemplo, esto es usado por nuestra integración de Partytown para inyectar el servidor de Partytown como middleware:

export default {
  name: 'partytown',
  hooks: {
    'astro:server:setup': ({ server }) => {
      server.middlewares.use(
        function middleware(req, res, next) {
          // handle requests
        }
      );
    }
  }
}

Opción toolbar

Type: ReturnType<typeof getToolbarServerCommunicationHelpers>

Añadido en: astro@4.7.0

Un objeto que proporciona funciones callback para interactuar con la dev toolbar:

toolbar.on()

Tipo: <T>(event: string, callback: (data: T) => void) => void

Una función que toma un nombre de evento como primer argumento y una función callback como segundo argumento. Esto te permite recibir un mensaje desde una app de la dev toolbar con datos asociados a ese evento.

toolbar.onAppInitialized()

Type: (appId: string, callback: (data: Record<string, never>) => void) => void

Una función que se dispara cuando se inicializa una app de la dev toolbar. El primer argumento es el id de la app que se inicializó. El segundo argumento es una función callback que se ejecuta cuando la app se inicializa.

toolbar.onAppToggled()

Type: (appId: string, callback: (data: { state: boolean; }) => void) => void

Una función que se dispara cuando una app de la dev toolbar se activa o desactiva. El primer argumento es el id de la app que se activó o desactivó. El segundo argumento es una función callback que proporciona el estado a ejecutar cuando la aplicación se activa o desactiva.

toolbar.send()

Type: <T>(event: string, payload: T) => void

Una función que envía un mensaje a la dev toolbar que una app puede escuchar. Toma un nombre de evento como primer argumento y un payload como segundo argumento, que puede ser cualquier dato serializable.

Opción refreshContent()

Type: (options: { loaders?: Array<string>; context?: Record<string, any>; }) => Promise<void>

Añadido en: astro@5.0.0

Una función para que las integraciones disparen una actualización del content layer durante astro dev. Esto se puede usar, por ejemplo, para registrar un endpoint de webhook durante el dev, o para abrir un socket a un CMS para escuchar cambios.

Por defecto, refreshContent() refrescará todas las colecciones. Puedes pasar opcionalmente una propiedad loaders, que es un array de nombres de loaders. Si se proporciona, solo se refrescarán las colecciones que usen esos loaders. Por ejemplo, una integración de CMS podría usar esta propiedad para refrescar solo sus propias colecciones.

También puedes pasar un objeto context a los loaders. Esto se puede usar para pasar datos arbitrarios como el cuerpo del webhook, o un evento del websocket.

my-integration.ts

{
  name: 'my-integration',
  hooks: {
    'astro:server:setup': async ({ server, refreshContent }) => {
      // Register a dev server webhook endpoint
      server.middlewares.use('/_refresh', async (req, res) => {
        if(req.method !== 'POST') {
          res.statusCode = 405
          res.end('Method Not Allowed');
          return
        }
        let body = '';
        req.on('data', chunk => {
          body += chunk.toString();
        });
        req.on('end', async () => {
          try {
            const webhookBody = JSON.parse(body);
            await refreshContent({
              context: { webhookBody },
              loaders: ['my-loader']
            });
            res.writeHead(200, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify({ message: 'Content refreshed successfully' }));
          } catch (error) {
            res.writeHead(500, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify({ error: 'Failed to refresh content: ' + error.message }));
          }
        });
      });
    }
  }
}

El loader puede entonces acceder a la propiedad refreshContextData para obtener el cuerpo del webhook. Consulta la propiedad refreshContextData para más información.

astro:server:start

Previous hook: astro:server:setup

Next hook: astro:server:done

Cuándo: Justo después de que se haya disparado el evento listen() del servidor.

Por qué: Para interceptar peticiones de red en la dirección especificada. Si planeas usar esta dirección para middleware, considera usar astro:server:setup en su lugar.

'astro:server:start'?: (options: {
  address: AddressInfo;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Opción address

Type: AddressInfo

La dirección, familia y número de puerto proporcionados por el método server.address() del módulo Net de Node.js.

astro:server:done

Previous hook: astro:server:start

Cuándo: Justo después de que el dev server se cierre.

Por qué: Para ejecutar cualquier evento de limpieza que puedas disparar durante los hooks de astro:server:setup o astro:server:start.

'astro:server:done'?: (options: {
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

astro:build:start

Previous hook: astro:config:done

Next hook: astro:build:setup

Cuándo: Después del evento astro:config:done, pero antes de que comience el build de producción.

Por qué: Para configurar cualquier objeto o cliente global necesario durante un build de producción. Esto también puede extender las opciones de configuración del build en la API de adapters.

'astro:build:start'?: (options: {
  logger: AstroIntegrationLogger;
  setPrerenderer: (prerenderer: AstroPrerenderer | ((defaultPrerenderer: AstroPrerenderer) => AstroPrerenderer)) => void;
}) => void | Promise<void>;

Opción setPrerenderer()

Type: (prerenderer: AstroPrerenderer | ((defaultPrerenderer: AstroPrerenderer) => AstroPrerenderer)) => void

Añadido en: astro@6.0.0

Una función callback para establecer un prerenderer personalizado para el build. Esto permite que los adapters proporcionen su propia lógica de prerendering.

La función acepta directamente un objeto AstroPrerenderer, o una función factory que recibe el prerenderer por defecto y devuelve uno personalizado. Esto es útil cuando quieres envolver o extender el comportamiento por defecto.

'astro:build:start': ({ setPrerenderer }) => {
  setPrerenderer((defaultPrerenderer) => ({
    name: 'my-prerenderer',
    async setup() {
      // Optional: called once before prerendering starts
    },
    async getStaticPaths() {
      // Returns array of { pathname: string, route: RouteData }
      return defaultPrerenderer.getStaticPaths();
    },
    async render(request, { routeData }) {
      // request: Request, options: { routeData: RouteData }
      // Returns: Response
    },
    async teardown() {
      // Optional: called after all pages are prerendered
    }
  }));
}

Consulta la referencia de adapters para más detalles sobre cómo implementar un prerenderer personalizado.

astro:build:setup

Previous hook: astro:build:start

Next hook: astro:build:ssr

Cuándo: Después del hook astro:build:start, se ejecuta inmediatamente antes del build.

Por qué: En este punto, la configuración de Vite para el build se ha construido completamente, esta es tu última oportunidad para modificarla. Esto puede ser útil, por ejemplo, para sobrescribir algunos valores por defecto. Si no estás seguro de si deberías usar este hook o astro:build:start, usa astro:build:start en su lugar.

'astro:build:setup'?: (options: {
  vite: vite.InlineConfig;
  pages: Map<string, PageBuildData>;
  updateConfig: (newConfig: vite.InlineConfig) => void;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Opción vite

Type: InlineConfig

Un objeto que te permite acceder a la configuración de Vite usada en el build.

Esto puede ser útil si necesitas acceder a opciones de configuración en tu integración:

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:setup': ({ vite }) => {
      const { publicDir, root } = vite;
    },
  }
}

Opción pages

Type: Map<string, PageBuildData>

Un Map con una lista de páginas como clave y sus datos de build como valor.

Esto se puede usar para realizar una acción si una ruta coincide con un criterio:

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:setup': ({ pages }) => {
      pages.forEach((data) => {
        if (data.route.pattern.test("/blog")) {
          console.log(data.route.type);
        }
      });
    },
  }
}

El objeto PageBuildData

Describe cómo construir una página.

PageBuildData.key

Type: string

Añadido en: astro@4.8.0

Especifica un identificador único para la página.

PageBuildData.component

Type: string

Especifica la URL del componente de origen.

PageBuildData.route

Type: RouteData

Describe la información sobre la ruta de la página.

PageBuildData.moduleSpecifier

Type: string

Define una cadena que puede resolverse en una ruta de archivo para el módulo.

PageBuildData.styles

Type: Array<{ depth: number; order: number; sheet: { type: 'inline'; content: string } | { type: 'external'; src: string } }>

Añadido en: astro@2.4.0

Una lista de estilos para renderizar en la página. Cada estilo contiene su depth en el árbol de componentes y su order de visualización en la página, así como una indicación de si debería aplicarse como un estilo inline o externo.

Opción updateConfig()

Type: (newConfig: InlineConfig) => void

Una función callback para actualizar las opciones de Vite usadas en el build. Cualquier configuración que proporciones se combinará con la configuración del usuario + otras actualizaciones de configuración de integraciones, ¡así que puedes omitir claves libremente!

Por ejemplo, esto se puede usar para proporcionar un plugin al proyecto del usuario:

import awesomeCssPlugin from 'awesome-css-vite-plugin';

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:setup': ({ updateConfig }) => {
      updateConfig({
        plugins: [awesomeCssPlugin()],
      })
    }
  }
}

astro:build:ssr

Previous hook: astro:build:setup

Next hook: astro:build:generated

Cuándo: Después de que un build de producción SSR haya completado.

Por qué: Para acceder al manifest SSR y al mapeo de los entry points emitidos. Esto es útil cuando se crean builds SSR personalizados en plugins o integraciones.

• middlewareEntryPoint es la ruta del sistema de archivos del archivo de middleware;

'astro:build:ssr'?: (options: {
  manifest: SerializedSSRManifest;
  middlewareEntryPoint: URL | undefined;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Opción manifest

Type: SerializedSSRManifest

Te permite crear un build personalizado accediendo a una versión serializada del SSRManifest. Esto contiene la misma información que SSRManifest, con algunas propiedades convertidas a formatos serializables.

El siguiente ejemplo comprueba la configuración de i18n.strategy almacenada en el manifest:

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:ssr': ({ manifest }) => {
      const { i18n } = manifest;
      if (i18n?.strategy === "domains-prefix-always") {
        // do something
      }
    },
  },
}

manifest.rootDir

Type: string

Especifica una versión serializada del SSRManifest.rootDir.

manifest.srcDir

Type: string

Especifica una versión serializada del SSRManifest.srcDir.

manifest.cacheDir

Type: string

Especifica una versión serializada del SSRManifest.cacheDir.

manifest.outDir

Type: string

Especifica una versión serializada del SSRManifest.outDir.

manifest.publicDir

Type: string

Especifica una versión serializada del SSRManifest.publicDir.

manifest.buildClientDir

Type: string

Especifica una versión serializada del SSRManifest.buildClientDir.

manifest.buildServerDir

Type: string

Especifica una versión serializada del SSRManifest.buildServerDir.

manifest.routes

Type: SerializedRouteInfo[]

Define una lista de información de rutas serializada. Cada ruta contiene las mismas propiedades que SSRManifest.routes, con routeData convertido a un formato serializable con JSON.

manifest.assets

Type: string[]

Define una lista de rutas de archivos de assets serializadas.

manifest.componentMetadata

Type: [string, SSRComponentMetadata][]

Añadido en: astro@2.1.7

Define un array de pares clave-valor donde el primer elemento es el identificador del componente y el segundo es un objeto que describe los metadatos del build.

manifest.inlinedScripts

Type: [string, string][]

Define un array de pares clave-valor donde cada entrada es una tupla. El primer elemento es el identificador del script y el segundo es el contenido del script.

manifest.clientDirectives

Type: [string, string][]

Añadido en: astro@2.5.0

Define un array de pares clave-valor donde el primer elemento es el nombre de la directiva (ej. load, visible) y el segundo es el código de implementación de la directiva.

manifest.key

Type: string

Añadido en: astro@4.13.4

Especifica la clave criptográfica, serializada como una cadena, usada para encriptar las props de las server islands.

Opción middlewareEntryPoint

Type: URL | undefined

Añadido en: astro@2.8.0

Expone la ruta del archivo de middleware.

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:ssr': ({ middlewareEntryPoint }) => {
      if (middlewareEntryPoint) {
        // do some operations if a middleware exist
      }
    },
  },
}

astro:build:generated

Añadido en: astro@1.3.0

Previous hook: astro:build:ssr

Next hook: astro:build:done

Cuándo: Después de que un build de producción estático haya terminado de generar rutas y assets.

Por qué: Para acceder a las rutas y assets generados antes de que los artefactos del build se limpien. Este es un caso de uso muy poco común. Recomendamos usar astro:build:done a menos que realmente necesites acceder a los archivos generados antes de la limpieza.

'astro:build:generated'?: (options: {
  dir: URL;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Opción dir

Type: URL

Una ruta URL al directorio de output del build.

El siguiente ejemplo usa la utilidad integrada de Node fileURLToPath() para computar una cadena de ruta absoluta válida para un archivo proporcionado por la integración:

import { fileURLToPath } from 'node:url';

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:generated': ({ dir }) => {
      const outFile = fileURLToPath(new URL('./my-integration.json', dir));
    }
  }
}

astro:build:done

Previous hook: astro:build:generated

Cuándo: Después de que un build de producción (SSG o SSR) haya completado.

Por qué: Para acceder a las rutas y assets generados para extensión (ej. copiar contenido al directorio /assets generado). Si planeas transformar los assets generados, recomendamos explorar la API de Plugins de Vite y configurar vía astro:config:setup en su lugar.

'astro:build:done'?: (options: {
  pages: { pathname: string }[];
  dir: URL;
  assets: Map<string, URL[]>;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Opción dir

Type: URL

Una ruta URL al directorio de output del build.

El siguiente ejemplo usa la utilidad integrada de Node fileURLToPath() para computar una cadena de ruta absoluta válida para un archivo proporcionado por la integración antes de escribir en él:

import { writeFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';

export default function myIntegration() {
  return {
    hooks: {
      'astro:build:done': async ({ dir }) => {
        const metadata = await getIntegrationMetadata();
        // Use fileURLToPath to get a valid, cross-platform absolute path string
        const outFile = fileURLToPath(new URL('./my-integration.json', dir));
        await writeFile(outFile, JSON.stringify(metadata));
      }
    }
  }
}

Opción assets

Type: Map<string, URL[]>

Añadido en: astro@5.0.0

Contiene URLs a las rutas de archivos de output, agrupadas por la propiedad pattern de IntegrationResolvedRoute.

Opción pages

Type: { pathname: string }[]

Una lista de todas las páginas generadas. Cada entrada es un objeto con una propiedad:

• pathname - la ruta finalizada de la página.

Hooks personalizados

Se pueden añadir hooks personalizados a las integraciones extendiendo la interfaz IntegrationHooks mediante augmentación global.

declare global {
  namespace Astro {
    export interface IntegrationHook {
      'your:hook': (params: YourHookParameters) => Promise<void>
    }
  }
}

Astro reserva el prefijo astro: para futuros hooks integrados. Por favor, elige un prefijo diferente al nombrar tu hook personalizado.

Entornos Vite de Astro

Astro hereda los entornos que Vite proporciona por defecto, ssr y client.

Adicionalmente hay otros dos entornos que Astro crea:

• prerender es un entorno usado durante el build y se usa para construir páginas estáticas.
• astro es un entorno usado durante el desarrollo, y se usa como un entorno SSR “secundario” cuando el entorno ssr de Vite no es un entorno de dev ejecutable.

Los entornos de Vite de Astro te permiten optimizar los plugins de Vite de tu integración para diferentes entornos. Uno de los usos principales de los entornos de Vite es la capacidad de ejecutar y configurar los plugins de Vite de tu integración condicionalmente:

resolveId(id) {
  if (id === '\0virtual:foo') {
    if (this.environment.name === 'client') {
      throw new Error('This is a server-only module');
    }
    return 'export const foo = "bar"';
  }
}

Referencia de tipos de integración

Los siguientes tipos pueden importarse desde el módulo astro:

import type {
  AstroIntegrationLogger,
  AstroIntegrationMiddleware,
  AstroMiddlewareInstance,
  AstroPrerenderer,
  ClientDirectiveConfig,
  HookParameters,
  IntegrationResolvedRoute,
  RedirectConfig,
  RouteData,
  RoutePart,
  RouteType,
  SSRComponentMetadata,
  SSRManifest,
  ValidRedirectStatus,
} from "astro";

AstroIntegrationLogger

Una instancia del logger de Astro, útil para escribir logs. Este logger usa el mismo log level configurado vía CLI.

Métodos disponibles para escribir en la terminal:

• logger.info("Message");
• logger.warn("Message");
• logger.error("Message");
• logger.debug("Message");

Todos los mensajes se preceden con una etiqueta que tiene el mismo valor que el nombre de la integración.

integration.ts

import type { AstroIntegration } from "astro";
export function formatIntegration(): AstroIntegration {
  return {
    name: "astro-format",
    hooks: {
      "astro:build:done": ({ logger }) => {
        // do something
        logger.info("Integration ready.");
      }
    }
  }
}

El ejemplo anterior registrará un mensaje que incluye el mensaje info proporcionado:

[astro-format] Integration ready.

Para registrar algunos mensajes con una etiqueta diferente, usa el método .fork para especificar una alternativa al name por defecto:

integration.ts

import type { AstroIntegration } from "astro";
export function formatIntegration(): AstroIntegration {
  return {
    name: "astro-format",
    hooks: {
      "astro:config:done": ({ logger }) => {
        // do something
        logger.info("Integration ready.");
      },
      "astro:build:done": ({ logger }) => {
        const buildLogger = logger.fork("astro-format/build");
        // do something
        buildLogger.info("Build finished.")
      }
    }
  }
}

El ejemplo anterior producirá logs con [astro-format] por defecto, y [astro-format/build] cuando se especifique:

[astro-format] Integration ready.
[astro-format/build] Build finished.

AstroIntegrationMiddleware

Type: { order: "pre" | "post"; entrypoint: string | URL; }

Describe un middleware añadido por una integración.

AstroIntegrationMiddleware.order

Type: "pre" | "post"

Especifica si el middleware debería ejecutarse antes (pre) o después (post) de otro middleware.

AstroIntegrationMiddleware.entrypoint

Type: string | URL

Define la ruta de importación del middleware.

AstroMiddlewareInstance

Type: { onRequest?: MiddlewareHandler; }

Un objeto que contiene una propiedad onRequest() definida con la función de middleware del proyecto cuando existe.

AstroPrerenderer

Type: string

Añadido en: astro@6.0.0

Describe un prerender personalizado que los adapters pueden proporcionar para controlar el prerendering de páginas.

AstroPrerenderer.name

Type: string

Especifica un nombre único para el prerender.

AstroPrerenderer.setup()

Type: () => Promise<void>

Define un método opcional que se llamará una vez antes de que comience el prerendering. Esto es útil para iniciar un servidor de preview.

AstroPrerenderer.getStaticPaths()

Type: () => Promise<Array<{ pathname: string; route: RouteData; }>>

Devuelve una lista de objetos que describen la ruta prerenderizada y sus datos asociados.

AstroPrerenderer.render()

Type: (request: Request, options: { routeData: RouteData }) => Promise<Response>

Define un método opcional que describe cómo renderizar una página. Esto será llamado por Astro para cada ruta devuelta por getStaticPaths().

AstroPrerenderer.teardown()

Type: () => Promise<void>

Define un método opcional llamado una vez que todas las páginas han sido prerenderizadas. Esto es útil para realizar tareas de limpieza como detener un servidor de preview.

ClientDirectiveConfig

Type: { name: string; entrypoint: string | URL; }

Describe una directiva de cliente personalizada añadida por una integración.

ClientDirectiveConfig.name

Type: string

Un nombre personalizado para el evento disparado por la directiva.

ClientDirectiveConfig.entrypoint

Type: string | URL

Define la ruta de importación del código que se ejecuta cada vez que se usa la directiva.

HookParameters

Puedes obtener el tipo de los argumentos de un hook pasando el nombre del hook al utility type HookParameters.

En el siguiente ejemplo, el argumento options de una función está tipado para coincidir con los parámetros del hook astro:config:setup:

import type { HookParameters } from 'astro';

function mySetup(options: HookParameters<'astro:config:setup'>) {
  options.updateConfig({ /* ... */ });
}

IntegrationResolvedRoute

Un subconjunto de RouteData con propiedades remapeadas.

interface IntegrationResolvedRoute extends Pick<
    RouteData,
    'params' | 'pathname' | 'segments' | 'type' | 'redirect' | 'origin'
  > & {
  pattern: RouteData['route'];
  patternRegex: RouteData['pattern'];
  entrypoint: RouteData['component'];
  isPrerendered: RouteData['prerender'];
  redirectRoute?: IntegrationResolvedRoute;
  fallbackRoutes: IntegrationResolvedRoute[];
  generate: (data?: any) => string;
}

IntegrationResolvedRoute.pattern

Type: RouteData['route']

Te permite identificar el tipo de ruta basándose en su path. Aquí hay algunos ejemplos de paths asociados con su patrón:

• src/pages/index.astro será /
• src/pages/blog/[...slug].astro será /blog/[...slug]
• src/pages/site/[blog]/[...slug].astro será /site/[blog]/[...slug]

IntegrationResolvedRoute.patternRegex

Type: RouteData['pattern']

Te permite acceder a un regex usado para coincidir una URL de entrada con una ruta solicitada.

Por ejemplo, dada una ruta [fruit]/about.astro, el regex será /^\/([^/]+?)\/about\/?$/. Usando pattern.test("banana/about") devolverá true.

IntegrationResolvedRoute.entrypoint

Type: RouteData['component']

El pathname de la URL del componente de origen.

IntegrationResolvedRoute.isPrerendered

Type: RouteData['prerender']

Determina si la ruta usa renderizado on demand. El valor será true para proyectos configurados con:

• output: 'static' cuando la ruta no exporta const prerender = true
• output: 'server' cuando la ruta exporta const prerender = false

IntegrationResolvedRoute.redirectRoute

Type: IntegrationResolvedRoute | undefined

Cuando el valor de IntegrationResolvedRoute.type es redirect, el valor será el IntegrationResolvedRoute al que redirigir. De lo contrario, el valor será undefined.

IntegrationResolvedRoute.fallbackRoutes

Type: IntegrationResolvedRoute[]

Añadido en: astro@6.1.0

Cuando el proyecto usa i18n con rutas fallback, el valor será una lista de las rutas a las que esta ruta recurre cuando el locale solicitado no está disponible. El contenido fallback puede servirse como una redirección o rewrite dependiendo de i18n.routing.fallbackType. De lo contrario, el valor será un array vacío.

IntegrationResolvedRoute.generate()

Type: (data?: any) => string

Añadido en: astro@6.0.0

Una función que proporciona los parámetros opcionales de la ruta, los interpola con el patrón de la ruta, y devuelve el pathname de la ruta.

Por ejemplo, con una ruta como /blog/[...id].astro, la función generate() podría devolver:

generate({ id: 'presentation' }) // will output `/blog/presentation`

RedirectConfig

Type: string | { status: ValidRedirectStatus; destination: string; }

Describe el destino de una redirección. Puede ser una cadena o un objeto que contiene información sobre el código de estado y su destino.

RouteData

Describe la información sobre una ruta.

RouteData.route

Type: string

Define el patrón de la ruta actual. Aquí hay algunos ejemplos de paths asociados con su patrón:

• src/pages/index.astro será /
• src/pages/blog/[...slug].astro será /blog/[...slug]
• src/pages/site/[blog]/[...slug].astro será /site/[blog]/[...slug]

RouteData.component

Type: string

Especifica la URL del componente de origen.

RouteData.params

Type: string[]

Te permite acceder a los params de la ruta. Por ejemplo, cuando un proyecto usa las siguientes rutas dinámicas /pages/[lang]/[...slug].astro, el valor será ['lang', '...slug'].

RouteData.pathname

Type: string | undefined

Para rutas regulares, el valor será el pathname de la URL donde esta ruta se servirá. Cuando el proyecto usa rutas dinámicas (ej. [dynamic] o [...spread]), el pathname será undefined.

RouteData.distURL

Type: URL[]

Añadido en: astro@5.0.0

Define las rutas de los archivos físicos emitidos por esta ruta. Cuando una ruta no está prerenderizada, el valor es un array vacío.

RouteData.pattern

Type: RegExp

Especifica un regex para coincidir una URL de entrada con una ruta solicitada.

Por ejemplo, dada una ruta [fruit]/about.astro, el regex será /^\/([^/]+?)\/about\/?$/. Usando pattern.test("banana/about") devolverá true.

RouteData.segments

Type: RoutePart[][]

Te permite acceder a los params de la ruta con metadatos adicionales. Cada objeto contiene las siguientes propiedades:

• content: el nombre del param,
• dynamic: si la ruta es dinámica o no,
• spread: si la ruta dinámica usa la sintaxis spread o no.

Por ejemplo, la siguiente ruta /pages/[blog]/[...slug].astro producirá los segmentos:

[
  [ { content: 'pages', dynamic: false, spread: false } ],
  [ { content: 'blog', dynamic: true, spread: false } ],
  [ { content: '...slug', dynamic: true, spread: true } ]
]

RouteData.type

Type: RouteType

Te permite identificar el tipo de ruta.

RouteData.prerender

Type: boolean

Determina si una ruta usa renderizado on demand o está prerenderizada estáticamente en tiempo de build.

Ver también prerendered en la referencia de routing.

RouteData.redirect

Type: RedirectConfig | undefined

Te permite acceder a la ruta a la que redirigir.

RouteData.redirectRoute

Type: RouteData | undefined

Especifica el RouteData al que redirigir cuando RouteData.type es redirect.

RouteData.fallbackRoutes

Type: RouteData[]

Añadido en: astro@3.5.6

Define una lista de RouteData a los que recurrir cuando i18n.fallback tiene una lista de locales.

RouteData.isIndex

Type: boolean

Especifica si la ruta es un índice de directorio (ej. src/pages/index.astro, src/pages/blog/index.astro).

RouteData.origin

Type: 'internal' | 'external' | 'project'

Añadido en: astro@5.0.0

Determina si una ruta viene del core de Astro (internal), de una integración (external) o del proyecto del usuario (project).

RoutePart

Type: { content: string; dynamic: boolean; spread: boolean; }

Describe un segmento de ruta.

RoutePart.content

Type: string

Especifica el nombre del parámetro para la ruta. Por ejemplo:

• about.astro tiene el nombre about
• [slug].astro tiene el nombre slug
• [...id].astro tiene el nombre id

RoutePart.dynamic

Type: boolean

Si la ruta es dinámica o no.

RoutePart.spread

Type: boolean

Si la ruta dinámica usa la sintaxis spread o no.

RouteType

Type: 'page' | 'endpoint' | 'redirect' | 'fallback'

Una unión de tipos de rutas soportados:

• page: una ruta que vive en el sistema de archivos, usualmente un componente de Astro
• endpoint: una ruta que vive en el sistema de archivos, usualmente un archivo JS que expone métodos de endpoints
• redirect: una ruta que apunta a otra ruta que vive en el sistema de archivos
• fallback: una ruta que no existe en el sistema de archivos que necesita ser manejada con otros medios, usualmente un middleware

SSRComponentMetadata

Type: { propagation: PropagationHint; containsHead: boolean; }

Describe los metadatos del build de un componente renderizado por el servidor.

SSRComponentMetadata.propagation

Type: 'none' | 'self' | 'in-tree'

Una descripción de cómo renderizar el contenido del head desde este componente, incluyendo si el runtime de Astro necesita esperar a un componente:

• none: El componente no propaga el contenido del head.
• self: El componente añade el contenido del head.
• in-tree: Otro componente dentro del árbol de dependencias de este componente añade el contenido del head.

SSRComponentMetadata.containsHead

Type: boolean

Determina si el componente contiene el contenido del head.

SSRManifest

Un objeto que contiene la configuración del build y los metadatos del proyecto que los adapters del servidor usan en runtime para servir páginas renderizadas on-demand.

SSRManifest.adapterName

Type: string

Define el nombre del adapter del servidor usado para el renderizado on-demand.

SSRManifest.routes

Type: RouteInfo[]

Una lista de información sobre las rutas disponibles en este proyecto. Cada entrada contiene las siguientes propiedades.

RouteInfo.routeData

Type: RouteData

Un objeto que describe información conocida sobre una ruta.

RouteInfo.file

Type: string

Especifica la ruta del archivo al entrypoint de la ruta construida.

RouteInfo.links

Type: string[]

Define una lista de elementos link de HTML requeridos por esta ruta.

RouteInfo.scripts

Type: Array<{ children: string; stage: string } | { type: 'inline' | 'external'; value: string }>

Define una lista de scripts asociados con esta ruta. Esto incluye tanto scripts inyectados por integraciones con propiedades children y stage como scripts hoisted con propiedades type y value.

RouteInfo.styles

Type: Array<{ type: "inline"; content: string; } | { type: "external"; src: string; }>

Añadido en: astro@2.4.0

Define la lista de hojas de estilo asociadas con esta ruta. Esto incluye tanto estilos inline como URLs de hojas de estilo.

SSRManifest.site

Type: string

Especifica el site configurado.

SSRManifest.base

Type: string

Especifica el base path configurado para desplegar.

SSRManifest.userAssetsBase

Type: string | undefined

Añadido en: astro@5.3.1

Especifica el base path a usar en modo desarrollo para assets generados por el usuario, como scripts y estilos.

SSRManifest.trailingSlash

Type: AstroConfig['trailingSlash']

Añadido en: astro@3.5.4

Especifica el comportamiento configurado para trailing slashes en modo desarrollo y para páginas renderizadas on-demand.

SSRManifest.buildFormat

Type: NonNullable<AstroConfig['build']>['format']

Añadido en: astro@4.2.2

Especifica el formato de archivo de output configurado.

SSRManifest.compressHTML

Type: boolean | "jsx"

Añadido en: astro@2.7.2

Determina si la minificación de HTML está habilitada en la configuración del proyecto.

SSRManifest.assetsPrefix

Type: string | ({ fallback: string; } & Record<string, string>) | undefined

Añadido en: astro@2.3.1

Especifica el prefijo configurado para los enlaces de assets generados por Astro.

SSRManifest.renderers

Type: SSRLoadedRenderer[]

Una lista de renderers (ej. React, Vue, Svelte, MDX) disponibles para que el servidor los use.

SSRManifest.serverLike

Type: boolean

Añadido en: astro@6.0.0

Determina si esta aplicación usa alguna ruta renderizada on-demand.

SSRManifest.clientDirectives

Type: Map<string, string>

Añadido en: astro@2.5.0

Define un mapeo de nombres de directivas de cliente (ej. load, visible) a su código de implementación. Esto incluye tanto directivas de cliente integradas como directivas de cliente personalizadas.

SSRManifest.entryModules

Type: Record<string, string>

Define un mapeo de entrypoints a sus rutas de archivo de output.

SSRManifest.inlinedScripts

Type: Map<string, string>

Añadido en: astro@4.5.0

Define un mapeo de identificadores de scripts a su contenido para scripts que serán inlineados en el output HTML.

SSRManifest.assets

Type: Set<string>

Define un conjunto de rutas de archivo para todos los assets que son parte del build.

SSRManifest.componentMetadata

Type: Map<string, SSRComponentMetadata>

Añadido en: astro@2.1.7

Define un mapeo de identificadores de componentes a sus metadatos de build. Cada entrada contiene información sobre el comportamiento de propagation y si contiene elementos del head.

SSRManifest.pageModule

Type: { page: ImportComponentInstance; onRequest?: MiddlewareHandler; }

Añadido en: astro@2.7.0

Especifica información sobre un módulo de página.

SSRManifest.pageModule.page()

Type: () => Promise<ComponentInstance>

Una función para obtener una instancia del componente de página.

SSRManifest.pageModule.onRequest()

Type: MiddlewareHandler

Añadido en: astro@3.0.3

Una función de middleware de Astro cuando está definida en el proyecto del usuario.

SSRManifest.pageMap

Type: Map<string, () => Promise<typeof pageModule>>

Define un mapeo de rutas de componentes a sus instancias importables.

SSRManifest.serverIslandMappings

Type: () => Promise<ServerIslandMappings> | ServerIslandMappings

Añadido en: astro@6.0.0

Un objeto, o una función que devuelve un objeto, que describe el mapeo de server islands disponibles.

SSRManifest.serverIslandMappings.serverIslandMap

Type: Map<string, () => Promise<ComponentInstance>>

Añadido en: astro@4.12.0

Define un mapeo de IDs de server islands a sus instancias de componentes.

SSRManifest.serverIslandMappings.serverIslandNameMap

Type: Map<string, string>

Añadido en: astro@4.12.0

Define un mapeo de rutas de componentes de server islands a sus nombres asignados.

SSRManifest.key

Type: Promise<CryptoKey>

Añadido en: astro@4.13.4

Determina la clave criptográfica usada para encriptar las props de las server islands.

SSRManifest.i18n

Type: SSRManifestI18n | undefined

Añadido en: astro@3.5.0

Especifica la configuración de i18n resuelta cuando está habilitada en el proyecto.

SSRManifest.i18n.strategy

Type: "manual" | "pathname-prefix-always" | "pathname-prefix-other-locales" | "pathname-prefix-always-no-redirect" | "domains-prefix-always" | "domains-prefix-other-locales" | "domains-prefix-always-no-redirect"

Define la estrategia de routing de i18n configurada. Esto determina cómo se manejan los locales en las URLs y si ocurren redirecciones.

SSRManifest.i18n.locales

Type: Locales

Especifica una lista de locales soportados configurados en el proyecto.

SSRManifest.i18n.defaultLocale

Type: string

Determina el locale por defecto configurado en el proyecto.

SSRManifest.i18n.fallback

Type: Record<string, string> | undefined

Especifica un mapeo de locales a sus locales fallback como está configurado en i18n.fallback.

SSRManifest.i18n.fallbackType

Type: "redirect" | "rewrite"

Determina la estrategia de fallback configurada para el proyecto.

SSRManifest.i18n.domainLookupTable

Type: Record<string, string>

Un mapeo de dominios configurados a sus locales asociados.

SSRManifest.middleware

Type: () => Promise<AstroMiddlewareInstance> | AstroMiddlewareInstance

Añadido en: astro@4.2.5

Define una instancia para cargar el middleware.

SSRManifest.actions

Type: () => Promise<{ server: Record<string, ActionClient>; }> | { server: Record<string, ActionClient>; }

Añadido en: astro@5.4.2

Un objeto, o una función que devuelve un objeto, con una propiedad server que mapea nombres de acciones a sus funciones invocables.

SSRManifest.sessionDriver()

Type: () => Promise<{ default: SessionDriverFactory | null }>

Añadido en: astro@6.0.0

Obtiene el driver de sesión configurado cuando está habilitado.

SSRManifest.checkOrigin

Type: boolean

Añadido en: astro@4.6.0

Determina si la comprobación de origin está habilitada en la configuración de seguridad.

SSRManifest.allowedDomains

Type: Partial<RemotePattern>[]

Especifica la lista configurada de patrones de host permitidos para peticiones entrantes cuando se usa renderizado on-demand.

SSRManifest.sessionConfig

Type: SessionConfig<TDriver> & { driverModule?: () => Promise<{ default: () => unstorage.Driver }>; }

Añadido en: astro@5.1.0

Un objeto que contiene la configuración de sesión resuelta y una propiedad adicional que define el driver en uso.

SSRManifest.cacheDir

Type: URL

Añadido en: astro@5.2.0

Especifica el directorio configurado para cachear artefactos del build.

SSRManifest.srcDir

Type: URL

Añadido en: astro@5.2.0

Especifica el directorio configurado del que Astro leerá el sitio.

SSRManifest.outDir

Type: URL

Añadido en: astro@5.2.0

Especifica el directorio configurado en el que escribir el build final.

SSRManifest.rootDir

Type: URL

Añadido en: astro@6.0.0

Especifica la URL resuelta para el directorio configurado como raíz del proyecto.

SSRManifest.publicDir

Type: URL

Añadido en: astro@5.2.0

Especifica el directorio configurado para los assets estáticos.

SSRManifest.assetsDir

Type: string

Añadido en: astro@6.0.0

Especifica el directorio configurado para los assets generados en el output del build.

SSRManifest.buildClientDir

Type: URL

Añadido en: astro@5.2.0

Determina la ruta donde los artefactos del build del lado del cliente (ej. JavaScript, CSS) se output dentro del directorio del build.

SSRManifest.buildServerDir

Type: URL

Añadido en: astro@5.2.0

Determina la ruta donde los artefactos del build del lado del servidor se output dentro del directorio del build.

SSRManifest.csp

Type: SSRManifestCSP | undefined

Añadido en: astro@5.9.0

Describe la configuración de Content Security Policy.

SSRManifest.csp.cspDestination

Type: 'adapter' | 'meta' | 'header' | undefined

Especifica si las directivas CSP deberían inyectarse como un elemento meta, como un header de respuesta, o por el adapter cuando soporta establecer headers de respuesta.

SSRManifest.csp.algorithm

Type: 'SHA-256' | 'SHA-384' | 'SHA-512'

Especifica la función de hash configurada.

SSRManifest.csp.scriptHashes

Type: string[]

Especifica una lista de hashes generados para los scripts del proyecto y hashes proporcionados por el usuario para scripts externos.

SSRManifest.csp.scriptResources

Type: string[]

Especifica una lista de sources válidos que combinan los recursos de scripts configurados y los recursos de scripts inyectados.

SSRManifest.csp.isStrictDynamic

Type: boolean

Determina si el soporte para inyección dinámica de scripts está habilitado en la configuración.

SSRManifest.csp.styleHashes

Type: string[]

Especifica una lista de hashes generados para los estilos del proyecto y hashes proporcionados por el usuario para estilos externos.

SSRManifest.csp.styleResources

Type: string[]

Especifica una lista de sources válidos que combinan los recursos de estilos configurados y los recursos de estilos inyectados.

SSRManifest.csp.directives

Type: CspDirective[]

Especifica la lista configurada de sources válidos para tipos de contenido específicos.

SSRManifest.devToolbar

Type: { enabled: boolean; latestAstroVersion: string | undefined; debugInfoOutput: string | undefined; }

Añadido en: astro@6.0.0

Describe la configuración resuelta de la dev toolbar.

SSRManifest.devToolbar.enabled

Type: boolean

Añadido en: astro@6.0.0

Determina si la dev toolbar está habilitada.

SSRManifest.devToolbar.latestAstroVersion

Type: string | undefined

Añadido en: astro@6.0.0

Especifica la última versión disponible de Astro. Esto se usa para notificar al usuario en la dev toolbar cuando hay una actualización disponible. Esto será undefined cuando se cumpla una de las siguientes condiciones:

• la comprobación falla o no se ha completado todavía
• el usuario ha deshabilitado la comprobación
• el usuario ya está usando la última versión

SSRManifest.devToolbar.debugInfoOutput

Type: string | undefined

Añadido en: astro@6.0.0

Define la información de debug serializada pasada a la dev toolbar para su visualización.

SSRManifest.internalFetchHeaders

Type: Record<string, string>

Añadido en: astro@5.15.0

Especifica los headers que se añaden automáticamente a las peticiones fetch internas realizadas durante el renderizado.

SSRManifest.logLevel

Type: "error" | "warn" | "debug" | "info" | "silent"

Añadido en: astro@6.0.0

Especifica el nivel de logging de Vite.

ValidRedirectStatus

Type: 301 | 302 | 303 | 307 | 308 | 300 | 304

Una unión de códigos de estado de redirección soportados.

Permitir instalación con astro add

El comando astro add permite a los usuarios añadir fácilmente integraciones y adaptadores a su proyecto. Si quieres que tu integración sea instalable con esta herramienta, añade astro-integration al campo keywords en tu package.json:

{
  "name": "example",
  "keywords": ["astro-integration"],
}

Una vez que publiques tu integración en npm, ejecutar astro add example instalará tu paquete con cualquier peer dependency especificada en tu package.json. Esto también aplicará tu integración al astro.config.* del usuario así:

astro.config.mjs

import { defineConfig } from 'astro/config';
import example from 'example';

export default defineConfig({
  integrations: [example()],
})

Precaución

Esto asume que la definición de tu integración es 1) un export default y 2) una función. Asegúrate de que esto sea cierto antes de añadir el keyword astro-integration!

Orden de integraciones

Todas las integraciones se ejecutan en el orden en que están configuradas. Por ejemplo, para el array [react(), svelte()] en el astro.config.* de un usuario, react se ejecutará antes que svelte.

Tu integración debería idealmente ejecutarse en cualquier orden. Si esto no es posible, recomendamos documentar que tu integración necesita ir primera o última en el array de configuración de integrations de tu usuario.

Combinar integraciones en presets

Una integración también puede escribirse como una colección de múltiples integraciones más pequeñas. Llamamos a estas colecciones presets. En lugar de crear una función factory que devuelve un único objeto de integración, un preset devuelve un array de objetos de integración. Esto es útil para construir características complejas a partir de múltiples integraciones.

integrations: [
  // Example: where examplePreset() returns: [integrationOne, integrationTwo, ...etc]
  examplePreset()
]

Recursos de la comunidad

• Construye tus propias Integraciones de Astro - por Emmanuel Ohans en FreeCodeCamp
• Plantilla de Integración de Astro - por Florian Lefebvre en GitHub