ESLint JSON Compatibility Utilities

0.2.3 · active · verified Sun Apr 19

eslint-json-compat-utils is a specialized utility designed to bridge the gap between ESLint rules written for `jsonc-eslint-parser` and those compatible with `@eslint/json`. It provides conversion functions that adapt rule objects, plugin objects, and `create` functions, enabling developers to reuse existing logic across different JSON AST parsers in ESLint. The current stable version is 0.2.3, with releases occurring periodically to address bugs and add minor features, as seen in recent patch updates. Its key differentiator is its focused purpose on AST transformation for JSON linting rules, specifically to ensure compatibility when transitioning between or supporting both `jsonc-eslint-parser` (which supports JSONC, JSON5) and `@eslint/json` (standard JSON).

Common errors

```
TypeError: Cannot read properties of undefined (reading 'elements') at JSONArrayExpression
```
cause The rule is trying to access properties of an AST node that do not exist in the `@eslint/json` AST, indicating incomplete or incorrect conversion by `eslint-json-compat-utils` or a mismatch in AST expectations.

fix Ensure `toCompatRule` or `toCompatCreate` was used correctly on the rule/create function. Verify the `jsonc-eslint-parser` version is compatible with `eslint-json-compat-utils` (current minimum `^2.4.0 || ^3.0.0`). For complex rules, manually inspect the converted AST structure or simplify the original rule's AST traversal.
```
ESLint couldn't find the plugin "@your-plugin/json"
```
cause This error is typically an ESLint configuration issue, not directly related to `eslint-json-compat-utils`, but can arise when attempting to use a converted plugin without properly installing or configuring it in your ESLint setup.

fix Ensure the converted plugin is correctly installed (`npm install your-plugin`) and registered in your `.eslintrc.*` file under the `plugins` array, and that `parser: '@eslint/json'` is set.

Warnings

gotcha This utility is specifically designed for converting rules *from* `jsonc-eslint-parser` to `@eslint/json`. It is not a general-purpose AST transformer or a solution for converting rules between arbitrary ESLint parsers. Misapplication to other parser contexts will not work as expected.
Fix: Only use this package when migrating or supporting rules that were originally written for `jsonc-eslint-parser` and need to function with `@eslint/json`.
gotcha The package currently assumes that the target rule's AST node visitors (`JSONArrayExpression`, `JSONObjectExpression`, etc.) are based on `jsonc-eslint-parser`'s AST structure. While it performs a conversion, complex or highly parser-specific AST queries might require manual adjustments after conversion if the transformation is not fully comprehensive for edge cases.
Fix: Thoroughly test converted rules with `@eslint/json` to ensure all original logic is preserved. For very complex rules, manual review of the converted rule's behavior and potential post-conversion tweaks may be necessary.
breaking Older versions of `eslint-json-compat-utils` might not correctly convert certain JSON AST nodes, particularly related to negative numbers or unofficial JSON5 static nodes. This could lead to incorrect linting results or crashes.
Fix: Ensure you are using `eslint-json-compat-utils` version `0.2.3` or newer to benefit from recent fixes for node conversion issues, especially for minus number nodes and JSON5 unofficial static nodes. Update your `jsonc-eslint-parser` peer dependency to `^2.4.0 || ^3.0.0`.

Install

npm install eslint-json-compat-utils npm
yarn add eslint-json-compat-utils yarn
pnpm add eslint-json-compat-utils pnpm

Imports

toCompatRule

wrong:

const { toCompatRule } = require('eslint-json-compat-utils');

correct:

import { toCompatRule } from 'eslint-json-compat-utils';

This is the primary function for converting individual ESLint rules.

toCompatPlugin

wrong:

import toCompatPlugin from 'eslint-json-compat-utils';

correct:

import { toCompatPlugin } from 'eslint-json-compat-utils';

Used for converting an entire ESLint plugin object to be `@eslint/json` compatible.

toCompatCreate

wrong:

import { toCompatCreate as create } from 'eslint-json-compat-utils';

correct:

import { toCompatCreate } from 'eslint-json-compat-utils';

Converts only the `create` function of an ESLint rule, allowing more granular control.

Quickstart

Demonstrates how to use `toCompatRule` to convert an existing ESLint rule, originally targeting `jsonc-eslint-parser` AST nodes, into a version compatible with `@eslint/json`.

import { toCompatRule } from 'eslint-json-compat-utils';

// Example of a rule originally designed for jsonc-eslint-parser
const originalRule = {
  meta: {
    type: 'suggestion',
    docs: {
      description: 'Ensure all array elements are strings',
      category: 'Possible Errors',
      recommended: false,
    },
    schema: [],
  },
  create(context) {
    return {
      // This visitor key is specific to jsonc-eslint-parser's AST
      JSONArrayExpression(node) {
        for (const element of node.elements) {
          if (element.type !== 'Literal' || typeof element.value !== 'string') {
            context.report({
              node: element,
              message: 'Array element must be a string.',
            });
          }
        }
      },
    };
  },
};

// Convert the rule for compatibility with @eslint/json
export default toCompatRule(originalRule);

// To run this in an ESLint setup, ensure your .eslintrc.js has:
// parser: '@eslint/json',
// parserOptions: { ecmaVersion: 2020 },
// rules: { 'your-plugin/your-rule-name': 'error' }

view raw JSON →