samples-typescript

• Samples
  • Basic
  • API demos
    • Activity APIs and Design Patterns
    • Workflow APIs
    • Production APIs
    • Advanced APIs
  • Apps
• Contributing
  • Config files

Samples

Each directory in this repo is a sample Temporal project built with the TypeScript SDK.

To run these samples locally, go through the prerequisites listed in our Getting Started docs.

To check them out without installing locally, you can try:

• 
• GitHub Codespaces (if you have access)

To scaffold a new project from one of these samples, run:

npx @temporalio/create@latest my-project-name
# or npx @temporalio/create@latest my-project-name --sample sample-name

Basic

• Basic hello world: Simple example of a Workflow Definition and an Activity Definition.
  • Variant: Basic hello world with mTLS shows how to connect to your Temporal Cloud namespace with mTLS authentication.
• Pure ES Modules: Configure Temporal with TypeScript and Pure ESM.
• JavaScript: The Hello World sample in JavaScript instead of TypeScript.

API demos

Activity APIs and Design Patterns

• Activities Examples:
  • makeHTTPRequest: Make an external HTTP request in an Activity (using axios)
  • cancellableFetch: Make a cancellable HTTP request with cancellationSignal.
• Activity Cancellation and Heartbeating: Heartbeat progress for long running activities and cancel them.
• Dependency Injection: Share dependencies between activities (for example, when you need to initialize a database connection once and then pass it to multiple activities).
• Sticky Activities: Dynamically assign task queue names to ensure activities execute sequentially on the same machine (eg for CI/CD, file processing workflows).

Workflow APIs

• Timers:
  • The progress example demonstrates how to use the sleep function from @temporalio/workflow.
  • Timer Examples:
    • Send a notification to the customer if their order is taking longer than expected (using a Promise.race between the order activity and sleep).
    • Create an UpdatableTimer that can be slept on, and at the same time, have its duration updated via Signals.
• Signals and Triggers:
  • The Signals and Queries example demonstrates the usage of Signals, Queries, and Workflow Cancellation.
  • Async activity completion: Example of an Expense reporting Workflow that communicates with a server API. Shows how to kick off a Workflow and manually complete it at an arbitrarily later date.
• Cron Workflows: Schedule a cron job.
• Child Workflows: Start and control Child Workflows.
• Infinite Workflows: Use the continueAsNew API for indefinitely long running Workflows.
• Search Attributes: Set up Search Attributes (an experimental feature for now).

Production APIs

• Production Build: Build code in advance for faster Worker startup times.
• Patching: Patch in new Workflow code when making updates to Workflows that have executions in progress in production.
• Logging: Use Sinks to extract data out of Workflows for logging/metrics/tracing purposes.

Advanced APIs

• Interceptors
  • OpenTelemetry: Use the Interceptors feature to add OpenTelemetry metrics reporting to your workflows. ⚠️ This sample is broken for now.
  • Query Subscriptions: Use Redis Streams, Immer, and SDK Interceptors to subscribe to Workflow state.

Full Apps

• Next.js:
  • One-click e-commerce: Buy an item with one click, and the Workflow will wait 5 seconds to see if the user cancels before it executes the order.
  • Food Delivery: https://github.com/lorensr/food-delivery
• Subscription Workflow example: https://github.com/temporalio/subscription-workflow-project-template-typescript/ (useful to compare with other SDKs)
• E-commerce example: https://github.com/vkarpov15/temporal-ecommerce-ts
• XState example: https://github.com/Devessier/temporal-electronic-signature

Contributing

External contributions are very welcome! 🤗 (Big thank you to those who have already contributed 🙏)

Before submitting a major PR, please find consensus on it in Issues.

To start, run these commands in the root directory:

npm install
npm run prepare
npm run bootstrap

Prettier and ESLint are run on each commit, but you can also run them manually:

npm run format
npm run lint

Upgrading the SDK version

for f in */package.json; do jq '.dependencies.temporalio = "NEW_VERSION_HERE"' $f | sponge $f; done

Config files

Also on each commit, config files from .shared/ are copied into each sample directory, overwriting the sample directory's config files (with a few exceptions listed in .scripts/copy-shared-files.mjs). So if you're editing config files, you usually want to be editing the versions in .shared/.

The .post-create file is a chalk template that is displayed in the command line after someone uses npx @temporalio/create. If you're adding a sample that requires different instructions from the default message, then add your sample name to POST_CREATE_EXCLUDE and your message template to your-sample/.post-create.