Publier sur NPM

Vous développez un nouveau composant Astro ? Publiez-le sur NPM !

Publier un composant Astro est une excellente façon de réutiliser votre travail existant dans vos projets et de le partager avec la communauté d’Astro à grande échelle. Les composants Astro peuvent être publiés directement et installés depuis NPM, comme tout autre Paquet JavaScript.

Vous cherchez de l’inspiration ? Regardez quelques-uns de nos thèmes et composants préférés issus la communauté d’Astro. Vous pouvez aussi rechercher sur NPM pour voir l’ensemble du catalogue public.

Pour commencer à développer rapidement votre composant, nous avons un modèle déjà configuré pour vous.

# Initialise le modèle de composant Astro dans un nouveau répertoire
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

Avant de se lancer, avoir une compréhension basique des sujets suivants vous sera d’une grande aide :

• Modules Node
• Manifeste de Paquet (package.json)
• Espaces de travail

Pour créer un nouveau Paquet, nous vous recommandons fortement de configurer votre environnement de développement pour utiliser les “Workspaces” (ou espaces de travail) dans votre projet. Cela vous permettra de développer votre composant avec une copie fonctionnelle d’Astro.

Dans cet exemple nommé my-project, nous créons un projet avec un seul Paquet, nommé my-component, et un répertoire demo/ pour les tests et les démonstrations du composant.

Tout cela est configuré dans le fichier package.json situé dans le répertoire racine du projet.

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

Dans cet exemple, plusieurs Paquets peuvent être développés ensemble depuis le répertoire packages. Ces Paquets peuvent également être référencés depuis demo, où vous pouvez installer une copie fonctionnelle d’Astro.

npm init astro demo --template minimal
# yarn
yarn create astro my-new-component-directory --template minimal
# pnpm
pnpm create astro@latest my-new-component-directory -- --template minimal

Il y a deux fichiers initiaux qui constituent votre Paquet individuel : package.json et index.js.

Le fichier package.json dans le répertoire du Paquet contient toutes les informations relatives à votre projet, y compris sa description, ses dépendances, et toutes autres métadonnées du Paquet.

{
  "name": "my-component",
  "description": "Description du composant",
  "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","astro-component", "...", "..."]
}

Une courte description de votre composant pour aider les autres à comprendre ce qu’il fait.

{
  "description": "Un Generateur d'éléments Astro"
}

Le format de module utilisé par Node.js et Astro pour interpréter vos fichiers index.js.

{
  "type": "module"
}

Nous recommandons d’utiliser "type": "module" pour que votre fichier index.js puisse être utilisé comme point d’entrée avec import et export.

L’url de la page d’accueil de votre projet.

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

C’est une bonne façon de diriger les utilisateurs vers une démonstration, une documentation ou la page d’accueil de votre projet.

Les points d’entrée d’un Paquet lorsqu’il est importé par nom.

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

Dans cet exemple, l’importation de my-component utilise index.js, tandis que l’importation de my-component/astro ou my-component/react utilise MyAstroComponent.astro ou MyReactComponent.jsx, respectivement.

C’est une optimisation optionnelle pour exclure les fichiers inutiles du paquet fourni aux utilisateurs via NPM. Notez que seuls les fichiers listés ici seront inclus dans votre Paquet, donc si vous ajoutez ou modifiez des fichiers nécessaires à votre Paquet pour qu’il fonctionne, vous devez mettre à jour cette liste en conséquence.

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

Une liste de mots-clés pertinents à votre composant qui sont utilisés pour aider les autres à trouver votre composant sur NPM et dans tous les autres catalogues de recherche.

Nous recommandons d’ajouter astro-component comme mot-clé spécial pour maximiser sa découverte dans l’écosystème Astro.

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

Les mots-clés sont également utilisés par notre bibliothèque d’intégration! Voir ci-dessous pour une liste complète des mots-clés que nous utilisons dans NPM.

Le point d’entrée principal du Paquet utilisé lorsque votre Paquet est importé.

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

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

Cela vous permet de mettre plusieurs composants ensemble dans une seule interface.

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

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

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

Astro n’a pas de mode Paquet pour le développement. Au lieu de cela, vous devriez utiliser un projet de démonstration pour développer et tester votre Paquet dans votre projet. Cela peut être un site web privé uniquement utilisé pour le développement, ou un site de démonstration/documentation pour votre Paquet.

Si vous voulez extraire des composants d’un projet existant, vous pouvez aussi continuer à utiliser ce projet pour développer vos composants maintenant extraits.

Astro ne livre actuellement pas de suites de tests. C’est quelque chose que nous aimerions aborder. (Si vous êtes intéressé·e·s pour aider, rejoignez nous dans notre Discord !)

En attendant, nos recommandations actuelles pour les tests sont :

1. Ajoutez un répertoire de test nommé fixtures à votre répertoire demo/src/pages.
2. Ajoutez une nouvelle page pour chaque test que vous souhaitez exécuter.
3. Chaque page devrait inclure un usage de composant différent que vous souhaitez tester.
4. Exécutez astro build pour construire vos fixtures, puis comparez le résultat de dist/__fixtures__/ à ce que vous attendiez.

Une fois que votre Paquet est prêt, vous pouvez le publier sur NPM !

Pour publier un Paquet sur NPM, utilisez la commande npm publish. Si cela échoue, assurez-vous que vous vous êtes connecté via npm login et que votre package.json est correct. Si cela réussit, vous avez fini !

Notez que il n’y avait pas de étape build pour les Paquets Astro. Tous les types de fichiers que Astro supporte peuvent être publiés directement sans étape de construction, car nous savons que Astro supporte déjà ces types de fichiers. Cela inclut tous les fichiers avec des extensions comme .astro, .ts, .jsx, et .css.

Si vous avez besoin d’un autre type de fichier qui n’est pas supporté nativement par Astro, vous pouvez ajouter une étape de Build à votre Paquet. Nous vous laissons cet exercice avancé.

Partagez votre travail en ajoutant votre intégration à notre bibliothèque d’intégrations !

La bibliothèque est mise à jour tous les jours automatiquement; chaque Paquet publié sur NPM avec le mot-clé astro-component est extrait.

La bibliothèque d’intégration lit les données name, description, repository, et homepage de votre package.json.

Les avatars sont une bonne façon de mettre en évidence votre marque dans la bibliothèque ! Une fois que votre Paquet est publié, vous pouvez créer une Issue GitHub avec votre avatar attaché et nous l’ajouterons à la liste.

En plus du mot-clé obligatoire astro-component ou withastro, des mots-clés spéciaux sont également utilisés pour organiser automatiquement les Paquets. Inclure n’importe quel mots-clés ci-dessous ajoutera votre intégration à notre bibliothèque d’intégrations.

Nous vous encourageons à partager votre travail, nous apprécions vraiment de voir ce que nos talentueux Astronautes créent. Partagez ce que vous créez avec nous dans notre Discord ou mentionnez @astrodotbuild dans un Tweet !