docs: clarify unsupported nested lint/fmt config (#2668)

Nested lint/fmt config is not supported by Vite+ for now.

This PR adds document to clarify it is the expected behavior, and leave
a discussion to put users' feedback together to avoid treating it as bug
and too many issues about it.

Author: liangmiQwQ

docs/config/fmt.md

@@ -1,6 +1,6 @@
 # Format Config
 
-`vp fmt` and `vp check` read Oxfmt settings from the `fmt` block in `vite.config.ts`. See [Oxfmt's configuration](https://oxc.rs/docs/guide/usage/formatter/config.html) for details.
+`vp fmt` and `vp check` read Oxfmt settings from the `fmt` block in the root `vite.config.ts`. See [Oxfmt's configuration](https://oxc.rs/docs/guide/usage/formatter/config.html) for details.
 
 ## Example
 
@@ -17,4 +17,6 @@ export default defineConfig({
 });
 ```
 
-For package-specific formatting settings in a workspace, use [`fmt.overrides`](/guide/monorepo#format-overrides) from the root `vite.config.ts`.
+For file- or package-specific formatting settings, use [`fmt.overrides`](/guide/monorepo#format-overrides) from the root `vite.config.ts`.
+
+Vite+ does not currently support nested format configuration. See [troubleshooting](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) for details and how to give feedback on future support.

docs/config/lint.md

@@ -1,6 +1,6 @@
 # Lint Config
 
-`vp lint` and `vp check` read Oxlint settings from the `lint` block in `vite.config.ts`. See [Oxlint's configuration](https://oxc.rs/docs/guide/usage/linter/config.html) for details.
+`vp lint` and `vp check` read Oxlint settings from the `lint` block in the root `vite.config.ts`. See [Oxlint's configuration](https://oxc.rs/docs/guide/usage/linter/config.html) for details.
 
 ## Example
 
@@ -23,4 +23,6 @@ export default defineConfig({
 
 We recommend enabling both `options.typeAware` and `options.typeCheck` so `vp lint` and `vp check` can use the full type-aware path.
 
-For package-specific lint rules in a workspace, use [`lint.overrides`](/guide/monorepo#root-config-with-overrides) from the root `vite.config.ts`.
+For file- or package-specific lint rules, use [`lint.overrides`](/guide/monorepo#root-config-with-overrides) from the root `vite.config.ts`.
+
+Vite+ does not currently support nested lint configuration. See [troubleshooting](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) for details and how to give feedback on future support.

docs/guide/fmt.md

@@ -18,7 +18,9 @@ vp fmt . --write
 
 ## Configuration
 
-Put formatting configuration directly in the `fmt` block in `vite.config.ts` so all your configuration stays in one place. We do not recommend using `.oxfmtrc.json` with Vite+.
+Put formatting configuration directly in the `fmt` block in the root `vite.config.ts` so all your configuration stays in one place. We do not recommend using `.oxfmtrc.json` with Vite+.
+
+Vite+ does not currently support nested format configuration. For now, use [`fmt.overrides`](/guide/monorepo#format-overrides) in the root `vite.config.ts` for file- or package-specific options. The long-term behavior is open for discussion; [share your use case and expectations](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) to help shape it.
 
 For editors, disable nested formatter configs so format-on-save uses the root Vite+ `fmt` block:
 

docs/guide/lint.md

@@ -18,7 +18,9 @@ vp lint --type-aware
 
 ## Configuration
 
-Put lint configuration directly in the `lint` block in `vite.config.ts` so all your configuration stays in one place. We do not recommend using `oxlint.config.ts` or `.oxlintrc.json` with Vite+.
+Put lint configuration directly in the `lint` block in the root `vite.config.ts` so all your configuration stays in one place. We do not recommend using `oxlint.config.ts` or `.oxlintrc.json` with Vite+.
+
+Vite+ does not currently support nested lint configuration. For now, use [`lint.overrides`](/guide/monorepo#root-config-with-overrides) in the root `vite.config.ts` for file- or package-specific rules. The long-term behavior is open for discussion; [share your use case and expectations](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) to help shape it.
 
 For the upstream rule set, options, and compatibility details, see the [Oxlint docs](https://oxc.rs/docs/guide/usage/linter.html).
 

docs/guide/monorepo.md

@@ -6,6 +6,8 @@ Because `vite.config.ts` is just JavaScript, you can choose to put your entire c
 
 ## Root Config With Overrides
 
+Vite+ does not currently support nested lint or format configuration. Package-level `lint` and `fmt` blocks are not automatically applied. For now, define file- or package-specific settings with overrides in the root `vite.config.ts`. The long-term behavior is open for discussion; [share your use case and expectations](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) to help shape it.
+
 Use `lint.overrides` for Oxlint rules that only apply to some packages:
 
 ```ts [vite.config.ts]

docs/guide/troubleshooting.md

@@ -28,6 +28,20 @@ The Oxlint type checker path powered by `tsgolint` does not support `baseUrl`.
 fix before enabling type-aware linting. If that fix fails or is declined, Vite+
 skips `typeAware` and `typeCheck`.
 
+## Nested lint or format config is not applied
+
+Vite+ does not currently support nested lint or format configuration. When running `vp lint`, `vp fmt`, or `vp check` from the workspace root, do not rely on configs in subdirectories or on `lint` and `fmt` blocks in package-level `vite.config.ts` files to override the root settings.
+
+Keep lint and format settings in the root `vite.config.ts`. Use [`lint.overrides`](/guide/monorepo#root-config-with-overrides) and [`fmt.overrides`](/guide/monorepo#format-overrides) for file- or package-specific settings. You can also [import configuration objects](/guide/monorepo#composing-configuration-files) into the root config to keep settings in separate files.
+
+For IDE integration, we have `disableNestedConfig` and `fmt.disableNestedConfig` config to disable nested lint and format configs and keep editor behavior aligned with the root Vite+ config. See [IDE Integration](/guide/ide-integration) for setup instructions for your editor.
+
+We're holding off on nested config support for now. Some of the factors we're considering are how implicit config discovery affects the predictability of linting and formatting, what context AI agents need to understand the settings that apply, and the potential performance cost of finding and loading multiple configs. At the same time, we recognize that keeping package-specific context close to the code may have benefits. The use cases we've heard so far haven't given us a strong enough reason to commit to those semantics. Waiting leaves room to add support later, and we'd like to hear why your project needs nested configs, especially where root-level overrides fall short.
+
+Do you need nested configs? [Share your use case and opinion on GitHub](https://github.com/voidzero-dev/vite-plus/discussions/2669), including your project structure, the reason why you want them and whether root-level overrides meet your needs.
+
+We sincerely hope to hear your feedback. This will help us decide whether to improve the current situation in the future.
+
 ## VS Code extension does not read `vite.config.ts`
 
 If VS Code has multiple folders open, the shared Oxc language server may pick a different workspace than expected. That can make it look like `vite.config.ts` support is missing.