BunPackage es

BunPackage: paquetes npm vía .csproj

🌐 Esta página en: English · Português · Español · Français · Deutsch

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

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

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

1. Genera un package.json temporal en obj/eQuantic/npm/
2. Instala los paquetes usando el runtime Bun embebido
3. Crea un symlink node_modules para que las herramientas resuelvan
4. 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>
    <BunPackage Include="dayjs" Version="1.11.13" />
    <BunPackage Include="marked" Version="15.0.6" />
</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>
    <BunPackage Include="tw-animate-css" Version="1.2.5" />
</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í	Sí	Hay que gestionar dos ecosistemas
BunPackage	No	No	.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