App Router

Next.js

The cleanest Next.js integration is a server-owned submission endpoint. Your page or component collects form input, while a route handler or server action forwards the payload to 1DB with the API key.

Route Handler Pattern

app/api/lead/route.ts
export async function POST(request: Request) {
  const data = await request.json();

  const response = await fetch("https://your-deployment.convex.site/v1/leads", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.ONEDB_API_KEY!,
    },
    body: JSON.stringify({
      formSlug: "demo-request",
      ...data,
    }),
  });

  return Response.json(await response.json(), { status: response.status });
}

Server Action Pattern

app/actions.ts
"use server";

export async function submitLead(formData: FormData) {
  const payload = Object.fromEntries(formData.entries());

  const response = await fetch("https://your-deployment.convex.site/v1/leads", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.ONEDB_API_KEY!,
    },
    body: JSON.stringify({
      formSlug: "newsletter",
      ...payload,
    }),
  });

  if (!response.ok) {
    throw new Error("Lead submission failed");
  }
}

Deployment Checklist

  • Set `ONEDB_API_KEY` in every deployed environment.
  • Keep the key out of `NEXT_PUBLIC_` variables.
  • Return validation errors to the form with clear user messaging.
  • Track the source form via `formSlug` for reporting and routing.

React Guide

Pair this route handler pattern with a typed React form component.

Webhooks Guide

Trigger downstream automations after a lead is accepted.