vue-sql-workbench-embedded

v0.1.2

Published

2 months ago

Vue 3 wrapper component for the sql-workbench-embedded package, which is a library for creating interactive SQL editors in the browser using DuckDB WASM.

0High
0Medium
0Low

tobilg

vue vue3 sql duckdb wasm embed embedded embeddable interactive sql-editor sql-workbench documentation tutorial education queries in-browser

Vue 3 SQL Workbench Embedded

A Vue 3 wrapper component for sql-workbench-embedded, which provides an interactive SQL editor powered by DuckDB WASM.

Features

🚀 Easy integration with Vue 3 applications
🎨 Theme support (light, dark, auto)
✏️ Editable or read-only SQL code
🔧 Full TypeScript support
📦 Tree-shakeable ESM and UMD builds
🎯 Template ref support for programmatic access

Installation

npm install vue-sql-workbench-embedded
# or
yarn add vue-sql-workbench-embedded
# or
pnpm add vue-sql-workbench-embedded

Usage

CDN Usage

ES Module (Recommended)

Important: When using the ESM build in browsers, you need an import map to resolve the "vue" dependency.

<!DOCTYPE html>
<html>
<head>
  <!-- Import map to resolve bare module specifiers -->
  <script type="importmap">
    {
      "imports": {
        "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js"
      }
    }
  </script>
</head>
<body>
  <div id="app"></div>

  <script type="module">
    import { createApp, h } from 'vue';
    import { SQLWorkbenchEmbedded, SQLWorkbenchProvider } from 'https://unpkg.com/vue-sql-workbench-embedded@latest/dist/vue-sql-workbench-embedded.esm.js';

    const app = createApp({
      setup() {
        return () => h(SQLWorkbenchProvider, {}, () => [
          h(SQLWorkbenchEmbedded, {
            initialCode: 'SELECT * FROM generate_series(1, 10);',
            theme: 'auto',
            editable: true
          })
        ]);
      }
    });

    app.mount('#app');
  </script>
</body>
</html>

UMD (Global)

The UMD build works directly in browsers without build tools. Use Vue's h() render function for component composition:

<!DOCTYPE html>
<html>
<body>
  <div id="app"></div>

  <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
  <script src="https://unpkg.com/vue-sql-workbench-embedded@latest/dist/vue-sql-workbench-embedded.umd.js"></script>

  <script>
    const { createApp, h } = Vue;
    const { SQLWorkbenchEmbedded, SQLWorkbenchProvider } = VueSQLWorkbenchEmbedded;

    const app = createApp({
      setup() {
        return () => h(SQLWorkbenchProvider, {}, () => [
          h(SQLWorkbenchEmbedded, {
            initialCode: 'SELECT * FROM generate_series(1, 10);',
            theme: 'auto',
            editable: true
          })
        ]);
      }
    });

    app.mount('#app');
  </script>
</body>
</html>

Note: Template strings (e.g., template: '<div>...</div>') require Vue's template compiler and won't work with the browser ESM/UMD builds. Use the h() render function as shown above, or use a build tool like Vite.

NPM Installation

npm install vue-sql-workbench-embedded
# or
yarn add vue-sql-workbench-embedded
# or
pnpm add vue-sql-workbench-embedded

Basic Example

<script setup>
import { SQLWorkbenchEmbedded } from 'vue-sql-workbench-embedded';

const initialCode = `
SELECT * FROM generate_series(1, 10);
`;
</script>

<template>
  <SQLWorkbenchEmbedded
    :initialCode="initialCode"
    theme="dark"
    :editable="true"
  />
</template>

With Provider (Recommended for Multiple Instances)

<script setup>
import {
  SQLWorkbenchProvider,
  SQLWorkbenchEmbedded,
  useSQLWorkbench
} from 'vue-sql-workbench-embedded';

const { isReady, error } = useSQLWorkbench();
</script>

<template>
  <SQLWorkbenchProvider
    :config="{
      theme: 'dark',
      editable: true,
      initQueries: ['INSTALL spatial', 'LOAD spatial']
    }"
  >
    <div v-if="error">Error: {{ error.message }}</div>
    <div v-else-if="!isReady">Loading...</div>
    <div v-else>
      <SQLWorkbenchEmbedded
        initialCode="SELECT * FROM generate_series(1, 10);"
      />
    </div>
  </SQLWorkbenchProvider>
</template>

Using Template Refs

<script setup>
import { ref, onMounted } from 'vue';
import { SQLWorkbenchEmbedded } from 'vue-sql-workbench-embedded';

