Skip to main content

​
Lovable + Oxygen SDK

Lovable is an AI-powered web app builder that lets you create full-stack React applications through natural language. Combined with the Oxygen SDK, you can build beautiful, data-connected dashboards that query your Oxygen agents and databases in real time.

​
How It Works

The Oxygen SDK (@oxy-hq/sdk) exposes a React provider and hooks that connect your Lovable app to a running Oxygen backend. Your app calls oxy start --enterprise locally (or on a server), and the SDK handles authentication, querying, and data transformation. 
Lovable app (React + Vite)
        │
        │  @oxy-hq/sdk
        ▼
  OxyProvider / useOxy
        │
        │  HTTP (localhost:3000)
        ▼
   oxy start --enterprise
        │
        ▼
   Your databases & agents

​
Prerequisites

  • An Oxygen project with at least one database configured
  • oxy start --enterprise running and accessible from your browser
  • A Lovable account

​
Getting Started

The fastest way to get started is to use the Lovable starter prompt. It gives Lovable all the context it needs to scaffold a working dashboard with the Oxygen SDK already wired up correctly — including BigInt-safe data handling, error boundaries, and connection error states.

Lovable Starter Prompt

A ready-to-use prompt you can paste into Lovable to scaffold a fully working Oxygen-connected dashboard.

​
What Gets Built

The starter prompt produces a dashboard that:
  • Wraps the app in OxyProvider with graceful loading and error fallbacks
  • Queries a monthly_values table via sdk.loadAppData() and sdk.query()
  • Handles DuckDB-specific data types (epoch dates, BigInt values)
  • Shows a data table and optional line chart with Recharts
  • Displays a helpful connection error screen if the Oxygen backend is unreachable

​
SDK Reference

ImportDescription
OxyProviderRoot provider — wrap your app with this
useOxyHook to access the sdk instance inside your components
sdk.loadAppData(path)Load a .app.yml data app
sdk.query(sql)Run a SQL query and return { columns, rows }
Install the SDK: 
npm install @oxy-hq/sdk