@rawdash/nextjs

Rawdash SDK for the Next.js App Router.

What it is

@rawdash/nextjs extends @rawdash/client with Next.js-specific behavior: the http function tags widget requests with Next.js cache tags so they can be invalidated via revalidateTag, and createRawdashClient wraps a data source so triggerSync automatically revalidates widget data in Server Components after the sync completes.

Use this package when your rawdash server runs separately from your Next.js app. For an in-process setup (engine in the same Next.js process), use @rawdash/client's inProcess directly.

Install

npm install @rawdash/nextjs

Requires Next.js 14+.

Quick example

// lib/rawdash.ts
import { createRawdashClient, http } from '@rawdash/nextjs';

export const rawdash = createRawdashClient(
  http({
    baseUrl: process.env.RAWDASH_URL!,
    apiKey: process.env.RAWDASH_API_KEY,
  }),
);

// app/dashboard/page.tsx
import { rawdash } from '@/lib/rawdash';

export default async function DashboardPage() {
  const widgets = await rawdash.getWidgets('engineering');

  return (
    <div>
      {widgets.map((w) => (
        <div key={w.id}>{/* render widget */}</div>
      ))}
    </div>
  );
}

In app/actions.ts:

'use server';

import { rawdash } from '@/lib/rawdash';

export async function syncDashboard() {
  // Triggers sync, polls /sync/state until it settles (succeeded or failed),
  // then calls revalidateTag('rawdash') so the Server Components re-fetch
  // widget data on next request. Throws on sync failure.
  await rawdash.triggerSync();
}

Don't block SSR on a sync. triggerSync (and ensureFresh) wait for the sync to settle, which can take up to ~30s. Calling either from a Server Component would block every page render. Use them in Server Actions, cron-triggered routes, or webhooks — and let pages render against whatever's cached.

Switching between in-process and HTTP

// lib/rawdash.ts
import { inProcess } from '@rawdash/client';
import { createRawdashClient } from '@rawdash/nextjs';
import { http } from '@rawdash/nextjs';

const source =
  process.env.NODE_ENV === 'production'
    ? http({ baseUrl: process.env.RAWDASH_URL! })
    : inProcess(localEngine);

export const rawdash = createRawdashClient(source);

API

http(options): DataSource

Next.js-aware variant of http from @rawdash/client. Adds the 'rawdash' cache tag to all widget fetch requests so they can be invalidated with revalidateTag('rawdash'). Accepts the same options as @rawdash/client's http.

createRawdashClient(dataSource): DataSource

Wraps any DataSource with Next.js behavior: triggerSync polls /sync/state until the sync settles (transitions to succeeded or failed), then calls revalidateTag('rawdash') to bust Server Component caches. Throws on failed or if the sync doesn't settle within 30s. ensureFresh is also tagged to revalidate after a sync. All other methods are passed through unchanged.

Links

• rawdash docs
• GitHub
• Issues

License

Apache-2.0