Comment publier un package npm open source de A à Z en 7 étapes (2026)

Publier un package npm open source, c'est bien plus que lancer npm publish. En 2026, l'écosystème Node.js a mûri : les utilisateurs attendent du TypeScript natif, une compatibilité ESM et CommonJS, des tests automatisés, et un processus de release reproductible. Ce guide vous accompagne de A à Z — de l'initialisation du projet jusqu'à la maintenance long terme — avec la stack la plus robuste de 2026.

Que vous publiiez votre premier package ou que vous modernisiez un package existant, chaque étape est conçue pour être copiée et adaptée directement. Pas de filler, pas de théorie abstraite : du code concret et des explications de chaque décision technique.

Étape 1 : Initialiser le projet avec les bons outils

Le choix des outils d'initialisation détermine la qualité de tout le reste. En 2026, la stack recommandée pour un nouveau package npm est :

• pnpm comme gestionnaire de packages — plus rapide et plus efficace en espace disque que npm et yarn.
• TypeScript 5.9 — le standard de fait pour les packages npm sérieux.
• tsup comme bundler — basé sur esbuild, rapide, configuration minimale, génère ESM + CJS + déclarations de types.

Commencez par créer le projet :

# Créer le dossier et initialiser
mkdir mon-package && cd mon-package
pnpm init

# Installer TypeScript et tsup
pnpm add -D typescript tsup @types/node

# Initialiser la configuration TypeScript
pnpm tsc --init

Configurez le tsconfig.json pour un package npm moderne :

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

Quelques choix importants ici. verbatimModuleSyntax est nouveau en TypeScript 5.x et force l'utilisation explicite de import type pour les imports de types, ce qui aide le bundler à éliminer le code mort. moduleResolution: "bundler" est le mode recommandé quand vous utilisez un bundler comme tsup, car il supporte les champs exports du package.json.

Créez la structure de base du projet :

mkdir src
touch src/index.ts

# Structure recommandée
# src/
# ├── index.ts          ← Point d'entrée principal
# ├── core/             ← Logique métier
# │   └── parser.ts
# ├── utils/            ← Utilitaires internes
# │   └── helpers.ts
# └── types.ts          ← Types exportés

Un point essentiel : créez un fichier .gitignore adapté dès le départ. Ne laissez pas le dist/ dans git — il sera généré à chaque build.

# .gitignore
node_modules/
dist/
*.tsbuildinfo
.DS_Store
coverage/
.env
.env.local

Étape 2 : Structurer le code pour l'export (ESM + CJS dual package)

C'est l'étape qui fait trébucher la majorité des auteurs de packages. En 2026, l'écosystème Node.js est partagé entre deux systèmes de modules : ESM (la norme moderne, utilisée par Next.js, Vite, Astro, Deno) et CommonJS (utilisé par les projets legacy, Jest par défaut, et de nombreux outils CLI). Votre package doit supporter les deux.

Configurez tsup pour générer les deux formats :

// tsup.config.ts
import { defineConfig } from "tsup";

export default defineConfig({
  entry: ["src/index.ts"],
  format: ["cjs", "esm"],
  dts: true,
  splitting: false,
  sourcemap: true,
  clean: true,
  minify: false, // Ne pas minifier un package npm
  treeshake: true,
  outDir: "dist",
});

Pourquoi minify: false ? Contrairement à une application web, un package npm ne doit pas être minifié. Les consommateurs de votre package utilisent leur propre bundler (Vite, webpack, esbuild) qui minifiera le code final. Minifier un package npm rend le débogage impossible pour vos utilisateurs.

Configurez le package.json avec les champs d'export corrects. C'est la partie la plus critique — une mauvaise configuration ici et votre package sera inutilisable pour la moitié de vos utilisateurs :

{
  "name": "mon-package",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch",
    "test": "vitest",
    "prepublishOnly": "pnpm run build"
  }
}

Détaillons les champs clés :

• "type": "module" : déclare que votre package utilise ESM par défaut. Les fichiers .js seront traités comme ESM, les fichiers .cjs comme CommonJS.
• exports : le champ moderne de résolution de modules. Node.js 16+ et tous les bundlers modernes l'utilisent. L'ordre import/require compte : mettez toujours types en premier dans chaque condition.
• files : limite les fichiers publiés sur npm au strict nécessaire. Seul le dossier dist/ est inclus (plus le package.json, README, et LICENSE automatiquement).
• prepublishOnly : script exécuté automatiquement avant npm publish, garantissant que le build est à jour.

Vérifiez que tout fonctionne en exécutant un premier build :

# Créer un fichier source de test
cat > src/index.ts << 'EOF'
export function greet(name: string): string {
  return `Bonjour, ${name} !`;
}

