Trabajando con integraciones

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

Las integraciones pueden…

• Habilitar React, Vue, Svelte, Solid y otros frameworks populares de UI con un renderizador.
• Habilitar 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 funciones a tu proyecto, como la generación automática de sitemaps.
• Escribir código personalizado que se enganche al proceso de compilación, al servidor de desarrollo y más.

Directorio de integraciones

Explora o busca la colección completa 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íticas, rendimiento, SEO, accesibilidad, UI, herramientas de desarrollo y más.

Integraciones oficiales

Las siguientes integraciones son mantenidas por Astro.

Frameworks UI

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

Adaptadores SSR

• 

  @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 las integraciones oficiales. También se pueden añadir varios plugins de la comunidad usando este comando. Por favor, consulta la documentación propia de cada integración para comprobar si es compatible con astro add, o si debes instalarla manualmente.

Ejecuta el comando astro add utilizando el gestor de paquetes de tu preferencia y nuestro asistente automático de integraciones actualizará tu archivo de configuración e instalará cualquier dependencia necesaria.

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 integración

Si ves alguna advertencia 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 compartidas por ti. Para instalar estos paquetes faltantes, ejecuta el siguiente comando:

npm

npm install [nombre-del-paquete]

pnpm

pnpm add [nombre-del-paquete]

Yarn

yarn add [nombre-del-paquete]

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 a tu proyecto de Astro:

1. Instalar una integración desde un 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. Importado desde un paquete npm instalado
       installedIntegration(),
       // 2. Importado desde un archivo JS local
       localIntegration(),
       // 3. Un objeto en línea
       { name: 'namespace:id', hooks: { /* ... */ } },
     ]
   });

Consulta la referencia de la API de Integraciones para aprender todas las diferentes maneras en que puedes escribir una integración.

Instalar un paquete npm

Instala una integración de un 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 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 cualquier opción de configuración necesaria a la integración que hayas elegido en astro.config.mjs.

Opciones personalizadas

Las integraciones casi siempre se crean como funciones factoría que devuelven el objeto de integración real. Esto te permite pasar argumentos y opciones a la función factoría para personalizar la integración según tu proyecto.

integrations: [
  // Ejemplo: Personaliza tu integración con argumentos de función
  sitemap({ filter: true })
]

Alternar una integración

Las integraciones falsy se ignoran, por lo que puedes activar y desactivar integraciones sin preocuparte por dejar valores booleanos o undefined restantes.

integrations: [
  // Ejemplo: Omite la construcción de un sitemap en Windows
  process.platform !== 'win32' && sitemap()
]

Actualizar 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

# Actualizar Astro y las integraciones oficiales a la vez a la última versión
npx @astrojs/upgrade

pnpm

# Actualizar Astro y las integraciones oficiales a la vez a la última versión
pnpm dlx @astrojs/upgrade

Yarn

# Actualizar Astro y las integraciones oficiales a la vez a la última versión
yarn dlx @astrojs/upgrade

Actualización manual

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

npm

# Ejemplo: actualizar las integraciones de React y Partytown
npm install @astrojs/react@latest @astrojs/partytown@latest

pnpm

# Ejemplo: actualizar las integraciones de React y Partytown
pnpm add @astrojs/react@latest @astrojs/partytown@latest

Yarn

# Ejemplo: actualizar las integraciones de React y Partytown
yarn add @astrojs/react@latest @astrojs/partytown@latest

Eliminar una integración

1. Para eliminar una integración, primero desinstala la integración 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()
     ]
   });

Encontrar más integraciones

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

Construir tu propia integración

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

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

Publicar tu integración en npm

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

¿Buscas inspiración? Revisa algunos de los temas y componentes favoritos de la comunidad de Astro. También puedes buscar en npm para ver todo el catálogo público.

¿No quieres hacerlo solo?

¡Revisa la plantilla de componentes de la comunidad de Astro para obtener una plantilla lista para usar y respaldada por la comunidad!

Inicio rápido

Para empezar a desarrollar tu componente rápidamente, puedes usar una plantilla ya configurada.

npm

# Inicializa la plantilla de componentes de Astro en un nuevo directorio
npm create astro@latest my-new-component-directory -- --template component

pnpm

# Inicializa la plantilla de componentes de Astro en un nuevo directorio
pnpm create astro@latest my-new-component-directory -- --template component

Yarn

# Inicializa la plantilla de componentes de Astro en un nuevo directorio
yarn create astro my-new-component-directory --template component

Crear un paquete

Requisitos previos

Antes de empezar, te será útil tener un conocimiento básico sobre:

• Módulos de Node
• Manifiesto del paquete (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 a 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 único 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. Estos paquetes también se pueden referenciar 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 conformarán tu paquete individual: package.json e 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": "Descripción del componente",
  "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": "Un generador de elementos de Astro"
}

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 pueda usarse como punto de entrada con import y export .

homepage

La URL de la página principal del proyecto.

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

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

exports

Los puntos de entrada de un paquete cuando se importa por su 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, utilizado 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 visibilidad en el ecosistema de Astro.

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

Consejo

¡Nuestra biblioteca de integraciones también utiliza las palabras clave! 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 importa 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 única interfaz.

Ejemplo: Uso de importaciones con nombre

---
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 utilizado únicamente para 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 recién extraídos.

Probar tu componente

Actualmente, Astro no incluye un ejecutor de pruebas. (Si te interesa ayudar con esto, ¡únete a nosotros en Discord!)

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

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

2. Agrega una nueva página por cada prueba que te gustaría ejecutar.

3. Cada página debe incluir un uso diferente del componente que te gustaría probar.

4. Ejecuta astro build para compilar tus fixtures y 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

Publicar tu componente

Una vez que tengas tu paquete listo, puedes publicarlo en npm usando el comando npm publish. Si esto falla, asegúrate de haber iniciado sesión con npm login y de que tu archivo package.json esté correcto. Si se ejecuta con éxito, ¡ya terminaste!

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

Si necesitas utilizar otro tipo de archivo que Astro no admita de forma nativa, añade un paso de compilación a tu paquete. Este ejercicio avanzado corre por tu cuenta.

Biblioteca de integraciones

¡Comparte tu gran trabajo añadiendo tu integración a nuestra biblioteca de integraciones!

Consejo

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

Datos de package.json

La biblioteca se actualiza automáticamente cada semana, incorporando todos los paquetes publicados 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 desde tu archivo package.json.

¡Los avatares son una excelente manera de destacar tu marca en la biblioteca! Una vez que tu paquete esté publicado, puedes abrir una incidencia en GitHub con tu avatar adjunto y lo agregaremos a tu listado.

Consejo

¿Necesitas sobrescribir la información que nuestra biblioteca lee de npm? ¡No hay problema! Abre una incidencia con la información actualizada y nos aseguraremos de utilizar tu name, description, o homepage personalizado en su lugar.

Categorías

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

categoría	palabras clave
Accesibilidad	a11y, accessibility
Adaptadores	astro-adapter
Analíticas	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
Barra de herramientas de desarrollo	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 Uncategorized.

Compartir

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