Trabajar con integraciones

Las integraciones de Astro añaden nuevas funcionalidades y comportamientos para tu proyecto con solo unas pocas líneas de código. Puedes utilizar una integración oficial, integraciones creadas por la comunidad o incluso crear una integración personalizada tú mismo.

Las integraciones pueden…

• Desbloquea React, Vue, Svelte, Solid y otros frameworks de UI populares con un renderizador.
• Habilita el renderizado bajo demanda con un adaptador SSR.
• Integrar herramientas como MDX y Partytown con unas pocas líneas de código.
• Añadir nuevas características a tu proyecto, como la generación automática de sitemaps.
• Escribir código personalizado que se conecte al proceso de compilación, servidor de desarrollo y más.

Directorio de integraciones

Navega o busca en el conjunto completo de cientos de integraciones oficiales y de la comunidad en nuestro directorio de integraciones. Encuentra paquetes para añadir a tu proyecto de Astro para autenticación, analítica, rendimiento, SEO, accesibilidad, UI, herramientas de desarrollo y más.

Integraciones oficiales

Las siguientes integraciones son mantenidas por Astro.

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

Configuración automática de integraciones

Astro incluye un comando astro add para automatizar la configuración de integraciones oficiales. Varios plugins de la comunidad también se pueden añadir utilizando este comando. Consulta la documentación de cada integración para ver si es compatible con astro add o si debes realizar una instalación manual.

Ejecuta el comando astro add utilizando el gestor de paquetes de tu elección y nuestro asistente de integración automática actualizará tu archivo de configuración e instalará todas las dependencias necesarias.

npm

npx astro add react

pnpm

pnpm astro add react

Yarn

yarn astro add react

¡Incluso es posible añadir múltiples integraciones al mismo tiempo!

npm

npx astro add react sitemap partytown

pnpm

pnpm astro add react sitemap partytown

Yarn

yarn astro add react sitemap partytown

Manejo de dependencias de integraciones

Si ves advertencias como Cannot find package '[package-name]' después de añadir una integración, es posible que tu gestor de paquetes no haya instalado las dependencias de pares (peer dependencies) por ti. Para instalar estos paquetes faltantes, ejecuta el siguiente comando:

npm

npm install [package-name]

pnpm

pnpm add [package-name]

Yarn

yarn add [package-name]

Instalación manual

Las integraciones de Astro siempre se añaden a través de la propiedad integrations en tu archivo astro.config.mjs.

Hay tres formas comunes de importar una integración en tu proyecto de Astro:

1. Instalar una integración de paquete npm.

2. Importar tu propia integración desde un archivo local dentro de tu proyecto.

3. Escribir tu integración en línea, directamente en tu archivo de configuración.

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import installedIntegration from '@astrojs/vue';
   import localIntegration from './my-integration.js';
   
   export default defineConfig({
     integrations: [
       // 1. Imported from an installed npm package
       installedIntegration(),
       // 2. Imported from a local JS file
       localIntegration(),
       // 3. An inline object
       { name: 'namespace:id', hooks: { /* ... */ } },
     ]
   });

Consulta la referencia de la API de Integración para conocer todas las diferentes formas en que puedes escribir una integración.

Instalación de un paquete npm

Instala una integración de paquete npm utilizando un gestor de paquetes y luego actualiza astro.config.mjs manualmente.

Por ejemplo, para instalar la integración @astrojs/sitemap:

1. Instala la integración en las dependencias de tu proyecto utilizando tu gestor de paquetes preferido:

   npm

   npm install @astrojs/sitemap

   pnpm

   pnpm add @astrojs/sitemap

   Yarn

   yarn add @astrojs/sitemap

2. Importa la integración en tu archivo astro.config.mjs y añádela a tu array de integraciones (integrations[]), junto con cualquier opción de configuración:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import sitemap from '@astrojs/sitemap';
   
   export default defineConfig({
     // ...
     integrations: [sitemap()],
     // ...
   });

   Ten en cuenta que diferentes integraciones pueden tener diferentes ajustes de configuración. Lee la documentación de cada integración y aplica las opciones de configuración necesarias a la integración elegida en astro.config.mjs.

Opciones personalizadas

