Le moyen le plus simple de créer votre premier package NPM

Ce guide vous guidera à travers le processus le plus simple de création et de publication de votre package NPM, du début à la fin, à l'aide d'un microbundle .

Parlons-en un peu microbundle . Je le trouve particulièrement efficace pour les bibliothèques simples car vous n'avez pas à vous soucier de la configuration, ce qui vous permet de vous concentrer sur le développement de votre package.

Voici une courte liste de ses fonctionnalités :

• Configurations intégrées ; il suffit d'ajouter un champ « exports » dans package.json
• Prise en charge de TypeScript prête à l'emploi sans tsconfig.json
• Plusieurs formats de sortie (CJS, UMD et ESM)
• Compression Terser intégrée

Fondamentalement, microbundle est construit sur rollup.js . Si vous avez des bibliothèques plus complexes à créer que celles mentionnées dans cet article, vous pouvez envisager d'utiliser une configuration pure rollup.js .

Initialisation de votre package

À titre d'exemple, créons une bibliothèque simple pour additionner deux nombres, qui n'exportera qu'une seule fonction sum .

1. Créez un dossier pour le projet et exécutez npm init avec les valeurs par défaut pour générer package.json

   
   

2. Créez index.ts dans le dossier src

    // src/index.ts export function sum(a: number, b: number) { return a + b; }

3. Installer microbundle

   npm i -D microbundle

   
   

4. Mettez à jour package.json avec les valeurs suivantes :

    // package.json ... "type": "module", "source": "src/index.ts", // your source code "exports": { "types": "./dist/index.d.ts", // TypeScript declaration file "require": "./dist/index.cjs", // CommonJS entry point "default": "./dist/index.esm.js" // ES Module entry point }, "main": "./dist/index.cjs", // where to generate the CommonJS bundle "module": "./dist/index.esm.js", // where to generate the ESM bundle "unpkg": "./dist/index.umd.js", // where to generate the UMD bundle "types": "./dist/index.d.ts", // TypeScript declaration file for the package "scripts": { "build": "microbundle", // compiles "source" to "main", "module", "unpkg" "dev": "microbundle watch" // re-build when source files change } ...

5. Exécutez le script de construction

   npm run build

   
   

   La sortie doit contenir exactement les fichiers que nous avons déclarés dans package.json

   

Et voilà, nous avons réalisé notre premier package. Jetons un coup d'œil à des scénarios plus complexes.

Ajouter React à votre bibliothèque

Si vous souhaitez intégrer React à votre bibliothèque, vous pouvez toujours l'utiliser microbundle , mais maintenant, votre commande build devrait ressembler à ceci :

 microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx

Ajoutez la commande à package.json dans le script build pour plus de commodité :

 // package.json ... "scripts": { "build": "microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx" } ...

Utilisation de Storybook pour les composants de l'interface utilisateur

Lors de la création d'une bibliothèque d'interface utilisateur, vous aurez peut-être besoin d'un bac à sable dans lequel vous pourrez développer, visualiser des composants et fournir des composants de démonstration pour votre documentation.

Voici le livre d'histoires . Il s'agit d'un bac à sable doté de sa propre interface pratique et de son propre bundle, dans lequel vous pouvez facilement décrire différents états de vos composants. Chaque capture de l'état de votre composant est appelée une « histoire ».

Cette image, tirée de leur documentation, montre à quoi cela ressemble :

L'installation de Storybook est assez simple ; exécutez simplement la commande dans votre bibliothèque :

 npx storybook@latest init

Cette commande installera toutes les dépendances requises pour Storybook, ajoutera des scripts à exécuter et créera Storybook dans package.json , créera un dossier .storybook avec la configuration par défaut et ajoutera quelques exemples d'histoires au dossier src/stories .

Intégrer le style dans votre bibliothèque

Vous pouvez ajouter un style de deux manières : via un fichier CSS ou CSS-in-JS. Le fichier CSS permet une personnalisation facile mais nécessite une inclusion séparée, tandis que le CSS-in-JS simplifie le style mais augmente la taille du bundle.

