Pular para o conteúdo principal

json-pdf-designer

Desenhe um relatório PDF no navegador e gere ele em qualquer lugar.

Um editor visual de relatórios pra React — um canvas de arrastar/ redimensionar (<Designer>) sobre um motor de vínculo de dados JSON, mais um gerador de PDF (generatePdf) que é JavaScript puro: sem DOM, sem canvas, sem navegador headless. O template que você desenha é um objeto JSON serializável, então o mesmo caminho de código renderiza ele no navegador, numa API Node ou num worker de fila — não existe uma segunda implementação pra divergir.

Em resumo​

Tamanho da instalação3 dependências de runtime (pdf-lib, fontkit, tiny-inflate). Os 5 peers são opcionais — um backend que só gera não instala nenhum deles
RequisitosNode ≥ 18 · React 18 ou 19 (só pro editor) · TypeScript opcional, tipos incluídos
Formatos de móduloESM e CJS, com .d.ts em todos os entry points
Entry pointsjson-pdf-designer · /server (sem React) · /preview · /theme.css · /reset.css
Tipos de campotexto, tabela, imagem, seção (faixa repetida), gráfico, cartão de KPI
Expressões11 funções, parseadas pra AST — sem eval, sem new Function
Composição10 peças posicionáveis do editor · 10 hooks de estado · 12 primitivos de UI substituíveis
Estilo190 classes .jpd-* estáveis, 123 tokens --jpd-*, CSS escrito à mão, sem build do seu lado
Idiomas da interfaceInglês e português, trocados por uma prop locale

O que você ganha​

PeçaO que faz
<Designer>O canvas React — arrasta/redimensiona campos, painel lateral em abas (Campos/Dados/Estilo/Filtro/Página), zoom, réguas, seleção múltipla, copiar/colar, estado amigável a undo. Desde a 3.0.0 ele é um preset sobre dez peças posicionáveis, então dá pra montar o layout do editor você mesmo — ver Compondo o Designer.
generatePdfTransforma um Template + dado JSON real + Binding[] em bytes de PDF (pdf-lib) — funciona no navegador ou em Node, sem headless browser envolvido.
Tipos de campoTexto, tabela, imagem, seção repetida (mestre-detalhe), gráfico (pizza/barra), cartão indicador (KPI).
Vínculo de dadosTemplates {token}/{FUNÇÃO(...)} contra JSON real — SUM, COUNT, AVG, DATE, CURRENCY, NUMBER, aritmética, e mais.
Idioma da UIUma prop locale no <Designer> (inglês ou português) — só afeta a casca do editor, nunca o conteúdo do relatório gerado.

Feito pra ser dependência​

Concreto, e conferível no repositório:

  • 1115 testes em 75 arquivos, com peso onde está o risco: 19 arquivos cobrem só geração de PDF e paginação, mais 8 no parser de expressão, 8 no kit de UI, 7 nas fronteiras de estado do editor, 6 em tabelas, 4 em vínculo de dados.
  • O CI testa o artefato publicado, não a fonte. Ele roda npm pack, instala o tarball num diretório limpo e afirma que sai PDF de verdade — e que uma falha volta como classe tipada com texto localizado. É isso que pega exports errado, arquivo fora do files, ou um import que arrasta React em silêncio pro build /server.
  • Peer opcional é verificado, não só declarado. O mesmo passo de CI falha se pdfjs-dist, react-rnd, react ou react-dom aparecerem numa instalação só de backend.
  • Toda falha é uma classe tipada com code e blame (data/template/config/package), e o describePdfError transforma uma delas em texto que uma pessoa lê, em qualquer dos dois idiomas. Um backend escolhe o status HTTP sem casar mensagem — ver Modos de falha.
  • Semver honesto. As quebras da 3.0.0 estão enumeradas com diff de migração no changelog, e o caminho removido da folha de estilo falha em tempo de build de propósito, em vez de resolver pra algo sutilmente diferente.

Por onde começar​

Instalação​

npm install json-pdf-designer

Peer deps: react e react-dom (18 ou 19) — e são opcionais: se você só importa de json-pdf-designer/server, nunca precisa instalar nenhum dos dois. Veja Instalação pro quadro completo.