best-practices

226 notes in this subject, read out of this brain and free to use. This is page 4 of 4.

TypeScript SDK technical resources and community

Key resources include: TypeScript SDK Quickstart Setup Guide, TypeScript API Documentation at typescript.temporal.io, TypeScript SDK Code Samples on GitHub at temporalio/samples-typescript, TypeScript SDK GitHub repository at temporalio/sdk-typescript, and Temporal 101 in TypeScript Free Course at learn.temporal.io. Community resources include Temporal TypeScript Community Slack and TypeScript SDK Forum.

Recommended setup for TypeScript projects

Projects created with @temporalio/create include recommended TypeScript and ESLint configurations. For projects that incrementally added Temporal to an existing app, setting up linting and types is recommended because it helps catch bugs before production and improves development feedback loop. A reference .eslintrc file is available in the temporalio/samples-typescript repository.

Recommended ESLint configuration for TypeScript

If incrementally adding Temporal to an existing app, use linting and types to catch bugs before production. The recommended .eslintrc configuration is available in the samples-typescript repository and can be customized for project needs.

Create new TypeScript project with scaffold

Use 'npx @temporalio/create@latest ./your-app' to create a new Temporal project with the recommended configuration for TypeScript, ESLint, and other development tools.

TypeScript SDK works with JavaScript

The TypeScript SDK is designed with a TypeScript-first developer experience but works equally well with JavaScript code.

ECMAScript module configuration for pure ESM dependencies

To use pure ESM dependencies like node-fetch@3 in a Temporal TypeScript project, set 'type': 'module' in package.json, configure tsconfig.json to output in esnext format, and include the .js file extension in import statements.

Workflow ID best practices

When starting a workflow, use a meaningful business ID for the workflowId, such as customerId or transactionId, rather than a random value.

All interceptor methods are optional

When implementing any interceptor interface, all methods are optional. The implementor chooses which specific methods to intercept based on their use case.

Interceptors overview and types

Interceptors are SDK hooks that intercept inbound and outbound Temporal calls to apply shared behavior across many calls, such as tracing and authorization, before calls reach application code and after they return. There are two main types: outbound interceptors wrap network calls running before and after they reach the network, and inbound interceptors run after the network hop, wrapping application code.

Interceptor chain execution model

Interceptors run as a chain where each interceptor wraps the entire inner call. Code runs before the call, invokes next to execute the rest of the chain, and then runs after the call completes. This allows you to inspect or modify both input and result, handle errors, and perform side effects at either stage.

Register interceptors via Plugin

Interceptors can be registered through a Plugin if building a reusable library or wanting to bundle interceptors with other primitives. This approach allows for better modularity and code organization.

Actively tune worker options instead of relying on defaults

Each SDK provides default slot counts, but Temporal recommends actively tuning these values for your workload rather than relying on the defaults.

Use fixed-size suppliers for predictable per-task consumption

Scenarios with tasks that have variable or very high per-task resource needs should rely on fixed-size suppliers and manual tuning rather than resource-based suppliers.

When to use mTLS certificates vs API keys

If your organization requires mutual authentication and stronger cryptographic guarantees, use mTLS certificates to authenticate Temporal clients to Temporal Cloud and use API keys for automation, because the Temporal Cloud Operations API and Terraform provider only support API key authentication. Unlike API keys tied to users or service accounts, mTLS certificate authentication is not tied to Temporal Cloud RBAC identities. Namespace access is based on CA trust, with optional Certificate Filters to narrow access by Common Name.

Credential rotation end-to-end process

The high-level end-to-end credential rotation process consists of five steps: (1) Generate new credentials by creating new certificates or API keys in Temporal Cloud before the current ones expire, (2) Support dual credentials by updating Temporal Cloud to support both old and new credentials, (3) Migrate Workers by transitioning Worker applications from old credentials to new credentials, (4) Validate connectivity by confirming all Workers can authenticate and business processes operate normally with new credentials, (5) Remove old credentials by removing old certificates and API keys from your secrets provider after confirming successful migration.

Default authentication method recommendation

By default, teams should use API keys with service accounts for both Temporal client connections and automation operations. API keys are generally easier to set up and rotate than mTLS certificates, and service accounts let you assign account-level and namespace-level roles.

Service Account best practices

Create one Service Account per service or worker deployment, not one shared Service Account for an entire team. Use account-level Service Accounts only when a service genuinely needs cross-Namespace or account-wide access. Prefer Namespace-scoped Service Accounts when a service should only access one Namespace. Grant Service Accounts namespace-level access only to the specific Namespaces they need. This approach gives cleaner ownership, easier rotation, and better auditability than sharing a single machine identity across multiple services.

