Instalação do ecossistema Sulfite

Como instalar e rodar Sulfite Core, Studio, Server e App Example

Instalação do ecossistema Sulfite#

Este guia existe para responder uma pergunta simples: "o que eu preciso instalar para começar com Sulfite?"

Aqui você vai configurar o ambiente e escolher um caminho de início.

O que é o ecossistema Sulfite#

O repositório é um monorepo com vários pacotes:

sulfite_core: engine de relatório (JSON -> PDF/HTML/CSV/Excel/ZPL)
sulfite_studio: editor visual de relatórios
sulfite_server: API HTTP para geração, armazenamento e compartilhamento
examples/app: app de exemplo com fluxos prontos

Pré-requisitos#

Antes de instalar qualquer módulo:

Dart SDK >= 3.11.1
Flutter >= 3.41 (recomendado usar FVM)
Git

Opcional (mas comum para backend):

Docker
PostgreSQL/Supabase

1) Clonar e preparar o monorepo#

git clone https://github.com/rafagazani/sulfite.git
cd sulfite

Instale dependências por pacote conforme o que você vai usar.

2) Escolha seu caminho de início#

Caminho A: Quero só gerar relatórios no meu app (Core)#

No seu projeto Flutter:

flutter pub add sulfite_core

Ou via pubspec.yaml:

dependencies:
  sulfite_core:
    git:
      url: https://github.com/rafagazani/sulfite.git
      path: packages/sulfite_core

Caminho B: Quero editar relatórios visualmente (Studio)#

Dentro do monorepo:

cd packages/sulfite_studio
flutter pub get
flutter run -d macos

Troque -d macos pelo seu target (windows, linux, etc.).

Caminho C: Quero API de geração de relatórios (Server)#

Dentro do monorepo:

cd packages/sulfite_server
dart pub get
dart run bin/sulfite_server.dart

A API sobe por padrão em http://localhost:8080.

Para ambiente com banco/migrations, veja:

Caminho D: Quero ver tudo funcionando no app exemplo#

cd examples/app
flutter pub get
flutter run -d chrome

Esse app inclui relatórios e fluxos reais para explorar rapidamente.

3) Primeiro resultado em 5 minutos (Core)#

Crie report.json e data.json mínimos e rode este script:

import 'dart:convert';
import 'dart:io';
import 'package:sulfite_core/sulfite_core.dart';

Future<void> main() async {
  final engine = SulfiteEngineImpl();

  final report = await engine.parseReport(
    File('report.json').readAsStringSync(),
  );

  final data = jsonDecode(File('data.json').readAsStringSync())
      as Map<String, dynamic>;

  final context = await engine.processData(report, data);
  final pdf = await engine.renderToPdf(context);

  File('output.pdf').writeAsBytesSync(pdf);
  print('PDF gerado: output.pdf');
}

Estrutura mínima dos arquivos#

report.json: layout (bands, elementos, dataSources)
data.json: payload real consumido pelos bindings

Regra importante:

o dataSource.id definido no relatório deve existir no payload

Exemplo: se no relatório existe "id": "items", o data.json precisa ter "items": [...].

Problemas comuns de instalação#

Versão do Dart/Flutter incompatível Verifique dart --version e flutter --version.
Dependências não resolvidas no monorepo Rode dart pub get ou flutter pub get no pacote correto.
Server sem acesso a banco Revise DATABASE_URL e leia server/config.

Próximos passos#

Depois de instalar, siga essa ordem:

Se você quer aprender construindo: