Skip to content

Commit

Permalink
Docs: Clarify global-require inside try/catch (fixes #3834)
Browse files Browse the repository at this point in the history
  • Loading branch information
btmills committed Feb 8, 2016
1 parent 3685b3e commit a4cde1b
Showing 1 changed file with 5 additions and 3 deletions.
8 changes: 5 additions & 3 deletions docs/rules/global-require.md
Expand Up @@ -6,7 +6,7 @@ In Node.js, module dependencies are included using the `require()` function, suc
var fs = require("fs");
```

While `require()` may be called anywhere in code, some style guide prescribe that it should be called only in the top-level scope of a module to make it easier to identify dependencies. For instance, it's arguably harder to identify dependencies when they are deeply nested inside of functions and other statements:
While `require()` may be called anywhere in code, some style guides prescribe that it should be called only in the top level of a module to make it easier to identify dependencies. For instance, it's arguably harder to identify dependencies when they are deeply nested inside of functions and other statements:

```js
function foo() {
Expand All @@ -19,9 +19,11 @@ function foo() {

Since `require()` does a synchronous load, it can cause performance problems when used in other locations.

Further, ES6 modules mandate that `import` and `export` statements can only occur in the top level of the module's body.

## Rule Details

This rule requires all calls to `require()` to be at the top-level module scope.
This rule requires all calls to `require()` to be at the top level of the module, similar to ES6 `import` and `export` statements, which also can occur only at the top level.

You can enable this rule with the following syntax:

Expand Down Expand Up @@ -90,4 +92,4 @@ var x = require("x"),

## When Not To Use It

If you have a module that must be initialized with information that comes from the file-system or if a module is only used in very rare situations and will cause significant overhead to load it may make sense to disable the rule.
If you have a module that must be initialized with information that comes from the file-system or if a module is only used in very rare situations and will cause significant overhead to load it may make sense to disable the rule. If you need to `require()` an optional dependency inside of a `try`/`catch`, you can disable this rule for just that dependency using the `// eslint disable-line global-require` comment.

0 comments on commit a4cde1b

Please sign in to comment.