• Fichier CSS

  Créez un fichier CSS dans le répertoire src et importez-le dans le fichier du composant root React :

   // src/index.tsx import './styles.css'; export const MySuperComponent = () => { return ( <h1 className="title">Hi there!</h1> ) };

  
  

  Alors, exécutons à nouveau la commande build.

   npm run build

  
  

  Et votre fichier styles.css importé sera créé dans le dossier dist :

  

  Super! Nous avons obtenu un fichier CSS avec les styles nécessaires. Cette solution présente cependant un léger inconvénient. Le fichier CSS doit être ajouté séparément après l'installation du package.

  
  

  Par conséquent, les utilisateurs de votre bibliothèque devront utiliser un chargeur CSS (par exemple, un chargeur CSS pour le webpack) pour gérer votre fichier CSS, et leur utilisation ressemblera à ceci :

   import { MySuperComponent } from 'my-super-library'; import 'my-super-library/dist/styles.css'; export const App = () => { return ( <MySuperComponent /> ); }

  
  

• CSS-en-JS

  Vous pouvez utiliser des bibliothèques telles que des composants stylisés à cette fin. Et cela ressemblera à ceci :

   import styled from 'styled-components'; const Title = styled.h1` font-size: 30px; font-weight: bold; `; export const MySuperComponent = () => { return ( <Title>Hi there!</Title> ) };

  Avec cette solution, les utilisateurs n'auront pas besoin d'importer un fichier CSS et d'ajouter un chargeur spécial pour leur projet. Après avoir installé la bibliothèque, le composant aura son propre style. Cependant, cela augmentera la taille du bundle et rendra plus difficile pour les utilisateurs la personnalisation des éléments à l'aide des sélecteurs CSS.

Choisissez l'option qui vous convient le mieux. Je préfère utiliser le fichier CSS car il permet aux utilisateurs de personnaliser n'importe quel élément avec des sélecteurs CSS, n'affecte pas la taille du bundle et fonctionne plus rapidement.

Développement d'un fichier README.md détaillé

Un fichier README.md fournit des informations sur votre bibliothèque, comment l'installer, son utilisation de base et ses fonctionnalités. Il s'agit souvent du premier fichier que les développeurs lisent lorsqu'ils rencontrent votre référentiel ou votre package NPM, il doit donc être concis et informatif.

J'aime créer une structure dans l'ordre suivant :

1. Titre
2. Description très courte du colis
3. Badges statistiques fantaisie ( shields.io )
4. Si votre bibliothèque est un composant d'interface utilisateur, incluez une capture d'écran ou fournissez un lien de démonstration sur CodeSandbox
5. Liste des fonctionnalités
6. Guide d'installation
7. Fragments de code avec utilisation
8. Options et accessoires acceptés par votre bibliothèque pour la configuration

Vous pouvez vous référer à des exemples de fichiers README.md de mes packages, tels que dot-path-value et réagir-nested-dropdown , pour vous inspirer.

Naviguer dans la gestion des dépendances

C'est une partie importante car si vous le faites mal, les utilisateurs peuvent être confrontés à des conflits de versions ou à d'autres problèmes, et ils devront supprimer votre bibliothèque. Jetons donc un coup d'œil aux principales différences entre les types de dépendances.

• Les « devDependencies » sont uniquement destinées au développement et ne seront pas incluses dans votre offre groupée. Par exemple, si le package microbundle est installé, que les utilisateurs n'ont pas besoin d'utiliser, conservez-le dans devDependencies et il n'apparaîtra pas dans le bundle.

• Les "dépendances" seront installées avec le package. Incluez les dépendances dont votre package a besoin pour fonctionner dans les projets des utilisateurs. Notez que certaines dépendances, telles que « react », peuvent déjà être installées dans le projet de l'utilisateur. Avoir une « réaction » en double dans votre package pourrait augmenter la taille du bundle. C’est là que les « peerDependencies » s’avèrent utiles.

