From 7d855e65e31e447434f5863aa39d4279d31887a6 Mon Sep 17 00:00:00 2001 From: Sebastian Good <2230835+scagood@users.noreply.github.com> Date: Mon, 25 Sep 2023 10:27:11 +0300 Subject: [PATCH] docs: Create a shared settings document (#115) --- .eslint-doc-generatorrc.js | 1 + docs/rules/file-extension-in-import.md | 36 +--- docs/rules/no-extraneous-import.md | 51 +----- docs/rules/no-extraneous-require.md | 63 ++----- docs/rules/no-missing-import.md | 82 +-------- docs/rules/no-missing-require.md | 90 ++-------- docs/rules/no-unpublished-bin.md | 76 +------- docs/rules/no-unpublished-import.md | 100 +---------- docs/rules/no-unpublished-require.md | 109 +----------- docs/rules/shebang.md | 76 +------- docs/shared-settings.md | 235 +++++++++++++++++++++++++ 11 files changed, 298 insertions(+), 621 deletions(-) create mode 100644 docs/shared-settings.md diff --git a/.eslint-doc-generatorrc.js b/.eslint-doc-generatorrc.js index a7f61e00..526d133c 100644 --- a/.eslint-doc-generatorrc.js +++ b/.eslint-doc-generatorrc.js @@ -10,6 +10,7 @@ const config = { ["flat/recommended", "☑️"], ["flat/mixed-esm-and-cjs", "🟠"], ], + ruleDocSectionOptions: false, } module.exports = config diff --git a/docs/rules/file-extension-in-import.md b/docs/rules/file-extension-in-import.md index 3339fa55..cfec2f36 100644 --- a/docs/rules/file-extension-in-import.md +++ b/docs/rules/file-extension-in-import.md @@ -92,39 +92,15 @@ import logo from "./logo.png" ### Shared Settings -The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings). -Several rules have the same option, but we can set this option at once. +#### tsconfigPath -#### typescriptExtensionMap - -Adds the ability to change the extension mapping when converting between typescript and javascript - -You can also use the [typescript compiler jsx options](https://www.typescriptlang.org/tsconfig#jsx) to automatically use the correct mapping. +This can be configured in the shared settings [`settings.tsconfigPath`](../shared-settings.md#tsconfigpath). +Please see the shared settings documentation for more information. -If this option is left undefined we: - -1. Check your `tsconfig.json` `compilerOptions.jsx` -2. Return the default mapping (jsx = `preserve`) +#### typescriptExtensionMap -```js -// .eslintrc.js -module.exports = { - "settings": { - "node": { - "typescriptExtensionMap": [ - [ "", ".js" ], - [ ".ts", ".js" ], - [ ".cts", ".cjs" ], - [ ".mts", ".mjs" ], - [ ".tsx", ".jsx" ], - ] - } - }, - "rules": { - "n/file-extension-in-import": "error" - } -} -``` +This can be configured in the shared settings [`settings.typescriptExtensionMap`](../shared-settings.md#typescriptextensionmap). +Please see the shared settings documentation for more information. ## 🔎 Implementation diff --git a/docs/rules/no-extraneous-import.md b/docs/rules/no-extraneous-import.md index 97e56dd6..4e8fd622 100644 --- a/docs/rules/no-extraneous-import.md +++ b/docs/rules/no-extraneous-import.md @@ -26,57 +26,18 @@ This rule warns `import` declarations of extraneous modules. #### allowModules -Some platforms have additional embedded modules. -For example, Electron has `electron` module. - -We can specify additional embedded modules with this option. -This option is an array of strings as module names. - -```json -{ - "rules": { - "n/no-extraneous-import": ["error", { - "allowModules": ["electron"] - }] - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.allowModules`](../shared-settings.md#allowmodules). +Please see the shared settings documentation for more information. #### resolvePaths -Adds additional paths to try for when resolving imports. -If a path is relative, it will be resolved from CWD. - -Default is `[]` +This can be configured in the rule options or as a shared setting [`settings.resolvePaths`](../shared-settings.md#resolvepaths). +Please see the shared settings documentation for more information. #### convertPath -- `exclude`: TODO -- `include`: TODO -- `replace`: TODO - -### Shared Settings - -The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings). -Several rules have the same option, but we can set this option at once. - -- `allowModules` -- `resolvePaths` - -```js -// .eslintrc.js -module.exports = { - "settings": { - "node": { - "allowModules": ["electron"], - "resolvePaths": [__dirname], - } - }, - "rules": { - "n/no-extraneous-import": "error" - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.convertPath`](../shared-settings.md#convertpath). +Please see the shared settings documentation for more information. ## 🔎 Implementation diff --git a/docs/rules/no-extraneous-require.md b/docs/rules/no-extraneous-require.md index 9e6f1890..535f0951 100644 --- a/docs/rules/no-extraneous-require.md +++ b/docs/rules/no-extraneous-require.md @@ -27,66 +27,23 @@ This rule warns `require()` of extraneous modules. #### allowModules -Some platforms have additional embedded modules. -For example, Electron has `electron` module. - -We can specify additional embedded modules with this option. -This option is an array of strings as module names. - -```json -{ - "rules": { - "n/no-extraneous-require": ["error", { - "allowModules": ["electron"] - }] - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.allowModules`](../shared-settings.md#allowmodules). +Please see the shared settings documentation for more information. #### resolvePaths -Adds additional paths to try for when resolving imports. -If a path is relative, it will be resolved from CWD. +This can be configured in the rule options or as a shared setting [`settings.resolvePaths`](../shared-settings.md#resolvepaths). +Please see the shared settings documentation for more information. -Default is `[]` - -#### tryExtensions - -When an import path does not exist, this rule checks whether or not any of `path.js`, `path.json`, and `path.node` exists. -`tryExtensions` option is the extension list this rule uses at the time. +#### convertPath -Default is `[".js", ".json", ".node"]`. +This can be configured in the rule options or as a shared setting [`settings.convertPath`](../shared-settings.md#convertpath). +Please see the shared settings documentation for more information. -#### convertPath +#### tryExtensions -- `exclude`: TODO -- `include`: TODO -- `replace`: TODO - -### Shared Settings - -The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings). -Several rules have the same option, but we can set this option at once. - -- `allowModules` -- `resolvePaths` -- `tryExtensions` - -```js -// .eslintrc.js -module.exports = { - "settings": { - "node": { - "allowModules": ["electron"], - "resolvePaths": [__dirname], - "tryExtensions": [".js", ".json", ".node"] - } - }, - "rules": { - "n/no-extraneous-require": "error" - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.tryExtensions`](../shared-settings.md#tryextensions). +Please see the shared settings documentation for more information. ## 🔎 Implementation diff --git a/docs/rules/no-missing-import.md b/docs/rules/no-missing-import.md index 3138b22d..903e72b1 100644 --- a/docs/rules/no-missing-import.md +++ b/docs/rules/no-missing-import.md @@ -46,87 +46,23 @@ import existingModule from "existing-module"; #### allowModules -Some platforms have additional embedded modules. -For example, Electron has `electron` module. - -We can specify additional embedded modules with this option. -This option is an array of strings as module names. - -```json -{ - "rules": { - "n/no-missing-import": ["error", { - "allowModules": ["electron"] - }] - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.allowModules`](../shared-settings.md#allowmodules). +Please see the shared settings documentation for more information. #### resolvePaths -Adds additional paths to try for when resolving imports. -If a path is relative, it will be resolved from CWD. - -Default is `[]` - -#### typescriptExtensionMap - -Adds the ability to change the extension mapping when converting between typescript and javascript - -You can also use the [typescript compiler jsx options](https://www.typescriptlang.org/tsconfig#jsx) to automatically use the correct mapping. - -If this option is left undefined we: - -1. Check the Shared Settings -2. Check your `tsconfig.json` `compilerOptions.jsx` -3. Return the default mapping (jsx = `preserve`) - -Default is: - -```json -[ - [ "", ".js" ], - [ ".ts", ".js" ], - [ ".cts", ".cjs" ], - [ ".mts", ".mjs" ], - [ ".tsx", ".jsx" ], -] -``` +This can be configured in the rule options or as a shared setting [`settings.resolvePaths`](../shared-settings.md#resolvepaths). +Please see the shared settings documentation for more information. #### tsconfigPath -Adds the ability to specify the tsconfig used by the typescriptExtensionMap tool. - -### Shared Settings +This can be configured in the rule options or as a shared setting [`settings.tsconfigPath`](../shared-settings.md#tsconfigpath). +Please see the shared settings documentation for more information. -The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings). -Several rules have the same option, but we can set this option at once. - -- `allowModules` -- `resolvePaths` -- `typescriptExtensionMap` +#### typescriptExtensionMap -```js -// .eslintrc.js -module.exports = { - "settings": { - "node": { - "allowModules": ["electron"], - "resolvePaths": [__dirname], - "typescriptExtensionMap": [ - [ "", ".js" ], - [ ".ts", ".js" ], - [ ".cts", ".cjs" ], - [ ".mts", ".mjs" ], - [ ".tsx", ".js" ], - ] - } - }, - "rules": { - "n/no-missing-import": "error" - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.typescriptExtensionMap`](../shared-settings.md#typescriptextensionmap). +Please see the shared settings documentation for more information. ## 🔎 Implementation diff --git a/docs/rules/no-missing-require.md b/docs/rules/no-missing-require.md index b0fe2d90..d519baa2 100644 --- a/docs/rules/no-missing-require.md +++ b/docs/rules/no-missing-require.md @@ -52,96 +52,28 @@ var foo = require(FOO_NAME); #### allowModules -Some platforms have additional embedded modules. -For example, Electron has `electron` module. - -We can specify additional embedded modules with this option. -This option is an array of strings as module names. - -```json -{ - "rules": { - "n/no-missing-require": ["error", { - "allowModules": ["electron"] - }] - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.allowModules`](../shared-settings.md#allowmodules). +Please see the shared settings documentation for more information. #### resolvePaths -Adds additional paths to try for when resolving a require. -If a path is relative, it will be resolved from CWD. - -Default is `[]` +This can be configured in the rule options or as a shared setting [`settings.resolvePaths`](../shared-settings.md#resolvepaths). +Please see the shared settings documentation for more information. #### tryExtensions -When an import path does not exist, this rule checks whether or not any of `path.js`, `path.json`, and `path.node` exists. -`tryExtensions` option is the extension list this rule uses at the time. - -Default is `[".js", ".json", ".node"]`. - -#### typescriptExtensionMap - -Adds the ability to change the extension mapping when converting between typescript and javascript - -You can also use the [typescript compiler jsx options](https://www.typescriptlang.org/tsconfig#jsx) to automatically use the correct mapping. - -If this option is left undefined we: - -1. Check the Shared Settings -2. Check your `tsconfig.json` `compilerOptions.jsx` -3. Return the default mapping (jsx = `preserve`) - -Default is: - -```json -[ - [ "", ".js" ], - [ ".ts", ".js" ], - [ ".cts", ".cjs" ], - [ ".mts", ".mjs" ], - [ ".tsx", ".jsx" ], -] -``` +This can be configured in the rule options or as a shared setting [`settings.tryExtensions`](../shared-settings.md#tryextensions). +Please see the shared settings documentation for more information. #### tsconfigPath -Adds the ability to specify the tsconfig used by the typescriptExtensionMap tool. - -### Shared Settings +This can be configured in the rule options or as a shared setting [`settings.tsconfigPath`](../shared-settings.md#tsconfigpath). +Please see the shared settings documentation for more information. -The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings). -Several rules have the same option, but we can set this option at once. - -- `allowModules` -- `resolvePaths` -- `tryExtensions` -- `typescriptExtensionMap` +#### typescriptExtensionMap -```js -// .eslintrc.js -module.exports = { - "settings": { - "node": { - "allowModules": ["electron"], - "resolvePaths": [__dirname], - "tryExtensions": [".js", ".json", ".node"], - "typescriptExtensionMap": [ - [ "", ".js" ], - [ ".ts", ".js" ], - [ ".cts", ".cjs" ], - [ ".mts", ".mjs" ], - [ ".tsx", ".js" ], - ] - } - }, - "rules": { - "n/no-missing-require": "error" - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.typescriptExtensionMap`](../shared-settings.md#typescriptextensionmap). +Please see the shared settings documentation for more information. ## 🔎 Implementation diff --git a/docs/rules/no-unpublished-bin.md b/docs/rules/no-unpublished-bin.md index 726a61e4..e6af925c 100644 --- a/docs/rules/no-unpublished-bin.md +++ b/docs/rules/no-unpublished-bin.md @@ -36,80 +36,8 @@ If `npm` ignores the files in `bin` field, this rule warns the files. #### convertPath -If we use transpilers (e.g. Babel), perhaps the file path to a source code is never published. -`convertPath` option tells to the rule, it needs to convert file paths. - -For example: - -```json -{ - "rules": { - "n/no-unpublished-bin": ["error", { - "convertPath": { - "src/bin/**/*.js": ["^src/(.+)$", "$1"] - } - }] - } -} -``` - -This option has the following shape: `: [, ]` - -`targetFiles` is a glob pattern. -It converts paths which are matched to the pattern with the following way. - -```js -path.replace(new RegExp(fromRegExp), toString); -``` - -So on this example, `src/bin/index.js` is handled as `bin/index.js`. - -The `convertPath` option can be an array as well. - -For example: - -```json -{ - "rules": { - "n/no-unpublished-bin": ["error", { - "convertPath": [ - { - "include": ["src/bin/**/*.js"], - "exclude": ["**/*.spec.js"], - "replace": ["^src/(.+)$", "$1"] - } - ] - }] - } -} -``` - -In this style, this option has the following shape as the same expression as above: `{include: [], replace: [, ]}`. -In addition, we can specify glob patterns to exclude files. - -### Shared Settings - -The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings). -Several rules have the same option, but we can set this option at once. - -- `convertPath` - -For Example: - -```json -{ - "settings": { - "node": { - "convertPath": { - "src/bin/**/*.js": ["^src/bin/(.+)$", "bin/$1"] - } - } - }, - "rules": { - "n/no-unpublished-bin": "error" - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.convertPath`](../shared-settings.md#convertpath). +Please see the shared settings documentation for more information. ## 🔎 Implementation diff --git a/docs/rules/no-unpublished-import.md b/docs/rules/no-unpublished-import.md index 850c3827..eab9516b 100644 --- a/docs/rules/no-unpublished-import.md +++ b/docs/rules/no-unpublished-import.md @@ -35,78 +35,18 @@ Then this rule warns `import` declarations in \*published\* files if the `import #### allowModules -Some platforms have additional embedded modules. -For example, Electron has `electron` module. +This can be configured in the rule options or as a shared setting [`settings.allowModules`](../shared-settings.md#allowmodules). +Please see the shared settings documentation for more information. -We can specify additional embedded modules with this option. -This option is an array of strings as module names. +#### resolvePaths -```json -{ - "rules": { - "n/no-unpublished-import": ["error", { - "allowModules": ["electron"] - }] - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.resolvePaths`](../shared-settings.md#resolvepaths). +Please see the shared settings documentation for more information. #### convertPath -If we use transpilers (e.g. Babel), perhaps the file path to a source code is never published. -`convertPath` option tells to the rule, it needs to convert file paths. - -For example: - -```json -{ - "rules": { - "n/no-unpublished-import": ["error", { - "convertPath": { - "src/**/*.jsx": ["^src/(.+?)\\.jsx$", "lib/$1.js"] - } - }] - } -} -``` - -This option has the following shape: `: [, ]` - -`targetFiles` is a glob pattern. -It converts paths which are matched to the pattern with the following way. - -```js -path.replace(new RegExp(fromRegExp), toString); -``` - -So on this example, `src/a/foo.jsx` is handled as `lib/a/foo.js`. - -The `convertPath` option can be an array as well. - -For example: - -```json -{ - "rules": { - "n/no-unpublished-import": ["error", { - "convertPath": [ - { - "include": ["src/**/*.js"], - "exclude": ["**/*.spec.js"], - "replace": ["^src/(.+)$", "lib/$1"] - } - ] - }] - } -} -``` - -In this style, this option has the following shape as the same expression as above: `{include: [], replace: [, ]}`. -In addition, we can specify glob patterns to exclude files. - -#### resolvePaths - -TODO +This can be configured in the rule options or as a shared setting [`settings.convertPath`](../shared-settings.md#convertpath). +Please see the shared settings documentation for more information. ### ignoreTypeImport @@ -128,32 +68,6 @@ In this way, the following code will not be reported: import type foo from "foo"; ``` -### Shared Settings - -The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings). -Several rules have the same option, but we can set this option at once. - -- `allowModules` -- `convertPath` - -For Example: - -```json -{ - "settings": { - "node": { - "allowModules": ["electron"], - "convertPath": { - "src/**/*.jsx": ["^src/(.+?)\\.jsx$", "lib/$1.js"] - } - } - }, - "rules": { - "n/no-unpublished-import": "error" - } -} -``` - ## 🔎 Implementation - [Rule source](../../lib/rules/no-unpublished-import.js) diff --git a/docs/rules/no-unpublished-require.md b/docs/rules/no-unpublished-require.md index a2759391..bfbdfa69 100644 --- a/docs/rules/no-unpublished-require.md +++ b/docs/rules/no-unpublished-require.md @@ -35,114 +35,23 @@ Then this rule warns `require()` expressions in \*published\* files if the `requ #### allowModules -Some platforms have additional embedded modules. -For example, Electron has `electron` module. +This can be configured in the rule options or as a shared setting [`settings.allowModules`](../shared-settings.md#allowmodules). +Please see the shared settings documentation for more information. -We can specify additional embedded modules with this option. -This option is an array of strings as module names. +#### resolvePaths -```json -{ - "rules": { - "n/no-unpublished-require": ["error", { - "allowModules": ["electron"] - }] - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.resolvePaths`](../shared-settings.md#resolvepaths). +Please see the shared settings documentation for more information. #### convertPath -If we use transpilers (e.g. Babel), perhaps the file path to a source code is never published. -`convertPath` option tells to the rule, it needs to convert file paths. - -For example: - -```json -{ - "rules": { - "n/no-unpublished-require": ["error", { - "convertPath": { - "src/**/*.jsx": ["^src/(.+?)\\.jsx$", "lib/$1.js"] - }, - "tryExtensions": [".js", ".jsx", ".json"] - }] - } -} -``` - -This option has the following shape: `: [, ]` - -`targetFiles` is a glob pattern. -It converts paths which are matched to the pattern with the following way. - -```js -path.replace(new RegExp(fromRegExp), toString); -``` - -So on this example, `src/a/foo.jsx` is handled as `lib/a/foo.js`. - -The `convertPath` option can be an array as well. - -For example: - -```json -{ - "rules": { - "n/no-unpublished-require": ["error", { - "convertPath": [ - { - "include": ["src/**/*.js"], - "exclude": ["**/*.spec.js"], - "replace": ["^src/(.+)$", "lib/$1"] - } - ] - }] - } -} -``` - -In this style, this option has the following shape as the same expression as above: `{include: [], replace: [, ]}`. -In addition, we can specify glob patterns to exclude files. +This can be configured in the rule options or as a shared setting [`settings.convertPath`](../shared-settings.md#convertpath). +Please see the shared settings documentation for more information. #### tryExtensions -When an import path does not exist, this rule checks whether or not any of `path.js`, `path.json`, and `path.node` exists. -`tryExtensions` option is the extension list this rule uses at the time. - -Default is `[".js", ".json", ".node"]`. - -#### resolvePaths - -TODO - -### Shared Settings - -The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings). -Several rules have the same option, but we can set this option at once. - -- `allowModules` -- `convertPath` -- `tryExtensions` - -For Example: - -```json -{ - "settings": { - "node": { - "allowModules": ["electron"], - "convertPath": { - "src/**/*.jsx": ["^src/(.+?)\\.jsx$", "lib/$1.js"] - }, - "tryExtensions": [".js", ".jsx", ".json"] - } - }, - "rules": { - "n/no-unpublished-require": "error" - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.tryExtensions`](../shared-settings.md#tryextensions). +Please see the shared settings documentation for more information. ## 🔎 Implementation diff --git a/docs/rules/shebang.md b/docs/rules/shebang.md index fc56e474..205e5d11 100644 --- a/docs/rules/shebang.md +++ b/docs/rules/shebang.md @@ -67,80 +67,8 @@ console.log("hello"); #### convertPath -If we use transpilers (e.g. Babel), perhaps the file path to a source code is never handled as a bin file. -`convertPath` option tells to the rule, it needs to convert file paths. - -For example: - -```json -{ - "rules": { - "n/shebang": ["error", { - "convertPath": { - "src/**/*.jsx": ["^src/(.+?)\\.jsx$", "lib/$1.js"] - } - }] - } -} -``` - -This option has the following shape: `: [, ]` - -`targetFiles` is a glob pattern. -It converts paths which are matched to the pattern with the following way. - -```js -path.replace(new RegExp(fromRegExp), toString); -``` - -So on this example, `src/a/foo.jsx` is handled as `lib/a/foo.js`. - -The `convertPath` option can be an array as well. - -For example: - -```json -{ - "rules": { - "n/shebang": ["error", { - "convertPath": [ - { - "include": ["src/**/*.js"], - "exclude": ["**/*.spec.js"], - "replace": ["^src/(.+)$", "lib/$1"] - } - ] - }] - } -} -``` - -In this style, this option has the following shape as the same expression as above: `{include: [], replace: [, ]}`. -In addition, we can specify glob patterns to exclude files. - -### Shared Settings - -The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings). -Several rules have the same option, but we can set this option at once. - -- `convertPath` - -For Example: - -```json -{ - "settings": { - "node": { - "convertPath": { - "src/**/*.jsx": ["^src/(.+?)\\.jsx$", "lib/$1.js"] - } - } - }, - "rules": { - "n/shebang": "error" - } -} -``` +This can be configured in the rule options or as a shared setting [`settings.convertPath`](../shared-settings.md#convertpath). +Please see the shared settings documentation for more information. ## 🔎 Implementation diff --git a/docs/shared-settings.md b/docs/shared-settings.md new file mode 100644 index 00000000..47b85ee9 --- /dev/null +++ b/docs/shared-settings.md @@ -0,0 +1,235 @@ +# Shared Settings + +The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings). +Several rules have the same option, but we can set this option at once. + +`eslint-plugin-n` reads both the `node`, and the `n` settings to allow for backward compatibility with `eslint-plugin-node`. + +## version + +This rule reads the [`engines`] field of `package.json` but, you can overwrite the version by `version` option. + +The `version` option accepts [the valid version range of `node-semver`](https://github.com/npm/node-semver#range-grammar). + +### Example version + +```json +{ "version": ">= 14" } +``` + +### Default version + +```json +{ "version": ">= 16.0.0" } +``` + +## allowModules + +Some platforms have additional embedded modules. +For example, Electron has `electron` module. + +We can specify additional embedded modules with this option. +This option is an array of strings as module names. + +### Example allowModules + +```json +{ "allowModules": ["electron"] } +``` + +### Default allowModules + +```json +{ "allowModules": [] } +``` + +## resolvePaths + +Adds additional paths to try for when resolving imports. +If a path is relative, it will be resolved from CWD. + +### Example resolvePaths + +```json +{ "resolvePaths": ["/path/to/somewhere", "../relative/path"] } +``` + +### Default resolvePaths + +```json +{ "resolvePaths": [] } +``` + +## convertPath + +If we use transpilers (e.g. Babel), perhaps the file path to a source code is never published. +`convertPath` option tells to the rule, it needs to convert file paths. + +This option has two shapes: + +```ts +type ConvertPathObject = { + [includedFiles: string]: [ pattern: string, replacement: string ] +} +``` + +```ts +type ConvertPathArray = { + include: string[], + exclude?: string[], + replace: [ pattern: string, replacement: string ] +}[] +``` + +All replacements use the following code: + +```js +path.replace(new RegExp(pattern), replacement); +``` + +This means the following replacements are permitted: + +| Pattern | Inserts | +| --- | --- | +| `$$` | Inserts a "$". | +| `$&` | Inserts the matched substring. | +| `` $` `` | Inserts the portion of the string that precedes the matched substring. | +| `$'` | Inserts the portion of the string that follows the matched substring. | +| `$n` | Inserts the nth (1-indexed) capturing group where n is a positive integer less than 100. | +| `$` | Inserts the named capturing group where Name is the group name. | + +### convertPath - Object + +This option has the following shape: `: [, ]` + +- `targetFiles` is a glob pattern matching linted files +- `pattern` is a string escaped regex we pass to `new RegExp` +- `replacement` is the replacement string. + +#### Example convertPath - Object + +So in this example, `src/bin/index.js` is handled as `bin/index.js`. + +```json +{ "convertPath": { + "src/bin/**/*.js": ["^src/bin/(.+)$", "bin/$1"] +} } +``` + +### convertPath - Array + +This option has the following shape: `{ include: , exclude: , replace: [, ] }` + +- `includedFiles` is a glob pattern matching linted files +- `excludedFiles` is a glob pattern matching files in includedFiles that we want to exclude +- `pattern` is a string escaped regex we pass to `new RegExp` +- `replacement` is the replacement string. + +#### Example 1 - Basics + +So in this example, `src/bin/index.js` is handled as `bin/index.js`. + +```json +{ "convertPath": [ + { + "include": ["src/bin/**/*.js"], + "replace": ["^src/bin/(.+)$", "bin/$1"] + } +] } +``` + +#### Example 2 - Exclude specs + +So in this example, `src/bin/index.js` is handled as `bin/index.js` but, we exclude all `.spec.js` from the conversion. + +```json +{ "convertPath": [ + { + "include": ["src/bin/**/*.js"], + "exclude": ["**/*.spec.js"], + "replace": ["^src/bin/(.+)$", "bin/$1"] + } +] } +``` + +## tryExtensions + +When an import path does not exist, this rule checks whether or not any of `path.js`, `path.json`, and `path.node` exists. +`tryExtensions` option is the extension list this rule uses at the time. + +### Example tryExtensions + +In this example we only allow the .js, and .ts extensions to be tried. + +```json +{ "tryExtensions": [ ".js", ".ts" ] } +``` + +### Default tryExtensions + +```json +{ "tryExtensions": [ ".js", ".json", ".node" ] } +``` + +## tsconfigPath + +Adds the ability to specify the tsconfig used by the typescriptExtensionMap tool. + +### Example absolute tsconfigPath + +```json +{ "tsconfigPath": "/path/to/tsconfig.json" } +``` + +### Example relative tsconfigPath + +```json +{ "tsconfigPath": "./.tsconfig/development.json" } +``` + +### Default tsconfigPath + +By default the `tsconfigPath` is searched for up the file tree from the currently linted file. + +## typescriptExtensionMap + +Adds the ability to change the extension mapping when converting between typescript and javascript + +You can also use the [typescript compiler jsx options](https://www.typescriptlang.org/tsconfig#jsx) to automatically use the correct mapping. + +We perform the following checks to work out what your ts extension mappings should be: + +1. This checks `options.typescriptExtensionMap`, if its an array then it gets returned. +2. This checks `options.typescriptExtensionMap`, if its a string, convert to the correct mapping. +3. This checks `options.tsconfigFile`, if its set it check for a `compilerOptions.jsx` property +4. This checks `settings.typescriptExtensionMap`, if its an array then it gets returned. +5. This checks `settings.typescriptExtensionMap`, if its a string, convert to the correct mapping. +6. This checks `settings.tsconfigFile`, if its set it check for a `compilerOptions.jsx` property +7. This tries to find the closest `tsconfig.json`, then checks for a `compilerOptions.jsx` property +8. This returns `PRESERVE_MAPPING`. + +### Example - Custom react mappings + +```json +{ "typescriptExtensionMap": [ + [ "", ".js" ], + [ ".ts", ".js" ], + [ ".cts", ".cjs" ], + [ ".mts", ".mjs" ], + [ ".tsx", ".js" ], +] } +``` + +### Example - Wordy react mappings + +```json +{ "typescriptExtensionMap": "react" } +``` + +### Default typescriptExtensionMap + +If we cannot find a tsconfig file, we fall back to using: + +```json +{ "typescriptExtensionMap": "preserve" } +```