DOCSEARCHbyAlgolia
Submit Docs

eslint-plugin-n

repository·master·Indexed 43 days ago

https://github.com/eslint-community/eslint-plugin-n

Additional ESLint rules for Node.js environments, helping to identify unsupported features and ensure compatibility with target Node.js versions. A maintained fork of eslint-plugin-node, version 18.3.0 provides preset configurations for ES Modules, CommonJS, and mixed environments.

Tokens
31.6K
Snippets
118
Records
139
Agent score
54%

What's inside eslint-plugin-n

  1. Understand the n/process-exit-as-throw rule

    master

    The n/process-exit-as-throw rule ensures that code following a process.exit() call is correctly identified as unreachable by ESLint.

    By default, ESLint does not treat process.exit() as a terminating expression (unlike throw or return). This can cause other rules, such as consistent-return, to trigger false positive warnings on code that follows a process.exit() call because ESLint assumes the code path continues.

    This rule overrides the default code path analyzer to mark code after process.exit() as unreachable, preventing these false positives. Note that this rule itself does not issue warnings; it facilitates the correct behavior of other ESLint rules.

    function foo(a) {
    if (a) {
        return new Bar();
    } else {
        process.exit(1);
    }
    // Without this rule, ESLint might think code here is reachable,
    // potentially triggering warnings from rules like 'consistent-return'.
}

  3. Understand the Semantic Versioning Policy

    master

    eslint-plugin-n follows Semantic Versioning and ESLint's Semantic Versioning Policy. Be aware of how version updates might affect your linting results:

    Patch releases (No breaking changes)

    • Bug fixes that result in fewer errors.
    • Documentation improvements.
    • Internal refactoring or test changes.

    Minor releases (May break your lint build)

    • Bug fixes that result in more errors.
    • New rules or new rule options.
    • Deprecation of existing rules.

    Major releases (Likely to break your lint build)

    • Dropping support for old Node.js or ESLint versions.
    • Existing rules changing to report more errors.
    • Removal of existing rules or rule options.
    • Updates to existing configurations.

  4. Understand limitations of the n/callback-return rule

    master

    The n/callback-return rule relies on static analysis, which means it has certain limitations regarding what it can detect:

    False Negatives (Missed errors)

    • Passing by reference: The rule will not warn if a callback is passed as an argument to another function (e.g., setTimeout(callback, 0)), even if that leads to multiple executions.
    • Nested functions/IIFEs: The rule cannot detect if a callback is triggered from within a nested function or an Immediately-Invoked Function Expression (IIFE).

    False Positives (Incorrect warnings)

    • If/Else branches: The rule may warn about code that is actually safe if the callback is only called once across all possible execution branches (e.g., an if/else block where each branch calls the callback exactly once).

  5. How eslint-plugin-n determines the configured Node.js version

    master

    The plugin's rules (such as n/no-unsupported-features/*) require knowledge of the supported Node.js version range to validate code correctly. The plugin resolves this version using the following priority order:

    1. The version property in the specific rule configuration.
    2. The ESLint shared setting settings.node.version.
    3. The engines field in package.json.
    4. The devEngines.runtime field in package.json (where name is set to "node").
    5. A default fallback of >=16.0.0.

    Best Practice: For Node.js packages, it is highly recommended to use the engines field in package.json to officially indicate supported Node.js versions. For shareable configs or non-Node environments, use settings.node.version in your ESLint configuration.

  8. Use mixed CommonJS and ES Modules in ESLint config

    master

    If your project uses a mix of CommonJS and ES Modules, you can use the mixed-esm-and-cjs configuration provided by eslint-plugin-n. This is applied via the extends key in your ESLint flat configuration.

    import node from "eslint-plugin-n"
import {defineConfig} from "eslint/config"

export default defineConfig([
    {
        plugins: {n: node},
        extends: ["n/mixed-esm-and-cjs"],
    },
])

  9. Configure eslint-plugin-n in eslint.config.js

    master

    To use the plugin with the recommended module configuration in ESLint Flat Config, import the plugin and extend the n/recommended-module config.

    If you want to use the plugin without recommended configurations, register the plugin under the n namespace and define your specific rules manually.

    import node from "eslint-plugin-n"
import {defineConfig} from "eslint/config"

export default defineConfig([
    {
        plugins: {n: node},
        extends: ["n/recommended-module"],
    }
])

  10. Use the n/callback-return rule to prevent multiple callback executions

    master

    The n/callback-return rule ensures that whenever a callback is triggered outside of the main function body, it is preceded by a return statement. This prevents common bugs where a callback is accidentally invoked multiple times, which in Node.js can lead to errors like Can't render headers after they are sent to the client.

    To satisfy this rule, you must return the result of the callback call when it is used within conditional blocks (like if statements) to ensure the function execution stops immediately after the callback is triggered.

    function doSomething(err, callback) {
    if (err) {
        return callback(err);
    }
    callback();
}

  11. Use the n/hashbang rule

    master

    The n/hashbang rule ensures that files designated as executables in your package.json have the correct hashbang (e.g., #!/usr/bin/env node), use Unix linebreaks (LF), and do not contain a Unicode BOM. Conversely, it ensures that files NOT listed in the bin field do not have a hashbang.

    This rule is automatically included in the following configurations:

    • recommended-module
    • recommended-script

    It is automatically fixable using the ESLint --fix CLI option.

    npx eslint --fix your-file.js