Dbos Typescript

1---
2name: dbos-typescript
3description: DBOS TypeScript SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing TypeScript code with DBOS, creating workflows and steps, using queues, using DBOSClient from external applications, or building applications that need to be resilient to failures.
4risk: safe
5source: https://docs.dbos.dev/
6license: MIT
7metadata:
8  author: dbos
9  version: "1.0.0"
10  organization: DBOS
11  date: January 2026
12  abstract: Comprehensive guide for building fault-tolerant TypeScript applications with DBOS. Covers workflows, steps, queues, communication patterns, and best practices for durable execution.
13---
14 
15# DBOS TypeScript Best Practices
16 
17Guide for building reliable, fault-tolerant TypeScript applications with DBOS durable workflows.
18 
19## When to Use
20 
21Reference these guidelines when:
22- Adding DBOS to existing TypeScript code
23- Creating workflows and steps
24- Using queues for concurrency control
25- Implementing workflow communication (events, messages, streams)
26- Configuring and launching DBOS applications
27- Using DBOSClient from external applications
28- Testing DBOS applications
29 
30## Rule Categories by Priority
31 
32| Priority | Category | Impact | Prefix |
33|----------|----------|--------|--------|
34| 1 | Lifecycle | CRITICAL | `lifecycle-` |
35| 2 | Workflow | CRITICAL | `workflow-` |
36| 3 | Step | HIGH | `step-` |
37| 4 | Queue | HIGH | `queue-` |
38| 5 | Communication | MEDIUM | `comm-` |
39| 6 | Pattern | MEDIUM | `pattern-` |
40| 7 | Testing | LOW-MEDIUM | `test-` |
41| 8 | Client | MEDIUM | `client-` |
42| 9 | Advanced | LOW | `advanced-` |
43 
44## Critical Rules
45 
46### Installation
47 
48Always install the latest version of DBOS:
49 
50```bash
51npm install @dbos-inc/dbos-sdk@latest
52```
53 
54### DBOS Configuration and Launch
55 
56A DBOS application MUST configure and launch DBOS before running any workflows:
57 
58```typescript
59import { DBOS } from "@dbos-inc/dbos-sdk";
60 
61async function main() {
62  DBOS.setConfig({
63    name: "my-app",
64    systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
65  });
66  await DBOS.launch();
67  await myWorkflow();
68}
69 
70main().catch(console.log);
71```
72 
73### Workflow and Step Structure
74 
75Workflows are comprised of steps. Any function performing complex operations or accessing external services must be run as a step using `DBOS.runStep`:
76 
77```typescript
78import { DBOS } from "@dbos-inc/dbos-sdk";
79 
80async function fetchData() {
81  return await fetch("https://api.example.com").then(r => r.json());
82}
83 
84async function myWorkflowFn() {
85  const result = await DBOS.runStep(fetchData, { name: "fetchData" });
86  return result;
87}
88const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);
89```
90 
91### Key Constraints
92 
93- Do NOT call, start, or enqueue workflows from within steps
94- Do NOT use threads or uncontrolled concurrency to start workflows - use `DBOS.startWorkflow` or queues
95- Workflows MUST be deterministic - non-deterministic operations go in steps
96- Do NOT modify global variables from workflows or steps
97 
98## How to Use
99 
100Read individual rule files for detailed explanations and examples:
101 
102```
103references/lifecycle-config.md
104references/workflow-determinism.md
105references/queue-concurrency.md
106```
107 
108## References
109 
110- https://docs.dbos.dev/
111- https://github.com/dbos-inc/dbos-transact-ts
112