React quickstart

Want the complete host integration? Try the live demo. Want isolated components and states? Open the React SDK playground.

1. Install the packages

Both packages are public on npm:

npm install @dataira/react @dataira/node

@dataira/node is optional; use it here to keep the first server route small.

2. Mint a token on your backend

app/api/dataira-token/route.ts

import { Dataira } from "@dataira/node";

const dataira = new Dataira({
  apiKey: process.env.DATAIRA_API_KEY!,
  baseUrl: process.env.DATAIRA_GATEWAY_URL!,
});

export async function POST(request: Request) {
  const user = await requireUser(request); // Your authentication
  const result = await dataira.createToken({
    endUserId: user.id,
    datasourceId: process.env.DATAIRA_DATASOURCE_ID!,
    scopeColumn: "customer_id",
    scopeValue: user.customerId,
  });
  return Response.json(result);
}

The API key belongs to one Project and one Environment. Never expose it to the browser or prefix it with NEXT_PUBLIC_. Before production, create and bind a deny-by-default data policy using the partner launch checklist.

3. Render the workspace

app/analytics/page.tsx

"use client";

import { DatairaInsights, DatairaProvider } from "@dataira/react";
import "@dataira/react/styles.css";

const getToken = async () => {
  const response = await fetch("/api/dataira-token", { method: "POST" });
  if (!response.ok) throw new Error("Could not start Dataira");
  return (await response.json()).token;
};

export default function AnalyticsPage({ userId }: { userId: string }) {
  return (
    <main style={{ height: "100dvh" }}>
      <DatairaProvider baseUrl="https://api.dataira.ai" sessionKey={userId}
        getToken={getToken}>
        <DatairaInsights examplePrompts={["Revenue by month", "Top products"]} />
      </DatairaProvider>
    </main>
  );
}

Give the host a definite height. Long conversations then scroll inside the SDK instead of growing the surrounding page. The layout adapts to its container for desktop, tablet, and mobile widths.

sessionKey is required: pass a stable identifier for the signed-in user (for example the host user ID). Changing it resets the SDK session when the principal changes.

Next, customize the React SDK.