API Reference

Package exports

The package provides several entry points:

Main export (next-workflow-builder)

import nextWorkflowBuilder from "next-workflow-builder";
import type { NextWorkflowBuilderConfig, WithNextWorkflowBuilder } from "next-workflow-builder";

nextWorkflowBuilder(config?)

The default export. Returns a function that wraps your Next.js config.

const withNextWorkflowBuilder = nextWorkflowBuilder({
  authOptions: { /* Better Auth options */ },
  debug: true,
});
const nextConfig = withNextWorkflowBuilder({ /* Next.js config */ });

Parameters: NextWorkflowBuilderConfig (see Configuration) Returns: (nextConfig: NextConfig) => NextConfig

API export (next-workflow-builder/api)

export { GET, POST, PUT, PATCH, DELETE, OPTIONS } from "next-workflow-builder/api";

Re-export these HTTP method handlers in your catch-all API route (app/api/[[...slug]]/route.ts). They handle all workflow, auth, integration, and API key endpoints.

Server exports (next-workflow-builder/server)

import {
  auth,
  db,
  fetchCredentials,
  generateWorkflowMetadata,
  withStepLogging,
  generateId,
  encrypt,
  decrypt,
  getErrorMessage,
  getErrorMessageAsync,
  discoverPlugins,
  // Database tables
  users,
  sessions,
  accounts,
  verifications,
  workflows,
  integrations,
  workflowExecutions,
  workflowExecutionLogs,
  apiKeys,
} from "next-workflow-builder/server";
 
import type { StepInput, ResultComponentProps } from "next-workflow-builder/server";

auth

The Better Auth instance. Use for session management:

const session = await auth.api.getSession({ headers: request.headers });

db

The Drizzle ORM database instance with the full schema:

const userWorkflows = await db.query.workflows.findMany({
  where: eq(workflows.userId, userId),
});

fetchCredentials(integrationId)

Fetch and decrypt credentials for an integration. Used in step handlers.

const credentials = await fetchCredentials(input.integrationId);

Parameters: string - Integration ID Returns: Promise<Record<string, string>>

generateWorkflowMetadata(props)

Generate dynamic page metadata for workflow pages. Export as generateMetadata in your catch-all page:

export { generateWorkflowMetadata as generateMetadata } from "next-workflow-builder/server";

withStepLogging(input, fn)

Wrap a step handler function with execution logging for the workflow runs panel.

return withStepLogging(input, () => stepHandler(input, credentials));

Parameters:

• input - StepInput object
• fn - () => Promise<T> - The step handler function

Returns: Promise<T>

encrypt(text) / decrypt(text)

Encrypt and decrypt integration credentials stored in the database.

generateId()

Generate a unique nanoid-based identifier for database records.

getErrorMessage(error) / getErrorMessageAsync(error)

Extract a human-readable error message from unknown error types.

Database tables

All Drizzle ORM table schemas are exported directly: users, sessions, accounts, verifications, workflows, integrations, workflowExecutions, workflowExecutionLogs, apiKeys.

Plugin exports (next-workflow-builder/plugins)

import {
  registerIntegration,
  registerCodegenTemplates,
  registerOutputDisplayConfigs,
  getIntegration,
  getAllIntegrations,
  getIntegrationTypes,
  getAllActions,
  getActionsByCategory,
  findActionById,
  getCodegenTemplate,
  getOutputDisplayConfig,
  computeActionId,
  parseActionId,
  flattenConfigFields,
  isFieldGroup,
  getIntegrationLabels,
  getIntegrationDescriptions,
  getSortedIntegrationTypes,
  getAllDependencies,
  getDependenciesForActions,
  getAllEnvVars,
  getPluginEnvVars,
  getCredentialMapping,
  generateAIActionPrompts,
} from "next-workflow-builder/plugins";

registerIntegration(plugin)

Register a plugin with the integration registry.

registerIntegration(myPlugin);

Parameters: IntegrationPlugin - The plugin definition object

registerCodegenTemplates(templates)

Register code generation templates. Called from auto-generated lib/codegen-registry.ts.

registerOutputDisplayConfigs(configs)

Register output display configurations. Called from auto-generated lib/output-display-configs.ts.

Registry query functions

Utility functions

Client export (next-workflow-builder/client)

import {
  Layout,
  WorkflowPage,
  WorkflowEditor,
  isAiGatewayManagedKeysEnabled,
  isAiGatewayManagedKeysEnabledClient,
} from "next-workflow-builder/client";

See Components for detailed component documentation.

Types

IntegrationPlugin

Full plugin definition. See Creating Plugins for field details.

PluginAction

Action definition within a plugin.

ActionConfigField

Config field definition. Can be ActionConfigFieldBase or ActionConfigFieldGroup.

ActionWithFullId

A PluginAction extended with id (full action ID) and integration (integration type).

OutputField

type OutputField = {
  field: string;
  description: string;
};

OutputDisplayConfig

type OutputDisplayConfig =
  | { type: "image" | "video" | "url"; field: string }
  | { type: "component"; component: React.ComponentType<ResultComponentProps> };

StepInput

Base input type for step handlers. Extend this for your step’s specific inputs.

NextWorkflowBuilderConfig

type NextWorkflowBuilderConfig = {
  debug?: boolean;
  authOptions?: Record<string, unknown>;
};

Built-in API routes

All routes are relative to the /api base path.

Authentication

Workflows

Executions

Integrations

API Keys