hxdb-vue

Vue/Nuxt client library for HxDB — query your database with Vue composables.

Install

npm install hxdb-vue

Quick Start

Option A: Vue Plugin (recommended)

The baseUrl defaults to https://hxdb-test.kubo.hexabase.io, so you only need to provide your API key:

// main.ts
import { createApp } from "vue";
import { HxDBPlugin } from "hxdb-vue";
import App from "./App.vue";

const app = createApp(App);

app.use(HxDBPlugin, {
  apiKey: "your-api-key", // from HxDB Settings page
});

app.mount("#app");

To connect to a different HxDB instance, override baseUrl:

app.use(HxDBPlugin, {
  baseUrl: "http://localhost:5213",
  apiKey: "your-api-key",
});

Option B: Nuxt Plugin

// plugins/hxdb.ts
import { HxDBPlugin } from "hxdb-vue";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(HxDBPlugin, {
    apiKey: "your-api-key",
  });
});

Option C: Component-level provide

<!-- ParentComponent.vue -->
<script setup lang="ts">
import { provideHxDB } from "hxdb-vue";

provideHxDB({
  apiKey: "your-api-key",
});
</script>

Query with useHxDB

<script setup lang="ts">
import { useHxDB } from "hxdb-vue";

interface User {
  id: number;
  name: string;
  email: string;
}

const { data, columns, loading, error, executionTimeMs, refetch } = useHxDB<User>(
  "SELECT * FROM users LIMIT 10"
);
</script>

<template>
  <p v-if="loading">Loading...</p>
  <p v-else-if="error">Error: {{ error }}</p>
  <div v-else>
    <p>Fetched in {{ executionTimeMs }}ms</p>
    <button @click="refetch">Refresh</button>
    <table>
      <thead>
        <tr>
          <th v-for="col in columns" :key="col">{{ col }}</th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="user in data" :key="user.id">
          <td>{{ user.id }}</td>
          <td>{{ user.name }}</td>
          <td>{{ user.email }}</td>
        </tr>
      </tbody>
    </table>
  </div>
</template>

Reactive Queries

Pass a getter function to make the query reactive:

<script setup lang="ts">
import { ref } from "vue";
import { useHxDB } from "hxdb-vue";

const limit = ref(10);

const { data, loading } = useHxDB(
  () => `SELECT * FROM users LIMIT ${limit.value}`
);

// Query re-executes automatically when limit changes
</script>

<template>
  <select v-model="limit">
    <option :value="10">10 rows</option>
    <option :value="50">50 rows</option>
    <option :value="100">100 rows</option>
  </select>
  <p v-if="loading">Loading...</p>
  <ul v-else>
    <li v-for="(row, i) in data" :key="i">{{ row }}</li>
  </ul>
</template>

Conditional Execution

<script setup lang="ts">
import { ref } from "vue";
import { useHxDB } from "hxdb-vue";

const shouldFetch = ref(false);

const { data, loading } = useHxDB(
  "SELECT * FROM orders",
  { enabled: () => shouldFetch.value }
);
</script>

<template>
  <button @click="shouldFetch = true">Load Orders</button>
  <p v-if="loading">Loading...</p>
  <pre v-else>{{ data }}</pre>
</template>

API Reference

HxDBPlugin

Vue plugin for global installation.

app.use(HxDBPlugin, {
  baseUrl: "https://hxdb-test.kubo.hexabase.io",  // optional, this is the default
  apiKey: "your-api-key",   // required
  headers: { ... },          // optional custom headers
});

useHxDB<T>(query, options?)

Composable for executing SQL queries with reactive state.

const state = useHxDB<User>("SELECT * FROM users", {
  enabled: true, // boolean or () => boolean
});

Returns HxDBQueryState<T>:

| Field | Type | Description | |-------|------|-------------| | data | Ref<T[]> | Query result rows | | columns | Ref<string[]> | Column names | | loading | Ref<boolean> | Loading state | | error | Ref<string \| null> | Error message | | executionTimeMs | Ref<number \| null> | Query execution time | | rowsAffected | Ref<number> | Rows affected (INSERT/UPDATE/DELETE) | | refetch | () => Promise<void> | Re-execute the query |

provideHxDB(config)

Provide the client at component level (alternative to plugin).

useHxDBClient()

Access the raw HxDBClient instance from the injection context.

HxDBClient

Standalone client for use outside components (API routes, scripts, etc).

import { createHxDBClient } from "hxdb-vue";

// Uses default URL (https://hxdb-test.kubo.hexabase.io)
const client = createHxDBClient({ apiKey: "your-api-key" });

// Or specify a custom URL
// const client = createHxDBClient({ baseUrl: "http://localhost:5213", apiKey: "your-api-key" });

const { data, columns } = await client.query("SELECT * FROM users LIMIT 5");
const datasets = await client.datasets();

License

MIT