export type GreetOptions = {
  name: string;
  formal?: boolean;
};
EOF

# Builder
pnpm run build

# Vérifier la sortie
ls -la dist/
# dist/index.js      (ESM)
# dist/index.cjs     (CJS)
# dist/index.d.ts    (Types)
# dist/index.d.cts   (Types CJS)

Étape 3 : Écrire les tests et configurer la CI

Un package npm sans tests est un package que personne ne devrait utiliser en production. En 2026, Vitest est le framework de test standard pour les projets TypeScript. Il est rapide (basé sur Vite), supporte ESM nativement, et sa syntaxe est compatible avec Jest pour une migration facile.

# Installer Vitest
pnpm add -D vitest

# Créer le fichier de configuration
cat > vitest.config.ts << 'EOF'
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true,
    coverage: {
      provider: "v8",
      reporter: ["text", "lcov", "html"],
      thresholds: {
        branches: 80,
        functions: 80,
        lines: 80,
        statements: 80,
      },
    },
  },
});
EOF

Écrivez des tests pour chaque fonction exportée. La règle est simple : si c'est exporté, c'est testé.

// src/__tests__/index.test.ts
import { describe, it, expect } from "vitest";
import { greet } from "../index";

describe("greet", () => {
  it("retourne un message de salutation basique", () => {
    expect(greet("Sophie")).toBe("Bonjour, Sophie !");
  });

  it("gère les noms avec des caractères spéciaux", () => {
    expect(greet("Jean-François")).toBe("Bonjour, Jean-François !");
  });

  it("gère une chaîne vide", () => {
    expect(greet("")).toBe("Bonjour,  !");
  });
});

Configurez maintenant la CI avec GitHub Actions. Ce workflow exécute les tests sur chaque PR et chaque push sur main :

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: "pnpm"
      - run: pnpm install --frozen-lockfile
      - run: pnpm run build
      - run: pnpm test
      - run: pnpm vitest run --coverage
        if: matrix.node-version == 22

Un détail important : testez sur plusieurs versions de Node.js (18, 20, 22 dans cet exemple). Votre package sera utilisé par des projets sur différentes versions, et les incompatibilités ESM/CJS varient entre les versions de Node.

Ajoutez les scripts de test au package.json :

{
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch",
    "test": "vitest",
    "test:run": "vitest run",
    "test:coverage": "vitest run --coverage",
    "lint": "tsc --noEmit",
    "prepublishOnly": "pnpm run lint && pnpm run test:run && pnpm run build"
  }
}

Le script prepublishOnly a été enrichi : il vérifie les types, exécute les tests, puis build. C'est votre dernier filet de sécurité avant la publication — il est impossible de publier un package cassé si ce script est correctement configuré.

Étape 4 : Rédiger le README et la documentation

Le README est la vitrine de votre package. C'est la première chose que les développeurs voient sur npm et GitHub. Un bon README convertit un visiteur en utilisateur. Un mauvais README envoie le visiteur chez la concurrence — même si votre code est meilleur.

Structure recommandée pour un README de package npm :

# mon-package

> Description courte et percutante (une ligne)

