Création d'un Package

Un package est un répertoire avec du code et un fichier package.json qui fournit des informations à Yarn sur votre package.

La plupart des packages utilisent une sorte de système de contrôle de version. Le plus souvent, c’est git mais ça ne dérange pas Yarn si vous en choisissez un autre. Pour ce guide, nos exemples vont utiliser git.

Remarque : Si vous souhaitez suivre ce guide, assurez-vous d’installer d’abord git et Yarn.

Création de votre premier package

Afin de créer votre premier package, ouvrez le terminal/la console de votre système et exécutez les commandes suivantes :

git init my-new-project
cd my-new-project
yarn init

Cela va créer un nouveau dépôt git, positionnez vous à l’intérieur et puis ouvrez un formulaire interactif pour la création d’un nouveau projet yarn avec les questions suivantes :

name (my-new-project):
version (1.0.0):
description:
entry point (index.js):
git repository:
author:
license (MIT):

Vous pouvez répondre à chacune d’entre elles, ou vous pouvez simplement appuyer sur entrée/retour pour utiliser la valeur par défaut ou la laisser vide.

Astuce : Si vous souhaitez utiliser les valeurs par défaut pour tout, vous pouvez également exécuter yarn init --yes et il ignore toutes les questions.

`package.json`

Vous devriez maintenant avoir un package.json qui ressemble à ceci :

{
  "name": "mon-nouveau-projet",
  "version": "1.0.0",
  "description": "La description de mon nouveau projet.",
  "main": "index.js",
  "repository": {
    "url": "https://exemple.com/votre-nomutilisateur/mon-nouveau-projet",
    "type": "git"
  },
  "author": "Votre Nom <toi@exemple.com>",
  "license": "MIT"
}

Les champs que vous voyez dans le package.json ont les significations suivantes :

name correspond à l’identificateur de votre package, si vous souhaitez publier sur le registre global, vous devez vous assurer qu’il soit unique.
version est la version compatible semver de votre package, vous pouvez publier un package autant de fois que vous voulez, mais ils doivent avoir de nouvelle version.
description est un champ facultatif, mais recommandé pour les autres utilisateurs de Yarn pour le chercher et comprendre votre projet.
main est utilisé pour définir un point d’entrée dans votre code utilisé par des programmes comme Node.js. Si rien n’est spécifié, la valeur par défaut sera index.js.
repository est un autre champs optionnel bien que recommandé, qui aide les utilisateurs de votre package à retrouver le code source afin d’y contribuer.
author est le créateur ou le mainteneur d’un package. Il suit le format "Votre nom <votre-email@exemple.com> (http://votre-site-web.com)"
license représente les termes légaux de publication de votre package et la manière dont il est possible d’utiliser le code de votre package.

Lorsque vous lancez yarn init, cela crée uniquement ce fichier, rien n’est effectué en tâche de fond. Vous pouvez tout à fait éditer ce fichier autant que vous le souhaitez.

Champs additionnels

Parcourons quelques champs additionnels du package.json que vous pourriez souhaiter ajouter.

{
  "name": "mon-nouveau-projet",
  "...": "...",
  "keywords": ["cool", "utile", "machin"],
  "homepage": "https://site-de-mon-nouveau-projet.com",
  "bugs": "https://github.com/vous/mon-nouveau-projet/issues",
  "contributors": [
    "Votre Ami <son-email@exemple.com> (http://son-site-web.com)",
    "Un Autre Ami <un-autre-email@exemple.com> (https://un-autre-site-web.org)"
  ],
  "files": [
    "index.js",
    "lib/*.js",
    "bin/*.js"
  ],
  "bin": {
    "mon-nouveau-projet-cli": "bin/mon-nouveau-projet-cli.js"
  }
}

keywords est une list de termes que les autres développeurs peuvent chercher pour trouver votre package ou d’autres packages similaires.
homepage est une l’URL d’un site web permettant d’informer les utilisateurs sur le package avec une introduction, de la documentation et des liens vers des ressources additionnelles.
bugs est une URL permettant aux utilisateurs de votre package de signaler un bug rencontré avec votre package.
contributors est la liste des contributeurs de votre package. S’il y a d’autres personnes impliquées dans votre projet, vous pouvez les mentionner ici.
files est une liste de fichiers qui doivent être inclus dans votre package quand celui-ci est publié et installé. Si non-spécifié, Yarn inclura tous les fichiers.
bin est une association de commandes CLI (des binaires) à créer par Yarn lors de l’installation de votre package.

Pour une liste complète des champs du package.json et pour plus de détails sur chacun de ces champs, veuillez vous référer à la documentation du package.json.

License et open source

Les packages Yarn sont généralement encouragés à être open source, cependant il est important de noter qu’ils ne sont pas automatiquement open source lorsqu’ils sont simplement publiés.

Afin que votre code soit open source, vous devez avoir une licence open source. Il en existe de nombreuses, en voici quelques unes :

Si vous souhaitez plus d’alternatives, vous pouvez trouver une liste plus complète ici.

Quand vous choisissez une licence open source pour votre package, soyez certain d’ajouter un fichier LICENSE à la racine de votre package avec le contenu de la license et mettez à jour le champs license de votre package.json.

Remarque : si vous ne voulez pas que votre projet ait une licence open source, vous devriez indiquer explicitement quelle est la licence ou s’il n’a aucune licence d’utilisation.

Partage de code

Vous allez probablement vouloir autoriser les utilisateurs de votre package à accéder au code source et à vous signaler des problèmes. Voici plusieurs sites populaires pour héberger votre code source :

Ces sites permettront à vos utilisateurs de voir votre code, signaler des problèmes et faire des contributions. Une fois que votre code aura été déposé quelque part, vous devriez ajouter les champs suivant à votre package.json :

{
  "homepage": "https://github.com/username/mon-nouveau-projet",
  "bugs": "https://github.com/username/mon-nouveau-projet/issues",
  "repository": {
    "url": "https://github.com/username/mon-nouveau-projet",
    "type": "git"
  }
}

Documentation

Idéalement, vous devriez écrire votre documentation avant de publier votre package. Le strict minimum serait d’écrire un fichier README.md à la racine de votre projet pour présenter votre package et documenter l’API publique.

Une bonne documentation se caractérise par le fait de donner à vos utilisateurs toute la connaissance nécessaire pour débuter avec votre projet et à l’utiliser par la suite. Pensez aux questions qu’une personne ne connaissant strictement rien à votre projet pourrait avoir. Décrivez précisément les choses avec autant de détails que possible, mais pensez également à être concis et facile à lire. Les projets avec une documentation riche sont généralement ceux qui rencontrent le plus grand succès.

Gardez vos packages légers

Lorsque vous créez des packages Yarn, vous êtes encouragé à les garder légers et simples. Décomposez les gros packages en plus petits si cela fait sens. C’est fortement conseillé étant donné que Yarn est capable d’installer des centaines voire des milliers de packages de manière très efficace.

Un grand nombre de petits packages est très bon modèle d’organisation des packages. Généralement cela mène à des téléchargement plus petits étant donné que vous ne construisez pas des dépendances énormes mais que vous utilisez des petites portions du code.

Vous devriez également tenir compte du contenu de votre package. Soyez sûr de ne pas accidentellement distribuer vos tests ou tout autre fichier qui n’est pas nécessaire pour l’utilisation du package (scripts de build, images, etc).

Prêtez également attention aux packages que vous utilisez comme dépendances, préférez des petits dépendances à moins que vous ayez une bonne raison. Soyez certain de ne pas dépendre accidentellement d’un énorme package.

Publication d'un Package →