Las integraciones casi siempre se crean como funciones de fábrica que devuelven el objeto de integración real. Esto te permite pasar argumentos y opciones a la función de fábrica que personalizan la integración para tu proyecto.

integrations: [
  // Example: Customize your integration with function arguments
  sitemap({ filter: true })
]

Alternar una integración

Las integraciones que se evalúan como falsas (falsy) son ignoradas, por lo que puedes activar y desactivar integraciones sin preocuparte por valores booleanos o undefined que queden atrás.

integrations: [
  // Example: Skip building a sitemap on Windows
  process.platform !== 'win32' && sitemap()
]

Actualización de integraciones

Para actualizar todas las integraciones oficiales a la vez, ejecuta el comando @astrojs/upgrade. Esto actualizará tanto Astro como todas las integraciones oficiales a sus últimas versiones.

Actualización automática

npm

# Upgrade Astro and official integrations together to latest
npx @astrojs/upgrade

pnpm

# Upgrade Astro and official integrations together to latest
pnpm dlx @astrojs/upgrade

Yarn

# Upgrade Astro and official integrations together to latest
yarn dlx @astrojs/upgrade

Actualización manual

Para actualizar una o más integraciones manualmente, utiliza el comando adecuado para tu gestor de paquetes.

npm

# Example: upgrade React and Partytown integrations
npm install @astrojs/react@latest @astrojs/partytown@latest

pnpm

# Example: upgrade React and Partytown integrations
pnpm add @astrojs/react@latest @astrojs/partytown@latest

Yarn

# Example: upgrade React and Partytown integrations
yarn add @astrojs/react@latest @astrojs/partytown@latest

Eliminación de una integración

1. Para eliminar una integración, primero desinstálala de tu proyecto.

   npm

   npm uninstall @astrojs/react

   pnpm

   pnpm remove @astrojs/react

   Yarn

   yarn remove @astrojs/react

2. A continuación, elimina la integración de tu archivo astro.config.*:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import react from '@astrojs/react';
   
   export default defineConfig({
     integrations: [
       react()
     ]
   });

Búsqueda de más integraciones

Puedes encontrar muchas integraciones desarrolladas por la comunidad en el Directorio de Integraciones de Astro. Sigue los enlaces allí para obtener instrucciones detalladas de uso y configuración.

Creación de tu propia integración

La API de Integración de Astro está inspirada en Rollup y Vite, y diseñada para resultar familiar a cualquiera que haya escrito un plugin de Rollup o Vite anteriormente.

Consulta la referencia de la API de Integración para saber qué pueden hacer las integraciones y cómo escribir una tú mismo.

Publicación de tu integración en npm

Publicar un componente de Astro es una excelente manera de reutilizar tu trabajo existente en todos tus proyectos y compartirlo con la comunidad de Astro en general. Los componentes de Astro se pueden publicar directamente en npm e instalarse desde allí, al igual que cualquier otro paquete de JavaScript.

¿Buscas inspiración? Echa un vistazo a algunos de nuestros temas y componentes favoritos de la comunidad de Astro. También puedes buscar en npm para ver el catálogo público completo.

¿No quieres hacerlo solo?

Echa un vistazo a la plantilla de componentes de la comunidad de Astro para obtener una plantilla nativa (out-of-the-box) y con soporte de la comunidad.

Inicio rápido

Para comenzar a desarrollar tu componente rápidamente, puedes usar una plantilla que ya está configurada para ti.

npm

# Initialize the Astro Component template in a new directory
npm create astro@latest my-new-component-directory -- --template component

pnpm

# Initialize the Astro Component template in a new directory
pnpm create astro@latest my-new-component-directory -- --template component

Yarn

# Initialize the Astro Component template in a new directory
yarn create astro my-new-component-directory --template component

Creación de un paquete

Prerrequisitos

Antes de comenzar, te resultará útil tener una comprensión básica de:

• Módulos de Node
• Package Manifest (package.json)
• Workspaces

Para crear un nuevo paquete, configura tu entorno de desarrollo para usar workspaces dentro de tu proyecto. Esto te permitirá desarrollar tu componente junto con una copia funcional de Astro.

• Directoriomy-new-component-directory/

  • Directoriodemo/

    • … para pruebas y demostración
  • package.json
  • Directoriopackages/

    • Directoriomy-component/

      • index.js
      • package.json
      • … archivos adicionales utilizados por el paquete