[![npm version](https://img.shields.io/npm/v/mon-package)](https://www.npmjs.com/package/mon-package)
[![CI](https://github.com/votre-user/mon-package/actions/workflows/ci.yml/badge.svg)](https://github.com/votre-user/mon-package/actions)
[![License](https://img.shields.io/npm/l/mon-package)](LICENSE)

## Installation

```bash
pnpm add mon-package
# ou
npm install mon-package
# ou
yarn add mon-package
```

## Utilisation rapide

```typescript
import { greet } from "mon-package";

console.log(greet("Sophie"));
// => "Bonjour, Sophie !"
```

## API

### `greet(name: string): string`

Retourne un message de salutation.

| Paramètre | Type     | Description         |
|-----------|----------|---------------------|
| name      | `string` | Le nom à saluer     |

**Retourne** : `string` — Le message formaté

## Exemples

### Avec Next.js

```typescript
// app/page.tsx
import { greet } from "mon-package";
export default function Home() {
  return <h1>{greet("monde")}</h1>;
}
```

## Contribution

Les contributions sont les bienvenues !
Voir [CONTRIBUTING.md](CONTRIBUTING.md).

## Licence

MIT © [Votre Nom]

Les erreurs classiques à éviter dans un README :

• Pas d'exemple d'installation : ne supposez jamais que les gens savent comment installer un package npm.
• Pas d'exemple d'utilisation : montrez du code qui fonctionne en 3 lignes maximum.
• Documenter uniquement l'API complète : commencez par le cas d'utilisation le plus simple avant de documenter toutes les options.
• Pas de badges CI : les badges indiquent immédiatement si le projet est maintenu et les tests passent.

Créez aussi un fichier CONTRIBUTING.md si vous voulez attirer des contributeurs, et un CHANGELOG.md (qui sera automatisé à l'étape 7). Pour comprendre comment recruter et garder des contributeurs sur un projet open source, consultez notre guide comment recruter des contributeurs open source seniors.

Étape 5 : Configurer le package.json pour la publication

Avant de publier, votre package.json doit inclure toutes les métadonnées nécessaires pour npm. Voici la configuration complète et validée :

{
  "name": "mon-package",
  "version": "0.1.0",
  "description": "Description courte et riche en mots-clés",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    }
  },
  "files": ["dist", "README.md", "LICENSE"],
  "keywords": [
    "typescript",
    "esm",
    "commonjs",
    "votre-domaine"
  ],
  "author": "Votre Nom <email@example.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/votre-user/mon-package"
  },
  "bugs": {
    "url": "https://github.com/votre-user/mon-package/issues"
  },
  "homepage": "https://github.com/votre-user/mon-package#readme",
  "engines": {
    "node": ">=18"
  },
  "sideEffects": false,
  "publishConfig": {
    "access": "public",
    "provenance": true
  },
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch",
    "test": "vitest",
    "test:run": "vitest run",
    "test:coverage": "vitest run --coverage",
    "lint": "tsc --noEmit",
    "prepublishOnly": "pnpm run lint && pnpm run test:run && pnpm run build"
  }
}

Détaillons les champs importants pour la publication :

• keywords : les mots-clés utilisés par la recherche npm. Choisissez 5-10 mots pertinents. Évitez les mots génériques (« javascript », « node ») au profit de termes spécifiques à votre domaine.
• engines : déclare la version minimale de Node.js requise. En 2026, Node 18 est le minimum raisonnable (LTS jusqu'en avril 2025, encore largement utilisé).
• sideEffects: false : indique aux bundlers que votre package ne produit pas d'effets de bord, permettant un tree-shaking optimal.
• publishConfig.provenance: true : active la provenance npm — chaque publication est liée à son workflow CI, renforçant la sécurité supply chain. Consultez notre article sur la sécurisation du pipeline npm pour comprendre pourquoi c'est essentiel en 2026.

Avant de publier, vérifiez le contenu du package avec pnpm pack --dry-run :

# Voir exactement ce qui sera publié sur npm
pnpm pack --dry-run

# Sortie attendue :
# mon-package-0.1.0.tgz
# Tarball Contents:
#   dist/index.js
#   dist/index.cjs
#   dist/index.d.ts
#   dist/index.d.cts
#   package.json
#   README.md
#   LICENSE

Si vous voyez des fichiers inattendus (tests, fichiers de config, node_modules), ajustez le champ files ou créez un .npmignore.

Étape 6 : Publier sur npm et configurer les releases automatiques

C'est le moment de publier. Si c'est votre première publication, vous devez d'abord créer un compte npm et vous authentifier :

# Se connecter à npm (une seule fois)
npm login

# Vérifier l'authentification
npm whoami

# Publier la première version
npm publish --access public

Pour les publications suivantes, automatisez le processus avec changesets — l'outil utilisé par les projets majeurs de l'écosystème (Radix UI, TanStack, Turborepo) :

# Installer changesets
pnpm add -D @changesets/cli @changesets/changelog-github

# Initialiser
pnpm changeset init

Configurez changesets dans .changeset/config.json :

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    { "repo": "votre-user/mon-package" }
  ],
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

Le workflow de release automatisé avec GitHub Actions :

# .github/workflows/release.yml
name: Release

on:
  push:
    branches: [main]

concurrency: $\{{ github.workflow }}-$\{{ github.ref }}

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      id-token: write  # Pour la provenance npm
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: "pnpm"
          registry-url: "https://registry.npmjs.org"
      - run: pnpm install --frozen-lockfile
      - name: Create Release Pull Request or Publish
        id: changesets
        uses: changesets/action@v1
        with:
          publish: pnpm run release
        env:
          GITHUB_TOKEN: $\{{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: $\{{ secrets.NPM_TOKEN }}

Ajoutez le script release au package.json :

{
  "scripts": {
    "release": "pnpm run build && changeset publish"
  }
}

Le flux de travail est le suivant :

1. Vous faites vos modifications et ajoutez un changeset : pnpm changeset
2. Vous commitez et poussez sur main
3. GitHub Actions crée automatiquement une PR « Version Packages » qui regroupe les changesets en attente
4. Quand vous mergez cette PR, le workflow publie automatiquement sur npm avec provenance

Étape 7 : Maintenir et itérer (semantic versioning, changelog)

Publier un package, c'est 20 % du travail. Le maintenir sur le long terme, c'est les 80 % restants. Voici les pratiques essentielles pour un package npm durable.

Semantic Versioning (SemVer)

Le versioning sémantique n'est pas optionnel — c'est un contrat avec vos utilisateurs. Chaque numéro de version communique une information précise :

• MAJOR (1.0.0 → 2.0.0) : changement breaking — les utilisateurs doivent modifier leur code pour mettre à jour.
• MINOR (1.0.0 → 1.1.0) : nouvelle fonctionnalité rétro-compatible — mise à jour safe.
• PATCH (1.0.0 → 1.0.1) : correction de bug rétro-compatible — mise à jour recommandée.

Avec changesets, le versioning est intégré au workflow. Quand vous exécutez pnpm changeset, l'outil vous demande :

1. Quels packages sont affectés (pertinent pour les monorepos)
2. Le type de changement (major, minor, patch)
3. Une description du changement (utilisée pour le CHANGELOG)

# Ajouter un changeset après une modification
pnpm changeset

# Exemple d'interaction :
# ? What kind of change is this for mon-package?
#   patch - Bug fix
# > minor - New feature
#   major - Breaking change
# ? Summary: Ajout de la fonction farewell() pour les messages d'au revoir

CHANGELOG automatique

Avec la configuration @changesets/changelog-github, le CHANGELOG est généré automatiquement avec des liens vers les PRs et les contributeurs :

# CHANGELOG.md (généré automatiquement)

## 0.2.0

### Minor Changes

- Ajout de la fonction farewell() pour les messages d'au revoir
  ([#12](https://github.com/votre-user/mon-package/pull/12))
  par [@contributeur](https://github.com/contributeur)

## 0.1.1

### Patch Changes

- Correction du typo dans le message de salutation
  ([#8](https://github.com/votre-user/mon-package/pull/8))

Gestion des issues et des PRs

Un package maintenu répond aux issues. Configurez des templates d'issues pour structurer les rapports de bugs et les demandes de fonctionnalités :

# .github/ISSUE_TEMPLATE/bug_report.md
---
name: Bug report
about: Signaler un bug
labels: bug
---

## Description du bug
<!-- Description claire et concise -->

## Reproduction
<!-- Étapes pour reproduire -->

## Comportement attendu
<!-- Ce qui devrait se passer -->

## Environnement
- OS:
- Node.js:
- Version du package: 

Sécurité supply chain

En 2026, la sécurité de la supply chain npm est critique. Les attaques par packages malveillants sont en hausse constante — nous avons documenté plusieurs incidents majeurs cette année, dont les 57 paquets npm compromis par Phantom Gyp Miasma et l'attaque Mini Shai-Hulud sur TanStack.

Pour protéger votre package et vos utilisateurs :

• Activez la 2FA sur npm : obligatoire pour toute publication. Utilisez npm profile enable-2fa auth-and-writes.
• Utilisez la provenance npm : déjà configurée dans notre publishConfig, elle lie chaque version publiée à son workflow CI.
• Auditez vos dépendances : exécutez régulièrement pnpm audit et configurez Dependabot ou Renovate pour les mises à jour automatiques.
• Limitez les permissions npm : n'accordez jamais le rôle « owner » à quelqu'un qui n'en a pas besoin. Utilisez les « teams » npm pour les accès granulaires.

Checklist de maintenance mensuelle

Réservez une heure par mois pour la maintenance de votre package :

1. Vérifier et merger les PRs de Dependabot/Renovate
2. Répondre aux issues ouvertes (même si c'est pour dire « pas prévu »)
3. Exécuter pnpm audit et corriger les vulnérabilités
4. Vérifier que les tests passent sur les dernières versions de Node.js
5. Mettre à jour le README si nécessaire
6. Publier les changesets en attente

Récapitulatif : la stack complète 2026

Voici un récapitulatif de la stack recommandée pour publier un package npm open source en 2026 :

Conclusion : Publier un package npm open source en 2026 demande plus de rigueur qu'il y a cinq ans, mais les outils sont aussi bien meilleurs. La stack pnpm + TypeScript + tsup + Vitest + changesets couvre 95 % des cas d'usage, de la bibliothèque utilitaire au framework complet. L'investissement initial (2-3 heures pour la configuration) est remboursé dès la première release : plus de builds cassés, plus de publications accidentelles, plus de CHANGELOG à rédiger manuellement. Lancez-vous — l'écosystème open source a besoin de packages bien maintenus. Obtenir un devis gratuit si vous avez besoin d'aide pour publier ou migrer un package existant.