| name | dbos-typescript |
| description | Guide for building reliable, fault-tolerant TypeScript applications with DBOS durable workflows. Use when adding DBOS to existing TypeScript code, creating workflows and steps, or using queues for con |
| category | Development & Code Tools |
| source | antigravity |
| tags | ["typescript","api","ai","workflow"] |
| url | https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/dbos-typescript |
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
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
Limitations
- 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.