Este ejemplo, llamado my-project, crea un proyecto con un solo paquete, llamado my-component, y un directorio demo/ para probar y demostrar el componente.

Esto se configura en el archivo package.json de la raíz del proyecto:

{
  "name": "my-project",
  "workspaces": ["demo", "packages/*"]
}

En este ejemplo, se pueden desarrollar múltiples paquetes juntos desde el directorio packages. También se puede hacer referencia a estos paquetes desde demo, donde puedes instalar una copia funcional de Astro.

npm

npm create astro@latest demo -- --template minimal

pnpm

pnpm create astro@latest demo -- --template minimal

Yarn

yarn create astro demo --template minimal

Hay dos archivos iniciales que compondrán tu paquete individual: package.json y index.js.

package.json

El package.json en el directorio del paquete incluye toda la información relacionada con tu paquete, incluyendo su descripción, dependencias y cualquier otro metadato del paquete.

{
  "name": "my-component",
  "description": "Component description",
  "version": "1.0.0",
  "homepage": "https://github.com/owner/project#readme",
  "type": "module",
  "exports": {
    ".": "./index.js",
    "./astro": "./MyAstroComponent.astro",
    "./react": "./MyReactComponent.jsx"
  },
  "files": ["index.js", "MyAstroComponent.astro", "MyReactComponent.jsx"],
  "keywords": ["astro-component", "withastro", "... etc", "... etc"]
}

description

Una breve descripción de tu componente utilizada para ayudar a otros a saber qué hace.

{
  "description": "An Astro Element Generator"
}

type

El formato de módulo utilizado por Node.js y Astro para interpretar tus archivos index.js.

{
  "type": "module"
}

Usa "type": "module" para que tu index.js se pueda usar como un punto de entrada con import y export.

homepage

La URL de la página de inicio del proyecto.

{
  "homepage": "https://github.com/owner/project#readme"
}

Esta es una excelente manera de dirigir a los usuarios a una demo en línea, a la documentación o a la página de inicio de tu proyecto.

exports

Los puntos de entrada de un paquete cuando se importa por nombre.

{
  "exports": {
    ".": "./index.js",
    "./astro": "./MyAstroComponent.astro",
    "./react": "./MyReactComponent.jsx"
  }
}

En este ejemplo, importar my-component usaría index.js, mientras que importar my-component/astro o my-component/react usaría MyAstroComponent.astro o MyReactComponent.jsx respectivamente.

files

Una optimización opcional para excluir archivos innecesarios del paquete enviado a los usuarios a través de npm. Ten en cuenta que solo los archivos listados aquí se incluirán en tu paquete, por lo que si agregas o cambias archivos necesarios para que tu paquete funcione, debes actualizar esta lista en consecuencia.

{
  "files": ["index.js", "MyAstroComponent.astro", "MyReactComponent.jsx"]
}

keywords

Un array de palabras clave relevantes para tu componente, que se utiliza para ayudar a otros a encontrar tu componente en npm y en cualquier otro catálogo de búsqueda.

Agrega astro-component, astro-integration o withastro como una palabra clave especial para maximizar su descubrimiento en el ecosistema de Astro.

{
  "keywords": ["astro-component", "withastro", "... etc", "... etc"]
}

Consejo

¡Las palabras clave también son utilizadas por nuestra biblioteca de integraciones! Consulta a continuación la lista completa de palabras clave que buscamos en npm.

---

index.js

El punto de entrada principal del paquete utilizado siempre que se importe tu paquete.

export { default as MyAstroComponent } from './MyAstroComponent.astro';
export { default as MyReactComponent } from './MyReactComponent.jsx';

Esto te permite empaquetar múltiples componentes juntos en una sola interfaz.

Ejemplo: Uso de importaciones nombradas

---
import { MyAstroComponent } from 'my-component';
import { MyReactComponent } from 'my-component';
---
<MyAstroComponent />
<MyReactComponent />

Ejemplo: Uso de importaciones de espacio de nombres

---
import * as Example from 'example-astro-component';
---
<Example.MyAstroComponent />
<Example.MyReactComponent />

Ejemplo: Uso de importaciones individuales

