useTopLevelRequire (JavaScript)

Language JavaScript (and super languages)

Summary

Rule available since: v2.6.8
Diagnostic Category: lint/nursery/useTopLevelRequire
This rule doesn’t have a fix.
The default severity of this rule is warning.
Sources:
- Same as global-require
- Same as n/global-require

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useTopLevelRequire": "error"
6
      }
7
    }
8
  }
9
}

Description

Require require() calls to be placed at the top level of the module.

When require() calls are spread across functions, blocks, and other expressions, it’s hard to see at a glance which modules a file depends on. require() also loads modules synchronously, so a call inside a function that runs later can pause the program at a moment you don’t expect.

A require() call is allowed only at the top level of the module, and only when it is used as a statement on its own, in a variable declaration, in an assignment, in a conditional (? :) expression, as an argument of another call, or when its result is accessed with a property or called. The rule reports every other require() call, including top-level calls inside objects, arrays, export declarations, or loops.

The rule doesn’t report require when it’s a variable, parameter, or function declared in your own code.

Examples

Invalid

1
function readFile(filename, callback) {
2
    const fs = require("fs");
3
    fs.readFile(filename, callback);
4
}

code-block.js:2:16 lint/nursery/useTopLevelRequire ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This require() call isn't directly part of a top-level statement.
  
    1 │ function readFile(filename, callback) {
  > 2 │     const fs = require("fs");
      │                ^^^^^^^^^^^^^
    3 │     fs.readFile(filename, callback);
    4 │ }
  
  ℹ Modules loaded inside functions, blocks, or other expressions make it hard to see what the file depends on, and can be loaded at unexpected times.
  
  ℹ Load the module in a top-level declaration, for example const name = require("module"), and use that variable here.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

1
if (DEBUG) {
2
    require("debug");
3
}

code-block.js:2:5 lint/nursery/useTopLevelRequire ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This require() call isn't directly part of a top-level statement.
  
    1 │ if (DEBUG) {
  > 2 │     require("debug");
      │     ^^^^^^^^^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Modules loaded inside functions, blocks, or other expressions make it hard to see what the file depends on, and can be loaded at unexpected times.
  
  ℹ Load the module in a top-level declaration, for example const name = require("module"), and use that variable here.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

1
const getModule = (name) => require(name);

code-block.js:1:29 lint/nursery/useTopLevelRequire ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This require() call isn't directly part of a top-level statement.
  
  > 1 │ const getModule = (name) => require(name);
      │                             ^^^^^^^^^^^^^
    2 │ 
  
  ℹ Modules loaded inside functions, blocks, or other expressions make it hard to see what the file depends on, and can be loaded at unexpected times.
  
  ℹ Load the module in a top-level declaration, for example const name = require("module"), and use that variable here.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

1
try {
2
    require(unsafeModule);
3
} catch (e) {
4
    console.log(e);
5
}

code-block.js:2:5 lint/nursery/useTopLevelRequire ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This require() call isn't directly part of a top-level statement.
  
    1 │ try {
  > 2 │     require(unsafeModule);
      │     ^^^^^^^^^^^^^^^^^^^^^
    3 │ } catch (e) {
    4 │     console.log(e);
  
  ℹ Modules loaded inside functions, blocks, or other expressions make it hard to see what the file depends on, and can be loaded at unexpected times.
  
  ℹ Load the module in a top-level declaration, for example const name = require("module"), and use that variable here.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

Valid

1
require("x");
2
const y = require("y");
3
let z;
4
z = require("z").initialize();
5

6
const fs = require("fs");
7
function readFile(filename, callback) {
8
    fs.readFile(filename, callback);
9
}
10

11
const logger = DEBUG ? require("dev-logger") : require("logger");
12

13
function localRequire(require) {
14
    require("y");
15
}