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

</ItemGroup>

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

Erzeugt eine temporäre package.json in obj/eQuantic/npm/

Installiert die Pakete mit der eingebetteten Bun-Runtime

Erzeugt einen node_modules-Symlink, damit Werkzeuge auflösen

Ü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>

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>

/* 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

Zwei Ökosysteme zu verwalten

BunPackage

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

PREVIOUSAssets

NEXTSicherheit