eQuantic.UI permite declarar dependencias de paquetes npm directamente en los archivos .csproj, manteniendo la experiencia de desarrollo 100% .NET con cero package.json, cero npm y cero Node.js.

Arranque rápido

</ItemGroup>

Eso es todo. En dotnet build, el SDK automáticamente:

Genera un package.json temporal en obj/eQuantic/npm/

Instala los paquetes usando el runtime Bun embebido

Crea un symlink node_modules para que las herramientas resuelvan

Se salta la instalación en los builds incrementales

Cómo funciona

Pipeline de build

dotnet build

│

├── 1. ResolveBunPath ← Extrae el Bun embebido del paquete NuGet

│

├── 2. InstallBunPackages ← NUEVO: instala los items <BunPackage>

│ ├── Crea obj/eQuantic/npm/package.json

│ ├── Ejecuta: bun add <paquete>@<versión>

│ └── Enlaza: node_modules → obj/eQuantic/npm/node_modules/

│

├── 3. CompileEQuanticUI ← C# → TypeScript → JavaScript

│

├── 4. CopyEQuanticRuntime ← Copia runtime.js

│

Disposición de archivos

MiApp/

├── MiApp.csproj ← BunPackage se declara aquí

├── node_modules/ ← Symlink (en gitignore)

│ └── → obj/eQuantic/npm/node_modules/

├── obj/

│ └── eQuantic/

│ └── npm/ ← Oculto para quien programa

│ ├── package.json ← Autogenerado

│ ├── bun.lock ← Autogenerado

│ └── node_modules/ ← Los paquetes de verdad

└── src/

Quien programa nunca ve ni toca package.json. El symlink node_modules está en gitignore y se crea automáticamente.

Ejemplos de uso

Varios paquetes

Se admiten varios items BunPackage. Cada uno corre como un bun add aparte:

</ItemGroup>

Todos ellos se instalan (Desde 0.2.0-preview.62). Antes de eso solo el primero: la instalación preguntaba "¿hay ya un node_modules?" otra vez antes de cada paquete, y el primer bun add ya lo había creado.

Paquetes solo de CSS

Funciona igual de bien con paquetes solo de CSS importados vía @import:

</ItemGroup>

/* src/styles.css */

@import "tw-animate-css";

Detalles del target de MSBuild

El target InstallBunPackages vive en Sdk.targets:

<Target Name="InstallBunPackages"

AfterTargets="ResolveBunPath"

BeforeTargets="CompileEQuanticUI"

Condition="'@(BunPackage)' != '' And '$(BunPath)' != ''">

Comportamientos clave

Comportamiento

Detalles

Incremental

Se salta si obj/eQuantic/npm/node_modules/ ya existe

Build limpio

Ejecuta bun add por cada paquete en el primer build o después de dotnet clean

Multiplataforma

Un enlace simbólico en todos los sistemas, hecho por el SDK a través de la llamada propia del sistema y sin shell (Desde 0.2.0-preview.62). Windows pide el Modo de desarrollador o elevación para hacer uno, como hacía mklink /D. Lo que ya esté en node_modules se queda: un enlace de un build anterior, o una carpeta tuya

Aislamiento

Los paquetes viven en obj/, no en la raíz del proyecto

Sin contaminación

Ningún package.json, bun.lockb ni node_modules commiteado a git

Forzar la reinstalación

Para forzar una instalación fresca (por ejemplo, después de cambiar versiones):

# Opción 1: borrar la caché npm

rm -rf obj/eQuantic/npm

# Opción 2: limpieza completa

dotnet clean

dotnet build

Decisiones de diseño

¿Por qué no generar package.json en la raíz del proyecto?

•

Contamina el proyecto .NET con artefactos de npm

•

Quien programa podría commitearlo por accidente

•

Confunde a los IDEs, que lo tratan como un proyecto Node.js

•

Viola el principio del "100% .NET"

¿Por qué un symlink en lugar de NODE_PATH?

•

Los symlinks están soportados universalmente por las herramientas que resuelven node_modules

•

NODE_PATH tiene comportamiento inconsistente entre herramientas

•

El symlink es transparente: si una herramienta busca node_modules/, los encuentra

¿Por qué bun add en lugar de bun install?

•

bun add funciona con un package.json mínimo {"private": true}

•

El batching de items de MSBuild (%(BunPackage.Identity)) se mapea de forma natural a llamadas individuales de bun add

•

Cada paquete se instala con su versión exacta

¿Por qué no usar bun x --install?

•

bun x es para ejecutar herramientas de CLI, no para instalar bibliotecas

•

Los paquetes referenciados en CSS (@plugin, @import) tienen que existir en node_modules/

•

bun add es la semántica correcta para "instala esta biblioteca"

Comparación

Enfoque

¿Hace falta package.json?

¿Hacen falta npm/Node.js?

Experiencia de desarrollo

npm tradicional

Sí

Hay que gestionar dos ecosistemas

BunPackage

.NET puro, cero friction

Resolución de problemas

Los paquetes no se actualizan tras cambiar la versión

Causa: node_modules ya existe, así que InstallBunPackages se lo salta

Arreglo:

rm -rf obj/eQuantic/npm

dotnet build

Error de permisos del symlink en Windows

Causa: crear symlinks en Windows requiere permisos elevados o el Modo de desarrollador

Arreglo: activa el Modo de desarrollador en la Configuración de Windows, o ejecuta el terminal como Administrador

Documentación relacionada

•

Flujo de build: el orden completo de ejecución de los targets de MSBuild

•

Arquitectura de paquetes: diseño de paquetes autocontenidos

•

Gestión de assets: dependencias de assets de los componentes

PREVIOUSAssets

NEXTSeguridad