Publication

Ce document explique comment publier @lh-ui/vue3 sur le dépôt public npm, et comment l'héberger sur un serveur privé (deux approches : tarball en lien direct et métadonnées de registry).

La publication dispose d'une double voie, manuelle et CI : les commandes changeset sont exécutées localement, avec confirmation humaine du numéro de version et des notes de mise à jour avant l'envoi (voir « Flux de publication » ci-dessous) ; lors d'un push sur main avec des modifications dans .changeset/**, GitHub Actions exécute automatiquement version + publish (voir « Publication automatique avec GitHub Actions »).

Prérequis

1. Compte npm et propriété du scope

• Inscrivez-vous sur npm et activez la double authentification (2FA).

• Vérifiez que votre compte dispose des droits de publication sur le scope @lh-ui : les scopes sont attribués selon le principe du premier arrivé, et le compte ayant publié le premier paquet @lh-ui/* devient propriétaire du scope.

• Connexion locale :

  npm whoami          # Vérifier le compte actuellement connecté
  npm login           # Suivre les instructions pour vous connecter + 2FA si nécessaire

2. Vérifier que le registry pointe vers le dépôt public

Le fichier .npmrc à la racine du dépôt ne contient que shamefully-hoist = true, sans registry figé : c'est https://registry.npmjs.org/ qui est utilisé par défaut. Le publishConfig du package.json verrouille également le dépôt public :

"publishConfig": {
  "access": "public",
  "registry": "https://registry.npmjs.org/"
}

N'inscrivez pas d'adresse de registry privé dans le .npmrc à la racine du dépôt — cela redirigerait également les publications vers la source privée. Pour basculer temporairement de registry, utilisez le ~/.npmrc utilisateur hors projet ou un paramètre de ligne de commande.

3. Ce que contient une publication

La liste blanche files ne publie que les artéfacts de construction : es/ (ESM + types + styles des composants), lib/ (CJS), dist/ (UMD + styles complets). Le code source, la documentation, les tests et les scripts sont exclus via .npmignore. Lors de la commande de publication, prepublishOnly lance automatiquement un pnpm build au préalable : inutile de construire manuellement.

Flux de publication

Étape 1 : rédiger un changeset

Toute modification visible par l'utilisateur devrait avoir son changeset. Si la modification en cours en a déjà un, passez à l'étape 2.

pnpm changeset

Suivez les invites interactives pour choisir @lh-ui/vue3, le type de bump (major / minor / patch) et la description des changements.

Remarque : les changesets de ce dépôt sont cumulatifs. Des dizaines de changesets non consommés s'accumulent actuellement dans .changeset/, et l'étape 2 (changeset version) les consommera tous en une seule fois, fusionnés en une seule version. Si vous souhaitez publier par lots, il faudra d'abord contrôler le rythme via des branches git ou en déplaçant manuellement une partie des fichiers changeset.

Étape 2 : incrémenter le numéro de version et générer le CHANGELOG

pnpm changeset:version

Cette commande :

• calcule le nouveau numéro de version en fonction du niveau de bump le plus élevé parmi les changesets et l'inscrit dans package.json
• agrège tous les changesets pour générer CHANGELOG.md
• supprime les .changeset/*.md consommés (commit: false dans config.json, aucune validation automatique)

Après exécution, vérifiez manuellement :

git status              # Confirmer que les changesets ont été consommés et le CHANGELOG généré
git diff package.json   # Confirmer que le numéro de version est conforme aux attentes

Étape 3 : publier

pnpm changeset:publish

Elle exécute en interne pnpm publish, selon le flux suivant :

1. Déclenche prepublishOnly → pnpm build (construction complète ESM / CJS / UMD / types / styles)
2. Emballe selon publishConfig et envoie vers le dépôt public npm
3. Génère et pousse le tag git (au format @lh-ui/vue3@<version>)

Comme publishConfig.access vaut public, le paquet scoped sera également visible publiquement, sans nécessiter de --access public supplémentaire.

Étape 4 : pousser (à exécuter par vous)

git push --follow-tags

Vérification avant publication

Avant la publication effective, jetez un œil au contenu réellement empaqueté avec un dry-run :

npm pack --dry-run

Vérifiez dans la sortie que :

• seuls les trois répertoires es/, lib/, dist/ sont inclus
• src/, packages/, docs/, tests/, scripts/, ai/ n'y figurent pas
• la taille est raisonnable (environ 600 Ko pour le paquet UMD complet, 700 Ko pour les styles complets, valeurs attendues)

Vérification après publication

# 1. La nouvelle version est visible sur npm
npm view @lh-ui/vue3
npm view @lh-ui/vue3 versions

# 2. Créer un projet sandbox pour tester les trois formats de module
pnpm create vite verify-pkg --template vue-ts
cd verify-pkg && pnpm add @lh-ui/vue3

Dans le projet sandbox, vérifiez un par un :

Élément vérifié	Écriture
Import complet (ESM)	import LhUiPlus from '@lh-ui/vue3' + import '@lh-ui/vue3/dist/index.css'
Import à la demande d'un composant	import { LhButton } from '@lh-ui/vue3'
Import à la demande des styles (sass requis)	import '@lh-ui/vue3/style/button'
Import à la demande des styles (sans sass)	import '@lh-ui/vue3/style-css/button'
Outils de thème	import { getThemeVars } from '@lh-ui/vue3/theme'
CDN (à rafraîchir après quelques minutes)	https://unpkg.com/@lh-ui/vue3

Hébergement sur un serveur privé (tarball statique)

Le dépôt public npm est le canal de publication principal ; si vous avez besoin d'un miroir auto-hébergé (usage en intranet, npm bloqué, ou désir de verrouiller une version spécifique), placer le tarball sur votre propre serveur est la solution la plus légère, sans nécessiter de registry npm privé.

1. Empaqueter le tarball

pnpm build
npm pack

Le fichier généré s'appelle lh-ui-vue3-<version>.tgz — npm convertit @lh-ui/ du scope en lh-ui-vue3- (les barres obliques deviennent des tirets). npm pack --dry-run permet également de vérifier à l'avance.

2. Transférer sur le serveur

En suivant la convention des répertoires du site nginx existant (le site de documentation est déployé dans /home/webuser/nginx/lh-ui/vue3/), créez-y un répertoire packages/ et stockez les versions dans des sous-répertoires :

/home/webuser/nginx/lh-ui/vue3/
├── index.html              # Site de documentation
└── packages/
    ├── 1.0.0/
    │   └── lh-ui-vue3-1.0.0.tgz
    ├── 1.1.0/
    │   └── lh-ui-vue3-1.1.0.tgz
    └── latest              # Lien symbolique pointant vers la version recommandée
        └── lh-ui-vue3-1.1.0.tgz

URL correspondante :

https://www.lhgb.top/lhui/vue3/packages/1.0.0/lh-ui-vue3-1.0.0.tgz

packages/ est un répertoire de fichiers statiques : la configuration nginx du site existant est réutilisée, sans nouvelle location à déclarer :

# La location existante du site de documentation couvre déjà le préfixe /lhui/vue3/,
# packages/ y est accessible automatiquement comme sous-répertoire ; il suffit de
# s'assurer que le Content-Type des .tgz permet le téléchargement
# (octet-stream par défaut dans nginx convient)
location /lhui/vue3/ {
    alias /home/webuser/nginx/lh-ui/vue3/;
    autoindex off;
}

3. Installer depuis le serveur privé

Trois écritures équivalentes, au choix :

# pnpm
pnpm add https://www.lhgb.top/lhui/vue3/packages/1.0.0/lh-ui-vue3-1.0.0.tgz

# npm
npm install https://www.lhgb.top/lhui/vue3/packages/1.0.0/lh-ui-vue3-1.0.0.tgz

# yarn
yarn add https://www.lhgb.top/lhui/vue3/packages/1.0.0/lh-ui-vue3-1.0.0.tgz

Ou inscrivez-le directement dans package.json :

{
  "dependencies": {
    "@lh-ui/vue3": "https://www.lhgb.top/lhui/vue3/packages/1.0.0/lh-ui-vue3-1.0.0.tgz"
  }
}

4. Points d'attention

• Contournement de la résolution des dépendances du registry : l'installation par tarball n'interroge pas le registry, les dépendances proviennent directement des déclarations du tarball. Ce paquet n'a aucune dependencies d'exécution, uniquement peerDependencies.vue : un projet ayant Vue 3 d'installé peut donc l'installer et l'exécuter.
• Aucune métadonnée de version : npm update est sans effet sur une dépendance tarball, toute mise à niveau passe par le remplacement manuel de l'URL (ou la modification du lien symbolique latest suivie d'une réinstallation). Approche adaptée à un miroir de version verrouillée, pas aux mises à jour fréquentes.
• Le protocol https est obligatoire : pnpm / npm / yarn refusent par défaut les URL tarball en http.
• pnpm-lock.yaml contiendra l'URL complète + le hash d'intégrité : lors de la collaboration en équipe, le fichier de verrouillage reproduit correctement l'installation, sans accès npm nécessaire.

Hébergement sur un serveur privé (métadonnées registry)

Le lien direct vers le tarball décrit ci-dessus fonctionne, mais npm update est sans effet et le lockfile contient une longue URL. Si vous préférez que le projet consommateur installe pnpm add @lhgb/vue3 comme un paquet ordinaire, avec résolution des versions et dist-tags, vous pouvez faire générer au répertoire statique Nginx des métadonnées supplémentaires de registry npm, jouant le rôle de registry en lecture seule. Les deux approches peuvent coexister.

1. Empaquetage

pnpm build
node scripts/pack-private.mjs

Ce script : renomme les artéfacts de construction en @lhgb/vue3 (seuls name / publishConfig diffèrent), produit le tarball avec npm pack, calcule integrity (sha512) et shasum (sha1), assemble les métadonnées JSON du registry et les écrit dans private-registry/ :

private-registry/
├── @lhgb/vue3              # Métadonnées JSON (sans extension)
└── tarballs/@lhgb/vue3/
    └── lhgb-vue3-1.0.0.tgz

Paramètres usuels :

• --dry-run : se contente d'afficher la liste des fichiers qui seraient générés ainsi que les métadonnées, sans écrire sur le disque ; permet la vérification avant publication
• --incremental : lit les métadonnées existantes et fusionne la nouvelle version, afin de ne pas écraser les versions historiques

2. Déployer sur le serveur

Transférez le contenu de private-registry/ dans un répertoire du serveur, en appliquant la location du modèle scripts/nginx-private-registry.conf.example (même serveur Nginx que le site de documentation /lhui/vue3/, location indépendante) :

/home/webuser/nginx/registry/
├── @lhgb/vue3
└── tarballs/@lhgb/vue3/
    └── lhgb-vue3-1.0.0.tgz

Le point clé de la configuration Nginx est default_type application/json — les fichiers de métadonnées n'ont pas d'extension, et si le type n'est pas explicitement déclaré, les clients les analyseront comme du texte brut et échoueront. La configuration complète se trouve dans scripts/nginx-private-registry.conf.example (les .tgz doivent obligatoirement se trouver dans une location regex séparée au premier niveau, et non imbriquée dans ^~ /lhgb/, sous peine que la correspondance de préfixe ne saute la regex) :

location ^~ /lhgb/ {
  alias /home/webuser/nginx/registry/;
  default_type application/json;
  autoindex off;
  expires 5m;
}

location ~ ^/lhgb/(.+\.tgz)$ {
  alias /home/webuser/nginx/registry/$1;
  default_type application/octet-stream;
  expires 1y;
  add_header Cache-Control "public, immutable" always;
}

3. Installer depuis le registry privé

Ajoutez une ligne au .npmrc du projet ou de l'utilisateur :

@lhgb:registry=https://www.lhgb.top/lhgb

Identique pour les trois gestionnaires de paquets :

pnpm add @lhgb/vue3
# ou
npm install @lhgb/vue3
# ou
yarn add @lhgb/vue3

4. Relation avec le paquet public

@lhgb/vue3 et @lh-ui/vue3 sont issus de la même source et de la même version, leurs artéfacts de construction sont identiques, seuls name et registry diffèrent : ils sont interchangeables.

• Contextes intranet / npm bloqué / nécessité de verrouiller la source de publication : @lhgb/vue3
• Contextes ouverts au public et souhaitant être servis par les CDN unpkg / jsdelivr : @lh-ui/vue3

5. Points d'attention

• Mettre à jour les métadonnées de manière incrémentale : après chaque publication, fusionnez la nouvelle version avec --incremental ; un écrasement direct ferait perdre les métadonnées des versions historiques, dont l'installation deviendrait impossible.
• Les tarballs ne peuvent pas être déplacés : l'URL tarball dans les métadonnées est un chemin absolu, l'emplacement du fichier et l'URL doivent correspondre un à un.
• Le protocol https est tout aussi obligatoire : pnpm / npm / yarn refusent par défaut les adresses http.
• N'inscrivez pas le registry @lhgb dans le .npmrc à la racine du dépôt : le .npmrc racine ne conserve que shamefully-hoist = true, et l'adresse du registry privé va dans le ~/.npmrc utilisateur, afin de ne pas polluer la chaîne de publication.

Publication automatique avec GitHub Actions

En complément du flux manuel, .github/workflows/release.yml fournit un canal de publication automatique :

• Conditions de déclenchement : un push sur main avec des modifications dans .changeset/** ou package.json ; ou un déclenchement manuel depuis la page Actions du dépôt (workflow_dispatch).
• Comportement : exécute pnpm build + pnpm verify:dts puis le version + publish de changesets/action ; en l'absence de changeset en attente de publication, elle ne fait rien, son rattachement au push est donc sans risque.
• Secret requis : configurez NPM_TOKEN dans Settings → Secrets and variables → Actions du dépôt — un jeton d'accès granulaire doit être généré sur npm, avec les droits de publication sur l'organisation @lh-ui.

Les voies manuelle et automatique peuvent coexister : pnpm changeset:publish en local convient lorsque chaque publication nécessite une confirmation humaine ; la CI convient quand les changesets s'accumulent pour être publiés en rouleau de façon automatique.

Retour en arrière

# Marquer une version comme obsolète (recommandé, sans incidence sur les utilisateurs ayant déjà installé)
npm deprecate @lh-ui/vue3@1.0.0 "Cette version présente un problème xx, veuillez passer à la 1.0.1"

# Retirer complètement : possible uniquement dans les 72 heures suivant la publication,
# et si aucun autre paquet n'en dépend
npm unpublish @lh-ui/vue3@1.0.0

Le cache des CDN (unpkg / jsdelivr) s'invalide en quelques heures à une journée ; après un retour en arrière, un projet sandbox permet de vérifier, via une URL avec numéro de version, que l'ancienne version reste installable.