BunPackage fr

BunPackage : des paquets npm via .csproj

🌐 Cette page en : English · Português · Español · Français · Deutsch

eQuantic.UI permet de déclarer des dépendances de paquets npm directement dans les fichiers .csproj, en gardant l'expérience de développement 100% .NET avec zéro package.json, zéro npm et zéro Node.js.

Démarrage rapide

<!-- MonApp.csproj -->
<ItemGroup>
    <BunPackage Include="dayjs" Version="1.11.13" />
</ItemGroup>

C'est tout. Au dotnet build, le SDK fait automatiquement :

1. Génère un package.json temporaire dans obj/eQuantic/npm/
2. Installe les paquets avec le runtime Bun embarqué
3. Crée un lien symbolique node_modules pour que les outils résolvent
4. Saute l'installation lors des builds incrémentaux

Comment cela marche

Pipeline de build

dotnet build
    │
    ├── 1. ResolveBunPath          ← Extrait le Bun embarqué du paquet NuGet
    │
    ├── 2. InstallBunPackages      ← NOUVEAU : installe les items <BunPackage>
    │       ├── Crée obj/eQuantic/npm/package.json
    │       ├── Lance : bun add <paquet>@<version>
    │       └── Lie : node_modules → obj/eQuantic/npm/node_modules/
    │
    ├── 3. CompileEQuanticUI       ← C# → TypeScript → JavaScript
    │
    ├── 4. CopyEQuanticRuntime     ← Copie runtime.js
    │

Disposition des fichiers

MonApp/
├── MonApp.csproj                   ← BunPackage est déclaré ici
├── node_modules/                   ← Lien symbolique (dans le gitignore)
│   └── → obj/eQuantic/npm/node_modules/
├── obj/
│   └── eQuantic/
│       └── npm/                    ← Caché de qui développe
│           ├── package.json        ← Généré automatiquement
│           ├── bun.lock            ← Généré automatiquement
│           └── node_modules/       ← Les vrais paquets
└── src/

Qui développe ne voit ni ne touche jamais package.json. Le lien node_modules est dans le gitignore et créé automatiquement.

Exemples d'usage

Plusieurs paquets

Plusieurs items BunPackage sont pris en charge. Chacun tourne comme un bun add à part :

<ItemGroup>
    <BunPackage Include="dayjs" Version="1.11.13" />
    <BunPackage Include="marked" Version="15.0.6" />
</ItemGroup>

Chacun d'eux est installé (Depuis 0.2.0-preview.62). Avant cela, seul le premier l'était : l'installation demandait "y a-t-il déjà un node_modules ?" à nouveau avant chaque paquet, et le premier bun add l'avait créé.

Paquets uniquement CSS

Cela marche tout aussi bien avec des paquets uniquement CSS importés via @import :

<ItemGroup>
    <BunPackage Include="tw-animate-css" Version="1.2.5" />
</ItemGroup>

/* src/styles.css */
@import "tw-animate-css";

Détails de la cible MSBuild

La cible InstallBunPackages vit dans Sdk.targets :

<Target Name="InstallBunPackages"
    AfterTargets="ResolveBunPath"
    BeforeTargets="CompileEQuanticUI"
    Condition="'@(BunPackage)' != '' And '$(BunPath)' != ''">

Comportements clés

Comportement	Détails
Incrémental	Saute si obj/eQuantic/npm/node_modules/ existe déjà
Build propre	Lance bun add pour chaque paquet au premier build ou après dotnet clean
Multiplateforme	Un lien symbolique sur chaque système, fait par le SDK via l'appel propre au système et sans shell (Depuis 0.2.0-preview.62). Windows demande le Mode développeur ou une élévation pour en faire un, comme le faisait mklink /D. Ce qui est déjà à node_modules reste : un lien d'un build antérieur, ou un dossier à vous
Isolation	Les paquets vivent dans obj/, pas à la racine du projet
Aucune pollution	Aucun package.json, bun.lockb ni node_modules commité dans git

Forcer la réinstallation

Pour forcer une installation fraîche (par exemple après un changement de versions) :

# Option 1 : supprimer le cache npm
rm -rf obj/eQuantic/npm

# Option 2 : nettoyage complet
dotnet clean
dotnet build

Décisions de conception

Pourquoi ne pas générer package.json à la racine du projet ?

• Cela pollue le projet .NET avec des artefacts npm
• Qui développe pourrait le commiter par accident
• Cela trouble les IDE, qui le traitent comme un projet Node.js
• Cela viole le principe du "100% .NET"

Pourquoi un lien symbolique plutôt que NODE_PATH ?

• Les liens symboliques sont universellement pris en charge par les outils qui résolvent node_modules
• NODE_PATH a un comportement incohérent d'un outil à l'autre
• Le lien est transparent : si un outil cherche node_modules/, il les trouve

Pourquoi bun add plutôt que bun install ?

• bun add marche avec un package.json minimal {"private": true}
• Le batching d'items de MSBuild (%(BunPackage.Identity)) se mappe naturellement sur des appels individuels de bun add
• Chaque paquet est installé avec sa version exacte

Pourquoi ne pas utiliser bun x --install ?

• bun x sert à lancer des outils CLI, pas à installer des bibliothèques
• Les paquets référencés dans du CSS (@plugin, @import) doivent exister dans node_modules/
• bun add est la sémantique correcte pour "installe cette bibliothèque"

Comparaison

Approche	package.json nécessaire	npm/Node.js nécessaires	Expérience de développement
npm traditionnel	Oui	Oui	Il faut gérer deux écosystèmes
BunPackage	Non	Non	Du .NET pur, zéro friction

Dépannage

Les paquets ne se mettent pas à jour après un changement de version

Cause : node_modules existe déjà, donc InstallBunPackages saute

Correctif :

rm -rf obj/eQuantic/npm
dotnet build

Erreur de permission du lien symbolique sur Windows

Cause : créer des liens symboliques sur Windows demande des permissions élevées ou le Mode développeur

Correctif : activez le Mode développeur dans les Paramètres de Windows, ou lancez le terminal en tant qu'administrateur

Documentation associée

• Flux de build : l'ordre complet d'exécution des cibles MSBuild
• Architecture des paquets : conception de paquets autonomes
• Gestion des assets : les dépendances d'assets des composants