Skip to Content

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

Steps

  1. Install the plugin.
npm install @databrainhq/plugin
  1. 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 });
}
  1. 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"
    />
  );
}
  1. 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 defined or window is not defined. You imported @databrainhq/plugin/web at the top of a file. Import it inside useEffect in 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-dashboard does not exist on JSX.IntrinsicElements. Add this file, for example databrain.d.ts at the project root:

    import 'react';
    
    declare module 'react' {
      namespace JSX {
        interface IntrinsicElements {
          'dbn-dashboard': { [attr: string]: unknown };
          'dbn-metric': { [attr: string]: unknown };
        }
      }
    }
  • handleServerEvent never runs. Assign an inline arrow function. The element drops a named function.