Configuration

The plugin uses ESLint’s flat config format (eslint.config.js). It provides two preset configs (recommended and strict) and automatically detects Gadget action files.

Basic configuration

Import the plugin and use a preset:

eslint.config.js

import gadget from "@aurelienbbn/eslint-plugin-gadget";

export default [
  gadget.configs.recommended,
];

This enables all 16 rules with appropriate severity levels:

Critical validation errors (invalid options, params, timeout) at error
Runtime safety and best practices at warn

File pattern detection

Most rules only activate on files matching Gadget action file patterns:

**/api/actions/**/*.{js,ts} (global actions)
**/api/models/**/actions/**/*.{js,ts} (model actions)

The pattern matching uses minimatch internally. If a file does not match, the plugin skips rule execution.

Exceptions: Global rules

Two enqueue-related rules apply to all files because api.enqueue() can be called anywhere:

action-no-enqueue-max-concurrency-exceeded
action-no-implicit-enqueue-retries

These rules check any file in your project for problematic api.enqueue() calls.

Overriding rules

You can adjust individual rule severity by adding a second config object:

eslint.config.js

import gadget from "@aurelienbbn/eslint-plugin-gadget";

export default [
  gadget.configs.recommended,
  {
    rules: {
      // Disable the timeout comment requirement
      "gadget/action-require-timeout-ms-comment": "off",
      
      // Elevate runtime warnings to errors
      "gadget/action-no-await-handle-result-in-action": "error",
      "gadget/action-no-return-value-in-on-success": "error",
    },
  },
];

Override patterns

Disable a rule
Change severity
Apply to specific files

"gadget/action-require-timeout-ms-comment": "off"

"gadget/action-no-empty-on-success": "error" // was warn

{
  files: ["api/models/user/actions/**/*.ts"],
  rules: {
    "gadget/action-require-explicit-return-type": "off",
  },
}

Combining with other configs

The plugin works alongside other ESLint configs. Place it before or after other configs depending on precedence:

eslint.config.js

import js from "@eslint/js";
import tseslint from "typescript-eslint";
import gadget from "@aurelienbbn/eslint-plugin-gadget";

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  gadget.configs.strict, // Gadget rules apply last
];

Configs listed later override rules from earlier configs. If you want Gadget rules to take precedence, place gadget.configs last.

Strict mode

Use strict config to enforce all rules at error level:

eslint.config.js

import gadget from "@aurelienbbn/eslint-plugin-gadget";

export default [
  gadget.configs.strict,
];

This is useful for CI environments or projects with strict code quality requirements. See Configs for a detailed comparison.

Ignoring files

Use ESLint’s ignores key to exclude files:

eslint.config.js

import gadget from "@aurelienbbn/eslint-plugin-gadget";

export default [
  {
    ignores: [
      "**/dist/**",
      "**/node_modules/**",
      "api/actions/legacy/**", // Skip legacy actions
    ],
  },
  gadget.configs.recommended,
];

Custom plugin usage

If you prefer manual rule configuration, access the plugin object directly:

eslint.config.js

import gadget from "@aurelienbbn/eslint-plugin-gadget";

export default [
  {
    plugins: { gadget },
    rules: {
      "gadget/action-no-invalid-options": "error",
      "gadget/action-no-invalid-params": "error",
      "gadget/action-no-invalid-timeout-ms": "error",
      // ...add other rules as needed
    },
  },
];

See the full rule list in the README.

Type information

The plugin does not require TypeScript type information (parserServices). All rules operate on the AST level, so you do not need to configure @typescript-eslint/parser unless you are using other type-aware rules.

Example: Production config

Here is a complete config for a Gadget project:

eslint.config.js

import js from "@eslint/js";
import tseslint from "typescript-eslint";
import gadget from "@aurelienbbn/eslint-plugin-gadget";

export default [
  {
    ignores: ["**/dist/**", "**/node_modules/**"],
  },
  js.configs.recommended,
  ...tseslint.configs.recommended,
  gadget.configs.recommended,
  {
    rules: {
      // Project-specific overrides
      "gadget/action-require-timeout-ms-comment": "off",
      "gadget/action-no-await-handle-result-in-action": "error",
    },
  },
];

Get Started

ESLint Plugin

UI Components

Basic configuration

File pattern detection

Exceptions: Global rules

Overriding rules

Override patterns

Combining with other configs

Strict mode

Ignoring files

Custom plugin usage

Type information

Example: Production config

Next steps

Configs

Rules

​Basic configuration

​File pattern detection

​Exceptions: Global rules

​Overriding rules

​Override patterns

​Combining with other configs

​Strict mode

​Ignoring files

​Custom plugin usage

​Type information

​Example: Production config

​Next steps

Configs

Rules

Basic configuration

File pattern detection

Exceptions: Global rules

Overriding rules

Override patterns

Combining with other configs

Strict mode

Ignoring files

Custom plugin usage

Type information

Example: Production config

Next steps