APIs de integraciones de Astro
Las integraciones de Astro agregan nuevas funcionalidades y comportamientos para tu proyecto con unas pocas líneas de código.
Esta página de referencia es para cualquiera que escriba una integración. Para aprender a usar una integración en tu proyecto, consulta nuestra guía de uso de integraciones.
Ejemplos
Sección titulada EjemplosLas integraciones oficiales de Astro pueden actuar como referencia para ti a medida que avanzas para crear tus propias integraciones.
- Renderizadores:
lit
,svelte
,react
,preact
,vue
,solid
- Librerías:
tailwind
,partytown
- Funcionalidades:
sitemap
Referencia rápida de la API
Sección titulada Referencia rápida de la APIastro:config:setup
Sección titulada astro:config:setupSiguiente hook: astro:config:done
Cuando: En la inicialización, antes de que Vite o Astro config se hayan resuelto.
Por qué: Para ampliar la configuración del proyecto. Esto incluye actualizar Astro config, aplicar plugins de Vite, agregar renderizadores de componentes e inyectar scripts en la página.
Opción config
Sección titulada Opción configTipo: AstroConfig
Una copia de solo lectura de la Astro config proporcionada por el usuario. Esto se resuelve antes de que se haya ejecutado cualquier otra integración. Si necesitas una copia de la configuración luego de que todas las integraciones hayan completado sus actualizaciones de configuración, puedes ver el hook astro:config:done
.
Opción command
Sección titulada Opción commandTipo: 'dev' / 'build'
dev
- El proyecto se ejecuta conastro dev
oastro preview
build
- El proyecto se ejecuta conastro build
Opción isRestart
Sección titulada Opción isRestartTipo: boolean
false
cuando se inicia el servidor de desarrollo, true
cuando se provoca una recarga. Es útil para detectar si se llama a esta función más de una vez.
Opción updateConfig
Sección titulada Opción updateConfigTipo: (newConfig: Record<string, any>) => void;
Una función callback para actualizar la Astro config proporcionada por el usuario. Cualquier configuración que proporciones se fusionará con la configuración de usuario + otras actualizaciones de configuración de integración, ¡así que puedes omitir claves!
Por ejemplo, supongamos que necesitas proporcionar un plugin de Vite al proyecto del usuario:
Opción addRenderer
Sección titulada Opción addRendererTipo: (renderer:
AstroRenderer
) => void;
Ejemplos: lit
, svelte
, react
, preact
, vue
, solid
Una función callback para agregar un renderizador de framework (como React, Vue, Svelte, etc.). Puedes explorar los ejemplos y definiciones anteriores para obtener opciones más avanzadas, pero las 2 opciones principales que debes tener en cuenta son:
clientEntrypoint
- ruta a un archivo que se ejecuta en el cliente cada vez que el componente es usado. Esto es principalmente para renderizar o hidratar tu componente con JS.serverEntrypoint
- ruta a un archivo que se ejecuta durante las solicitudes al servidor o las compilaciones estáticas cada vez que el componente es usado. Estos deben renderizar componentes a un marcado estático, con hooks para la hidratarlos cuando corresponda.renderToString
de React es un ejemplo clásico.
Opción addWatchFile
Sección titulada Opción addWatchFileTipo: URL | string
Si tu integración depende de un archivo de configuración que no es vigilado por Vite y/o necesita un reinicio total de servidor para surtir efecto, agrégalo en addWatchFile
. Cada vez que haya cambios en ese archivo, el servidor de desarrollo de Astro se reiniciará (puedes comprobar cuando ocurre un reinicio con isRestart
).
Ejemplo de uso:
Opción addClientDirective
Sección titulada Opción addClientDirectiveastro@2.6.0
Tipo: (directive:
ClientDirectiveConfig
) => void;
Añade una directiva de cliente personalizada para utilizarla en los archivos .astro
.
Ten en cuenta que los puntos de entrada de las directivas solo se incluyen en el paquete a través de esbuild y se deben mantener pequeños para no ralentizar la hidratación del componente.
Ejemplo de uso:
También puedes añadir tipos para las directivas en el archivo de definición de tipos de tu biblioteca:
Opción addDevToolbarApp
Sección titulada Opción addDevToolbarAppastro@3.4.0
Tipo: (pluginEntrypoint: string) => void;
Agrega una app personalizada de barra de herramientas para desarrolladores (EN).
Ejemplo de uso:
Opción addMiddleware
Sección titulada Opción addMiddlewareastro@3.5.0
Tipo: (middleware:
AstroIntegrationMiddleware
) => void;
Agrega un middleware para ejecutar en cada solicitud. 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
).
Un middleware es definido en un paquete con una función onRequest
, como con el middleware definido por el usuario.
Opción injectRoute
Sección titulada Opción injectRouteTipo: ({ pattern: string, entrypoint: string }) => void;
Una función callback para inyectar rutas a un proyecto de Astro. Las rutas inyectadas pueden ser páginas .astro
o handlers de ruta .js
y .ts
.
injectRoute
toma un objeto con un pattern
y un entrypoint
.
pattern
- es la ruta en el navegador, por ejemplo/foo/bar
. Unpattern
puede usar la sintaxis de ruta de archivo de Astro para indicar rutas dinámicas, por ejemplo/foo/[bar]
o/foo/[...bar]
. Tenga en cuenta que no se necesita una extensión de archivo en elpatrón
.entrypoint
- un especificador de módulo simple que apunta hacia la página.astro
o el controlador de ruta.js
/.ts
que maneja la ruta indicada en elpattern
.
Ejemplo de uso
Sección titulada Ejemplo de usoPara una integración diseñada para ser instalada en otros proyectos, utiliza su nombre de paquete para referirse al punto de entrada de la ruta.
El siguiente ejemplo muestra un paquete publicado en npm como @fancy/dashboard
inyectando una ruta de panel:
Opción injectScript
Sección titulada Opción injectScriptTipo: (stage: InjectedScriptStage, content: string) => void;
Una función de callback para inyectar una cadena de contenido de JavaScript en cada página.
El stage
indica cómo debe insertarse este script (el content
). Algunas etapas permiten insertar scripts sin modificaciones, mientras que otras permiten la optimización durante el paso de empaquetado de Vite:
-
"head-inline"
: Inyectado en una etiqueta de script en el<head>
de cada página. No optimizado o 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 ahead-inline
, excepto que Vite maneja el fragmento inyectado y lo incluye con cualquier otra etiqueta<script>
definida dentro de los componentes de Astro en la página. El script se cargará con<script type="module">
en la salida de la página final, optimizado y resuelto por Vite. -
"page-ssr"
: Importado como un módulo separado en el frontmatter de cada componente de página de Astro. Debido a que esta etapa importa el script, el objeto globalAstro
no está disponible y el script solo se ejecutará una vez, cuando elimport
se evalúe por primera vez.El uso principal de la etapa
page-ssr
es inyectar unimport
de CSS en cada página para que Vite la optimice y la resuelva:
astro:config:done
Sección titulada astro:config:doneHook anterior: astro:config:setup
Siguiente hook: astro:server:setup
cuando se ejecuta en modo “dev”, y astro:build:start
durante las compilaciones de producción
Cuándo: Después que la configuración de Astro se haya resuelto y otras integraciones hayan ejecutado sus hooks astro:config:setup
.
Por qué: Obtener la configuración final para usarla en otros hooks.
Opción config
Sección titulada Opción configTipo: AstroConfig
Una copia de solo lectura de Astro config proporcionada por el usuario. Esto se resuelve después de que se hayan ejecutado otras integraciones.
astro:server:setup
Sección titulada astro:server:setupHook anterior: astro:config:done
Siguiente hook: astro:server:start
Cuándo: Justo después de que se crea el servidor Vite en modo “dev”, pero antes de que se dispare el evento listen()
. Consulta la API createServer de Vite para obtener más información.
Por qué: Para actualizar las opciones del servidor de Vite y el middleware.
Opción server
Sección titulada Opción serverTipo: ViteDevServer
Una instancia mutable del servidor de Vite utilizada en modo “dev”. Por ejemplo, esto es utilizado por nuestra integración Partytown para inyectar el servidor Partytown como middleware:
astro:server:start
Sección titulada astro:server:startHook anterior: astro:server:setup
Siguiente hook: astro:servidor:hecho
Cuándo: Justo después de que se haya disparado el evento listen()
del servidor.
Por qué: Para interceptar solicitudes de red en la dirección especificada. Si tienes la intención de usar esta dirección para el middleware, considera usar astro:server:setup
en su lugar.
Opción address
Sección titulada Opción addressTipo: AddressInfo
La dirección, familia y número de puerto proporcionados por el módulo NodeJS Net.
astro:server:done
Sección titulada astro:server:doneHook anterior: astro:server:start
Cuándo: Justo después de que se cierre el servidor de desarrollo.
Por qué: Para ejecutar cualquier evento de limpieza, ejecutados durante los hooks astro:server:setup
o astro:server:start
.
astro:build:start
Sección titulada astro:build:startHook anterior: astro:config:done
Siguiente hook: astro:build:setup
Cuándo: Después del evento astro:config:done
, pero antes de que comience la compilación de producción.
Por qué: Para configurar cualquier objeto global o cliente necesario durante la compilación a producción. Esto también puede ampliar las opciones de configuración de compilación de la API del adaptador.
astro:build:setup
Sección titulada astro:build:setupHook anterior: astro:build:start
Siguiente hook: astro:build:ssr
Cuando: Después del hook astro:build:start
, se ejecuta inmediatamente antes de la compilación.
Por qué: En este punto, la configuración de Vite para la compilación se ha construido por completo, esta es tu última oportunidad para modificarla. Esto puede ser útil, por ejemplo, para sobreescribir algunos valores predeterminados. Si no estás seguro de si debes usar este hook o astro:build:start
, usa astro:build:start
en su lugar.
astro:build:generated
Sección titulada astro:build:generatedHook anterior astro:build:setup
Cuándo: Después de que la compilación a producción haya terminado de generar las rutas y los demás recursos.
Por qué: Para acceder a rutas y recursos generados antes que los artefactos de la compilación sean limpiados. Este es un caso muy poco común. Recomendamos usar astro:build:done
a menos que realmente necesites acceder a los archivos generados antes de que éstos sean limpiados.
astro:build:ssr
Sección titulada astro:build:ssrHook anterior: astro:build:setup
Cuándo: después que se completa la compilación de producción SSR.
Por qué: Para acceder al manifiesto SSR y al mapeo de los puntos de entrada emitidos. Esto es útil al crear compilaciones SSR personalizadas en plugins o integraciones.
entryPoints
mapea una ruta de página al archivo físico emitido después de la compilación;middlewareEntryPoint
es la ruta del sistema de archivos del archivo de middleware;
astro:build:done
Sección titulada astro:build:doneHook anterior: astro:build:ssr
Cuándo: después de que se haya completado la compilación a producción (SSG o SSR).
Por qué: Para acceder a rutas y recursos generados para extensión (por ejemplo, copiar contenido en la carpeta /assets
generado). Si planeas transformar los recursos generados, te recomendamos explorar la API de plugin de Vite y la configuración a través de astro:config:setup
en su lugar.
Opción dir
Sección titulada Opción dirTipo: URL
La ruta URL a la carpeta de compilación. Ten en cuenta que si necesitas una ruta absoluta válida como string, debes usar la utilidad fileURLToPath
integrada de Node.
Opción routes
Sección titulada Opción routesTipo: RouteData[]
Una lista de todas las rutas generadas junto con sus metadatos asociados.
Puedes consultar la referencia completa del tipo RouteData
a continuación, pero las propiedades más comunes son:
component
- la ruta del archivo de entrada relativa a la raíz del proyectopathname
- la URL del archivo de salida (indefinido para rutas que usan parámetros[dynamic]
y[...spread]
)
Referencia del tipo RouteData
Sección titulada Referencia del tipo RouteDataOpción pages
Sección titulada Opción pagesTipo: { pathname: string }[]
Una lista de todas las páginas generadas. Es un objeto con una propiedad.
pathname
- la ruta final de la página.
Permitir la instalación con astro add
Sección titulada Permitir la instalación con astro addEl comando astro add
permite a los usuarios agregar fácilmente integraciones y adaptadores a su proyecto. Si deseas que tu integración se pueda instalar con esta herramienta, agrega astro-integration
al campo keywords
en el package.json
de la integración:
Una vez que publiques tu integración en npm, ejecutar astro add example
instalará tu paquete con cualquier dependencia peer especificada en tu package .json
. Esto también aplicará tu integración al astro.config
del usuario así:
Esto supone que la definición de la integración es 1) una exportación default
y 2) una función. ¡Asegúrate de que esto sea cierto antes de agregar la palabra clave astro-integration
!
AstroIntegrationLogger
Sección titulada AstroIntegrationLoggerUna instancia del logger de Astro, útil para escribir registros. Este logger utiliza el mismo nivel de registro configurado a través de la CLI.
Métodos disponibles para escribir en la terminal:
logger.info("Mensaje")
;logger.warn("Mensaje")
;logger.error("Mensaje")
;logger.debug("Mensaje")
;
Todos los mensajes son precedidos por una etiqueta que tiene el mismo valor de la integración.
El ejemplo anterior registrará un mensaje que incluye el mensaje info
proporcionado:
Para registrar algunos mensajes con una etiqueta diferente, utiliza el método .fork
para especificar una alternativa al nombre
predeterminado:
El ejemplo anterior generará registros con [astro-format]
de forma predeterminada, y con [astro-format/build]
cuando se especifique:
Orden de integración
Sección titulada Orden de integraciónTodas las integraciones se ejecutan en el orden en que están configuradas. Por ejemplo, para el array [react(), svelte()]
en astro.config.*
de un usuario, react
se ejecutará antes que svelte
.
Idealmente, la integración debería ejecutarse en cualquier orden. Si esto no es posible, recomendamos documentar que su integración debe ser la primera o la última en el array integrations
de la configuración del usuario.
Combinar integraciones en presets
Sección titulada Combinar integraciones en presetsUna integración también puede ser escrita como una colección de múltiples integraciones más pequeñas. Llamamos a estas colecciones presets. En lugar de crear una función que devuelve un solo objeto de integración, un preset devuelve una array de objetos de integración. Esto es útil para crear características complejas a partir de múltiples integraciones.
Reference