DBOS TypeScript Best Practices Skill

DBOS TypeScript Best Practices

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

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

| 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

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

main().catch(console.log);

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

Agent Skills: DBOS TypeScript Best Practices

Install this agent skill to your local

Skill Files