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

   1 ---
   2 title: no-restricted-imports
   3 rule_type: suggestion
   4 ---
   5
   6
   7 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`.
   8
   9 Why would you want to restrict imports?
  10
  11 * 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.
  12
  13 * 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.
  14
  15 ## Rule Details
  16
  17 This rule allows you to specify imports that you don't want to use in your application.
  18
  19 It applies to static imports only, not dynamic ones.
  20
  21 ## Options
  22
  23 The syntax to specify restricted imports looks like this:
  24
  25 ```json
  26 "no-restricted-imports": ["error", "import1", "import2"]
  27 ```
  28
  29 or like this:
  30
  31 ```json
  32 "no-restricted-imports": ["error", { "paths": ["import1", "import2"] }]
  33 ```
  34
  35 When using the object form, you can also specify an array of gitignore-style patterns:
  36
  37 ```json
  38 "no-restricted-imports": ["error", {
  39     "paths": ["import1", "import2"],
  40     "patterns": ["import1/private/*", "import2/*", "!import2/good"]
  41 }]
  42 ```
  43
  44 You may also specify a custom message for any paths you want to restrict as follows:
  45
  46 ```json
  47 "no-restricted-imports": ["error", {
  48     "name": "import-foo",
  49     "message": "Please use import-bar instead."
  50 }, {
  51     "name": "import-baz",
  52     "message": "Please use import-quux instead."
  53 }]
  54 ```
  55
  56 or like this:
  57
  58 ```json
  59 "no-restricted-imports": ["error", {
  60     "paths": [{
  61         "name": "import-foo",
  62         "message": "Please use import-bar instead."
  63     }, {
  64         "name": "import-baz",
  65         "message": "Please use import-quux instead."
  66     }]
  67 }]
  68 ```
  69
  70 or like this if you need to restrict only certain imports from a module:
  71
  72 ```json
  73 "no-restricted-imports": ["error", {
  74   "paths": [{
  75     "name": "import-foo",
  76     "importNames": ["Bar"],
  77     "message": "Please use Bar from /import-bar/baz/ instead."
  78   }]
  79 }]
  80 ```
  81
  82 or like this if you want to apply a custom message to pattern matches:
  83
  84 ```json
  85 "no-restricted-imports": ["error", {
  86     "patterns": [{
  87       "group": ["import1/private/*"],
  88       "message": "usage of import1 private modules not allowed."
  89     }, {
  90       "group": ["import2/*", "!import2/good"],
  91       "message": "import2 is deprecated, except the modules in import2/good."
  92     }]
  93 }]
  94 ```
  95
  96 The custom message will be appended to the default error message.
  97
  98 Pattern matches can also be configured to be case-sensitive:
  99
 100 ```json
 101 "no-restricted-imports": ["error", {
 102     "patterns": [{
 103       "group": ["import1/private/prefix[A-Z]*"],
 104       "caseSensitive": true
 105     }]
 106 }]
 107 ```
 108
 109 Pattern matches can restrict specific import names only, similar to the `paths` option:
 110
 111 ```json
 112 "no-restricted-imports": ["error", {
 113     "patterns": [{
 114       "group": ["utils/*"],
 115       "importNames": ["isEmpty"],
 116       "message": "Use 'isEmpty' from lodash instead."
 117     }]
 118 }]
 119 ```
 120
 121 To restrict the use of all Node.js core imports (via <https://github.com/nodejs/node/tree/master/lib>):
 122
 123 ```json
 124     "no-restricted-imports": ["error",
 125          "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"
 126     ],
 127 ```
 128
 129 ## Examples
 130
 131 Examples of **incorrect** code for this rule:
 132
 133 ::: incorrect
 134
 135 ```js
 136 /*eslint no-restricted-imports: ["error", "fs"]*/
 137
 138 import fs from 'fs';
 139 ```
 140
 141 :::
 142
 143 ::: incorrect
 144
 145 ```js
 146 /*eslint no-restricted-imports: ["error", "fs"]*/
 147
 148 export { fs } from 'fs';
 149 ```
 150
 151 :::
 152
 153 ::: incorrect
 154
 155 ```js
 156 /*eslint no-restricted-imports: ["error", "fs"]*/
 157
 158 export * from 'fs';
 159 ```
 160
 161 :::
 162
 163 ::: incorrect
 164
 165 ```js
 166 /*eslint no-restricted-imports: ["error", { "paths": ["cluster"] }]*/
 167
 168 import cluster from 'cluster';
 169 ```
 170
 171 :::
 172
 173 ::: incorrect
 174
 175 ```js
 176 /*eslint no-restricted-imports: ["error", { "patterns": ["lodash/*"] }]*/
 177
 178 import pick from 'lodash/pick';
 179 ```
 180
 181 :::
 182
 183 ::: incorrect
 184
 185 ```js
 186 /*eslint no-restricted-imports: ["error", { paths: [{
 187     name: "foo",
 188     importNames: ["default"],
 189     message: "Please use the default import from '/bar/baz/' instead."
 190 }]}]*/
 191
 192 import DisallowedObject from "foo";
 193 ```
 194
 195 :::
 196
 197 ::: incorrect
 198
 199 ```js
 200 /*eslint no-restricted-imports: ["error", { paths: [{
 201     name: "foo",
 202     importNames: ["DisallowedObject"],
 203     message: "Please import 'DisallowedObject' from '/bar/baz/' instead."
 204 }]}]*/
 205
 206 import { DisallowedObject } from "foo";
 207
 208 import { DisallowedObject as AllowedObject } from "foo";
 209
 210 import { "DisallowedObject" as AllowedObject } from "foo";
 211 ```
 212
 213 :::
 214
 215 ::: incorrect
 216
 217 ```js
 218 /*eslint no-restricted-imports: ["error", { paths: [{
 219     name: "foo",
 220     importNames: ["DisallowedObject"],
 221     message: "Please import 'DisallowedObject' from '/bar/baz/' instead."
 222 }]}]*/
 223
 224 import * as Foo from "foo";
 225 ```
 226
 227 :::
 228
 229 ::: incorrect
 230
 231 ```js
 232 /*eslint no-restricted-imports: ["error", { patterns: [{
 233     group: ["lodash/*"],
 234     message: "Please use the default import from 'lodash' instead."
 235 }]}]*/
 236
 237 import pick from 'lodash/pick';
 238 ```
 239
 240 :::
 241
 242 ::: incorrect
 243
 244 ```js
 245 /*eslint no-restricted-imports: ["error", { patterns: [{
 246     group: ["foo[A-Z]*"],
 247     caseSensitive: true
 248 }]}]*/
 249
 250 import pick from 'fooBar';
 251 ```
 252
 253 :::
 254
 255 ::: incorrect
 256
 257 ```js
 258 /*eslint no-restricted-imports: ["error", { patterns: [{
 259     group: ["utils/*"],
 260     importNames: ['isEmpty'],
 261     message: "Use 'isEmpty' from lodash instead."
 262 }]}]*/
 263
 264 import { isEmpty } from 'utils/collection-utils';
 265 ```
 266
 267 :::
 268
 269 Examples of **correct** code for this rule:
 270
 271 ::: correct
 272
 273 ```js
 274 /*eslint no-restricted-imports: ["error", "fs"]*/
 275
 276 import crypto from 'crypto';
 277 export { foo } from "bar";
 278 ```
 279
 280 :::
 281
 282 ::: correct
 283
 284 ```js
 285 /*eslint no-restricted-imports: ["error", { "paths": ["fs"], "patterns": ["eslint/*"] }]*/
 286
 287 import crypto from 'crypto';
 288 import eslint from 'eslint';
 289 export * from "path";
 290 ```
 291
 292 :::
 293
 294 ::: correct
 295
 296 ```js
 297 /*eslint no-restricted-imports: ["error", { paths: [{ name: "foo", importNames: ["DisallowedObject"] }] }]*/
 298
 299 import DisallowedObject from "foo"
 300 ```
 301
 302 :::
 303
 304 ::: correct
 305
 306 ```js
 307 /*eslint no-restricted-imports: ["error", { paths: [{
 308     name: "foo",
 309     importNames: ["DisallowedObject"],
 310     message: "Please import 'DisallowedObject' from '/bar/baz/' instead."
 311 }]}]*/
 312
 313 import { AllowedObject as DisallowedObject } from "foo";
 314 ```
 315
 316 :::
 317
 318 ::: correct
 319
 320 ```js
 321 /*eslint no-restricted-imports: ["error", { patterns: [{
 322     group: ["lodash/*"],
 323     message: "Please use the default import from 'lodash' instead."
 324 }]}]*/
 325
 326 import lodash from 'lodash';
 327 ```
 328
 329 :::
 330
 331 ::: correct
 332
 333 ```js
 334 /*eslint no-restricted-imports: ["error", { patterns: [{
 335     group: ["foo[A-Z]*"],
 336     caseSensitive: true
 337 }]}]*/
 338
 339 import pick from 'food';
 340 ```
 341
 342 :::
 343
 344 ::: correct
 345
 346 ```js
 347 /*eslint no-restricted-imports: ["error", { patterns: [{
 348     group: ["utils/*"],
 349     importNames: ['isEmpty'],
 350     message: "Use 'isEmpty' from lodash instead."
 351 }]}]*/
 352
 353 import { hasValues } from 'utils/collection-utils';
 354 ```
 355
 356 :::
 357
 358 ## When Not To Use It
 359
 360 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.