O eQuantic.UI oferece ferramentas de depuração profissionais parecidas com as do Next.js, com recursos exclusivos de desenvolvimento que ajudam a identificar e corrigir problemas rapidamente.

🔍 Detecção do modo de desenvolvimento

O framework detecta o ambiente automaticamente usando o IWebHostEnvironment.IsDevelopment() e o expõe ao browser por:

window.__EQ_DEV__; // true em desenvolvimento, false em produção

Todas as ferramentas de desenvolvimento são carregadas condicionalmente com base nessa flag.

📝 Sistema de logging

O logger fornece logs consistentes e com prefixo, que só saem em modo de desenvolvimento.

Uso

import { logger } from "@equantic/ui-runtime";

// Só em desenvolvimento (silenciado em produção)

logger.debug("Component state:", state);

logger.info("API call completed");

// Sempre loga (mesmo em produção)

logger.warn("Deprecated API used");

logger.error("Failed to load data:", error);

Níveis de log

Método

Saída

Produção

Prefixo

debug()

Console debug

❌ Silenciado

[eQuantic.UI]

info()

Console info

❌ Silenciado

[eQuantic.UI]

warn()

Console warn

✅ Sempre

[eQuantic.UI]

error()

Console error

✅ Sempre

[eQuantic.UI]

Filtrando os logs

No DevTools do browser, você pode filtrar pelo prefixo:

[eQuantic.UI]

Implementação

O logger está implementado em src/eQuantic.UI.Runtime/src/utils/logger.ts:

const isDev = typeof window !== "undefined" && window.__EQ_DEV__;