Align credential boundaries with Namespace boundaries

The way you partition Namespaces should usually match the way you partition machine identities. If multiple services share a Namespace, you may still want one Service Account per service so that each deployment can rotate credentials independently. If you split workloads into separate Namespaces for security, capacity, or team ownership reasons, those Namespaces should usually have separate Service Accounts and API keys as well. If you use Namespace-per-tenant isolation, expect your credential model and RBAC model to become correspondingly more granular.

Certificate management tools and providers

For mTLS implementations, using Let's Encrypt is not recommended, as it is designed primarily for public-facing services and lacks support for internal certificate requirements. Valid options for managing certificates include vendor solutions such as AWS Private CA, Sectigo, Microsoft Certification Authority, or DigiCert for their robust integration and lifecycle features. Alternatively, self-signed certificates are a valid and commonly used approach, even in production environments. Tools like OpenSSL, CFSSL, or step CLI can help generate and manage certificates effectively.

Certificate Filters for shared CA access control

Certificate Filters provide an additional way of validating the client certificate presented during client authentication. When using the same CA for multiple environments like dev and prod, give certificates a common name that matches the namespace. You can then leverage Certificate Filters to prevent access to production environments. This prevents production namespace access when using a shared CA.

Transient failures definition and retry strategy

A transient failure is a one-off event that resolves on its own without intervention, such as a Worker making a network request at the moment an administrator replaces a network cable. The cause is unlikely to affect future requests. Transient failures are resolved by retrying the operation shortly after the failure. Temporal's default Retry Policy handles transient failures automatically.

Intermittent failures definition and retry strategy

An intermittent failure is one that recurs but resolves over time. For example, a service using rate limiting will reject requests once the threshold is reached, but will accept requests again after the rate limiter resets. Intermittent failures require retries spaced out over a longer period. Configure your Retry Policy with an appropriate backoffCoefficient and maximumInterval to avoid overwhelming the failing service.

Permanent failures definition and handling

A permanent failure is one that will recur indefinitely until the cause is fixed. For example, a request that fails due to an invalid email address will continue to fail no matter how many times the operation retries. The only resolution is to correct the email address. Permanent failures cannot be resolved through retries and require different input data, a code fix, or some external intervention. Mark these errors as non-retryable to fail fast instead of consuming resources on retries that will not succeed.

Use cases for non-retryable errors

Mark errors as non-retryable for situations including: invalid input data such as malformed email addresses, negative payment amounts, or missing required fields; business rule violations such as a customer outside the service area, an order exceeding credit limits, or an expired promotion code; authorization failures where the caller does not have permission to perform the operation; and data validation errors such as a referenced record not existing or data failing integrity checks.

Two ways to mark errors as non-retryable

Errors can be marked as non-retryable in two ways: (1) In the Activity (implementer decides) by setting the non_retryable flag when throwing an Application Failure. This enforces the constraint for all callers and is used when the Activity implementer knows that the error can never be resolved through retries. (2) In the Retry Policy (caller decides) by adding the error type to the Retry Policy's list of non-retryable error types. This lets different Workflows make different decisions about the same Activity and is used when the decision depends on the caller's business logic.

Preserve retryability when wrapping errors

When an Activity returns an error, the SDK checks the outermost error type to determine retryability. If you catch a non-retryable Application Failure and re-throw it wrapped in a generic language error, the non_retryable flag is lost and the Activity will be retried. To add context to an error while preserving its retry behavior, wrap it in another Application Failure with the same non_retryable flag. Do not wrap Application Failures in generic language errors.

Outermost error type determines retryability

The SDK checks the outermost error type to determine whether an Activity should be retried. This means that error type wrapping significantly affects retry behavior, and generic error wrappers around Application Failures can cause non-retryable errors to be retried unexpectedly.

When to use non-retryable errors sparingly

In most cases, let the Retry Policy handle retry limits through timeouts and maximum attempts. Reserve non_retryable for cases where retrying is guaranteed to be futile.

Saga pattern for compensation

The Saga pattern coordinates a sequence of operations where each step has a compensating action that reverses its effects. When a multi-step process fails partway through, previous steps may need to be undone. If any step fails, the compensating actions for previously completed steps execute in reverse order.

Temporal Platform Hub template

