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 . 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. microbundle 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, est construit sur . 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 . microbundle rollup.js 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 Créez un dossier pour le projet et exécutez avec les valeurs par défaut pour générer npm init package.json Créez dans le dossier index.ts src // src/index.ts export function sum(a: number, b: number) { return a + b; } Installer microbundle npm i -D microbundle Mettez à jour avec les valeurs suivantes : package.json // 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 } ... 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 , mais maintenant, votre commande build devrait ressembler à ceci : microbundle microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx Ajoutez la commande à dans le script pour plus de commodité : package.json build // 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 . 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 ». livre d'histoires 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 , créera un dossier avec la configuration par défaut et ajoutera quelques exemples d'histoires au dossier . package.json .storybook src/stories le style bibliothèque Intégrer dans votre 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 importé sera créé dans le dossier : styles.css 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 à cette fin. Et cela ressemblera à ceci : des composants stylisés 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 détaillé README.md Un fichier 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. README.md J'aime créer une structure dans l'ordre suivant : Titre Description très courte du colis Badges statistiques fantaisie ( ) shields.io Si votre bibliothèque est un composant d'interface utilisateur, incluez une capture d'écran ou fournissez un lien de démonstration sur CodeSandbox Liste des fonctionnalités Guide d'installation Fragments de code avec utilisation Options et accessoires acceptés par votre bibliothèque pour la configuration Vous pouvez vous référer à des exemples de fichiers de mes packages, tels que et , pour vous inspirer. README.md dot-path-value réagir-nested-dropdown 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 est installé, que les utilisateurs n'ont pas besoin d'utiliser, conservez-le dans devDependencies et il n'apparaîtra pas dans le bundle. microbundle 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 affichera un avertissement, mais elle n'installera pas automatiquement la dépendance. npm install 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 est correctement configuré. Voici quelques étapes importantes à suivre : package.json Nommez et essayez de décrire les fonctionnalités de base de votre bibliothèque. Par exemple: "name": "react-color-picker" 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" }, ... Configurez les : files ... "files": [ "dist", ], ... Vous devez spécifier les fichiers qui seront inclus dans , lorsque votre bibliothèque sera installée. Habituellement, inclure le dossier suffit. node_modules dist 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 ». Créez un compte si vous ne l'avez pas déjà fait et exécutez dans votre terminal ; suivez les instructions pour authentifier votre compte. Par défaut, la version de votre package sera ; vous pouvez le vérifier dans le fichier . Je recommande de le changer en . NPM npm login 1.0.0 package.json 0.0.1 Exécutez et vous avez terminé ! Pour mettre à jour la version ultérieurement, utilisez la commande pour incrémenter la version, puis publiez le package mis à jour avec . npm publish npm version patch 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 , je vous recommande d'utiliser avec une configuration plus spécifique. microbundle rollup.js 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.
