DBOS TypeScript Best Practices

Guide for building reliable, fault-tolerant TypeScript applications with DBOS durable workflows. Targets DBOS TypeScript 5.x (@dbos-inc/dbos-sdk). If a project is on 4.x or uses removed APIs (new WorkflowQueue, @DBOS.scheduled/DBOS.registerScheduled, partitionQueue, priorityEnabled, @DBOS.requiredRole, dbos-config.yaml-based config), see references/advanced-upgrading.md.

When to Apply

Reference these guidelines when:

• Adding DBOS to existing TypeScript code
• Creating workflows and steps
• Using queues for concurrency control
• Implementing workflow communication (events, messages, streams)
• Configuring and launching DBOS applications
• Using DBOSClient from external applications
• Testing DBOS applications

Rule Categories by Priority

Critical Rules

Installation

Always install the latest version of DBOS:

npm install @dbos-inc/dbos-sdk@latest

DBOS Configuration and Launch

A DBOS application MUST configure and launch DBOS before running any workflows:

import { DBOS } from "@dbos-inc/dbos-sdk";

async function main() {
  DBOS.setConfig({
    name: "my-app",
    applicationVersion: "0.1.0",
    systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
  });
  await DBOS.launch();
  await myWorkflow();
}

main().catch(console.log);

When creating a new application, set applicationVersion to "0.1.0". If omitted, DBOS derives an opaque hash from workflow source code. When editing an existing application, leave its configured version alone — changing it is a deployment decision (see references/advanced-versioning.md).

Workflow and Step Structure

Workflows are comprised of steps. Any function performing complex operations or accessing external services must be run as a step using DBOS.runStep:

import { DBOS } from "@dbos-inc/dbos-sdk";

async function fetchData() {
  return await fetch("https://api.example.com").then(r => r.json());
}

async function myWorkflowFn() {
  const result = await DBOS.runStep(fetchData, { name: "fetchData" });
  return result;
}
const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);

Key Constraints

• Do NOT call, start, or enqueue workflows from within steps
• Do NOT use threads or uncontrolled concurrency to start workflows - use DBOS.startWorkflow or queues
• Workflows MUST be deterministic - non-deterministic operations go in steps
• Do NOT modify global variables from workflows or steps
• Register queues (DBOS.registerQueue) and create schedules (DBOS.applySchedules/DBOS.createSchedule) AFTER DBOS.launch() - they are stored in the system database
• Steps are only durable when called from a workflow; outside a workflow they run as plain function calls
• Connecting to DBOS Conductor (conductorKey, or deploying to DBOS Cloud), and auto-upgrade (autoUpgrade) require installing @dbos-inc/dbos-enterprise at the same minor version as @dbos-inc/dbos-sdk; auto-upgrade also needs an entitled key (conductorKey, or transactEnterpriseKey in development). See references/lifecycle-config.md
• Do NOT set enablePatching (deprecated in 5.4): DBOS.patch() and DBOS.deprecatePatch() work without it. To let patched code recover older workflows, pin applicationVersion or use auto-upgrade (see references/advanced-patching.md)

How to Use

Read individual rule files for detailed explanations and examples:

references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md
references/advanced-upgrading.md
references/advanced-shared-database.md

If multiple applications share one system database, always set applicationName on DBOSClient and see references/advanced-shared-database.md.

References

• https://docs.dbos.dev/
• https://github.com/dbos-inc/dbos-transact-ts