Implement DBOS TypeScript Best Practices
Best-practice rules for building fault-tolerant TypeScript apps with DBOS durable workflows, steps, queues, and client usage.
Why it matters
Build robust and fault-tolerant TypeScript applications using DBOS durable workflows. This asset provides guidelines for creating reliable workflows, managing concurrency, and ensuring deterministic operations.
Outcomes
What it gets done
Apply best practices for DBOS configuration and application launch.
Structure workflows and steps for optimal performance and reliability.
Implement effective concurrency control using queues and workflow communication.
Write deterministic workflows and handle non-deterministic operations within steps.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/ag-dbos-typescript | bash Overview
DBOS TypeScript Best Practices
A prioritized rule set for DBOS TypeScript applications covering lifecycle configuration, workflow and step structure, queue-based concurrency, communication, and client usage. Anchored by two literal code patterns for launching DBOS and defining a step-based workflow. Reference when adding DBOS to a TypeScript codebase, structuring workflows and steps, or using queues, communication, or DBOSClient - the hard constraints on workflow determinism and step isolation apply every time.
What it does
This skill is a rule-based reference guide for building reliable, fault-tolerant TypeScript applications on top of DBOS durable workflows. Rather than a single tutorial, it organizes guidance into nine prioritized rule categories, each with its own file prefix: Lifecycle (lifecycle-) and Workflow (workflow-) rated CRITICAL impact, Step (step-) and Queue (queue-) rated HIGH impact, Communication (comm-) and Pattern (pattern-) rated MEDIUM impact, Client (client-) also MEDIUM, Testing (test-) rated LOW-MEDIUM, and Advanced (advanced-) rated LOW. This priority ordering signals where to focus first: getting application lifecycle and workflow structure right matters more than, say, advanced patterns or test setup.
Two concrete code patterns anchor the critical rules. First, 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);
Second, workflows are composed of steps: any function doing complex work or calling an external service must run inside DBOS.runStep, and the containing workflow function itself is registered via DBOS.registerWorkflow. These two patterns map directly onto the two CRITICAL-impact categories - Lifecycle governs the configure-and-launch sequence, Workflow governs how workflow and step functions are structured and registered - which is why the guide places installation and configuration under its "Critical Rules" section rather than treating them as incidental setup steps.
When to use - and when NOT to
Reach for these rules when adding DBOS to existing TypeScript code, creating workflows and steps, using queues for concurrency control, implementing workflow communication via events, messages, or streams, configuring and launching a DBOS application, calling DBOSClient from an external application, or writing tests for DBOS applications. The guide is built around a small set of hard constraints that should not be violated: never call, start, or enqueue a workflow from within a step; never use threads or uncontrolled concurrency to start workflows - use DBOS.startWorkflow or queues instead; workflows must be deterministic, with any non-deterministic operation pushed into a step; and neither workflows nor steps should modify global variables.
Inputs and outputs
Installation is a single package add, always pinned to the latest release:
npm install @dbos-inc/dbos-sdk@latest
Inputs are the application's own workflow and step function definitions plus a systemDatabaseUrl for DBOS's durability layer; output is a running, fault-tolerant DBOS application whose workflow state survives restarts.
Integrations
For implementation detail beyond the summarized rules, the skill points to dedicated reference files - lifecycle-config.md, workflow-determinism.md, and queue-concurrency.md - plus the official DBOS documentation and the dbos-transact-ts GitHub repository.
Who it's for
TypeScript developers building or maintaining DBOS-based applications who need a fast, priority-ordered checklist of lifecycle, workflow, step, queue, communication, and client rules rather than reading the full DBOS documentation end to end.
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.