const workbenchRef = ref(null);

onMounted(() => {
  // Access the underlying SQL Workbench instance
  const instance = workbenchRef.value?.getInstance();
  console.log('Workbench instance:', instance);

  // Access the container element
  const element = workbenchRef.value?.getElement();
  console.log('Container element:', element);
});
</script>

<template>
  <SQLWorkbenchEmbedded
    ref="workbenchRef"
    initialCode="SELECT 1;"
  />
</template>

TypeScript Usage

<script setup lang="ts">
import { ref } from 'vue';
import {
  SQLWorkbenchEmbedded,
  SQLWorkbenchProvider,
  useSQLWorkbench,
  type SQLWorkbenchEmbeddedInstance,
  type Theme
} from 'vue-sql-workbench-embedded';

const { isReady, error } = useSQLWorkbench();
const theme = ref<Theme>('auto');
const workbenchRef = ref<InstanceType<typeof SQLWorkbenchEmbedded> | null>(null);

const onReady = (instance: SQLWorkbenchEmbeddedInstance) => {
  console.log('SQL Workbench instance ready:', instance);
};

const onError = (error: Error) => {
  console.error('SQL Workbench error:', error);
};
</script>

<template>
  <SQLWorkbenchProvider>
    <SQLWorkbenchEmbedded
      ref="workbenchRef"
      :initialCode="'SELECT 1;'"
      :theme="theme"
      @ready="onReady"
      @error="onError"
    />
  </SQLWorkbenchProvider>
</template>

API

SQLWorkbenchEmbedded Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | initialCode | string | '' | Initial SQL code to display | | theme | 'light' \| 'dark' \| 'auto' \| string | 'auto' | Color theme (auto detects system preference) | | editable | boolean | true | Whether the editor is editable | | showOpenButton | boolean | true | Show "Open in SQL Workbench" button | | className | string | '' | Custom CSS class for container | | style | Record<string, string> | undefined | Custom inline styles |

SQLWorkbenchEmbedded Events

| Event | Payload | Description | |-------|---------|-------------| | ready | SQLWorkbenchEmbeddedInstance | Fired when the workbench is initialized | | error | Error | Fired when initialization fails |

SQLWorkbenchEmbedded Template Refs

| Method | Return Type | Description | |--------|-------------|-------------| | getInstance() | SQLWorkbenchEmbeddedInstance \| null | Get the underlying SQL Workbench instance | | getElement() | HTMLDivElement \| null | Get the container DOM element |

SQLWorkbenchProvider Props

| Prop | Type | Description | |------|------|-------------| | config | SQLWorkbenchConfig | Global configuration for SQL Workbench |

SQLWorkbenchConfig

| Property | Type | Default | Description | |----------|------|---------|-------------| | theme | 'light' \| 'dark' \| 'auto' \| string | 'auto' | Global theme | | editable | boolean | true | Default editable state | | showOpenButton | boolean | true | Default show open button state | | initQueries | string[] | [] | Initialization queries to run | | duckdbVersion | string | '1.31.1-dev1.0' | DuckDB WASM version | | duckdbCDN | string | 'https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm' | DuckDB CDN URL | | baseUrl | string | 'https://data.sql-workbench.com' | Base URL for file resolution | | customThemes | Record<string, CustomTheme> | {} | Custom theme definitions |

SQLWorkbenchProvider Events

| Event | Payload | Description | |-------|---------|-------------| | ready | - | Fired when SQL Workbench is ready | | error | Error | Fired when initialization fails |

useSQLWorkbench Composable

Returns an object with:

isReady: Ref<boolean> - Whether SQL Workbench is initialized
error: Ref<Error \| null> - Any initialization error

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl/Cmd + Enter | Execute SQL query | | Ctrl/Cmd + Shift + Enter | Open in SQL Workbench | | Ctrl/Cmd + Backspace | Reset to original code | | Tab | Insert 2 spaces | | Enter | Insert newline |

Development

# Install dependencies
npm install

# Run demo in development mode
npm run dev

# Build library
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint
npm run lint

Testing Builds

The examples/ directory contains HTML files for testing the UMD and ESM builds:

examples/test-umd.html - Test the UMD build (can open directly in browser)
examples/test-esm.html - Test the ESM build (requires HTTP server)
examples/README.md - Full documentation for the test files

To test the ESM build:

# Start a local HTTP server
python3 -m http.server 8000

# Then open in browser:
# http://localhost:8000/examples/test-esm.html

See examples/README.md for more details.

License

MIT