BunPackage pt BR

BunPackage: pacotes npm pelo .csproj

🌐 Esta página em: English · Português

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

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

É isso. No dotnet build, o SDK automaticamente:

1. Gera um package.json temporário em obj/eQuantic/npm/
2. Instala os pacotes usando o Bun embarcado
3. Cria um symlink node_modules para as ferramentas resolverem
4. 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>
    <BunPackage Include="dayjs" Version="1.11.13" />
    <BunPackage Include="marked" Version="15.0.6" />
</ItemGroup>

Pacotes só de CSS

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

<ItemGroup>
    <BunPackage Include="tw-animate-css" Version="1.2.5" />
</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	Sim	Precisa gerenciar dois ecossistemas
BunPackage	Não	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