LearnAdd Causet to Next.js

Add Causet to Next.js

You can add Causet to an existing Next.js app by keeping your route handler and using it as a handoff point into Causet. The endpoint can stay synchronous from the client’s perspective. The workflow behind it becomes asynchronous.

Integration path: use @causet/sdk-next server helpers from Route Handlers and Server Actions. Point CAUSET_API_URL at your runtime — Causet Cloud for managed hosting, or a self-hosted Docker stack when you run one locally.

Submit intents from a Route Handler

// app/api/request-access/route.ts
import { serverEmitIntent } from '@causet/sdk-next/server';
 
export async function POST(req: Request) {
  const body = await req.json();
 
  try {
    const result = await serverEmitIntent(
      'lead_stream',
      body.email,
      'SUBMIT_LEAD',
      {
        email: body.email,
        company: body.company,
        name: body.name,
      },
    );
 
    if (!result.accepted) {
      return Response.json({ ok: false, message: result.error ?? 'Rejected' }, { status: 422 });
    }
 
    return Response.json({ ok: true, message: 'Request received' });
  } catch {
    // Fail closed, buffer, or fall back — see Production Rollout Checklist
    return Response.json({ ok: false, message: 'Unable to accept request' }, { status: 503 });
  }
}

Environment variables

# Server-only — never expose to the browser
CAUSET_API_URL=https://api.causet.cloud
CAUSET_PLATFORM=my-platform
CAUSET_APPLICATION=my-app
CAUSET_API_KEY=ck_live_xxx.secret

Runtime options: Causet Cloud is the managed hosted runtime (Early access). Self-hosted Docker is Coming soon. SDK packages are Preview. See What runs today? and Run Causet with a Local App.

Query from a Route Handler

// app/api/tickets/route.ts
import { serverRunQuery } from '@causet/sdk-next/server';
 
export async function GET() {
  const result = await serverRunQuery('open_tickets', { status: 'open' }, { limit: 20 });
  return Response.json(result);
}

Idempotency keys (webhooks)

serverEmitIntent does not accept an idempotency key — use createServerCausetClient when you need one:

import { createServerCausetClient } from '@causet/sdk-next/server';
 
const client = createServerCausetClient();
await client.init();
try {
  await client.emit(
    'lead_stream',
    leadId,
    'RECORD_CRM_ENRICHMENT',
    { crmLeadId: event.lead_id, providerEventId: event.id },
    event.id, // intent id / idempotency key
  );
} finally {
  client.destroy();
}

Client components — live entity state

'use client';
 
import { CausetProvider, useCausetEntity } from '@causet/sdk-next';
 
export function TicketDetail({ ticketId }: { ticketId: string }) {
  const state = useCausetEntity('ticket_stream', ticketId, true /* WebSocket */);
  if (!state) return <p>Loading…</p>;
  return <pre>{JSON.stringify(state, null, 2)}</pre>;
}

useCausetEntity(..., true) connects via WebSocket to wss://*.realtime.causet.cloud/ws and applies live patches. See Real-time Streams for subscription modes, sample responses, and SSE.

Retrofitting an existing route

The pattern above is the same handoff boundary described in the adoption guides:

Runnable reference: the inventory modernization demo (server/causet-adapter.mjs) — a production-style CausetClient adapter. See Examples.

Next steps

Install CausetQuickstart: Concert App