samples-typescript

• Samples
  • Basic
  • API demos
    • Activity APIs and Design Patterns
    • Workflow APIs
    • Production APIs
    • Advanced APIs
  • Fullstack Apps
• Contributing
  • Upgrading the SDK version
  • Config files

Samples

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

• The fastest way to try these out is starting Temporal and running these samples in the browser:
  • Gitpod: One click to try (there is a good free tier)
  • GitHub Codespaces (if your org admin has enabled this) - 90 second video demo
• To run these samples locally, go through the prerequisites listed in our Getting Started docs.
• 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.
• Debugging: The replay-history sample shows how to retrieve Workflow Event History and debug it using the runReplayHistory Worker API (video).
• 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.
• Instrumentation: Use a winston logger to get logs out of all SDK components and get metrics and traces out of Rust Core.
• Protobufs: Use Protobufs.
• Custom Payload Converter: Customize data serialization by creating a PayloadConverter that uses EJSON to convert Dates, binary, and regexes.

Advanced APIs

• Interceptors
  • OpenTelemetry: Use the Interceptors feature to add OpenTelemetry metrics reporting to your workflows.
  • Query Subscriptions: Use Redis Streams, Immer, and SDK Interceptors to subscribe to Workflow state.
• gRPC calls: Make raw gRPC calls for advanced queries not covered by the WorkflowClient API.

Fullstack Apps

• DSL Control Flows:
  • YAML DSL Interpreter: demonstrates how to make workflows interpret a custom YAML based Domain Specific Language of your design.
  • XState Interpreter: demonstrates how to write a workflow that interprets XState state charts. Presented at the November 2021 meetup.
• 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.
• GraphQL:
  • Temporal + GraphQL: Expose Temporal Workflows in an Apollo GraphQL API
• Example Apps:
  • 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
  • Chatbot example with Slack/Discord: Walkthrough, Video, Code
  • Temporal + Remix Survey app: https://github.com/gustavofsantos/temporal-survey
  • URL Batch Scraping demo: https://github.com/andreasasprou/temporal-url-batch-scraping

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

shopt -s extglob
for f in !(monorepo-folders)/package.json; do jq '.dependencies.temporalio = "NEW_VERSION_HERE"' $f | sponge $f; done
jq '.devDependencies."@temporalio/client" = "NEW_VERSION_HERE"' package.json | sponge package.json;
jq '.dependencies."@temporalio/interceptors-opentelemetry" = "NEW_VERSION_HERE"' interceptors-opentelemetry/package.json | sponge interceptors-opentelemetry/package.json;
for f in monorepo-folders/packages/!(frontend-ui)/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.