dbos-typescript – Coding skill for AI agents

DBOS TypeScript Best Practices

Guide for building reliable, fault-tolerant TypeScript applications with DBOS durable workflows.

When to Use

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

| Priority | Category | Impact | Prefix |

|----------|----------|--------|--------|

| 1 | Lifecycle | CRITICAL | lifecycle- |

| 2 | Workflow | CRITICAL | workflow- |

| 3 | Step | HIGH | step- |

| 4 | Queue | HIGH | queue- |

| 5 | Communication | MEDIUM | comm- |

| 6 | Pattern | MEDIUM | pattern- |

| 7 | Testing | LOW-MEDIUM | test- |

| 8 | Client | MEDIUM | client- |

| 9 | Advanced | LOW | advanced- |

Critical Rules

Installation

Install a supported SDK version compatible with the existing application and pin it in the lockfile. For a new project, first verify the current official release:

npm install @dbos-inc/dbos-sdk@<verified-version>

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",
    systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
  });
  await DBOS.launch();
  await myWorkflow();
}

main().catch(error => { console.error(error); process.exitCode = 1; });

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

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

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

Limitations

• Examples are version-specific sketches; verify signatures and migration guidance against the installed SDK. Register workflows/steps before launch. Keep database credentials private.
• Step replay/retries can repeat external effects. Use stable provider-side idempotency keys and application transactions; a workflow ID alone does not guarantee a card is charged only once.
• Database reset, cancellation, resume and fork examples require an explicit target and authorization; they may destroy data, bypass queue limits or repeat effects.
• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.