Créer et publier un package npm : le guide complet

Sommaire

• Pourquoi publier sur npm ?
• Préparer son environnement
• Créer le package
• Le fichier package.json
• Publier sur npmjs
• Publier des mises à jour
• Bonnes pratiques
• FAQ
• Conclusion

Pourquoi publier sur npm ?

npm est le registry de packages le plus utilisé au monde : plus de 2 millions de packages, des milliards de téléchargements hebdomadaires. C’est la vitrine et le canal de distribution standard du web moderne.

Publier un package sur npm, c’est partager du code réutilisable avec des millions de développeurs, mais aussi :

• Réutiliser votre utilitaire maison sur tous vos projets sans copier-coller de fichiers ;
• Documenter et versionner proprement votre travail, avec un historique public ;
• Contribuer à l’écosystème open source et bâtir une preuve de compétence (utile pour un portfolio, comme nous le détaillons dans notre guide pour devenir freelance) ;
• Distribuer des outils en ligne de commande installables en une commande : npx mon-outil.

Contrairement à une idée reçue, il n’y a pas besoin d’une librairie monumentale. Un formateur de dates, un petit parseur, un linter de config : des milliers de packages à succès ne font que quelques kilo-octets.

Préparer son environnement

Deux prérequis seulement :

1. Node.js et npm installés (Node 24 LTS « Krypton » à date, Node 22 encore supporté — vérifiez avec node -v et npm -v) ;
2. Un compte npm gratuit sur npmjs.com.

# Vérifier les versions installées
node -v   # v24.x
npm -v    # 11.x

Connectez ensuite votre terminal à votre compte :

npm login
# Le navigateur s'ouvre sur npmjs.com pour authentifier cette machine
npm whoami
# affiche votre nom d'utilisateur si tout est bon

Depuis 2023, npm login ouvre le navigateur plutôt que de demander le mot de passe en ligne de commande — plus sécurisé, avec support natif de la 2FA.

Créer le package

La structure minimale

Un package npm n’a besoin que de deux choses : un package.json et un fichier d’entrée. En pratique, voici la structure recommandée pour une librairie :

mon-package/
├── src/
│   └── index.js
├── test/
│   └── index.test.js
├── .gitignore
└── package.json

Initialiser le projet

mkdir mon-package && cd mon-package
git init
npm init
# ou, pour un package.json par défaut sans questions :
npm init -y

Écrire le code

Un exemple minimal avec une API publique volontairement simple :

// src/index.js
function slugify(text) {
  return text
    .toString()
    .normalize("NFD")
    .replace(/[\u0300-\u036f]/g, "")
    .toLowerCase()
    .trim()
    .replace(/[^a-z0-9\s-]/g, "")
    .replace(/[\s_-]+/g, "-");
}

export { slugify };

Tester avant de publier

Un package publié sera installé par d’autres : testez-le avant de le diffuser. Même une suite minimaliste protège des régressions.

// test/index.test.js
import { slugify } from "../src/index.js";
import assert from "node:assert";

assert.equal(slugify("Écrivain Français !"), "ecrivain-francais");
console.log("OK");

node --test test/

Node intègre un runner de test natif (node --test, stable depuis Node 20), aucun framework externe requis pour démarrer.

Le fichier package.json

C’est la carte d’identité du package. Voici les champs qui comptent pour la publication :

{
  "name": "@votre-compte/mon-package",
  "version": "1.0.0",
  "description": "Transforme un texte en slug URL-friendly",
  "type": "module",
  "main": "./src/index.js",
  "exports": {
    ".": "./src/index.js"
  },
  "files": ["src", "README.md"],
  "keywords": ["slug", "slugify", "url"],
  "author": "Votre Nom",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/votre-compte/mon-package.git"
  },
  "engines": { "node": ">=20" }
}

Points d’attention :

• name : unique sur le registry. Sans scope, vous devez trouver un nom libre ; avec un scope (@votre-compte/...), le nom est garanti disponible sous votre espace de noms.
• exports : définit les points d’entrée publics. Plus sûr que main seul, car il empêche d’importer des fichiers internes en profondeur.
• files : liste blanche de ce qui sera publié. Tout le reste (tests, config) reste local. Vérifiez avec npm pack --dry-run avant chaque publication.
• engines : la version minimale de Node requise. npm affichera un warning aux utilisateurs sur des versions plus anciennes.
• license : sans licence, personne n’a techniquement le droit d’utiliser votre code. MIT est le standard pour l’open source.

README et LICENSE

Le README est la vitrine du package sur npmjs.com : description, installation, usage, exemples. Il est affiché automatiquement. Un package sans README perd énormément de crédibilité — prévoyez au minimum installation + un exemple fonctionnel.

Publier sur npmjs

Vérifier le contenu publié

npm pack --dry-run
# liste exactement les fichiers qui iront dans l'archive .tgz

