BunPackage de

BunPackage: npm-Pakete über die .csproj

🌐 Diese Seite auf: English · Português · Español · Français · Deutsch

eQuantic.UI erlaubt es, Abhängigkeiten auf npm-Pakete direkt in .csproj-Dateien zu deklarieren, und hält die Entwicklungserfahrung damit 100% .NET, mit null package.json, null npm und null Node.js.

Schnellstart

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

Das ist alles. Bei dotnet build tut das SDK automatisch:

1. Erzeugt eine temporäre package.json in obj/eQuantic/npm/
2. Installiert die Pakete mit der eingebetteten Bun-Runtime
3. Erzeugt einen node_modules-Symlink, damit Werkzeuge auflösen
4. Überspringt die Installation bei inkrementellen Builds

Wie es funktioniert

Build-Pipeline

dotnet build
    │
    ├── 1. ResolveBunPath          ← Entpackt das eingebettete Bun aus dem NuGet-Paket
    │
    ├── 2. InstallBunPackages      ← NEU: installiert die <BunPackage>-Items
    │       ├── Erzeugt obj/eQuantic/npm/package.json
    │       ├── Führt aus: bun add <Paket>@<Version>
    │       └── Verlinkt: node_modules → obj/eQuantic/npm/node_modules/
    │
    ├── 3. CompileEQuanticUI       ← C# → TypeScript → JavaScript
    │
    ├── 4. CopyEQuanticRuntime     ← Kopiert runtime.js
    │

Dateiaufbau

MeineApp/
├── MeineApp.csproj                 ← BunPackage wird hier deklariert
├── node_modules/                   ← Symlink (im gitignore)
│   └── → obj/eQuantic/npm/node_modules/
├── obj/
│   └── eQuantic/
│       └── npm/                    ← Vor der Entwicklerin verborgen
│           ├── package.json        ← Automatisch erzeugt
│           ├── bun.lock            ← Automatisch erzeugt
│           └── node_modules/       ← Die echten Pakete
└── src/

Wer entwickelt, sieht und berührt die package.json nie. Der node_modules-Symlink ist im gitignore und wird automatisch erzeugt.

Nutzungsbeispiele

Mehrere Pakete

Mehrere BunPackage-Items werden unterstützt. Jedes läuft als eigenes bun add:

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

Jedes einzelne wird installiert (Seit 0.2.0-preview.62). Davor nur das erste: Die Installation fragte vor jedem Paket erneut "gibt es schon ein node_modules?", und das erste bun add hatte es gemacht.

Pakete mit nur CSS

Es funktioniert genauso gut mit Paketen, die nur CSS enthalten und über @import eingebunden werden:

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

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

Details des MSBuild-Targets

Das Target InstallBunPackages lebt in Sdk.targets:

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

Wichtige Verhaltensweisen

Verhalten	Details
Inkrementell	Überspringt, wenn obj/eQuantic/npm/node_modules/ schon existiert
Sauberer Build	Führt beim ersten Build oder nach dotnet clean je Paket ein bun add aus
Plattformübergreifend	Ein symbolischer Link auf jedem System, vom SDK über den eigenen Aufruf des Systems und ohne Shell gemacht (Seit 0.2.0-preview.62). Windows verlangt den Entwicklermodus oder eine Erhöhung, um einen zu machen, wie mklink /D es tat. Was schon unter node_modules liegt, bleibt: ein Link eines früheren Builds, oder ein eigener Ordner
Isolation	Die Pakete leben in obj/, nicht in der Projektwurzel
Keine Verschmutzung	Keine package.json, keine bun.lockb, kein node_modules im git

Neuinstallation erzwingen

Um eine frische Installation zu erzwingen (zum Beispiel nach einem Versionswechsel):

# Variante 1: den npm-Cache löschen
rm -rf obj/eQuantic/npm

# Variante 2: vollständig aufräumen
dotnet clean
dotnet build

Entwurfsentscheidungen

Warum die package.json nicht in der Projektwurzel erzeugen?

• Es verschmutzt das .NET-Projekt mit npm-Artefakten
• Wer entwickelt, könnte sie versehentlich commiten
• Es verwirrt IDEs, die es als Node.js-Projekt behandeln
• Es verletzt das Prinzip "100% .NET"

Warum ein Symlink statt NODE_PATH?

• Symlinks werden von den Werkzeugen, die node_modules auflösen, allgemein unterstützt
• NODE_PATH verhält sich von Werkzeug zu Werkzeug unterschiedlich
• Der Symlink ist durchsichtig: Sucht ein Werkzeug nach node_modules/, findet es sie

Warum bun add statt bun install?

• bun add funktioniert mit einer minimalen {"private": true}-package.json
• Das Item-Batching von MSBuild (%(BunPackage.Identity)) bildet sich natürlich auf einzelne bun add-Aufrufe ab
• Jedes Paket wird mit seiner exakten Version installiert

Warum nicht bun x --install nutzen?

• bun x dient dem Ausführen von CLI-Werkzeugen, nicht dem Installieren von Bibliotheken
• Pakete, die in CSS referenziert werden (@plugin, @import), müssen in node_modules/ existieren
• bun add ist die richtige Semantik für "installiere diese Bibliothek"

Vergleich

Ansatz	package.json nötig	npm/Node.js nötig	Entwicklungserfahrung
Herkömmliches npm	Ja	Ja	Zwei Ökosysteme zu verwalten
BunPackage	Nein	Nein	Reines .NET, null Reibung

Fehlersuche

Pakete aktualisieren sich nach einem Versionswechsel nicht

Ursache: node_modules existiert schon, also überspringt InstallBunPackages

Behebung:

rm -rf obj/eQuantic/npm
dotnet build

Symlink-Berechtigungsfehler unter Windows

Ursache: Symlinks unter Windows zu erzeugen verlangt erhöhte Rechte oder den Entwicklermodus

Behebung: Schalten Sie den Entwicklermodus in den Windows-Einstellungen ein, oder starten Sie das Terminal als Administrator

Verwandte Dokumentation

• Build-Ablauf: die vollständige Ausführungsreihenfolge der MSBuild-Targets
• Paketarchitektur: Entwurf eigenständiger Pakete
• Asset-Verwaltung: die Asset-Abhängigkeiten der Komponenten