Framework Integration
Embed in Next.js
Show a Databrain dashboard in a Next.js App Router page.
The plugin registers custom elements in the browser. It cannot run on the server, so you load it in a client component.
Before you start
- You have a data app API key in the server variable
DATABRAIN_API_KEY. Create a guest token - You have a dashboard id. Find the dashboard id
Steps
- Install the plugin.
npm install @databrainhq/plugin- Add a route that creates the guest token on the server, in
app/api/databrain-token/route.ts.
export async function GET() {
// Take the tenant id from the signed-in user's session, never from the request.
const clientId = 'your-customer-id';
const res = await fetch('https://api.usedatabrain.com/api/v2/guest-token/create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.DATABRAIN_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ clientId, dataAppName: 'Your data app name' }),
});
const data = await res.json();
if (!res.ok) return Response.json(data, { status: res.status });
return Response.json({ token: data.token });
}- Add a client component in
components/Dashboard.tsx. It imports the plugin in an effect.
'use client';
import { useEffect, useRef, useState } from 'react';
type DashboardElement = HTMLElement & {
handleServerEvent?: (...args: unknown[]) => unknown;
};
export function Dashboard({ dashboardId }: { dashboardId: string }) {
const [ready, setReady] = useState(false);
const [token, setToken] = useState<string>();
const ref = useRef<DashboardElement>(null);
useEffect(() => {
import('@databrainhq/plugin/web').then(() => setReady(true));
fetch('/api/databrain-token')
.then((res) => res.json())
.then((data) => setToken(data.token));
}, []);
useEffect(() => {
if (!ref.current) return;
ref.current.handleServerEvent = (event) => console.log(event);
}, [ready, token, dashboardId]);
if (!ready || !token) return null;
return (
<dbn-dashboard
key={dashboardId}
ref={ref}
token={token}
dashboard-id={dashboardId}
enable-download-csv="true"
/>
);
}- Use the component in a page, for example
app/analytics/page.tsx.
import { Dashboard } from '@/components/Dashboard';
export default function Page() {
return <Dashboard dashboardId="your-dashboard-id" />;
}You see the dashboard on /analytics.
The element renders only after the import finishes. The props then apply to a defined element. For a metric, render <dbn-metric token={token} metric-id={metricId} /> in the same way.
If something goes wrong
-
customElements is not definedorwindow is not defined. You imported@databrainhq/plugin/webat the top of a file. Import it insideuseEffectin a client component. -
The token route returns 403
entitlement_required. Embedding needs the Enterprise plan. Contact Databrain. -
The token route returns 400
INVALID_DATA_APP_NAME. Use the exact saved name of the data app. -
TypeScript says
dbn-dashboarddoes not exist onJSX.IntrinsicElements. Add this file, for exampledatabrain.d.tsat the project root:import 'react'; declare module 'react' { namespace JSX { interface IntrinsicElements { 'dbn-dashboard': { [attr: string]: unknown }; 'dbn-metric': { [attr: string]: unknown }; } } } -
handleServerEventnever runs. Assign an inline arrow function. The element drops a named function.