diff --git a/README.md b/README.md index 9bd7795..d22c63c 100644 --- a/README.md +++ b/README.md @@ -122,7 +122,9 @@ share a global config between different projects. The following configuration options are supported. - [`aliases`](#aliases) +- [`danglingCommas`](#danglingcommas) - [`declarationKeyword`](#declarationkeyword) +- [`emptyLineBetweenGroups`](#emptyLineBetweenGroups) - [`environments`](#environments) - [`excludes`](#excludes) - [`globals`](#globals) @@ -133,24 +135,15 @@ The following configuration options are supported. - [`importStatementFormatter`](#importstatementformatter) - [`logLevel`](#loglevel) - [`maxLineLength`](#maxlinelength) +- [`mergableOptions`](#mergableoptions) - [`minimumVersion`](#minimumversion) - [`moduleNameFormatter`](#modulenameformatter) - [`namedExports`](#namedexports) +- [`parserPlugins`](#parserPlugins) - [`sortImports`](#sortimports) - [`stripFileExtensions`](#stripfileextensions) -- [`danglingCommas`](#danglingcommas) - [`tab`](#tab) - [`useRelativePaths`](#userelativepaths) -- [`mergableOptions`](#mergableoptions) - -### `excludes` - -Define a list of glob patterns that match files and directories that you don't -want to include for importing. - -```javascript -excludes: ['./react-components/**/test/**']; -``` ### `aliases` @@ -164,6 +157,27 @@ aliases: { } ``` +### `danglingCommas` + +By default, ImportJS will add trailing commas when constructing import statements with multiple named imports. + +You can turn off this behavior by setting `danglingCommas` to `false`. + +```javascript +danglingCommas: false; +``` + +### `declarationKeyword` + +The default value for this property is `import`, making your import statements +use the [ES2015 modules syntax][]: + +[ES2015 modules syntax]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import + +```javascript +import Foo from 'foo'; +``` + Aliases can be made dynamic by using the `{filename}` string. This part of the alias will be replaced by the name of the file you are currently editing. @@ -181,6 +195,16 @@ will for a file `foo/bar.js` result in import styles from './bar.scss'; ``` +### `emptyLineBetweenGroups` + +By default, ImportJS will insert empty line between import groups. + +You can turn off this behavior by setting `emptyLineBetweenGroups` to `false`. + +```javascript +emptyLineBetweenGroups: false; +``` + ### `environments` This list of environments controls what core modules are available when @@ -208,118 +232,13 @@ values right now are environments: ['meteor', 'node']; ``` -### `namedExports` - -\*Note: Since 2.1.0 ImportJS finds your named exports automatically. Most -likely you don't need this option. If you end up having to use this -configuration anyway, there might be a bug in the exports-finding parts of -ImportJS. [File an issue](https://github.com/Galooshi/import-js/issues) and -tell us about it! - -If you have an ES6/ES2015 module that exports multiple things (named exports), -or a CommonJS module that exports an object with properties on it that you want -to destructure when importing, you can add those to a `namedExports` -configuration option. - -```javascript -namedExports: { - underscore: [ - 'omit', - 'debounce', - 'memoize' - ], - 'lib/utils': [ - 'escape', - 'hasKey', - ], -} -``` - -Imports that use the `import` declaration keyword then use [named imports -syntax][]. e.g. - -```javascript -import { memoize } from 'underscore'; - -memoize(() => { - foo(); -}); -``` - -and imports that use `const` or `var` use [ES2015 Destructuring -Assigment][destructing assignment], e.g. - -```javascript -const { memoize } = require('underscore'); - -memoize(() => { - foo(); -}); -``` - -[named imports syntax]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import -[destructuring assignment]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment - -The key used to describe the named exports should be a valid import path. This -can be e.g. the name of a package found under `node_modules`, a path to a -module you created yourself, or a relative import path. - -Consider the example as a valid use case for the `namedExports` property. Let's say we have a file: - -```jsx -import { Provider } from 'react-redux'; -import React from 'react'; -import store from './redux/redux-store'; -import ReactDOM from 'react-dom'; -import App from './App'; - -ReactDOM.render( - - - - - , - document.getElementById('root'), -); -``` - -And we're going to import `BrowserRouter` but instead of the desired result we get -the _No JS module to import for `BrowserRouter`_ message. -In order to fix the problem, populate `namedExports` in your config file as follows: - -```js -namedExports: { - 'react-router-dom': ['BrowserRouter', 'Route', 'Redirect'] -} -``` - -After that we are able to import `BrowserRouter` correctly. The resulting import statement will look like this: - -`import { BrowserRouter } from 'react-router-dom'` - -### `declarationKeyword` - -The default value for this property is `import`, making your import statements -use the [ES2015 modules syntax][]: - -[ES2015 modules syntax]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import - -```javascript -import Foo from 'foo'; -``` - -If you aren't ready for ES2015 yet, you have the option to use `var` or `const` -instead. - -```javascript -declarationKeyword: 'const'; -``` +### `excludes` -In such case, your import statements will look something like this: +Define a list of glob patterns that match files and directories that you don't +want to include for importing. ```javascript -var Foo = require('foo'); // "declarationKeyword": "var" -const Foo = require('foo'); // "declarationKeyword": "const" +excludes: ['./react-components/**/test/**']; ``` ### `globals` @@ -345,26 +264,19 @@ disabled, imports are listed alphabetically in one list. groupImports: false; ``` -### `sortImports` - -By default, ImportJS will sort imports by the name or path of the imported module. +### `ignorePackagePrefixes` -You can turn off this behavior by setting `sortImports` to `false`. When -disabled, existing imports are not rearranged, and new imports are always added above existing imports. +If you have package dependencies specified in `package.json` that are prefixed +with e.g. an organization name but want to be able to import these without the +package prefix, you can set the `ignorePackagePrefixes` configuration option. ```javascript -sortImports: false; +ignorePackagePrefixes: ['my-company-']; ``` -### `emptyLineBetweenGroups` - -By default, ImportJS will insert empty line between import groups. - -You can turn off this behavior by setting `emptyLineBetweenGroups` to `false`. - -```javascript -emptyLineBetweenGroups: false; -``` +When package dependencies are matched, these prefixes will be ignored. As an +example, a variable named `validator` would match a package named +`my-company-validator`. ### `importDevDependencies` @@ -377,16 +289,6 @@ importing. By default, only modules listed under `dependencies` and importDevDependencies: true; ``` -### `danglingCommas` - -By default, ImportJS will add trailing commas when constructing import statements with multiple named imports. - -You can turn off this behavior by setting `danglingCommas` to `false`. - -```javascript -danglingCommas: false; -``` - ### `importFunction` _Note: this only applies if you are using `var` or `const` as @@ -400,48 +302,89 @@ importing](http://wiki.commonjs.org/wiki/Modules/1.1). importFunction: 'myCustomRequireFunction'; ``` -### `stripFileExtensions` +### `importStatementFormatter` -An array that controls what file extensions are stripped out from the resulting -import statement. The default configuration strips out `[".js", ".jsx", ".ts", -".tsx"]`. Set to an empty array `[]` to avoid stripping out extensions. +Use a function here to control how the resulting import statement will look +like. This is useful if you for instance want to strip out trailing semicolons +(that ImportJS adds by default). + +Note: this method should only be used in rare cases. There's a chance that +ImportJS won't be able to recognize the resulting import statement next time it +is about to import something. ```javascript -stripFileExtensions: ['.web.js', '.js']; +importStatementFormatter({ importStatement }) { + return importStatement.replace(/;$/, ''); +}, ``` -### `useRelativePaths` +### `logLevel` -This option is enabled by default. When enabled, imports will be resolved -relative to the current file being edited. +One of `["debug", "info", "warn", "error"]`. This controls what ends up in the +logfile. The default is `info`. ```javascript -import Foo from './foo'; -import Bar from '../baz/bar'; +logLevel: 'debug'; ``` -You can disable this by setting it to false: +The logfile is written to "importjs.log" in your operating system's default +directory for temporary files. You can get the path to the log file by running +`importjs logpath`. + +### `maxLineLength` + +Defaults to `80`. This setting controls when import statements are broken into +multiple lines. ```javascript -useRelativePaths: false; +maxLineLength: 70; ``` -Package dependencies (located in `node_modules`) will not be imported -relatively. +### `mergableOptions` -### `ignorePackagePrefixes` +A dictionary of Options that be merged with defaults and values provided by an [`environment`](#environments). This can be used to overwrite options provided by environments. Defaults to: -If you have package dependencies specified in `package.json` that are prefixed -with e.g. an organization name but want to be able to import these without the -package prefix, you can set the `ignorePackagePrefixes` configuration option. +```javascript +mergableOptions: { + aliases: true, + coreModules: true, + namedExports: true, + globals: true, +} +``` + +Note: the `mergableOptions` option will always be merged and will be ignored if +included in a user config. + +To disable merging a particular option or set of options, set the key to +`false`: ```javascript -ignorePackagePrefixes: ['my-company-']; +mergableOptions: { + globals: false; +} ``` -When package dependencies are matched, these prefixes will be ignored. As an -example, a variable named `validator` would match a package named -`my-company-validator`. +For example, if you are using the `meteor` environment but want to explicitly +import modules which are provided as globals, you can use this setting to +overwrite the environment globals. + +```javascript +const globals = require('globals'); +module.exports = { + environments: ['meteor', 'node'], + mergableOptions: { + globals: false, // Overwrite globals + }, + globals: [ + // Add the globals you want back in + ...Object.keys(globals.builtin), // include javascript builtins + ...Object.keys(globals.node), // include node globals + 'Package', + 'Npm', // Include meteor globals for `package.js` files + ], +}; +``` ### `minimumVersion` @@ -454,15 +397,6 @@ warning that encourages you to upgrade your plugin. minimumVersion: '1.0.0'; ``` -### `maxLineLength` - -Defaults to `80`. This setting controls when import statements are broken into -multiple lines. - -```javascript -maxLineLength: 70; -``` - ### `moduleNameFormatter` Use a function here to control how the resulting module name string will look @@ -489,88 +423,107 @@ moduleNameFormatter({ moduleName, pathToCurrentFile }) { }, ``` -### `importStatementFormatter` +### `namedExports` -Use a function here to control how the resulting import statement will look -like. This is useful if you for instance want to strip out trailing semicolons -(that ImportJS adds by default). +\*Note: Since 2.1.0 ImportJS finds your named exports automatically. Most +likely you don't need this option. If you end up having to use this +configuration anyway, there might be a bug in the exports-finding parts of +ImportJS. [File an issue](https://github.com/Galooshi/import-js/issues) and +tell us about it! -Note: this method should only be used in rare cases. There's a chance that -ImportJS won't be able to recognize the resulting import statement next time it -is about to import something. +If you have an ES6/ES2015 module that exports multiple things (named exports), +or a CommonJS module that exports an object with properties on it that you want +to destructure when importing, you can add those to a `namedExports` +configuration option. ```javascript -importStatementFormatter({ importStatement }) { - return importStatement.replace(/;$/, ''); -}, +namedExports: { + underscore: [ + 'omit', + 'debounce', + 'memoize' + ], + 'lib/utils': [ + 'escape', + 'hasKey', + ], +} ``` -### `tab` - -Defaults to two spaces (`" "`). This setting controls how indentation is -constructed when import statements are broken into multiple lines. +Imports that use the `import` declaration keyword then use [named imports +syntax][]. e.g. ```javascript -tab: '\t'; -``` +import { memoize } from 'underscore'; -### `logLevel` +memoize(() => { + foo(); +}); +``` -One of `["debug", "info", "warn", "error"]`. This controls what ends up in the -logfile. The default is `info`. +and imports that use `const` or `var` use [ES2015 Destructuring +Assigment][destructing assignment], e.g. ```javascript -logLevel: 'debug'; +const { memoize } = require('underscore'); + +memoize(() => { + foo(); +}); ``` -The logfile is written to "importjs.log" in your operating system's default -directory for temporary files. You can get the path to the log file by running -`importjs logpath`. +[named imports syntax]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import +[destructuring assignment]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment -### `mergableOptions` +The key used to describe the named exports should be a valid import path. This +can be e.g. the name of a package found under `node_modules`, a path to a +module you created yourself, or a relative import path. -A dictionary of Options that be merged with defaults and values provided by an [`environment`](#environments). This can be used to overwrite options provided by environments. Defaults to: +Consider the example as a valid use case for the `namedExports` property. Let's say we have a file: -```javascript -mergableOptions: { - aliases: true, - coreModules: true, - namedExports: true, - globals: true, +```jsx +import { Provider } from 'react-redux'; +import React from 'react'; +import store from './redux/redux-store'; +import ReactDOM from 'react-dom'; +import App from './App'; + +ReactDOM.render( + + + + + , + document.getElementById('root'), +); +``` + +And we're going to import `BrowserRouter` but instead of the desired result we get +the _No JS module to import for `BrowserRouter`_ message. +In order to fix the problem, populate `namedExports` in your config file as follows: + +```js +namedExports: { + 'react-router-dom': ['BrowserRouter', 'Route', 'Redirect'] } ``` -Note: the `mergableOptions` option will always be merged and will be ignored if -included in a user config. +After that we are able to import `BrowserRouter` correctly. The resulting import statement will look like this: -To disable merging a particular option or set of options, set the key to -`false`: +`import { BrowserRouter } from 'react-router-dom'` + +If you aren't ready for ES2015 yet, you have the option to use `var` or `const` +instead. ```javascript -mergableOptions: { - globals: false; -} +declarationKeyword: 'const'; ``` -For example, if you are using the `meteor` environment but want to explicitly -import modules which are provided as globals, you can use this setting to -overwrite the environment globals. +In such case, your import statements will look something like this: ```javascript -const globals = require('globals'); -module.exports = { - environments: ['meteor', 'node'], - mergableOptions: { - globals: false, // Overwrite globals - }, - globals: [ - // Add the globals you want back in - ...Object.keys(globals.builtin), // include javascript builtins - ...Object.keys(globals.node), // include node globals - 'Package', - 'Npm', // Include meteor globals for `package.js` files - ], -}; +var Foo = require('foo'); // "declarationKeyword": "var" +const Foo = require('foo'); // "declarationKeyword": "const" ``` ### `parserPlugins` @@ -621,6 +574,55 @@ parserPlugins: [ ] ``` +### `sortImports` + +By default, ImportJS will sort imports by the name or path of the imported module. + +You can turn off this behavior by setting `sortImports` to `false`. When +disabled, existing imports are not rearranged, and new imports are always added above existing imports. + +```javascript +sortImports: false; +``` + +### `stripFileExtensions` + +An array that controls what file extensions are stripped out from the resulting +import statement. The default configuration strips out `[".js", ".jsx", ".ts", +".tsx"]`. Set to an empty array `[]` to avoid stripping out extensions. + +```javascript +stripFileExtensions: ['.web.js', '.js']; +``` + +### `tab` + +Defaults to two spaces (`" "`). This setting controls how indentation is +constructed when import statements are broken into multiple lines. + +```javascript +tab: '\t'; +``` + +### `useRelativePaths` + +This option is enabled by default. When enabled, imports will be resolved +relative to the current file being edited. + +```javascript +import Foo from './foo'; +import Bar from '../baz/bar'; +``` + +You can disable this by setting it to false: + +```javascript +useRelativePaths: false; +``` + +Package dependencies (located in `node_modules`) will not be imported +relatively. + ## Dynamic configuration Different sections of your application may have special importing needs. For