export const logger = {

debug(...args: any[]) {

if (isDev) console.debug("[eQuantic.UI]", ...args);

info(...args: any[]) {

if (isDev) console.info("[eQuantic.UI]", ...args);

warn(...args: any[]) {

console.warn("[eQuantic.UI]", ...args);

error(...args: any[]) {

console.error("[eQuantic.UI]", ...args);

};

🚨 Overlay de erro

O overlay de erro fornece uma interface de erro em tela cheia, no estilo do Next.js, que aparece automaticamente quando ocorrem erros em tempo de execução.

Recursos

•

Captura automática: pega erros não tratados e rejeições de promise

•

Stack traces em C# ✨: o overlay é ciente de source map: ele busca o .js.map de cada bundle, decodifica (src/dev/source-map.ts + src/dev/stack-remapper.ts), e reescreve a pilha de chamadas como os frames C# originais, mais um trecho da linha do código C# que falhou. Cai para a visão em JS se não houver mapa disponível. (É isso que torna real a promessa de "0 conhecimento de JS" na hora de depurar: quem desenvolve em C# vê C#, não JavaScript transpilado.)

•

Suporte a teclado: aperte Esc para fechar

•

Só em desenvolvimento: nunca aparece em produção (carregado por um import() dinâmico em dev)

•

UX limpa: cabeçalho vermelho, fonte monoespaçada, conteúdo rolável

Quando ele aparece

O overlay de erro aparece automaticamente para:

Erros não tratados: qualquer exceção não capturada no JavaScript

Rejeições de promise: erros assíncronos não tratados

// Isto dispara o overlay de erro em modo de desenvolvimento

throw new Error("Something went wrong");

Promise.reject("Async error");

await fetch("/api/data"); // Se o fetch falhar e não for capturado

A interface do overlay de erro

┌─────────────────────────────────────────────┐

│ ⚠️ Build Error Close (Esc)│

├─────────────────────────────────────────────┤

│ │

│ Mensagem de erro aqui │

│ │

│ ┌─────────────────────────────────────────┐ │

│ │ Stack trace: │ │

│ │ at MyComponent.render (page.js:42) │ │

│ │ at Reconciler.patch (reconciler.js:12)│ │

│ │ ... │ │

│ └─────────────────────────────────────────┘ │

│ │

├─────────────────────────────────────────────┤

│ Este overlay de erro só aparece em │

│ desenvolvimento. Corrija o erro para seguir.│

└─────────────────────────────────────────────┘

Mostrando erros manualmente

Você pode mostrar erros no overlay manualmente:

import { errorOverlay } from "@equantic/ui-runtime/dev";

if (window.__EQ_DEV__) {

errorOverlay.show({

message: "Custom error message",

stack: error.stack,

componentStack: "Component hierarchy...",

});

}

Limpando o overlay

// Limpeza programática

errorOverlay.clear();

// Ações do usuário

// - Apertar a tecla Esc

// - Clicar no botão "Close"

Implementação

O overlay de erro está implementado em src/eQuantic.UI.Runtime/src/dev/error-overlay.ts:

class ErrorOverlay {

private overlay: HTMLDivElement | null = null;

private errors: ErrorInfo[] = [];

show(error: ErrorInfo) {

if (!window.__EQ_DEV__) return; // Só em dev

this.errors.push(error);

this.render();

}

clear() {

this.errors = [];

if (this.overlay) {

this.overlay.remove();

this.overlay = null;

}

private render() {

// Cria o overlay de tela cheia com os detalhes do erro

}

export const errorOverlay = new ErrorOverlay();

// Captura automática de erros

if (window.__EQ_DEV__) {

window.addEventListener("error", (event) => {

errorOverlay.show({

message: event.message,

stack: event.error?.stack,

});

window.addEventListener("unhandledrejection", (event) => {

errorOverlay.show({

message: `Unhandled Promise Rejection: ${event.reason}`,

stack: event.reason?.stack,

});

}

🛠️ Depurando componentes

DevTools do browser

O eQuantic.UI gera source maps para depurar código C# no browser.

Chrome DevTools:

Abra o DevTools (F12)

Vá para a aba Sources

Encontre webpack:// ou os caminhos de arquivo na árvore

Ponha breakpoints direto no código TypeScript/C#

Inspecione estado, props e variáveis locais

Source maps

O compilador gera source maps V3 que mapeiam o JavaScript de volta ao código C# original:

{

"version": 3,

"sources": ["Page.cs"],

"mappings": "AAAA;AACA;...",

"names": ["MyComponent", "Render", "state"]

}

Isso permite:

•

Pôr breakpoints em código C#

•

Percorrer a lógica C# passo a passo

•

Inspecionar os nomes de variáveis do C#

•

Ver os números de linha originais nos stack traces

Inspeção de componentes

Para inspecionar o estado e as props de um componente:

// No console do browser

window.__EQ_DEBUG = true; // Liga o modo de depuração

// Os componentes expõem o estado deles

const component = document.querySelector(

'[data-component-id="abc"]',

).__component;

console.log(component.state);

console.log(component.props);

🧪 Testes e depuração

Testes de integração com o Playwright

Para depurar problemas de renderização entre SSR e CSR:

test("SSR matches CSR", async ({ page }) => {

// Pega o HTML do SSR

const ssrResponse = await page.goto("http://localhost:5000");

const ssrHtml = await ssrResponse.text();

// Espera a hidratação do CSR

await page.waitForLoadState("networkidle");

const csrHtml = await page.content();

// Compara

expect(normalizeHtml(ssrHtml)).toBe(normalizeHtml(csrHtml));

});

Depuração no servidor

Depure o código C# normalmente com o Visual Studio ou o VS Code:

Ponha breakpoints nos arquivos .cs

Rode com o depurador anexado: dotnet run

Os breakpoints são atingidos durante:

•

A renderização no servidor (SSR)

•

As invocações de Server Action

•

A compilação dos componentes

Depuração de rede

Monitore os Server Actions no DevTools do browser:

Abra a aba Network

Filtre por _equantic/actions

Inspecione:

•

A carga da requisição (nome do método, argumentos)

•

Os dados da resposta

•

As informações de tempo

•

Os erros (com stack traces)

Depuração de provedores de asset

Ao usar IRequireAssets, verifique se as dependências estão sendo injetadas corretamente:

Inspecione a fonte: abra o "Ver código-fonte da página" no browser e procure pelas tags de script/estilo.

Aba Network: confira se as URLs externas (por exemplo, CDNs) estão carregando com sucesso (Status 200).

Deduplicação: verifique se vários componentes não injetaram o mesmo script duas vezes.

Ordem: as folhas de estilo devem aparecer antes dos scripts para a renderização correta.

Assets na renderização no servidor (SSR)

Se os assets estiverem faltando no HTML inicial:

Verifique se o componente implementa IRequireAssets.

Garanta que o AddUI() é chamado no Program.cs.

Confira se a AssetCollection está reunindo os assets corretamente durante a passada de render.

📊 Depuração de performance

Performance em tempo de execução

O reconciliador rastreia métricas de performance em modo de desenvolvimento:

// Liga o rastreamento de performance

window.__EQ_PERF = true;

// Veja as métricas

console.table(window.__EQ_PERF_DATA);

As métricas incluem:

•

Tempo de render: quanto cada componente levou para renderizar

•

Tempo de diff: tempo gasto no reconciliador

•

Operações de DOM: número de mudanças reais no DOM

•

Listeners de evento: contagem de listeners ativos

Performance de build

Monitore os tempos de compilação:

dotnet build -v:detailed

Procure por:

•

A duração do target CompileEQuanticUI

•

O número de componentes compilados

•

O tempo de geração do TypeScript

•

O tempo de empacotamento do Bun

🔧 Problemas comuns

O runtime.js não carrega

Sintoma: o boot() nunca executa, GET /_equantic/runtime.js devolve 404

Solução: garanta que o pacote do SDK inclui o runtime.js e que o target CopyEQuanticRuntime executa

# Confira se o runtime existe no pacote do SDK

unzip -l ~/.nuget/packages/equantic.ui.sdk/0.1.1/equantic.ui.sdk.0.1.1.nupkg | grep runtime

# Force a reconstrução

dotnet clean

dotnet build -v:n # Procure pela mensagem "Copying runtime.js"

Tokens de tema faltando no CSR

Sintoma: o HTML renderizado no servidor está tematizado, mas a renderização no cliente não

Causa raiz: o blob da ponte de tema não foi adotado no boot

Solução:

Verifique se o runtime.js carrega antes dos scripts dos componentes

Procure no console do browser por [eQuantic.UI] Boot process started

Inspecione window.__EQ_THEME__ no console - deve conter o tema serializado

Source maps não funcionam

Sintoma: não dá para depurar o código C# original no DevTools do browser

Solução:

Garanta sourcemap: true no vite.config.ts

Confira se os arquivos .map existem em wwwroot/_equantic/

Ligue os source maps nas configurações do DevTools do browser

Limpe o cache do browser e reconstrua

O overlay de erro não aparece

Sintoma: erros logados no console mas nenhum overlay

Verificações:

O window.__EQ_DEV__ é verdadeiro? (confira no console)

O overlay de erro foi importado? (confira se o runtime.js o inclui)

O CSS do overlay de erro carregou? (procure pelos estilos de #equantic-error-overlay)

Forçar a exibição:

// Dispare o overlay manualmente

import { errorOverlay } from "@equantic/ui-runtime/dev";

errorOverlay.show({ message: "Test error" });

🎯 Boas práticas

Fluxo de desenvolvimento

Use o logger à vontade: adicione logs de depuração durante o desenvolvimento, eles são de graça em produção

Teste os dois modos: sempre teste com o ambiente Development e Production

Monitore a rede: deixe a aba Network do DevTools aberta para pegar Server Actions que falharam

Ligue os source maps: sempre construa com source maps em desenvolvimento

Use o overlay de erro: não suprima os erros, deixe o overlay mostrá-los

Depuração em produção

Para problemas em produção:

Logs do servidor: confira os logs do ASP.NET Core para erros de Server Action

Console do browser: só os logs de warn e error aparecem

Sentry/AppInsights: integre serviços de rastreamento de erros

Source maps: opcionalmente, publique os arquivos .map num servidor separado para depurar em produção

Checklist de depuração

Antes de reportar problemas:

•

[ ] Conferir o console do browser por erros

•

[ ] Verificar se window.__EQ_DEV__ é verdadeiro (dev) ou falso (prod)

•

[ ] Confirmar que o runtime.js carrega (aba Network)

•

[ ] Conferir o blob da ponte de tema (window.__EQ_THEME__)

•

[ ] Testar com o cache do browser desligado

•

[ ] Tentar em modo anônimo/privado

•

[ ] Comparar o HTML do SSR com o do CSR

•

[ ] Conferir a saída do MSBuild por avisos

•

[ ] Verificar se os pacotes NuGet estão nas versões corretas

📚 Documentação relacionada

•

Arquitetura do runtime - entendendo o sistema de runtime

•

Fluxo de build - como a compilação e o empacotamento funcionam

•

Performance - técnicas de otimização

PREVIOUSComponents-pt-BR

NEXTDeclarativeSurface-pt-BR

ON THIS PAGE

🔍 Detecção do modo de desenvolvimento

A interface do overlay de erro

Mostrando erros manualmente

Limpando o overlay

Implementação

🛠️ Depurando componentes

DevTools do browser

Source maps

Inspeção de componentes

🧪 Testes e depuração

Testes de integração com o Playwright

Depuração no servidor

Depuração de rede

Depuração de provedores de asset

Assets na renderização no servidor (SSR)

📊 Depuração de performance

Performance em tempo de execução

Performance de build

🔧 Problemas comuns

O runtime.js não carrega

Tokens de tema faltando no CSR

Source maps não funcionam

O overlay de erro não aparece

🎯 Boas práticas

Fluxo de desenvolvimento

Depuração em produção

Checklist de depuração

📚 Documentação relacionada