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.

Besoin d’aide ?

Regardez le modèle de composant de la communauté Astro pour un modèle de composant prêt à l’emploi et supporté par la communauté !

Démarrage rapide

Titre de la section Démarrage rapide

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

Création d’un Paquet

Titre de la section Création d’un Paquet

Prérequis

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.

• Répertoiremy-new-component-directory/

  • Répertoiredemo/

    • … pour les tests et les démonstrations
  • package.json
  • Répertoirepackages/

    • Répertoiremy-component/

      • index.js
      • package.json
      • … fichiers additionnels utilisés par le Paquet

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 create astro@latest demo -- --template minimal
# yarn
yarn create astro demo --template minimal
# pnpm
pnpm create astro@latest demo -- --template minimal

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

package.json

Titre de la section package.json

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", "...", "..."]
}

description

Titre de la section description

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

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

type

Titre de la section type

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.

homepage

Titre de la section homepage

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.

exports

Titre de la section exports

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.

files

Titre de la section files

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"]
}

keywords

Titre de la section keywords

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 ou withastro comme mot-clé spécial pour maximiser sa découverte dans l’écosystème Astro.

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

Astuce

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.

---

index.js

Titre de la section index.js

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.

Exemple : Utilisation des importations nommées

Titre de la section Exemple : Utilisation des importations nommées

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

Exemple : Utilisation des importations de Namespace (Espace de Noms)

Titre de la section Exemple : Utilisation des importations de Namespace (Espace de Noms)

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

Exemple : Utilisation des importations individuelles

Titre de la section Exemple : Utilisation des importations individuelles

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

---

Développement de votre Paquet

Titre de la section Développement de votre Paquet

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.

Tester votre composant

Titre de la section Tester votre composant

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.

• Répertoiremy-project/demo/src/pages/__fixtures__/

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

Publier votre composant

Titre de la section Publier votre composant

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é.

Bibliothèque d’intégrations

Titre de la section Bibliothèque d’intégrations

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

Astuce

Vous avez besoin d’aide pour construire votre intégration, ou vous voulez simplement rencontrer d’autres créateurs d’intégrations ? Nous avons un canal dédié #integrations sur notre serveur Discord. Venez nous saluer !

Données du fichier package.json

Titre de la section Données du fichier package.json

La bibliothèque est automatiquement mise à jour chaque semaine; chaque paquet publié sur NPM avec le mot-clé astro-component ou withastro 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.

Astuce

Besoin d’écraser les informations que notre bibliothèque lit de NPM ? Pas de problème ! Créez une Issue GitHub avec les informations mises à jour et nous allons nous assurer que les informations personnalisées name, description, ou homepage sont bien utilisées à la place.

Collections

Titre de la section Collections

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.

Collection	Mots-clés
Accessibilité	a11y, accessibility
Adapteurs	astro-adapter
Analyse de données	analytics
CSS + UI	css, ui, icon, icons, renderer
Frameworks	renderer
Performance + SEO	performance, perf, seo, optimization

Partagez

Titre de la section Partagez

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