• Les « peerDependencies » sont des dépendances que votre package utilise mais qui ne seront pas incluses dans votre bundle. Votre package utilisera la version de la dépendance dont dispose l'utilisateur dans son projet.

  
  

  Fondamentalement, nous devrions spécifier une dépendance homologue si nous créons une bibliothèque pour son écosystème. Par exemple, si vous créez un composant React, définissez React comme dépendance homologue. Si vous développez un composant React avec un calendrier, ajoutez React et une bibliothèque de calcul de date (par exemple, date-fns) en tant que peerDependencies.

  
  

  Si l'utilisateur n'a pas la dépendance homologue spécifiée dans son projet, la commande npm install affichera un avertissement, mais elle n'installera pas automatiquement la dépendance.

Juste un petit exemple de ce à quoi ça ressemble :

 // package.json ... "dependencies": { // libraries which will be installed along with your library "clsx": "^1.2.1" // just library for className combining }, "peerDependencies": { // user should have these packages installed "react": "^16.8.0 || ^17.0.0 || ^18.0.0" // user should have react 16.8+ version }, "devDependencies": { // won't be in user's bundle, these libraries just for your developing needs "@types/react": "^18.2.33", "react": "^18.2.0", // in case if we are using storybook, we need actual react library to render our components there "microbundle": "^0.15.1", }, ...

Utiliser GitHub pour votre package

Si vous publiez un package NPM, cela signifie qu'il sera accessible publiquement (si vous disposez d'un compte gratuit). Pour recueillir les commentaires des utilisateurs, vous pouvez créer un référentiel GitHub pour votre code d'origine. Les gens peuvent y créer des problèmes et communiquer avec vous au sujet de votre colis. Vous pouvez également décrire vos sorties et obtenir des étoiles !

Vous pouvez certainement sauter cette étape, mais elle fait partie intégrante de la culture du développeur et peut constituer une contribution précieuse à l’open source.

Publication et maintenance du package

Avant de pouvoir publier votre package, il est essentiel de vous assurer que votre fichier package.json est correctement configuré. Voici quelques étapes importantes à suivre :

1. Nommez et essayez de décrire les fonctionnalités de base de votre bibliothèque. Par exemple:

    "name": "react-color-picker"

   
   

2. Ajoutez les informations du référentiel GitHub (si elles existent) :

    ... "homepage": "https://github.com/{your_repository}", "repository": { "type": "git", "url": "https://github.com/{your_repository}" }, "bugs": { "url": "https://github.com/{your_repository}/issues" }, ...

   
   

3. Configurez les files :

    ... "files": [ "dist", ], ...

   Vous devez spécifier les fichiers qui seront inclus dans node_modules , lorsque votre bibliothèque sera installée. Habituellement, inclure le dossier dist suffit.

   
   

4. Ajouter keywords :

   Les mots clés sont un tableau de chaînes qui décrivent votre package et sont utilisés par NPM pour les recherches et les recommandations. Choisissez des mots pertinents pour votre package que vous prévoyez que les gens utiliseront lors de la recherche. Créons des mots-clés pour notre bibliothèque sum :

    ... "keywords": ["typescript", "math", "sum", "numbers", "arithmetic", "calculator", "calculation"] ...

   Il est important de spécifier vos technologies, car les utilisateurs recherchent souvent des termes tels que « bibliothèque dactylographiée pour les mathématiques » ou « sélecteur de calendrier React ».

   
   

5. Créez un compte NPM si vous ne l'avez pas déjà fait et exécutez npm login dans votre terminal ; suivez les instructions pour authentifier votre compte. Par défaut, la version de votre package sera 1.0.0 ; vous pouvez le vérifier dans le fichier package.json . Je recommande de le changer en 0.0.1 .

   
   

6. Exécutez npm publish et vous avez terminé ! Pour mettre à jour la version ultérieurement, utilisez la commande npm version patch pour incrémenter la version, puis publiez le package mis à jour avec npm publish .

Conclusion

Comme vous pouvez le constater, créer votre propre bibliothèque est très simple ! Essentiellement, c’est tout ce dont vous avez besoin pour créer et maintenir le package. Si vous avez du mal à limiter votre bibliothèque avec microbundle , je vous recommande d'utiliser rollup.js avec une configuration plus spécifique.

Créer des packages NPM et contribuer à l'open source est une expérience enrichissante et précieuse pour les développeurs de tous niveaux. Il vous permet de partager votre code avec la communauté, d'acquérir beaucoup d'expérience et de constituer un portfolio de votre travail.