@clipboard-health/oxlint-config

Shared Oxlint configuration for Clipboard Health repositories.

Table of contents

• Install
• Usage
• Categories
• What is shared
• Intentionally disabled rules

Install

npm install @clipboard-health/oxlint-config
Copy

The config package includes @clipboard-health/oxlint-plugin for presets that use Clipboard Health custom rules.

Repositories using the frontend preset must also install oxlint-plugin-react-doctor >= 0.9.12.

Requires oxlint >= 1.68.0: the config references rules that older oxlint versions do not register, which fails config parsing outright.

Usage

Use the package's TypeScript helper when a repo needs additive composition. Oxlint's built-in extends is useful for simple inheritance, but it does not let a repo safely append shared plugins, overrides, and similar array fields without re-specifying the shared values.

TypeScript config

Create an oxlint.config.ts in your repo root:

import {
  base,
  createOxlintConfig,
  customRules,
  typeAware,
  vitest,
} from "@clipboard-health/oxlint-config";
import { defineConfig } from "oxlint";

export default defineConfig(
  createOxlintConfig({
    localConfig: {
      categories: {
        correctness: "error",
        nursery: "off",
        pedantic: "error",
        perf: "error",
        restriction: "error",
        style: "off",
        suspicious: "error",
      },
      ignorePatterns: [".agents", "coverage/", "node_modules/"],
      options: {
        denyWarnings: true,
        reportUnusedDisableDirectives: "error",
        typeAware: true,
        typeCheck: true,
      },
      rules: {
        "vitest/require-test-timeout": "off",
      },
      settings: {
        node: {
          version: ">=24.14.1",
        },
      },
    },
    presets: [base, customRules, typeAware, vitest],
  }),
);
Copy

Available presets:

• base
• contractFixtures
• customRules
• frontend
• react
• jest
• typeAware
• vitest

Merge behavior:

• plugins, jsPlugins, overrides, and ignorePatterns append in order
• rules, settings, options, categories, env, and globals merge left-to-right
• localConfig always wins over preset values when keys conflict

For React applications, compose the standalone frontend policy with the repository's test runner:

import { createOxlintConfig, frontend, typeAware, vitest } from "@clipboard-health/oxlint-config";
import { defineConfig } from "oxlint";

export default defineConfig(
  createOxlintConfig({
    localConfig: {
      ignorePatterns: ["coverage/"],
    },
    presets: [frontend, typeAware, vitest],
  }),
);
Copy

Keep repository architecture rules, import restrictions, and additional JavaScript plugins in localConfig.

base is the organization-wide general JavaScript and TypeScript policy. frontend is the standalone frontend application policy, including React, accessibility, and browser-facing JavaScript rules. typeAware contains rules that require Oxlint's --type-aware mode, and vitest adds the complete Vitest policy. Keep repository-specific exceptions in localConfig.

JSON config

Create an .oxlintrc.json in your repo root:

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "extends": ["./node_modules/@clipboard-health/oxlint-config/src/base.json"],
  "categories": {
    "correctness": "error",
    "nursery": "off",
    "pedantic": "error",
    "perf": "error",
    "restriction": "error",
    "style": "off",
    "suspicious": "error"
  },
  "ignorePatterns": [".agents", "coverage/", "node_modules/"],
  "options": {
    "denyWarnings": true,
    "reportUnusedDisableDirectives": "error",
    "typeAware": true,
    "typeCheck": true
  },
  "settings": {
    "node": {
      "version": ">=24.14.1"
    }
  }
}
Copy

Use JSON only when simple inheritance is enough. JSON extends still works for shared presets, but repo-local array fields like plugins and overrides will not get the additive merge behavior provided by createOxlintConfig.

For repos using Vitest, extend from vitest.json instead of base.json to include the vitest plugin and rules:

{
  "extends": ["./node_modules/@clipboard-health/oxlint-config/src/vitest.json"]
}
Copy

Override shared rules as needed:

{
  "extends": ["./node_modules/@clipboard-health/oxlint-config/src/base.json"],
  "rules": {
    "no-console": "off"
  }
}
Copy

Categories

This config is tuned for agent-written code: enforce rules that prevent bugs or help agents work faster, ignore rules that only encode human style preferences. Categories are applied as a denylist (enable the category, then disable individual rules that are noise) rather than an allowlist, so new bug-catching rules in a category are adopted automatically as oxlint ships them.

style and nursery are off, not denylisted, because their future rules are noise rather than signal — there is nothing worth adopting automatically. Every style rule kept is therefore listed explicitly in base.json.

What is shared

The package includes:

• base.json: the backwards-compatible JSON preset for simple extends usage
• vitest.json: extends base.json with the vitest plugin and rules for JSON extends usage
• base preset: shared plugins, rules, and overrides exported for TypeScript composition
• frontend preset: shared frontend JavaScript, React Doctor, React, and JSX accessibility policy
• typeAware preset: rules that require Oxlint's type-aware execution mode
• react, jest, vitest presets: additive plugin presets for common repo types
• contractFixtures preset: warning-level enforcement that MSW, Playwright, and exported mock fixtures are parsed by producer-owned contract response schemas
• customRules preset: registers the ESLint-independent Clipboard plugin and reproduces the shared controller, module, contract, and cross-contract-import enforcement scopes
• createOxlintConfig: helper for composing presets with repo-local config

Intentionally disabled rules

base.json cannot hold comments, so the reasoning for non-obvious "off" entries lives here (audited against clipboard-health on oxlint 1.60, 2026-06-11):

• typescript/consistent-type-imports: oxlint's port is not emitDecoratorMetadata-aware (even type-aware with the flag in the tsconfig chain), so it flags NestJS constructor-injected classes as type-only. Applying its fix converts DI tokens to import type, which SWC erases from design:paramtypes metadata, breaking injection at runtime. Do not enable in NestJS repos until oxlint matches typescript-eslint's decorator handling.
• jest/no-confusing-set-timeout (jest preset): false-positive explosion — when a jest setup file calls jest.setTimeout, the rule flags spec files that contain no setTimeout call at all (265k diagnostics across 764 clean files). The vitest preset carries no jest/* keys at all: under oxlint ≥1.68 with only the vitest plugin enabled, jest/* config keys are silently ignored, and jest-plugin-only rules (such as this one and jest/prefer-ending-with-an-expect) cannot fire — vitest/no-confusing-set-timeout is not a registered rule name, so an "off" entry for it fails config parsing.
• import/no-named-as-default / import/no-named-as-default-member: low signal; they flag legitimate default-export import patterns far more often than real mistakes (870 hits, ~0 bugs).
• prefer-destructuring: style preference with no bug-prevention value; not worth the churn as an agent guardrail.

The test-file override in base.json disables the typescript/no-unsafe-* family, unbound-method, no-non-null-assertion, and restrict-template-expressions for test files: mocks, expect.any, and createMock make these rules ~90% noise in tests (mirrors the long-standing eslint-config override), while keeping them enforceable for production code.