SQLRooms Development Skill

SQLRooms is a React framework for building browser-based data analytics applications powered by DuckDB-WASM.

Key Features

In-browser DuckDB: SQL analytics runs entirely client-side

Modular Architecture: Compose apps from feature packages and slices

AI Integration: Built-in support for AI agents using Vercel AI SDK

Local-First: Data stays on device, works offline

Package Overview

Core packages (required):

@sqlrooms/room-shell - App shell, state management, panels

@sqlrooms/room-store - Store utilities, context providers

@sqlrooms/duckdb - DuckDB-WASM wrapper, React hooks

@sqlrooms/ui - Tailwind component library (shadcn based)

Feature packages (optional):

@sqlrooms/ai - AI integration, natural language queries

@sqlrooms/sql-editor - Monaco SQL editor with tabs

@sqlrooms/data-table - Interactive data grid

@sqlrooms/recharts / @sqlrooms/vega - Visualizations

Quick Start

hljs bash

npm install @sqlrooms/room-shell @sqlrooms/duckdb @sqlrooms/ui

Tailwind Setup

hljs typescript

// tailwind.config.ts
import {sqlroomsTailwindPreset} from '@sqlrooms/ui';

export default {
  presets: [sqlroomsTailwindPreset()],
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@sqlrooms/**/dist/**/*.js',
  ],
};

hljs css

/* main.css */
@import '@sqlrooms/ui/tailwind-preset.css';

Minimal App Structure

hljs tsx

import {RoomShell} from '@sqlrooms/room-shell';
import {ThemeProvider} from '@sqlrooms/ui';
import {roomStore} from './store';

export function App() {
  return (
    <ThemeProvider defaultTheme="light" storageKey="sqlrooms-ui-theme">
      <RoomShell className="h-screen" roomStore={roomStore}>
        <RoomShell.Sidebar />
        <RoomShell.LayoutComposer />
        <RoomShell.LoadingProgress />
      </RoomShell>
    </ThemeProvider>
  );
}

Reference Documentation

For detailed guidance on specific topics:

State Management: See references/state.md for Zustand store setup, slices pattern, persistence

DuckDB Integration: See references/duckdb.md for useSql hook, data operations, queries

AI Integration: See references/ai.md for AI agents, tools, sessions, model configuration

Components & Panels: See references/components.md for UI components, panel layout

Code Templates: See references/quickstart.md for complete store/panel templates

Essential Patterns

Store Creation with Slices

hljs typescript

import {createRoomStore, createRoomShellSlice, RoomShellSliceState} from '@sqlrooms/room-shell';

type RoomState = RoomShellSliceState;

export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
  (set, get, store) => ({
    ...createRoomShellSlice({
      config: { title: 'My App', dataSources: [] },
      layout: { config: {...}, panels: {...} },
    })(set, get, store),
  }),
);

SQL Query Hook

hljs typescript

import {useSql} from '@sqlrooms/duckdb';

function MyComponent() {
  const tableReady = useRoomStore((s) => s.db.findTableByName('mytable'));
  const {data, isLoading, error} = useSql<{count: number}>({
    query: 'SELECT COUNT(*) AS count FROM mytable',
    enabled: Boolean(tableReady),
  });
  return <div>Count: {data?.toArray()[0]?.count}</div>;
}

Panel Definition

hljs typescript

layout: {
  config: {
    type: LayoutTypes.enum.mosaic,
    nodes: {
      direction: 'row',
      first: 'sidebar',
      second: 'main',
      splitPercentage: 25,
    },
  },
  panels: {
    sidebar: {
      title: 'Data',
      icon: DatabaseIcon,
      component: DataPanel,
      placement: 'sidebar',
    },
    main: {
      title: 'Main',
      icon: () => null,
      component: MainPanel,
      placement: 'main',
    },
  },
}

Resources

Website: https://sqlrooms.org

GitHub: https://github.com/sqlrooms/sqlrooms

LLM Docs: https://sqlrooms.org/llms.txt

sqlrooms-skill

SQLRooms Development Skill

Key Features

Package Overview

Quick Start

Tailwind Setup

Minimal App Structure

Reference Documentation

Essential Patterns

Store Creation with Slices

SQL Query Hook

Panel Definition

Resources

Related Categories