---
import MyAstroComponent from 'example-astro-component/astro';
import MyReactComponent from 'example-astro-component/react';
---
<MyAstroComponent />
<MyReactComponent />

---

Desarrollo de tu paquete

Astro no tiene un “modo de paquete” dedicado para el desarrollo. En su lugar, debes usar un proyecto de demostración para desarrollar y probar tu paquete dentro de tu proyecto. Este puede ser un sitio web privado solo utilizado para el desarrollo, o un sitio web público de demostración/documentación para tu paquete.

Si estás extrayendo componentes de un proyecto existente, incluso puedes continuar usando ese proyecto para desarrollar tus componentes ahora extraídos.

Prueba de tu componente

Astro actualmente no incluye un ejecutor de pruebas. (Si estás interesado en ayudar con esto, ¡únete a nosotros en Discord!)

Mientras tanto, nuestra recomendación actual para las pruebas es:

1. Agrega un directorio de fixtures de prueba a tu directorio demo/src/pages.

2. Añadir una nueva página para cada prueba que quieras realizar.

3. Cada página debe incluir algún uso de componente diferente que desees probar.

4. Ejecuta astro build para compilar tus fixtures, luego compara la salida del directorio dist/__fixtures__/ con lo que esperabas.

   • Directoriomy-project/demo/src/pages/__fixtures__/

     • test-name-01.astro
     • test-name-02.astro
     • test-name-03.astro

Publicación de tu componente

Una vez que tengas tu paquete listo, puedes publicarlo en npm usando el comando npm publish. Si eso falla, asegúrate de haber iniciado sesión a través de npm login y de que tu package.json sea correcto. Si tiene éxito, ¡ya has terminado!

Ten en cuenta que no hubo un paso de compilación para los paquetes de Astro. Cualquier tipo de archivo que Astro soporte de forma nativa, como .astro, .ts, .jsx y .css, se puede publicar directamente sin un paso de compilación.

Si necesitas otro tipo de archivo que no sea compatible de forma nativa con Astro, añade un paso de compilación a tu paquete. Este ejercicio avanzado queda a tu elección.

Biblioteca de integraciones

¡Comparte tu arduo trabajo agregando tu integración a nuestra biblioteca de integraciones!

Consejo

¿Necesitas ayuda para construir tu integración o simplemente quieres conocer a otros creadores de integraciones? Tenemos un canal dedicado #integrations en nuestro servidor de Discord. ¡Pásate a saludar!

Datos de package.json

La biblioteca se actualiza automáticamente de forma semanal, extrayendo cada paquete publicado en npm con la palabra clave astro-component, astro-integration o withastro.

La biblioteca de integraciones lee los datos de name, description, repository y homepage de tu package.json.

¡Los avatares son una excelente manera de destacar tu marca en la biblioteca! Una vez que se publique tu paquete, puedes crear un problema en GitHub adjuntando tu avatar y lo agregaremos a tu listado.

Consejo

¿Necesitas anular la información que nuestra biblioteca lee de npm? ¡No hay problema! Crea un problema con la información actualizada y nos aseguraremos de que se use el name, description o homepage personalizado en su lugar.

Categorías

Además de la palabra clave requerida astro-component, astro-integration o withastro, también se utilizan palabras clave especiales para organizar automáticamente los paquetes. Incluir cualquiera de las palabras clave a continuación agregará tu integración a la categoría correspondiente en nuestra biblioteca de integraciones.

categoría	palabras clave
Accesibilidad	a11y, accessibility
Adaptadores	astro-adapter
Analítica	analytics
CSS + UI	css, ui, icon, icons, renderer
Frameworks	renderer
Cargadores de contenido	astro-loader
Imágenes + Multimedia	media, image, images, video, audio
Rendimiento + SEO	performance, perf, seo, optimization
Dev Toolbar	devtools, dev-overlay, dev-toolbar
Utilidades	tooling, utils, utility

Los paquetes que no incluyan ninguna palabra clave que coincida con una categoría se mostrarán como Sin categoría.

Compartir

Te animamos a compartir tu trabajo, y realmente nos encanta ver lo que crean nuestros talentosos Astronautas. ¡Ven a compartir lo que creas con nosotros en nuestro Discord o menciona a @astrodotbuild en un Tweet!