Docs

Playground

GitHub

DocsServidor

BunPackage: pacotes npm pelo .csproj

Editar esta página

3 min de leitura

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>

Todos eles são instalados (Desde 0.2.0-preview.62). Antes disso só o primeiro era: a instalação perguntava "já existe um node_modules?" de novo antes de cada pacote, e o primeiro bun add já o tinha criado.

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

Um link simbólico em todo sistema, feito pelo SDK pela chamada do próprio sistema e sem shell (Desde 0.2.0-preview.62). O Windows pede o Modo de Desenvolvedor ou elevação para criar um, como o mklink /D pedia. O que já está em node_modules fica: um link de um build anterior, ou uma pasta sua

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

ANTERIORAssets

PRÓXIMASegurança