Next.js

Overview

This guide configures Workflow Studio for Next.js applications.

Two settings control behavior:

execution.mode controls where workflow functions execute (local or remote).
adapter mode controls ingress routing behavior (passthrough or proxy-trigger).

Mode matrix

execution.mode	adapter mode	Behavior
`remote`	`passthrough`	Application keeps standard `start(...)` routes. Execution runs on remote compute worker when production reroute env is set.
`remote`	`proxy-trigger`	Same remote execution target, plus optional app-host trigger/webhook proxy routes.
`local`	`passthrough`	Local/default execution behavior.
`local`	`proxy-trigger`	Local execution, with optional app-host trigger/webhook proxy routes.

Default remote setup

next.config.ts

import { withWorkflowStudioNext } from 'workflow-studio/next';

const nextConfig = {};

export default await withWorkflowStudioNext(nextConfig, {
  execution: { mode: 'remote' },
  mode: 'passthrough',
});

Set production reroute on the deployment environment:

WORKFLOW_TARGET_WORLD=workflow-studio/world-remote

Optional proxy-trigger routes

Use this only when you need app-owned trigger or webhook proxy endpoints.

next.config.ts

import { withWorkflowStudioNext } from 'workflow-studio/next';

const nextConfig = {};

export default await withWorkflowStudioNext(nextConfig, {
  execution: { mode: 'remote' },
  mode: 'proxy-trigger',
});

app/api/workflow/route.ts

import { proxyTriggerFromNext } from 'workflow-studio/next';

export async function POST(req: Request): Promise<Response> {
  const body = await req.json();
  const result = await proxyTriggerFromNext({
    payload: {
      workflowName: 'send-welcome-email',
      input: { userId: body.userId },
    },
  });
  return Response.json(result);
}

app/api/webhooks/[provider]/route.ts

import { proxyWebhookFromNext } from 'workflow-studio/next';

export async function POST(
  req: Request,
  { params }: { params: { provider: string } }
): Promise<Response> {
  const body = new Uint8Array(await req.arrayBuffer());
  return await proxyWebhookFromNext({
    provider: params.provider,
    body,
    headers: Object.fromEntries(req.headers.entries()),
  });
}

Security note

withWorkflowStudioNext stores helper defaults under workflowStudio config metadata. It does not write sensitive values to nextConfig.env.

Required production settings

WORKFLOW_TARGET_WORLD=workflow-studio/world-remote
WORKFLOW_COMPUTE_BASE_URL
WORKFLOW_COMPUTE_API_KEY