eslint/docs/rules/no-restricted-imports.md

   1 # Disallow specific imports (no-restricted-imports)
   2
   3 Imports are an ES6/ES2015 standard for making the functionality of other modules available in your current module. In CommonJS this is implemented through the `require()` call which makes this ESLint rule roughly equivalent to its CommonJS counterpart `no-restricted-modules`.
   4
   5 Why would you want to restrict imports?
   6
   7 * Some imports might not make sense in a particular environment. For example, Node.js' `fs` module would not make sense in an environment that didn't have a file system.
   8
   9 * Some modules provide similar or identical functionality, think `lodash` and `underscore`. Your project may have standardized on a module. You want to make sure that the other alternatives are not being used as this would unnecessarily bloat the project and provide a higher maintenance cost of two dependencies when one would suffice.
  10
  11 ## Rule Details
  12
  13 This rule allows you to specify imports that you don't want to use in your application.
  14
  15 It applies to static imports only, not dynamic ones.
  16
  17 ## Options
  18
  19 The syntax to specify restricted imports looks like this:
  20
  21 ```json
  22 "no-restricted-imports": ["error", "import1", "import2"]
  23 ```
  24
  25 or like this:
  26
  27 ```json
  28 "no-restricted-imports": ["error", { "paths": ["import1", "import2"] }]
  29 ```
  30
  31 When using the object form, you can also specify an array of gitignore-style patterns:
  32
  33 ```json
  34 "no-restricted-imports": ["error", {
  35     "paths": ["import1", "import2"],
  36     "patterns": ["import1/private/*", "import2/*", "!import2/good"]
  37 }]
  38 ```
  39
  40 You may also specify a custom message for any paths you want to restrict as follows:
  41
  42 ```json
  43 "no-restricted-imports": ["error", {
  44     "name": "import-foo",
  45     "message": "Please use import-bar instead."
  46 }, {
  47     "name": "import-baz",
  48     "message": "Please use import-quux instead."
  49 }]
  50 ```
  51
  52 or like this:
  53
  54 ```json
  55 "no-restricted-imports": ["error", {
  56     "paths": [{
  57         "name": "import-foo",
  58         "message": "Please use import-bar instead."
  59     }, {
  60         "name": "import-baz",
  61         "message": "Please use import-quux instead."
  62     }]
  63 }]
  64 ```
  65
  66 or like this if you need to restrict only certain imports from a module:
  67
  68 ```json
  69 "no-restricted-imports": ["error", {
  70   "paths": [{
  71     "name": "import-foo",
  72     "importNames": ["Bar"],
  73     "message": "Please use Bar from /import-bar/baz/ instead."
  74   }]
  75 }]
  76 ```
  77
  78 The custom message will be appended to the default error message. Please note that you may not specify custom error messages for restricted patterns as a particular import may match more than one pattern.
  79
  80 To restrict the use of all Node.js core imports (via https://github.com/nodejs/node/tree/master/lib):
  81
  82 ```json
  83     "no-restricted-imports": ["error",
  84          "assert","buffer","child_process","cluster","crypto","dgram","dns","domain","events","freelist","fs","http","https","module","net","os","path","punycode","querystring","readline","repl","smalloc","stream","string_decoder","sys","timers","tls","tracing","tty","url","util","vm","zlib"
  85     ],
  86 ```
  87
  88 ## Examples
  89
  90 Examples of **incorrect** code for this rule:
  91
  92 ```js
  93 /*eslint no-restricted-imports: ["error", "fs"]*/
  94
  95 import fs from 'fs';
  96 ```
  97
  98 ```js
  99 /*eslint no-restricted-imports: ["error", "fs"]*/
 100
 101 export { fs } from 'fs';
 102 ```
 103
 104 ```js
 105 /*eslint no-restricted-imports: ["error", "fs"]*/
 106
 107 export * from 'fs';
 108 ```
 109
 110 ```js
 111 /*eslint no-restricted-imports: ["error", { "paths": ["cluster"] }]*/
 112
 113 import cluster from 'cluster';
 114 ```
 115
 116 ```js
 117 /*eslint no-restricted-imports: ["error", { "patterns": ["lodash/*"] }]*/
 118
 119 import pick from 'lodash/pick';
 120 ```
 121
 122 ```js
 123 /*eslint no-restricted-imports: ["error", { paths: [{
 124     name: "foo",
 125     importNames: ["default"],
 126     message: "Please use the default import from '/bar/baz/' instead."
 127 }]}]*/
 128
 129 import DisallowedObject from "foo";
 130 ```
 131
 132 ```js
 133 /*eslint no-restricted-imports: ["error", { paths: [{
 134     name: "foo",
 135     importNames: ["DisallowedObject"],
 136     message: "Please import 'DisallowedObject' from '/bar/baz/' instead."
 137 }]}]*/
 138
 139 import { DisallowedObject as AllowedObject } from "foo";
 140 ```
 141
 142 ```js
 143 /*eslint no-restricted-imports: ["error", { paths: [{
 144     name: "foo",
 145     importNames: ["DisallowedObject"],
 146     message: "Please import 'DisallowedObject' from '/bar/baz/' instead."
 147 }]}]*/
 148
 149 import * as Foo from "foo";
 150 ```
 151
 152 Examples of **correct** code for this rule:
 153
 154 ```js
 155 /*eslint no-restricted-imports: ["error", "fs"]*/
 156
 157 import crypto from 'crypto';
 158 export { foo } from "bar";
 159 ```
 160
 161 ```js
 162 /*eslint no-restricted-imports: ["error", { "paths": ["fs"], "patterns": ["eslint/*"] }]*/
 163
 164 import crypto from 'crypto';
 165 import eslint from 'eslint';
 166 export * from "path";
 167 ```
 168
 169 ```js
 170 /*eslint no-restricted-imports: ["error", { paths: [{ name: "foo", importNames: ["DisallowedObject"] }] }]*/
 171
 172 import DisallowedObject from "foo"
 173 ```
 174
 175 ```js
 176 /*eslint no-restricted-imports: ["error", { paths: [{
 177     name: "foo",
 178     importNames: ["DisallowedObject"],
 179     message: "Please import 'DisallowedObject' from '/bar/baz/' instead."
 180 }]}]*/
 181
 182 import { AllowedObject as DisallowedObject } from "foo";
 183 ```
 184
 185 ## When Not To Use It
 186
 187 Don't use this rule or don't include a module in the list for this rule if you want to be able to import a module in your project without an ESLint error or warning.