eslint-plugin-temporal weekly downloads statistics

eslint-plugin-temporal

ESLint plugin for the Temporal TypeScript SDK. Provides rules to enforce best practices and prevent common mistakes across workflows, activities, workers, and clients.

Installation

Requirements:

• Node.js 18.18.0 or higher • ESLint 9.0.0 or higher (flat config) • TypeScript 5.0.0 or higher

Quick Start

Add the plugin to your eslint.config.js:

That's it! The recommended config automatically detects the Temporal context (workflow, activity, worker, or client) based on your imports and applies the appropriate rules.

How Auto-Detection Works

The plugin detects context using a priority system:

1. Import-based detection (most reliable): • import { proxyActivities } from '@temporalio/workflow' → workflow rules apply • import { Context } from '@temporalio/activity' → activity rules apply • import { Worker } from '@temporalio/worker' → worker rules apply • import { Client } from '@temporalio/client' → client rules apply • import { TestWorkflowEnvironment } from '@temporalio/testing' → test context (relaxed rules)

2. File path detection (fallback): • /workflows/ → workflow rules • /activities/ → activity rules • /worker/ or /workers/ → worker rules • /client/ or /clients/ → client rules

3. Unknown context: Only shared/universal rules apply

Advanced: Explicit File Patterns

For projects with non-standard directory structures, you can still use explicit file patterns:

You can also keep auto-detection and customize the patterns with settings.temporal.filePatterns:

Configurations

| Configuration | Description |

| recommended | All rules with auto-detection. Rules apply based on detected context. | | workflow | Strict determinism rules. Use with explicit files pattern for manual config. | | activity | Retry safety rules. Use with explicit files pattern for manual config. | | worker | Clean bootstrap rules. Use with explicit files pattern for manual config. | | client | Client code rules. Use with explicit files pattern for manual config. | | strict | All rules enabled as errors. For maximum enforcement. |

Documentation

• Rule docs: documentation/rules/ • Settings: documentation/settings.md • Configs: documentation/configs.md • Docs consistency: bun run docs:check

Docs contribution

When you add or rename rules, regenerate the docs and keep the README rule list in sync. Run bun run docs:generate followed by bun run docs:check before committing to catch missing or extra docs.

Rules

All rules are included in both recommended and strict presets. The recommended preset uses a mix of warn and error severities, while strict sets all rules to error.

Workflow Rules

| Rule | Description | Fixable | Recommended |

| workflow-activity-timeout-duration-format | Enforce consistent duration literal format for activity timeouts. | | warn | | workflow-await-cancel-requested-in-non-cancellable-pattern | Suggest awaiting cancelRequested after nonCancellable cleanup. | | warn | | workflow-condition-timeout-style | Enforce consistent timeout style for condition() calls. | | warn | | workflow-deprecate-patch-requires-comment | Require a comment explaining why deprecatePatch is being used. | Yes | warn | | workflow-duration-format | Enforce consistent duration literal format (string vs ms number). | | warn | | workflow-local-activity-options-required | Require timeouts and retry policy for proxyLocalActivities(). | | warn | | workflow-message-name-literal | Require signal/query/update names to be string literals. | | warn | | workflow-no-activity-definitions-import | Disallow importing activity implementations. Use proxyActivities() instead. | | error | | workflow-no-any-in-workflow-public-api | Disallow any in workflow public API payload types. | | warn | | workflow-no-assert-in-production-workflow | Disallow Node assert usage in workflow code outside tests. | | warn | | workflow-no-async-query-handler | Disallow async query handlers (queries must be synchronous). | | error | | workflow-no-await-in-handler-without-exit-guard | Require allHandlersFinished() when handlers await work. | | warn | | workflow-no-bigint-in-payload | Disallow bigint in workflow payloads without a custom converter. | | warn | | workflow-no-busy-wait | Disallow busy-wait loops. Use sleep() or condition() instead. | | error | | workflow-no-client-import | Disallow importing @temporalio/client in workflow files. | | error | | workflow-no-console | Disallow console.* in workflow files. Use log from @temporalio/workflow. | Yes | error | | workflow-no-continue-as-new-in-update-handler | Disallow calling continueAsNew inside update handlers. | | error | | workflow-no-continue-as-new-without-state-argument | Require continueAsNew() to pass workflow state arguments. | | warn | | workflow-no-crypto-random | Disallow crypto.randomBytes(), getRandomValues(), randomFillSync(). | | error | | workflow-no-crypto-random-uuid | Disallow crypto.randomUUID(). Use uuid4() from @temporalio/workflow. | | error | | workflow-no-date-now-tight-loop | Warn on multiple Date.now() calls without yielding. | | warn | | workflow-no-date-object-in-payload | Disallow Date objects in workflow payloads. | | warn | | workflow-no-duplicate-patch-ids | Disallow duplicate patch IDs in the same workflow. | | error | | workflow-no-dynamic-import | Disallow dynamic import() expressions in workflows. | | error | | workflow-no-dynamic-require | Disallow dynamic require() calls in workflows. | | error | | workflow-no-error-as-payload | Disallow Error objects in workflow payload types. | | warn | | workflow-no-finalization-registry | Disallow FinalizationRegistry in workflows (non-deterministic). | | error | | workflow-no-floating-promises | Disallow floating (unhandled) promises in workflows. | | error | | workflow-no-frequent-search-attribute-upserts | Warn when upsertSearchAttributes is called inside loops. | | warn | | workflow-no-fs-in-workflow | Disallow filesystem access in workflows. Use activities for file I/O. | | error | |…

Description from the npm listing.