shaper

Shaper is a SQL-first, open-source analytics platform that lets teams build rich data dashboards and reports without leaving the query editor. Instead of dragging and dropping widgets or learning proprietary chart builders, you annotate your SELECT statements with custom SQL type casts like ::BARCHART_STACKED or ::XAXIS and Shaper renders the visualization automatically. This approach keeps all dashboard logic version-controllable in plain SQL files.

At its core, Shaper runs on DuckDB as its analytical engine, giving it exceptional performance on local or S3-backed data without requiring a separate database server. It ships as a single Go binary or Docker container that embeds the React frontend, making deployment straightforward on any VPS or container platform. NATS JetStream is used for internal state propagation and task orchestration, enabling multi-node setups and a reliable audit trail of all changes through event sourcing.

Beyond personal and team dashboards, Shaper is built for embedding customer-facing analytics. It provides row-level security via JWT tokens, white-labeling with custom styles, and JS/React SDKs that embed charts without an iframe. Automated reporting rounds out the feature set with scheduled PDF, PNG, CSV, and Excel exports that can be delivered via password-protected shareable links or email alerts.

The project is maintained by Taleshape, an Estonian company, and is licensed under MPL-2.0 — meaning the source is freely available, modifications to Shaper’s own files must be shared back, but it can be used in proprietary products without restriction. Taleshape offers managed hosting and expert support for teams that want production guarantees without the operational overhead.

What You Get

• A SQL-to-dashboard engine where chart types, axes, and controls are declared directly in query results via DuckDB UNION type casts, keeping all visualization logic inside your SQL files
• A single Go binary that embeds the React frontend, SQLite for metadata, DuckDB for analytics, and NATS JetStream for state — no external services required for single-node setups
• Embedded analytics SDKs (JS and React) with JWT-based row-level security and white-labeling support for shipping customer-facing charts inside your own product
• Automated report generation in PDF, PNG, CSV, and Excel formats with scheduled delivery and password-protected shareable links
• Git-based workflow for dashboards: SQL content is stored as text that can be committed, diffed, and reviewed like any other code
• Multi-data-source support through DuckDB’s extension ecosystem, enabling queries against local files, S3 buckets, PostgreSQL, and other sources from the same dashboard
• S3 snapshot backup and restore functionality with support for standard AWS credential discovery methods

Common Use Cases

• Product analytics dashboards where engineering teams write SQL against their application database or event streams and ship charts directly to stakeholders without a BI tool intermediary
• Customer-facing analytics embedded in SaaS products, where each tenant sees only their own rows via JWT claims and the charts match the host product’s brand
• Automated business reporting with scheduled PDF and Excel exports sent to executives or customers on a recurring schedule
• Data exploration on DuckDB-native sources such as Parquet files in S3, local CSVs, or Iceberg tables, without standing up a separate analytics warehouse
• Operational dashboards for infrastructure or DevOps teams that need low-latency views on metrics stored in DuckDB or exported from Prometheus
• Replacing heavyweight BI tools in small-to-medium teams that want version-controlled, code-centric dashboard management rather than GUI-driven drag-and-drop editors

Under The Hood

Architecture Shaper follows a layered, event-sourced design where all persistent state changes flow through NATS JetStream before being written to SQLite, creating an append-only audit log that can replay state across multiple nodes. The core package is the heart of the system: it defines the dashboard query engine, the custom DuckDB UNION type registry (over 60 named chart types), and the event handlers that translate NATS messages into idempotent SQLite mutations. The API layer is a thin Echo HTTP router that delegates to core functions and enforces JWT-based actor permissions, while the web layer embeds the compiled React frontend as a Go filesystem. This clean separation means the data path — DuckDB query execution, type-casting, result serialization — is entirely independent of the HTTP surface, making it straightforward to add new transport layers or query sources.

Tech Stack The backend is written in Go 1.26 and ships as a single statically-linked binary. DuckDB (via the official duckdb-go/v2 bindings) serves as the analytical query engine, while SQLite (via modernc.org/sqlite, a pure-Go CGO-free port) stores dashboard metadata, user accounts, and configuration. NATS JetStream handles internal pub/sub messaging, key-value state buckets, and task queuing. The Echo v4 framework serves the REST and WebSocket API. PDF and PNG generation uses chromedp to drive a headless Chrome instance. The frontend is a React 18 + TypeScript SPA built with Vite, using TanStack Router for file-based routing, ECharts for chart rendering, Monaco Editor for the SQL editor, and Radix UI primitives for accessible components — all compiled and embedded into the Go binary at build time via embed.FS.

Code Quality The codebase demonstrates comprehensive testing coverage across the core domain: stream query logic, SQL validation, dashboard retrieval, task initialization, authentication flows, and DuckDB schema management all have dedicated test files using Go’s standard testing package with the testify assertion library. Error handling is explicit throughout — errors are wrapped with context using fmt.Errorf and propagated rather than swallowed, with structured logging via Go’s log/slog. The codebase uses ESLint and TypeScript in strict mode on the frontend, and the Go side enforces go vet and go test ./... as part of the release workflow. CONTRIBUTING.md documents the full local development and build process clearly.

What Makes It Unique Shaper’s core innovation is the SQL type system for dashboards: rather than mapping queries to chart configurations in a separate GUI or config file, chart types and display semantics are embedded directly in DuckDB UNION type casts attached to individual SELECT columns. A column cast to ::BARCHART_STACKED becomes a stacked bar series; ::XAXIS defines the horizontal dimension; ::DROPDOWN renders an interactive filter widget — all within the same SQL file. This means dashboards are fully version-controllable, diff-able, and portable as plain text, with zero proprietary configuration format. Combined with DuckDB’s ability to query across heterogeneous data sources in a single statement, Shaper enables a workflow that no traditional BI tool supports: write a single SQL file, commit it to git, and get a production-ready interactive dashboard with embedded analytics and export capability.

Self-Hosting

Shaper is released under the Mozilla Public License 2.0 (MPL-2.0), a weak copyleft license. In practice this means you can use Shaper commercially and embed it in proprietary products without restriction, but any modifications you make to Shaper’s own source files must be made available under the same license if you distribute the software. For teams that only self-host and do not redistribute Shaper externally, the copyleft clause is effectively irrelevant — you can customize it freely for internal use.

Running Shaper yourself requires a Linux or macOS host with Go (for building from source) or Docker for the pre-built image. The single-binary deployment model keeps the operational surface small: Shaper manages its own SQLite metadata store and embeds NATS, so a single-node deployment has no external service dependencies. For PDF and PNG report generation you will need Chrome or Chromium installed on the host. For multi-node deployments you would need to configure an external NATS server and ensure shared DuckDB data access, which adds coordination complexity. Backups are handled via S3 snapshot support, but you are responsible for scheduling and verifying those snapshots in a self-hosted setup.

Taleshape, the company behind Shaper, offers managed hosting where they run Shaper inside your own infrastructure and handle updates, security patches, and monitoring. They also provide hands-on support for integrations and dashboard builds, and can assist with compliance requirements. Compared to a managed deployment, self-hosting means you own the update cadence (the project releases roughly every week), operational monitoring, and incident response — trade-offs worth weighing for teams without dedicated infrastructure capacity.