Publica en NPM

¿Construyendo un nuevo componente Astro? ¡Publícalo en npm!

Publicar un componente de Astro es una excelente manera de reutilizar tu trabajo y compartirlo con la comunidad de Astro. Los componentes de Astro se pueden publicar e instalar directamente desde NPM, como cualquier otro paquete de JavaScript.

¿Buscas inspiración? Mira algunos de nuestros temas y componentes favoritos de la comunidad de Astro. También puedes buscar en npm para ver el catálogo completo.

Inicio rápido

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

# Inicializar la plantilla de componentes de Astro en una nueva carpeta
# npm
npm create astro@latest my-new-component-directory -- --template component
# yarn
yarn create astro my-new-component-directory --template component
# pnpm
pnpm create astro@latest my-new-component-directory -- --template component

Creando un paquete

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

Directorymy-new-component-directory/
- Directorydemo/
  - … para pruebas y demostraciones
- package.json
- Directorypackages/
  - Directorymy-component/
    index.js
    package.json
    … archivos adicionales utilizados por el paquete

Este ejemplo, llamado mi-proyecto, crea un proyecto con un solo paquete, llamado mi-componente, 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": "mi-proyecto",
  "workspaces": ["demo", "packages/*"]
}

En este ejemplo, se pueden desarrollar varios 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
# yarn
yarn create astro demo --template minimal
# pnpm
pnpm create astro@latest 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 a tu paquete, incluida su descripción, dependencias y cualquier otro metadato.

{
  "name": "mi-componente",
  "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", "withastro", "astro-component", "...", "..."]
}

`description`

Una breve descripción de tu componente que será utilizado para ayudar a otros a saber lo que hace.

{
  "description": "Un generador de componentes de Astro"
}

`type`

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

{
  "type": "module"
}

Utiliza "type": "module" para que 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 demostración en línea, documentación o página de inicio de tu proyecto.

`exports`

Los puntos de entrada de un paquete cuando se importan 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 enumerados aquí se incluirán en tu paquete, por lo que, si agregas o cambias los archivos necesarios para que tu paquete funcione, debes actualizar esta lista en consecuencia.

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

`keywords`

Una serie de palabras clave relevantes para tu componente, utilizado para ayudar a otros usuarios a encontrar tu componente en npm y en cualquier otro catálogo de búsqueda.

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

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

`index.js`

El punto de entrada del paquete principal que se utiliza cada vez 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 sola interfaz.

Ejemplo: Usando importaciones nombradas

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

Ejemplo: Usando importaciones module-name

---
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 />

Desarrollando tu paquete

Astro no tiene un “modo de paquete” dedicado para el desarrollo. En su lugar, debes usar un proyecto demo para desarrollar y probar tu paquete dentro de tu proyecto. Este puede ser un sitio web privado que solo se use 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, puedes incluso continuar usando ese proyecto para desarrollar tus componentes ahora extraídos.

Probando tus componentes

Astro actualmente no incluye un test runner. Esto es algo que nos gustaría abordar. (Si estás interesado en ayudar con esto, ¡únete a nosotros en Discord!)

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

Agrega un directorio fixtures de prueba a su directorio demo/src/pages.
Agrega una nueva página para cada prueba que desee ejecutar.
Cada página debe incluir un uso distinto de los componentes que te gustaría probar.
Ejecuta astro build para construir tus fixtures, luego compara los resultados en el directorio dist/__fixtures__/ con los resultados esperados.

Directorymy-project/demo/src/pages/__fixtures__/
- test-name-01.astro
- test-name-02.astro
- test-name-03.astro

Publicando tu componente

Una vez que tengas tu paquete listo, puedes publicarlo en npm utiliza el comando npm publish para publicar tu paquete. Si falla, asegúrate de haber iniciado sesión con npm login y de que tu archivo package.json esté correcto. Si tiene éxito, ¡has terminado!

Es importante destacar que no hay un paso de “build” para los paquetes de Astro. Cualquier tipo de archivo que Astro admita de forma nativa, como .astro, .ts, .jsx y .css, puede ser publicado directamente sin necesidad de un paso de construcción adicional.

Si necesitas agregar otro tipo de archivo que no sea admitido de forma nativa por Astro, deberás agregar un paso de construcción a tu paquete. Este ejercicio avanzado queda a tu cargo y dependerá de tus necesidades específicas.

Biblioteca de integraciones

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

Datos en `package.json`

La biblioteca se actualiza automáticamente semanalmente, agregando todos los paquetes publicados en NPM con la palabra clave astro-component o withastro.

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

¡Los avatares son una excelente manera de resaltar tu marca en la biblioteca! Una vez que se publique tu paquete, puedes crear una issue en GitHub con tu avatar adjunto y lo agregaremos al listado.

Colecciones

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

colección	palabras clave
Accesibilidad	`a11y`, `accessibility`
Adaptadores	`astro-adapter`
Analíticas	`analytics`
CSS + UI	`css`, `ui`, `icon`, `icons`, `renderer`
Frameworks	`renderer`
Performance + SEO	`performance`, `perf`, `seo`, `optimization`

Comparte

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

Crear un problema en GitHub

Envíanos comentarios

Publica en NPM

Inicio rápido

Creando un paquete

`package.json`

`description`

`type`

`homepage`

`exports`

`files`

`keywords`

`index.js`

Ejemplo: Usando importaciones nombradas

Ejemplo: Usando importaciones module-name

Ejemplo: uso de importaciones individuales

Desarrollando tu paquete

Probando tus componentes

Publicando tu componente

Biblioteca de integraciones

Datos en `package.json`

Colecciones

Comparte

Publica en NPM

Inicio rápido

Creando un paquete

package.json

description

type

homepage

exports

files

keywords

index.js

Ejemplo: Usando importaciones nombradas

Ejemplo: Usando importaciones module-name

Ejemplo: uso de importaciones individuales

Desarrollando tu paquete

Probando tus componentes

Publicando tu componente

Biblioteca de integraciones

Datos en package.json

Colecciones

Comparte

`package.json`

`description`

`type`

`homepage`

`exports`

`files`

`keywords`

`index.js`

Datos en `package.json`