Publier

npm publish
# pour un package scoped public :
npm publish --access public

npm compresse le contenu, vous demande le code 2FA (si activée — et activez-la, voir les bonnes pratiques), puis publie. Le package est immédiatement visible sur https://www.npmjs.com/package/votre-package et installable :

npm install mon-package

Les pièges classiques du premier publish

• Nom déjà pris : npm ERR! code E403 avec « you do not have permission to publish ». Solution : scoped package ou autre nom.
• Version déjà publiée : un registry est immuable. On ne republie jamais une version existante, on incrémente (voir section suivante).
• Fichiers oubliés : si vous avez oublié le README dans files, publiez un 1.0.1 corrigé.
• 2FA perdue : si vous perdez l’accès à votre 2FA, la récupération passe par les recovery codes générés à l’activation. Gardez-les précieusement.

Publier des mises à jour

npm utilise le versioning sémantique : MAJOR.MINOR.PATCH. Une fois 1.0.0 publié :

• PATCH (1.0.0 → 1.0.1) : correction de bug, rien de nouveau ;
• MINOR (1.0.0 → 1.1.0) : ajout de fonctionnalité, rétrocompatible ;
• MAJOR (1.0.0 → 2.0.0) : breaking change, incompatible avec la version précédente.

npm fournit un raccourci qui incrémente la version :

npm version patch   # 1.0.0 -> 1.0.1
npm version minor   # 1.0.0 -> 1.1.0
npm version major   # 1.0.0 -> 2.0.0
npm publish

Pour automatiser via CI, GitHub Actions peut publier automatiquement à chaque tag — protégé par un token et la 2FA.

Bonnes pratiques

• Activez la 2FA sur votre compte npm, en mode « auth-only » ou sur l’écriture. Les comptes npm sont une cible privilégiée : un package populaire détourné peut injecter du malware chez tous ses installateurs, comme l’ont montré les incidents supply-chain de ces dernières années.
• Publiez depuis la CI depuis un tag Git, avec NPM_TOKEN en secret et --provenance pour attester l’origine du build (visible sur la page npm du package).
• Scopez vos packages (@vous/mon-package) : nom garanti, branding clair, publication publique gratuite — l’espace de noms évite les collisions et le typosquatting.
• Un README et une licence avant tout : c’est gratuit et multiplie l’adoption.
• npm pack --dry-run avant chaque publish : évite de publier des tests ou des fichiers de config.
• N’écrasez jamais une version publiée : le registry est immuable par design. Une version foireuse ? Publiez un fix en PATCH, ou npm deprecate pour marquer sans retirer (retrait possible seulement dans les 72 h si critique).
• .npmignore vs files : préférez la liste blanche files à la liste noire .npmignore — oublier un fichier dans npm pack --dry-run se voit immédiatement.
• Déprécier proprement : npm deprecate [email protected] "Voir 2.x" informe les utilisateurs sans casser leurs installs.

FAQ

Combien coûte la publication sur npm ?

Rien. Les packages publics sont gratuits et illimités, pour le téléchargement comme la publication. Les plans payants concernent les packages privés et les organisations avec permissions avancées.

Puis-je publier en TypeScript ?

Oui, et c’est recommandé pour l’expérience développeur. Publiez les types générés (.d.ts via tsc) à côté du JavaScript : les consommateurs TypeScript auront l’autocomplétion et la vérification de types sans configuration.

Comment retirer un package publié ?

npm unpublish fonctionne dans les 72 heures suivant la publication et sous conditions (peu de téléchargements). Passé ce délai, utilisez npm deprecate. Cette politique stricte existe car des projets dépendent potentiellement de votre package.

Quelle est la différence entre node_modules et le registry ?

Le registry (npmjs.com) est le dépôt central où vous publiez. node_modules est le dossier local où npm installe les dépendances de votre projet. package-lock.json, lui, verrouille l’arbre de dépendances pour reproduire les installations.

npm, yarn, pnpm : même registry ?

Oui. yarn et pnpm sont des clients compatibles avec le registry npm officiel — publier avec npm rend votre package installable par tous.

Conclusion

Publier sur npm est un processus simple — npm init, npm publish — mais les bonnes pratiques font la différence entre un package crédible et un fardeau de maintenance : 2FA, versioning sémantique, files propre, README soigné, publication depuis la CI avec provenance. Commencez petit : un utilitaire de quelques lignes suffit pour apprendre le cycle complet.

Envie d’aller plus loin sur la distribution de code ? Consultez notre guide sur l’introduction à Docker pour distribuer des environnements complets, ou celui sur GitHub Actions pour automatiser vos publications. Et si le package devient un volet de votre activité, notre guide de gestion des finances en freelance vous aide à séparer pro et perso dès le premier euro.

---

Article rédigé par Pierry Lim, développeur full-stack freelance spécialisé Symfony et React.