ESLint No Restricted Utility

Common errors

• TypeError: (0 , eslint_no_restricted_properties__WEBPACK_IMPORTED_MODULE_0__.create) is not a function

  cause Incorrect CommonJS `require()` syntax or improper ESM setup when using a bundler (like Webpack) that tries to resolve a default export that doesn't exist, or when running in a Node.js environment that struggles with ESM interop for the module.
  fix If using CommonJS, use `const { create } = require('eslint-no-restricted/properties');`. If using ESM, ensure `package.json` has `"type": "module"` or files end in `.mjs`, and verify bundler configuration correctly handles ESM imports. For TypeScript, ensure `moduleResolution` is correctly configured.

• ESLint: Definition for rule 'my-plugin/no-console-log' was not found.

  cause The custom ESLint rule created with `eslint-no-restricted` was not correctly registered in the `.eslintrc` configuration file under the `plugins` or `rules` section, or the path to the custom plugin is incorrect.
  fix Verify that your custom plugin (e.g., `my-eslint-plugin/index.ts`) is correctly exported and that its path is specified in the `plugins` array of your `.eslintrc` file. Also, ensure the rule name in `rules` (`'my-plugin/no-console-log'`) matches the plugin's name and the rule's `name` property.

Warnings

• breaking Version 0.1.0 introduced a 'narrowing down' of the `create*` return type. This change might cause TypeScript compilation errors if existing code relied on a broader or less specific type for the plugin object returned by `create` functions.
  Fix: Review TypeScript code consuming the `create` function's return value and adjust types if necessary to match the stricter `Plugin` interface. Consult the package's type definitions for the exact new shape.
• gotcha Prior to version 0.0.10, there were issues with TypeScript mistakenly reporting named exports for Node.js 16 when using ESM. Although fixed, developers should be mindful of correct module resolution settings, especially in mixed ESM/CJS environments or when using older Node.js versions, to avoid similar import or type-resolution problems.
  Fix: Ensure Node.js environment is `^20.9.0 || >=22.0.0` as specified, and use version `0.0.10` or newer. Configure `tsconfig.json` with appropriate `moduleResolution` (e.g., `Node16` or `Bundler`) and `module` settings (e.g., `ESNext`).
• gotcha This package is a utility for creating ESLint rules and has `eslint` as a peer dependency. Incompatible `eslint` versions can lead to runtime errors or unexpected behavior.
  Fix: Always ensure your `eslint` installation matches the peer dependency range (`^8.57.0 || ^9 || ^10`). Use `npm install` or `yarn add` to automatically resolve compatible versions, or manually check with `npm ls eslint`.

Install

• npm install eslint-no-restricted npm
• yarn add eslint-no-restricted yarn
• pnpm add eslint-no-restricted pnpm

Imports

• create
  wrong:

  import { create } from 'eslint-no-restricted';

  correct:

  import { create } from 'eslint-no-restricted/globals';

  The `create` function is exported from specific sub-paths like `/globals`, `/properties`, or `/syntax`, not directly from the root package.
• RuleBase

  import type { RuleBase } from 'eslint-no-restricted/shared';

  `RuleBase` is a shared interface for common rule options and should be imported as a type from the `/shared` sub-path for TypeScript usage.
• RuleConfig

  import type { RuleConfig } from 'eslint-no-restricted/properties';

  `RuleConfig` is a type definition that is specific to the type of restricted rule being created (e.g., `/globals`, `/properties`, or `/syntax`). Import the one relevant to your specific rule definition.

Quickstart

This quickstart demonstrates creating a custom ESLint rule that disallows `console.log` using `eslint-no-restricted/properties`, and integrating it into an ESLint configuration. It shows the `create` function for rule definition and how to expose it through a custom ESLint plugin.

import { create } from 'eslint-no-restricted/properties';
import type { RuleConfig } from 'eslint-no-restricted/properties';
import path from 'path';

// my-eslint-plugin/rules/no-console-log.ts
const noConsoleLogRuleConfig: RuleConfig = {
  name: 'no-console-log',
  message: 'Using {{property}} on {{object}} is not allowed. Please use a dedicated logger instead.',
  properties: {
    object: 'console',
    property: 'log',
  },
  defaultLevel: 'error',
  docUrl: 'https://example.com/docs/no-console-log',
};

const noConsoleLog = create(noConsoleLogRuleConfig);

// my-eslint-plugin/index.ts (main plugin file)
export = {
  rules: {
    'no-console-log': noConsoleLog,
  },
  // Optionally, you can add recommended configs
  // configs: {
  //   recommended: {
  //     plugins: ['my-plugin'],
  //     rules: {
  //       'my-plugin/no-console-log': 'error',
  //     },
  //   },
  // },
};

// .eslintrc.js (example ESLint configuration)
// module.exports = {
//   root: true,
//   plugins: [
//     // Assuming your custom plugin is in a directory relative to .eslintrc.js
//     path.resolve(__dirname, 'my-eslint-plugin'),
//   ],
//   rules: {
//     'my-eslint-plugin/no-console-log': 'error',
//     'no-debugger': 'error',
//   },
//   parserOptions: {
//     ecmaVersion: 'latest',
//     sourceType: 'module',
//   },
//   env: {
//     node: true,
//     browser: true,
//   },
// };