O eQuantic.UI permite declarar dependências de pacotes npm diretamente nos arquivos .csproj, mantendo a experiência de desenvolvimento 100% .NET, com zero package.json, zero npm e zero Node.js.

Começo rápido

</ItemGroup>

É isso. No dotnet build, o SDK automaticamente:

Gera um package.json temporário em obj/eQuantic/npm/

Instala os pacotes usando o Bun embarcado

Cria um symlink node_modules para as ferramentas resolverem

Pula a instalação em builds incrementais

Como funciona

Pipeline de build

dotnet build

│

├── 1. ResolveBunPath ← Extrai o Bun embarcado do pacote NuGet

│

├── 2. InstallBunPackages ← NOVO: instala os itens <BunPackage>

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

│ ├── Roda: bun add <pacote>@<versão>

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

│

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

│

├── 4. CopyEQuanticRuntime ← Copia o runtime.js

│

Organização de arquivos

MyApp/

├── MyApp.csproj ← BunPackage declarado aqui

├── node_modules/ ← Symlink (no gitignore)

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

├── obj/

│ └── eQuantic/

│ └── npm/ ← Escondido do desenvolvedor

│ ├── package.json ← Gerado automaticamente

│ ├── bun.lock ← Gerado automaticamente

│ └── node_modules/ ← Os pacotes de verdade

└── src/

O desenvolvedor nunca vê nem toca no package.json. O symlink node_modules está no gitignore e é criado automaticamente.

Exemplos de uso

Vários pacotes

Vários itens BunPackage são suportados. Cada um roda como um bun add separado:

</ItemGroup>

Pacotes só de CSS

Funciona igualmente bem com pacotes só de CSS importados via @import:

</ItemGroup>

/* src/styles.css */

@import "tw-animate-css";

Detalhes do target MSBuild

O target InstallBunPackages vive no Sdk.targets:

<Target Name="InstallBunPackages"

AfterTargets="ResolveBunPath"

BeforeTargets="CompileEQuanticUI"

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

Comportamentos-chave

Comportamento

Detalhes

Incremental

Pula se obj/eQuantic/npm/node_modules/ já existir

Build limpo

Roda bun add para cada pacote no primeiro build ou depois de um dotnet clean

Multiplataforma

Symlink no macOS/Linux, mklink /D no Windows

Isolamento

Os pacotes vivem em obj/, não na raiz do projeto

Sem poluição

Nenhum package.json, bun.lockb ou node_modules comitado no git

Forçando reinstalação

Para forçar uma instalação nova (por exemplo, depois de trocar versões):

# Opção 1: apague o cache npm

rm -rf obj/eQuantic/npm

# Opção 2: limpeza completa

dotnet clean

dotnet build

Decisões de design

Por que não gerar o package.json na raiz do projeto?

•

Polui o projeto .NET com artefatos npm

•

O desenvolvedor pode comitá-lo sem querer

•

Confunde as IDEs, que passam a tratá-lo como um projeto Node.js

•

Viola o princípio do "100% .NET"

Por que symlink em vez de NODE_PATH?

•

Symlinks são universalmente suportados pelas ferramentas que resolvem node_modules

•

O NODE_PATH tem comportamento inconsistente entre ferramentas

•

O symlink é transparente: se uma ferramenta procura node_modules/, ela encontra

Por que bun add em vez de bun install?

•

O bun add funciona com um package.json mínimo {"private": true}

•

O batching de itens do MSBuild (%(BunPackage.Identity)) mapeia naturalmente para chamadas individuais de bun add

•

Cada pacote é instalado na versão exata dele

Por que não usar bun x --install?

•

O bun x serve para rodar ferramentas de linha de comando, não para instalar bibliotecas

•

Pacotes referenciados em CSS (@plugin, @import) precisam existir em node_modules/

•

O bun add é a semântica correta para "instale esta biblioteca"

Comparação

Abordagem

Precisa de package.json

Precisa de npm/Node.js

Experiência de desenvolvimento

npm tradicional

Sim

Precisa gerenciar dois ecossistemas

BunPackage

Não

.NET puro, zero atrito

Solução de problemas

Os pacotes não atualizam depois de mudar a versão

Causa: o node_modules já existe, então o InstallBunPackages pula

Correção:

rm -rf obj/eQuantic/npm

dotnet build

Erro de permissão de symlink no Windows

Causa: criar symlinks no Windows exige permissões elevadas ou o Modo de Desenvolvedor

Correção: ative o Modo de Desenvolvedor nas configurações do Windows, ou rode o terminal como Administrador

Documentação relacionada

•

Fluxo de build: a ordem completa de execução dos targets do MSBuild

•

Arquitetura de pacotes: o design de pacotes autocontidos

•

Gestão de assets: dependências de assets dos componentes

PREVIOUSBuildFlow-pt-BR

NEXTCapabilities-pt-BR