From 4fe4dba5b3321920f011b1ad62da1d0c5812a4e2 Mon Sep 17 00:00:00 2001 From: Francesco Trotta Date: Mon, 2 Mar 2026 14:01:01 +0100 Subject: [PATCH 1/8] feat: support `--base-path` option --- designs/2026-custom-base-path/README.md | 172 ++++++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 designs/2026-custom-base-path/README.md diff --git a/designs/2026-custom-base-path/README.md b/designs/2026-custom-base-path/README.md new file mode 100644 index 00000000..b0b58454 --- /dev/null +++ b/designs/2026-custom-base-path/README.md @@ -0,0 +1,172 @@ +- Repo: `eslint/eslint`, possibly `eslint/rewrite` +- Start Date: 2026-02-03 +- RFC PR: (leave this empty, to be filled in later) +- Authors: Francesco Trotta + +# Support `--base-path` Option + +## Summary + +This document proposes a mechanism for configuring and linting files relative to a specified directory, regardless of the current working directory (CWD) or where the configuration file is located. This is achieved by introducing a new CLI option `--base-path`, and a corresponding `basePath` option on the `ESLint` constructor. + +## Motivation + +In the legacy eslintrc configuration system, users could lint files in arbitrary locations by explicitly specifying a config file (for example, via `--config`). +ESLint would resolve the target file paths relative to the current working directory and lint them, even though those files couldn’t be configured by that config. + +Flat config, on the other hand, enforces that only files under the current base path can be linted. When a config file is explicitly provided, the base path is the current working directory. This has caused problems for users migrating from legacy config to flat config, where linting files outside the current working directory previously worked. See [related discussions](#related-discussions) below for some examples. + +To support the legacy use case while allowing users to configure files independently, we propose introducing a new option that will allow users to specify a custom base path. + +## Detailed Design + +### Current Behavior + +The base path is the directory that defines which files a `ConfigArray` can lint. +Files outside that base path cannot be linted, even if they are matched by a config object. + +Today, ESLint determines the base path as follows: +- the current working directory, if either `--config` or `--no-config-lookup` is passed +- otherwise, the directory where the config file is located. If a project contains different config files, each config file has its own base path. + +Internally, this value is stored as `basePath` on `ConfigArray`. It serves two purposes: +- it limits which files can be linted +- it provides the default `basePath` for config objects that don't have one explicitly set. The config object's base path is then used to resolve that object's `files` and `ignores` + +### Proposed Change + +This proposal adds a way to set a custom base path that overrides the `basePath` of each config object. + +For users and integration developers, this introduces: +- a new CLI option, `--base-path` +- a corresponding `basePath` option on the `ESLint` constructor + +The base path must be a non-empty string and a valid absolute or relative path. If relative, it will be resolved against the current working directory, or against the `cwd` option when provided. + +When `basePath` is specified and no file patterns are passed on the command line, ESLint will enumerate files in that base path. For example: + +```shell +npx eslint --config=eslint.config.js --base-path=../src +``` + +will behave the same as + +```shell +npx eslint --config=eslint.config.js --base-path=../src ../src +``` + +### Alternative: Maintain Reference Location + +TODO + +### Example Usage + +The use case proposed in eslint/eslint#19118 involves linting files in a sibling directory of the current directory. + +```text +(root) +├─ app (cwd) +│ ├─ eslint.config.mjs +│ └─ ... (files to lint) +└─ tmp + └─ ... (more files to lint) +``` + +For this case, `--base-path` should point to a parent of both directories, i.e. `..`: + +```shell +npx eslint --config=eslint.config.mjs --base-path=.. . ../tmp +``` + +Relative paths in the config file will now be resolved relative to `..`. This includes `files` and `ignores` settings in config objects that don't include a `basePath`, or the config object's `basePath` itself. So, a config object that specifies different settings for the current directory and its sibling would look for example like this: + +```js +export default defineConfig([ + { + name: "app-config", + files: ["app/**/*.{,c,m}js"], + ...myAppConfig + }, + { + name: "tmp-config", + files: ["tmp/**/*.{c,m}js"], + ...myTmpConfig + }, +]); +``` + +or similarly, using a `basePath`: + +```js +export default defineConfig([ + { + name: "app-config", + basePath: "app", + files: ["**/*.{,c,m}js"], + ...myAppConfig + }, + { + name: "tmp-config", + basePath: "tmp", + files: ["**/*.{c,m}js"], + ...myTmpConfig + }, +]); +``` + +## Documentation + +- [CLI options](https://eslint.org/docs/latest/use/command-line-interface) +- [`ESLint` constructor options](https://eslint.org/docs/latest/integrate/nodejs-api#-new-eslintoptions) +- [`@eslint/config-array`](https://github.com/eslint/rewrite/tree/main/packages/config-array#readme) (if a new `ConfigArray` option is added) + +## Drawbacks + +Besides the added maintenance burden, this change will add complexity to the configuration. + +## Backwards Compatibility Analysis + +This proposal is backward-compatible and does not introduce any breaking changes. + +## Alternatives + +### Change `**/` semantics to match outside the base path + +One proposal was to make patterns prefixed with `**/` (such as `**/*.js`) match files regardless of base path. + +This approach has some drawbacks: + +- it creates edge cases for `ignores` (for example, `**/foo/` might unexpectedly match ancestor path segments) +- it does not provide a clear way to target only specific paths outside the base path +- it would require matching against absolute paths in some cases, which is harder to reason about +- it changes established glob semantics and is potentially breaking + +To address the last point and avoid a breaking change, additional solutions have been proposed: + +- adding a feature flag `v10_file_matching` for changed glob semantics +- adding a dedicated config key `matchAbsolute` for absolute matching + +### Rely on config lookup improvements only + +The `unstable_config_lookup_from_file` / `v10_config_lookup_from_file` flag was considered as a possible way to cover these scenarios. + +User feedback pointed out that this does not solve the specific problem of linting files outside the effective base path when using a centralized config/tooling setup. + +### Add only `basePath` on config objects + +Adding `basePath` to config objects (discussed in related design work, see [RFC \#131](https://github.com/eslint/rfcs/tree/main/designs/2025-base-path-in-config-objects)) was also considered as a standalone solution. However, this change alone was not sufficient for this issue because files external to the base path were still being ignored as external. + +## Open Questions + +When `--base-path` is provided, should relative `basePath` values in config objects continue to resolve exactly as they do today (relative to config location / CWD), or should CLI `--base-path` influence that resolution? + +Should `--base-path` be allowed when config lookup is enabled (i.e. neither `--config` nor `--no-config-lookup` is passed)? In that case, ESLint will search for a config file in a file's directory and its ancestors. This means that config files outside that line of search will not be considered, so that each file is required to have its associated config in an expected location. In this setup, I'm not sure how `--base-path` would be useful. + +## Help Needed + +I can implement this RFC. + +## Related Discussions + +- eslint/eslint#19118 +- eslint/eslint#18806 From 18ad811d2ce798df7e48b272bdd47666121cbeec Mon Sep 17 00:00:00 2001 From: Francesco Trotta Date: Wed, 4 Mar 2026 17:02:31 +0100 Subject: [PATCH 2/8] add alternative proposal --- designs/2026-custom-base-path/README.md | 62 +++++++++++++++++++++---- 1 file changed, 54 insertions(+), 8 deletions(-) diff --git a/designs/2026-custom-base-path/README.md b/designs/2026-custom-base-path/README.md index b0b58454..ce1f687d 100644 --- a/designs/2026-custom-base-path/README.md +++ b/designs/2026-custom-base-path/README.md @@ -1,6 +1,6 @@ - Repo: `eslint/eslint`, possibly `eslint/rewrite` - Start Date: 2026-02-03 -- RFC PR: (leave this empty, to be filled in later) +- RFC PR: #131 - Authors: Francesco Trotta # Support `--base-path` Option @@ -35,7 +35,7 @@ Internally, this value is stored as `basePath` on `ConfigArray`. It serves two p ### Proposed Change -This proposal adds a way to set a custom base path that overrides the `basePath` of each config object. +This proposal adds a way to set a custom base path that overrides the `basePath` of each config array. For users and integration developers, this introduces: - a new CLI option, `--base-path` @@ -55,10 +55,6 @@ will behave the same as npx eslint --config=eslint.config.js --base-path=../src ../src ``` -### Alternative: Maintain Reference Location - -TODO - ### Example Usage The use case proposed in eslint/eslint#19118 involves linting files in a sibling directory of the current directory. @@ -80,6 +76,8 @@ npx eslint --config=eslint.config.mjs --base-path=.. . ../tmp Relative paths in the config file will now be resolved relative to `..`. This includes `files` and `ignores` settings in config objects that don't include a `basePath`, or the config object's `basePath` itself. So, a config object that specifies different settings for the current directory and its sibling would look for example like this: + + ```js export default defineConfig([ { @@ -97,6 +95,8 @@ export default defineConfig([ or similarly, using a `basePath`: + + ```js export default defineConfig([ { @@ -114,6 +114,45 @@ export default defineConfig([ ]); ``` +### Alternative: Maintain Reference Location + +The above solution is fully backwards-compatible but it's hard to extend to existing configurations because changing the base path also means that all relative paths and patterns in existing configs (in `files`, `ignores` and `basePath`) must be modified to be relative to the new base path. + +For example, in the example in the previous section, a project may already have a config that lints files in the current directory (`app`) like this: + +```js +export default defineConfig([ + { + name: "app-config", + files: ["**/*.{,c,m}js"], + ...myAppConfig + }, +]); +``` + +In order to extend this config to also lint files in `../tmp`, besides passing `--base-path=..`, the existing config object(s) in the config must be changed if they should still apply to the current directory only, either by modifying the `files` patterns as in [the first example](#example-1), or by adding an explicit `basePath` like in [the second example](#example-2). Note that in both cases, the name of the current working directory (`app`) must be explicitly added, because there is no longer an implicit way to reference it from the config. + +To avoid this inconvenience, we could add a new property to config arrays, tentatively name `referenceLocation`. This property will hold the value of what is currently the base path (CWD or config file location), and it will be used to resolve relative `basePath` values in config objects. This will ensure that existing config arrays can be extended to lint additional files with a new common directory root without changing existing config objects. For example, with this alternative, the example above can be extended to lint `../tmp` without changing the other config object(s), like this: + +```js +export default defineConfig([ + { + name: "app-config", + files: ["**/*.{,c,m}js"], + ...myAppConfig + }, + { + name: "tmp-config", + files: ["../tmp/**/*.{c,m}js"], + ...myTmpConfig + }, +]); +``` + +With this alternative, `--base-path` would define which files are in scope for file enumeration and linting, but resolution of `basePath` values in config objects would remain unchanged. + +While still maintaining the changes non-breaking and backwards-compatible, this alternative solution requires changing `@eslint/config-array` to introduce a new property on `ConfigArray` instances. It will also add complexity to the implementation. + ## Documentation - [CLI options](https://eslint.org/docs/latest/use/command-line-interface) @@ -122,7 +161,7 @@ export default defineConfig([ ## Drawbacks -Besides the added maintenance burden, this change will add complexity to the configuration. +Besides the added maintenance burden, this change will add complexity to the configuration, in terms of logic, documentation, and testing. Users and maintainers will need to reason about an additional parameter that plays a role in the behavior of a config. ## Backwards Compatibility Analysis @@ -158,7 +197,14 @@ Adding `basePath` to config objects (discussed in related design work, see [RFC ## Open Questions -When `--base-path` is provided, should relative `basePath` values in config objects continue to resolve exactly as they do today (relative to config location / CWD), or should CLI `--base-path` influence that resolution? +### Path-resolution model when `--base-path` is provided + +- Main proposal: relative config paths (`files`, `ignores`, and config-object `basePath`) resolve from `--base-path`. +- Alternative proposal: `--base-path` defines linting scope, while relative config-object `basePath` values resolve from `referenceLocation` (CWD or config file location). + +Which model should ESLint adopt? + +### `--base-path` with config lookup? Should `--base-path` be allowed when config lookup is enabled (i.e. neither `--config` nor `--no-config-lookup` is passed)? In that case, ESLint will search for a config file in a file's directory and its ancestors. This means that config files outside that line of search will not be considered, so that each file is required to have its associated config in an expected location. In this setup, I'm not sure how `--base-path` would be useful. From 4671f7ebd27a682a1e49db87d8b24456ae9b09ba Mon Sep 17 00:00:00 2001 From: Francesco Trotta Date: Wed, 4 Mar 2026 17:06:03 +0100 Subject: [PATCH 3/8] fix RFC PR link --- designs/2026-custom-base-path/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/2026-custom-base-path/README.md b/designs/2026-custom-base-path/README.md index ce1f687d..62a32605 100644 --- a/designs/2026-custom-base-path/README.md +++ b/designs/2026-custom-base-path/README.md @@ -1,6 +1,6 @@ - Repo: `eslint/eslint`, possibly `eslint/rewrite` - Start Date: 2026-02-03 -- RFC PR: #131 +- RFC PR: eslint/rfcs#145 - Authors: Francesco Trotta # Support `--base-path` Option From 911182ebfdafc1c4618bb1a80630311cb259a5f6 Mon Sep 17 00:00:00 2001 From: Francesco Trotta Date: Sun, 8 Mar 2026 18:46:55 +0100 Subject: [PATCH 4/8] add testing impact and preview sections --- designs/2026-custom-base-path/README.md | 43 +++++++++++++++++-------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/designs/2026-custom-base-path/README.md b/designs/2026-custom-base-path/README.md index 62a32605..aa5cca30 100644 --- a/designs/2026-custom-base-path/README.md +++ b/designs/2026-custom-base-path/README.md @@ -26,7 +26,7 @@ The base path is the directory that defines which files a `ConfigArray` can lint Files outside that base path cannot be linted, even if they are matched by a config object. Today, ESLint determines the base path as follows: -- the current working directory, if either `--config` or `--no-config-lookup` is passed +- the current working directory, if one of `--config` or `--no-config-lookup` is passed - otherwise, the directory where the config file is located. If a project contains different config files, each config file has its own base path. Internally, this value is stored as `basePath` on `ConfigArray`. It serves two purposes: @@ -49,7 +49,7 @@ When `basePath` is specified and no file patterns are passed on the command line npx eslint --config=eslint.config.js --base-path=../src ``` -will behave the same as +will behave the same as ```shell npx eslint --config=eslint.config.js --base-path=../src ../src @@ -74,7 +74,7 @@ For this case, `--base-path` should point to a parent of both directories, i.e. npx eslint --config=eslint.config.mjs --base-path=.. . ../tmp ``` -Relative paths in the config file will now be resolved relative to `..`. This includes `files` and `ignores` settings in config objects that don't include a `basePath`, or the config object's `basePath` itself. So, a config object that specifies different settings for the current directory and its sibling would look for example like this: +Relative paths in the config file will now be resolved relative to `..`. This includes `files` and `ignores` settings in config objects that don't include a `basePath`, or the config object's `basePath` itself. So, a config object that specifies different settings for the current directory and its sibling would look like this: @@ -82,12 +82,12 @@ Relative paths in the config file will now be resolved relative to `..`. This in export default defineConfig([ { name: "app-config", - files: ["app/**/*.{,c,m}js"], + files: ["app/**/*.{js,cjs,mjs}"], ...myAppConfig }, { name: "tmp-config", - files: ["tmp/**/*.{c,m}js"], + files: ["tmp/**/*.{js,cjs,mjs}"], ...myTmpConfig }, ]); @@ -102,13 +102,13 @@ export default defineConfig([ { name: "app-config", basePath: "app", - files: ["**/*.{,c,m}js"], + files: ["**/*.{js,cjs,mjs}"], ...myAppConfig }, { name: "tmp-config", basePath: "tmp", - files: ["**/*.{c,m}js"], + files: ["**/*.{js,cjs,mjs}"], ...myTmpConfig }, ]); @@ -116,7 +116,7 @@ export default defineConfig([ ### Alternative: Maintain Reference Location -The above solution is fully backwards-compatible but it's hard to extend to existing configurations because changing the base path also means that all relative paths and patterns in existing configs (in `files`, `ignores` and `basePath`) must be modified to be relative to the new base path. +The above solution is fully backward-compatible but it's hard to extend to existing configurations because changing the base path also means that all relative paths and patterns in existing configs (in `files`, `ignores` and `basePath`) must be modified to be relative to the new base path. For example, in the example in the previous section, a project may already have a config that lints files in the current directory (`app`) like this: @@ -124,7 +124,7 @@ For example, in the example in the previous section, a project may already have export default defineConfig([ { name: "app-config", - files: ["**/*.{,c,m}js"], + files: ["**/*.{js,cjs,mjs}"], ...myAppConfig }, ]); @@ -132,18 +132,18 @@ export default defineConfig([ In order to extend this config to also lint files in `../tmp`, besides passing `--base-path=..`, the existing config object(s) in the config must be changed if they should still apply to the current directory only, either by modifying the `files` patterns as in [the first example](#example-1), or by adding an explicit `basePath` like in [the second example](#example-2). Note that in both cases, the name of the current working directory (`app`) must be explicitly added, because there is no longer an implicit way to reference it from the config. -To avoid this inconvenience, we could add a new property to config arrays, tentatively name `referenceLocation`. This property will hold the value of what is currently the base path (CWD or config file location), and it will be used to resolve relative `basePath` values in config objects. This will ensure that existing config arrays can be extended to lint additional files with a new common directory root without changing existing config objects. For example, with this alternative, the example above can be extended to lint `../tmp` without changing the other config object(s), like this: +To avoid this inconvenience, we could add a new property to config arrays, tentatively named `referenceLocation`. This property will hold the value of what is currently the base path (CWD or config file location), and it will be used to resolve relative `basePath` values in config objects. This will ensure that existing config arrays can be extended to lint additional files with a new common directory root without changing existing config objects. For example, with this alternative, the example above can be extended to lint `../tmp` without changing the other config object(s), like this: ```js export default defineConfig([ { name: "app-config", - files: ["**/*.{,c,m}js"], + files: ["**/*.{js,cjs,mjs}"], ...myAppConfig }, { name: "tmp-config", - files: ["../tmp/**/*.{c,m}js"], + files: ["../tmp/**/*.{js,cjs,mjs}"], ...myTmpConfig }, ]); @@ -151,7 +151,22 @@ export default defineConfig([ With this alternative, `--base-path` would define which files are in scope for file enumeration and linting, but resolution of `basePath` values in config objects would remain unchanged. -While still maintaining the changes non-breaking and backwards-compatible, this alternative solution requires changing `@eslint/config-array` to introduce a new property on `ConfigArray` instances. It will also add complexity to the implementation. +While still maintaining the changes non-breaking and backward-compatible, this alternative solution requires changing `@eslint/config-array` to introduce a new property on `ConfigArray` instances. It will also add complexity to the implementation. + +### Testing Impact + +The implementation should include coverage for: +- CLI `--base-path` validation (empty string, invalid values, relative and absolute paths) +- file enumeration behavior when `--base-path` is provided and no file patterns are passed on the command line +- interaction with `--config` and `--no-config-lookup` +- interaction with the ESLint constructor `cwd` option when resolving a relative `basePath` +- behavior when config lookup is enabled (depending on the decision for `--base-path` support in that mode) + +### Preview + +Prototype branches for the proposed implementations are available for testing and previewing: +- [issue-19118](https://github.com/eslint/eslint/tree/issue-19118): prototype implementation for the main proposal +- [issue-19118-alt](https://github.com/eslint/eslint/tree/issue-19118-alt): prototype implementation for the [alternative proposal](#alternative-maintain-reference-location) ## Documentation @@ -206,7 +221,7 @@ Which model should ESLint adopt? ### `--base-path` with config lookup? -Should `--base-path` be allowed when config lookup is enabled (i.e. neither `--config` nor `--no-config-lookup` is passed)? In that case, ESLint will search for a config file in a file's directory and its ancestors. This means that config files outside that line of search will not be considered, so that each file is required to have its associated config in an expected location. In this setup, I'm not sure how `--base-path` would be useful. +Should `--base-path` be allowed when config lookup is enabled (i.e. neither `--config` nor `--no-config-lookup` is passed)? In that case, ESLint searches for a config file in a file's directory and its ancestors. This means that config files outside that line of search are not considered, so that each file is required to have its associated config in an expected location. In this setup, I'm not sure how `--base-path` would be useful. ## Help Needed From fc4cb8097daae73738eff98b0dd18be42dde023a Mon Sep 17 00:00:00 2001 From: Francesco Trotta Date: Mon, 9 Mar 2026 14:48:40 +0100 Subject: [PATCH 5/8] update Documentation section --- designs/2026-custom-base-path/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/designs/2026-custom-base-path/README.md b/designs/2026-custom-base-path/README.md index aa5cca30..f12e49e5 100644 --- a/designs/2026-custom-base-path/README.md +++ b/designs/2026-custom-base-path/README.md @@ -170,9 +170,10 @@ Prototype branches for the proposed implementations are available for testing an ## Documentation -- [CLI options](https://eslint.org/docs/latest/use/command-line-interface) -- [`ESLint` constructor options](https://eslint.org/docs/latest/integrate/nodejs-api#-new-eslintoptions) -- [`@eslint/config-array`](https://github.com/eslint/rewrite/tree/main/packages/config-array#readme) (if a new `ConfigArray` option is added) +- [CLI options documentation](https://eslint.org/docs/latest/use/command-line-interface#options) needs to include the `--base-path` option +- [`ESLint` constructor documentation](https://eslint.org/docs/latest/integrate/nodejs-api#-new-eslintoptions) needs to include `options.basePath` +- [Configuration Migration Guide](https://eslint.org/docs/latest/use/configure/migration-guide) should mention the use case of linting files outside the current directory +- if a new `ConfigArray` option is added, [`@eslint/config-array`](https://github.com/eslint/rewrite/tree/main/packages/config-array#readme) documentation should be updated ## Drawbacks From dc7d12eb6a502c172bdb1a685ddd3786acedf619 Mon Sep 17 00:00:00 2001 From: Francesco Trotta Date: Tue, 24 Mar 2026 21:58:12 +0100 Subject: [PATCH 6/8] clarify motivation for current behavior and `referenceLocation` --- designs/2026-custom-base-path/README.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/designs/2026-custom-base-path/README.md b/designs/2026-custom-base-path/README.md index f12e49e5..5da66691 100644 --- a/designs/2026-custom-base-path/README.md +++ b/designs/2026-custom-base-path/README.md @@ -12,9 +12,9 @@ This document proposes a mechanism for configuring and linting files relative to ## Motivation In the legacy eslintrc configuration system, users could lint files in arbitrary locations by explicitly specifying a config file (for example, via `--config`). -ESLint would resolve the target file paths relative to the current working directory and lint them, even though those files couldn’t be configured by that config. +ESLint would resolve the target file paths relative to the current working directory and lint them, even though it wasn't possible to configure those files with the provided config. -Flat config, on the other hand, enforces that only files under the current base path can be linted. When a config file is explicitly provided, the base path is the current working directory. This has caused problems for users migrating from legacy config to flat config, where linting files outside the current working directory previously worked. See [related discussions](#related-discussions) below for some examples. +Flat config, on the other hand, enforces that only files under the current base path can be configured and linted. When a config file is explicitly provided, the base path is the current working directory. This has caused problems for users migrating from legacy config to flat config, where linting files outside the current working directory previously worked. See [related discussions](#related-discussions) below for some examples. To support the legacy use case while allowing users to configure files independently, we propose introducing a new option that will allow users to specify a custom base path. @@ -29,10 +29,14 @@ Today, ESLint determines the base path as follows: - the current working directory, if one of `--config` or `--no-config-lookup` is passed - otherwise, the directory where the config file is located. If a project contains different config files, each config file has its own base path. -Internally, this value is stored as `basePath` on `ConfigArray`. It serves two purposes: +The main reason for using CWD as the base path when a config file is explicitly specified is to support configs files located in a different folder (e.g. with shared resources), from where they can be used to lint different directories in the codebase. + +Internally, the base path is stored as a `basePath` property on `ConfigArray` (not to be confused with [`basePath`](https://eslint.org/docs/latest/use/configure/configuration-files#specify-base-path) in config objects). It serves two purposes: - it limits which files can be linted - it provides the default `basePath` for config objects that don't have one explicitly set. The config object's base path is then used to resolve that object's `files` and `ignores` +Note that this is different from other config systems where the two functions may be separate (for example, TypeScript separates concepts like `rootDir` from the location used to resolve relative paths). + ### Proposed Change This proposal adds a way to set a custom base path that overrides the `basePath` of each config array. @@ -130,9 +134,16 @@ export default defineConfig([ ]); ``` -In order to extend this config to also lint files in `../tmp`, besides passing `--base-path=..`, the existing config object(s) in the config must be changed if they should still apply to the current directory only, either by modifying the `files` patterns as in [the first example](#example-1), or by adding an explicit `basePath` like in [the second example](#example-2). Note that in both cases, the name of the current working directory (`app`) must be explicitly added, because there is no longer an implicit way to reference it from the config. +To extend this config to also lint files in `../tmp`, you must pass `--base-path=..`. If the existing config object(s) in the config should still apply only to the current directory, they must also be changed either by modifying the `files` patterns as in [the first example](#example-1), or by adding an explicit `basePath` as in [the second example](#example-2). Note that in both cases, the name of the current working directory (`app`) must be explicitly added, because there is no longer an implicit way to reference it from the config. + +To avoid this inconvenience, we could add a new internal property to config arrays, tentatively named `referenceLocation`. This property is set once by ESLint, at the time a `ConfigArray` instance is created, and it holds the directory that is currently used as a `basePath` for the config array (CWD or config file location). When computing the effective `basePath` for each config object, ESLint would: + +1. First check whether the config object specifies an explicit `basePath`. + - If that `basePath` is absolute, it is used as-is. + - If that `basePath` is relative, it is resolved against `referenceLocation`. +2. If the config object does not specify `basePath`, `referenceLocation` is used as its `basePath`. -To avoid this inconvenience, we could add a new property to config arrays, tentatively named `referenceLocation`. This property will hold the value of what is currently the base path (CWD or config file location), and it will be used to resolve relative `basePath` values in config objects. This will ensure that existing config arrays can be extended to lint additional files with a new common directory root without changing existing config objects. For example, with this alternative, the example above can be extended to lint `../tmp` without changing the other config object(s), like this: +This solution will ensure that existing config arrays can be extended to lint additional files with a new common directory root without changing existing config objects. For example, with this alternative, the example above can be extended to lint `../tmp` without changing the other config object(s), like this: ```js export default defineConfig([ From 8719a0a21e7e5228a42d4bdfa038028c4ede5747 Mon Sep 17 00:00:00 2001 From: Francesco Trotta Date: Mon, 20 Apr 2026 08:16:51 +0200 Subject: [PATCH 7/8] `--base-path` not allowed with config lookup --- designs/2026-custom-base-path/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/designs/2026-custom-base-path/README.md b/designs/2026-custom-base-path/README.md index 5da66691..479e688d 100644 --- a/designs/2026-custom-base-path/README.md +++ b/designs/2026-custom-base-path/README.md @@ -231,10 +231,18 @@ Adding `basePath` to config objects (discussed in related design work, see [RFC Which model should ESLint adopt? +## Resolved questions + ### `--base-path` with config lookup? +#### Question + Should `--base-path` be allowed when config lookup is enabled (i.e. neither `--config` nor `--no-config-lookup` is passed)? In that case, ESLint searches for a config file in a file's directory and its ancestors. This means that config files outside that line of search are not considered, so that each file is required to have its associated config in an expected location. In this setup, I'm not sure how `--base-path` would be useful. +#### Resolution + +`--base-path` will require `--config` or `--no-config-lookup` to be specified. Correspondingly, in the Node.js API, `basePath` will require `overrideConfigFile` to be non-null. If this constraint isn't met, an error will be thrown. The alternative of silently ignoring `--base-path` when config lookup is enabled would be confusing. + ## Help Needed I can implement this RFC. From 0da0ae63532ccd3d04816027e8f20acef551ae41 Mon Sep 17 00:00:00 2001 From: Francesco Trotta Date: Mon, 20 Apr 2026 08:46:26 +0200 Subject: [PATCH 8/8] clarify purpose of `referenceLocation` --- designs/2026-custom-base-path/README.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/designs/2026-custom-base-path/README.md b/designs/2026-custom-base-path/README.md index 479e688d..22063c55 100644 --- a/designs/2026-custom-base-path/README.md +++ b/designs/2026-custom-base-path/README.md @@ -136,7 +136,19 @@ export default defineConfig([ To extend this config to also lint files in `../tmp`, you must pass `--base-path=..`. If the existing config object(s) in the config should still apply only to the current directory, they must also be changed either by modifying the `files` patterns as in [the first example](#example-1), or by adding an explicit `basePath` as in [the second example](#example-2). Note that in both cases, the name of the current working directory (`app`) must be explicitly added, because there is no longer an implicit way to reference it from the config. -To avoid this inconvenience, we could add a new internal property to config arrays, tentatively named `referenceLocation`. This property is set once by ESLint, at the time a `ConfigArray` instance is created, and it holds the directory that is currently used as a `basePath` for the config array (CWD or config file location). When computing the effective `basePath` for each config object, ESLint would: +To avoid this inconvenience, we could separate these two concerns: +- which directory defines the linting scope +- which directory existing relative config paths resolve from + +Under this alternative, each config array would gain a new internal property, tentatively named `referenceLocation`. It would store the directory that ESLint would use today as the config array's `basePath`, i.e. either the CWD or the config file location. ESLint would set this property once, when the `ConfigArray` instance is created. + +The config array's `basePath` property, on the other hand, would become independently configurable via `--base-path`. + +In other words: +- `basePath` would define which files are in scope for enumeration and linting +- `referenceLocation` would define how relative config object paths are interpreted, keeping the current logic unchanged + +When computing the effective `basePath` for each config object, ESLint would: 1. First check whether the config object specifies an explicit `basePath`. - If that `basePath` is absolute, it is used as-is.