Use the Temporal Platform Hub template (available at go.temporal.io/platform-hub) as a foundation and starting point to bootstrap your internal Temporal knowledge hub.

Keep knowledge hub content current

Review each page at least quarterly with an assigned review owner and date. Update the knowledge hub whenever the organization changes its Temporal architecture, updates deployment tooling, or modifies its shared responsibility model. Remove or archive content that no longer applies, as outdated documentation is worse than no documentation.

Make knowledge hub discoverable

Register a short URL (for example, go/temporal) that redirects to the knowledge hub. Pin the link in Temporal-related communication channels like Slack or Microsoft Teams. When answering questions in Slack, respond with a link to the relevant knowledge hub page instead of re-explaining inline to build the habit of checking the hub first.

Knowledge hub ownership and maintenance

Designate a Platform team or developer experience team to own the knowledge hub, responsible for initial content creation, ongoing maintenance, and reviewing contributions from application teams.

What not to include in a knowledge hub

A knowledge hub should not duplicate Temporal's official documentation including SDK API references, concept explanations, or release notes. Instead, link to the official docs and reserve the knowledge hub for organization-specific decisions, conventions, and operational procedures that Temporal's public documentation does not cover.

Knowledge hub success metrics: traffic and page views

Knowledge Hub traffic should show steady or growing page views per month. Declining traffic on a page may indicate it is outdated; high traffic with high bounce rates may indicate the page is not answering the question.

Knowledge hub success metrics: support question rate

Support question rate to the Platform team should decrease from 20-30+ questions per week to fewer than 5 per week. This measures self-service resolution and shows whether developers are finding answers in the knowledge hub instead of asking the Platform team.

Knowledge hub success metrics: time to production Workflow

Time to Workflow in production measures the gap between development and delivering value. Target is under 2 weeks when developers follow documented self-service provisioning, compared to weeks or months without clear Namespace provisioning and deployment processes.

Knowledge hub success metrics: time to first Workflow

Time to first Workflow is a key metric for knowledge hub effectiveness. Target is under 30 minutes for developers following a single getting started guide, compared to days or weeks before having a centralized knowledge hub. This measures onboarding friction.

Operate section: troubleshooting and support

The Operate section should include troubleshooting and escalation content covering observability tools, runbooks for common issues, escalation paths, SLAs, and example alert definitions; and support and FAQs documenting support tier, ticket submission process, Temporal account contacts, expert-led session types, and frequently asked questions.

Ship section: architecture, standards, and design patterns

The Ship section should document Namespace conventions, connectivity requirements, Worker deployment standards, billable Actions and storage tiers, cost-saving tips, an ownership matrix between Platform and Application teams covering IAM, infrastructure, development, deployment, observability and operations, and curated Workflow patterns with code samples.

Build section: getting started and learning paths

The Build section should include a getting started guide (30-minute quickstart covering environment setup, starter template, and running a first Workflow locally and on Temporal Cloud) and learning paths providing self-paced courses from foundational to advanced topics, tailored by persona, with links to Temporal's free training.

Evaluate section: Temporal overview and decision framework

The Evaluate section should include a Temporal overview explaining what Temporal is, why the organization chose it, and business value metrics; and a decision framework with qualifying questions, good and bad use cases, and alternative recommendations. This section helps developers determine whether Temporal fits their problem.

Knowledge hub sections by developer journey stage

A Temporal knowledge hub should be organized into four main sections based on where developers are in their journey: Evaluate (understanding Temporal fit), Build (getting started and learning), Ship (production standards and deployment), and Operate (incident self-service and troubleshooting).

Use ActiveModel for translating to/from existing models

When working with Temporal workflows and activities alongside existing Rails models, use ActiveModel objects to translate data between Temporal-specific models and existing ORM models.

Do not reuse ActiveRecord models for Temporal workflows/activities

For ActiveRecord or other ORM models used for different purposes, it is not recommended to try to reuse them as Temporal models. Model purposes eventually diverge and models for Temporal workflows/activities should be specific to their use for clarity and compatibility reasons. Many Ruby ORMs perform lazy operations that provide unclear serialization semantics. Instead, create models specific for Workflows/Activities and translate to/from existing models as needed.

Worker tuning best practices

Worker tuning best practices include: scale test before production to validate configuration under realistic load, consider infrastructure factors like network latency and database performance, tune incrementally and observe metrics before making additional adjustments, and identify bottlenecks using the theory of constraints since improving non-bottleneck resources won't improve overall throughput.

Give your agent this brain