Package Ecosystem

DuckViz publishes seven npm packages — the same components that power the hosted product. Embed them in your own React app with full control over data flow, theming, and layout. Each package versions independently; check the latest on npm or in the package's CHANGELOG.md.

Package	Purpose
`@duckviz/db`	DuckDB-WASM engine + React provider
`@duckviz/ui`	Radix primitives + CSS theme system
`@duckviz/widgets`	80+ D3 charts + alias validator + error boundary
`@duckviz/dashboard`	Draggable widget grid
`@duckviz/explorer`	Three-panel data explorer
`@duckviz/report`	Report + deck builders, PDF/DOCX/PPTX export
`@duckviz/sdk`	Node-only server SDK for proxying AI endpoints
`duckviz` CLI	Terminal → browser file pipe

Install the core

npm install @duckviz/db @duckviz/explorer @duckviz/dashboard @duckviz/ui @duckviz/widgets

Add the report builder for PDF/DOCX/PPTX export, and the SDK for server-side AI proxying:

npm install @duckviz/report @duckviz/sdk

Peer deps:

npm install react react-dom @duckdb/duckdb-wasm apache-arrow d3 zustand @tanstack/react-query

See Installation for full requirements.

Components

@duckviz/db

DuckDB-WASM engine with React provider, ingestion hooks, and persistence.

@duckviz/explorer

Three-panel data explorer: file tree, data grid, AI widget recommendations.

@duckviz/dashboard

Embeddable dashboard grid with 80+ D3 chart types.

@duckviz/report

Report builder + deck presenter with PDF, DOCX, PPTX export.

@duckviz/widgets

Chart component registry and standalone renderer.

@duckviz/ui

Radix-based UI primitives and CSS theme system.

@duckviz/sdk

Node-only server SDK for proxying DuckViz AI endpoints.

Dependency graph

The packages have a layered dependency structure. Higher layers depend on lower layers:

┌─────────────────┐
│  @duckviz/sdk   │  ← Node-only, standalone
└─────────────────┘

┌──────────────────────────────────────────────┐
│              @duckviz/explorer               │
│  (uses db + dashboard + widgets + ui)        │
└──────────────────────────────────────────────┘

┌──────────────────────┐  ┌─────────────────────┐
│  @duckviz/dashboard  │  │  @duckviz/report    │
│  (uses db + ui +     │  │  (uses db + ui +    │
│   widgets)           │  │   widgets)          │
└──────────────────────┘  └─────────────────────┘

┌────────────────────┐
│  @duckviz/widgets  │
│  (uses ui)         │
└────────────────────┘

┌─────────────────┐  ┌─────────────────┐
│  @duckviz/db    │  │  @duckviz/ui    │
│  (standalone)   │  │  (standalone)   │
└─────────────────┘  └─────────────────┘

@duckviz/db and @duckviz/ui are the foundation — no DuckViz peer deps
@duckviz/widgets depends on ui
@duckviz/dashboard and @duckviz/report depend on db, ui, and widgets
@duckviz/explorer depends on all four above
@duckviz/sdk is standalone (Node-only, no React)

Minimal setup

Wrap your app in the DuckDB and theme providers:

import { DuckvizDBProvider } from "@duckviz/db";
import { DuckvizThemeProvider } from "@duckviz/ui";

function App({ children }) {
  return (
    <DuckvizThemeProvider preset="terracotta" mode="dark">
      <DuckvizDBProvider persistence batchSize={5000}>
        {children}
      </DuckvizDBProvider>
    </DuckvizThemeProvider>
  );
}

Then render the Explorer, Dashboard, or ReportBuilder:

import { Explorer } from "@duckviz/explorer";
import { Dashboard } from "@duckviz/dashboard";
import { ReportBuilder } from "@duckviz/report";

See the Next.js Integration Guide for a complete walkthrough.

Auto-ingest datasets

<Dashboard>, <Explorer>, <ReportBuilder>, and <DeckBuilder> all accept a shared datasets: DuckvizDataset[] prop that auto-ingests row data into DuckDB on mount. You don't need to call db.ingest() yourself:

import type { DuckvizDataset } from "@duckviz/db";

const datasets: DuckvizDataset[] = [
  { name: "Orders", data: orders },      // table derived: t_orders
  { name: "Users", data: users, tableName: "t_users" },
];

<Dashboard config={config} datasets={datasets} />

Tables are dropped from DuckDB on unmount by default (dropTablesOnUnmount={false} to keep them).

Peer dependency matrix

Package	react	react-dom	next	d3	@duckdb/duckdb-wasm	apache-arrow	zustand	@tanstack/react-query
`@duckviz/db`	^19	-	-	-	^1.33	^17	-	-
`@duckviz/explorer`	^19	^19	^16	-	-	-	^5	^5
`@duckviz/dashboard`	^19	^19	-	^7	-	-	-	-
`@duckviz/report`	^19	^19	-	-	-	-	-	-
`@duckviz/widgets`	^19	^19	-	^7	-	-	-	-
`@duckviz/ui`	^19	^19	-	-	-	-	-	-
`@duckviz/sdk`	-	-	-	-	-	-	-	-