From 8e7474b6f2018d183fe16abe3c2fb45d4a99f14f Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Mon, 29 Jun 2026 13:29:35 +0800
Subject: [PATCH 1/5] feat(check): support check.fmt/check.lint in
 vite.config.ts

Mirror the `vp check --no-fmt` / `--no-lint` flags as persistent config so a
project can make plain `vp check` skip formatting or linting by default,
without anyone needing to remember a flag.

- A step is skipped if config disables it or the matching flag is passed.
- Config-based disabling only affects `vp check`; standalone `vp fmt` /
  `vp lint` and git-hook/staged are unaffected.
- A short `note:` line is printed when config (not a flag) disables a step,
  for discoverability; CLI-flag output stays byte-identical.
---
 docs/.vitepress/config.mts                    |  1 +
 docs/config/check.md                          | 28 ++++++++++++++++
 docs/config/index.md                          |  2 ++
 docs/guide/check.md                           | 16 +++++++++
 packages/cli/binding/src/check/analysis.rs    | 33 ++++++++++++++++++-
 packages/cli/binding/src/check/mod.rs         | 29 ++++++++++++----
 packages/cli/binding/src/cli/types.rs         |  1 +
 .../check-config-flag-precedence/package.json |  5 +++
 .../check-config-flag-precedence/snap.txt     |  2 ++
 .../check-config-flag-precedence/src/index.js |  5 +++
 .../check-config-flag-precedence/steps.json   |  6 ++++
 .../vite.config.ts                            |  5 +++
 .../check-config-no-fmt/package.json          |  5 +++
 .../snap-tests/check-config-no-fmt/snap.txt   |  3 ++
 .../check-config-no-fmt/src/index.js          |  5 +++
 .../snap-tests/check-config-no-fmt/steps.json |  6 ++++
 .../check-config-no-fmt/vite.config.ts        |  5 +++
 .../check-config-no-lint/package.json         |  5 +++
 .../snap-tests/check-config-no-lint/snap.txt  |  3 ++
 .../check-config-no-lint/src/index.js         |  5 +++
 .../check-config-no-lint/steps.json           |  6 ++++
 .../check-config-no-lint/vite.config.ts       |  5 +++
 packages/cli/src/define-config.ts             | 20 +++++++++++
 packages/cli/src/resolve-vite-config.ts       |  1 +
 24 files changed, 195 insertions(+), 7 deletions(-)
 create mode 100644 docs/config/check.md
 create mode 100644 packages/cli/snap-tests/check-config-flag-precedence/package.json
 create mode 100644 packages/cli/snap-tests/check-config-flag-precedence/snap.txt
 create mode 100644 packages/cli/snap-tests/check-config-flag-precedence/src/index.js
 create mode 100644 packages/cli/snap-tests/check-config-flag-precedence/steps.json
 create mode 100644 packages/cli/snap-tests/check-config-flag-precedence/vite.config.ts
 create mode 100644 packages/cli/snap-tests/check-config-no-fmt/package.json
 create mode 100644 packages/cli/snap-tests/check-config-no-fmt/snap.txt
 create mode 100644 packages/cli/snap-tests/check-config-no-fmt/src/index.js
 create mode 100644 packages/cli/snap-tests/check-config-no-fmt/steps.json
 create mode 100644 packages/cli/snap-tests/check-config-no-fmt/vite.config.ts
 create mode 100644 packages/cli/snap-tests/check-config-no-lint/package.json
 create mode 100644 packages/cli/snap-tests/check-config-no-lint/snap.txt
 create mode 100644 packages/cli/snap-tests/check-config-no-lint/src/index.js
 create mode 100644 packages/cli/snap-tests/check-config-no-lint/steps.json
 create mode 100644 packages/cli/snap-tests/check-config-no-lint/vite.config.ts

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index ba764c9e2f..200c0f922a 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -169,6 +169,7 @@ export default extendConfig(
                 { text: 'Run', link: '/config/run' },
                 { text: 'Format', link: '/config/fmt' },
                 { text: 'Lint', link: '/config/lint' },
+                { text: 'Check', link: '/config/check' },
                 { text: 'Test', link: '/config/test' },
                 { text: 'Build', link: '/config/build' },
                 { text: 'Pack', link: '/config/pack' },
diff --git a/docs/config/check.md b/docs/config/check.md
new file mode 100644
index 0000000000..83e35b141d
--- /dev/null
+++ b/docs/config/check.md
@@ -0,0 +1,28 @@
+# Check Config
+
+`vp check` runs format, lint, and type checks together. The `check` block in `vite.config.ts` sets defaults for the composite command, mirroring the `--no-fmt` and `--no-lint` CLI flags.
+
+This is useful when a project wants to keep most of the toolchain but skip one step by default. For example, a team that lints but does not format can disable `check.fmt` so a plain `vp check` (the command agents and contributors run most) only lints, without anyone needing to remember `--no-fmt`.
+
+## Example
+
+```ts [vite.config.ts]
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  check: {
+    // Skip the format step in `vp check`. Defaults to true.
+    fmt: false,
+    // Skip lint rules in `vp check`. Type-check still runs when
+    // `lint.options.typeCheck` is enabled. Defaults to true.
+    lint: true,
+  },
+});
+```
+
+When a step is disabled here, `vp check` prints a short `note:` line so it is clear why the step did not run.
+
+## Scope and precedence
+
+- These options only affect the composite `vp check`. Standalone [`vp fmt`](/config/fmt), [`vp lint`](/config/lint), and the git-hook [`staged`](/config/staged) flow are unaffected, so you can still run a disabled tool directly when you need it once.
+- A step is skipped if the config disables it **or** the matching CLI flag is passed. There is no flag to re-enable a step disabled in config; run `vp fmt` or `vp lint` directly instead.
diff --git a/docs/config/index.md b/docs/config/index.md
index df20c6a683..d7f1b25543 100644
--- a/docs/config/index.md
+++ b/docs/config/index.md
@@ -14,6 +14,7 @@ export default defineConfig({
   run: {},
   fmt: {},
   lint: {},
+  check: {},
   test: {},
   pack: {},
   staged: {},
@@ -28,6 +29,7 @@ Vite+ extends the basic Vite configuration with these additions:
 - [`run`](/config/run) for Vite Task
 - [`fmt`](/config/fmt) for Oxfmt
 - [`lint`](/config/lint) for Oxlint
+- [`check`](/config/check) for `vp check` defaults
 - [`test`](/config/test) for Vitest
 - [`pack`](/config/pack) for tsdown
 - [`staged`](/config/staged) for staged-file checks
diff --git a/docs/guide/check.md b/docs/guide/check.md
index 92241a7cd9..efdc96d28d 100644
--- a/docs/guide/check.md
+++ b/docs/guide/check.md
@@ -42,3 +42,19 @@ export default defineConfig({
   },
 });
 ```
+
+### Disabling a step by default
+
+To make `vp check` skip formatting or linting without passing a flag every time, set the [`check`](/config/check) block in `vite.config.ts`. This is handy when a project wants the rest of the toolchain but not, say, formatting:
+
+```ts [vite.config.ts]
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  check: {
+    fmt: false, // `vp check` lints (and type-checks) but does not format
+  },
+});
+```
+
+These options only affect `vp check`; standalone `vp fmt` and `vp lint` still run normally. A step is skipped if it is disabled in config or the matching `--no-fmt` / `--no-lint` flag is passed.
diff --git a/packages/cli/binding/src/check/analysis.rs b/packages/cli/binding/src/check/analysis.rs
index 6068b1a866..b2ce4cb42c 100644
--- a/packages/cli/binding/src/check/analysis.rs
+++ b/packages/cli/binding/src/check/analysis.rs
@@ -94,6 +94,18 @@ pub(super) fn lint_config_type_check_enabled(lint_config: Option<&serde_json::Va
     type_aware && type_check
 }
 
+/// Read `check.<key>` from vite.config.ts. An absent block, an absent key, or a
+/// non-boolean value all default to `true` (the step runs).
+pub(super) fn check_config_step_enabled(
+    check_config: Option<&serde_json::Value>,
+    key: &str,
+) -> bool {
+    check_config
+        .and_then(|config| config.get(key))
+        .and_then(serde_json::Value::as_bool)
+        .unwrap_or(true)
+}
+
 fn parse_check_summary(line: &str) -> Option<CheckSummary> {
     let rest = line.strip_prefix("Finished in ")?;
     let (duration, rest) = rest.split_once(" on ")?;
@@ -247,7 +259,7 @@ pub(super) fn analyze_lint_output(output: &str) -> Option<Result<LintSuccess, Li
 mod tests {
     use serde_json::json;
 
-    use super::{LintMessageKind, lint_config_type_check_enabled};
+    use super::{LintMessageKind, check_config_step_enabled, lint_config_type_check_enabled};
 
     #[test]
     fn lint_message_kind_defaults_to_lint_only_without_typecheck() {
@@ -296,6 +308,25 @@ mod tests {
         }))));
     }
 
+    #[test]
+    fn check_config_step_defaults_to_enabled() {
+        // No `check` block, an absent key, or a non-bool value all default to true.
+        assert!(check_config_step_enabled(None, "fmt"));
+        assert!(check_config_step_enabled(Some(&json!({})), "fmt"));
+        assert!(check_config_step_enabled(Some(&json!({ "lint": false })), "fmt"));
+        assert!(check_config_step_enabled(Some(&json!({ "fmt": "false" })), "fmt"));
+        assert!(check_config_step_enabled(Some(&json!({ "fmt": 0 })), "fmt"));
+        assert!(check_config_step_enabled(Some(&json!({ "fmt": null })), "fmt"));
+    }
+
+    #[test]
+    fn check_config_step_respects_explicit_booleans() {
+        assert!(!check_config_step_enabled(Some(&json!({ "fmt": false })), "fmt"));
+        assert!(check_config_step_enabled(Some(&json!({ "fmt": true })), "fmt"));
+        assert!(!check_config_step_enabled(Some(&json!({ "lint": false })), "lint"));
+        assert!(check_config_step_enabled(Some(&json!({ "lint": true })), "lint"));
+    }
+
     #[test]
     fn lint_config_type_check_requires_type_aware_prerequisite() {
         assert!(!lint_config_type_check_enabled(Some(&json!({
diff --git a/packages/cli/binding/src/check/mod.rs b/packages/cli/binding/src/check/mod.rs
index f435bf81d9..f149a9b7b2 100644
--- a/packages/cli/binding/src/check/mod.rs
+++ b/packages/cli/binding/src/check/mod.rs
@@ -9,9 +9,9 @@ use vite_shared::output;
 use vite_task::ExitStatus;
 
 use self::analysis::{
-    LintMessageKind, analyze_fmt_check_output, analyze_lint_output, format_count, format_elapsed,
-    lint_config_type_check_enabled, print_error_block, print_pass_line, print_stdout_block,
-    print_summary_line,
+    LintMessageKind, analyze_fmt_check_output, analyze_lint_output, check_config_step_enabled,
+    format_count, format_elapsed, lint_config_type_check_enabled, print_error_block,
+    print_pass_line, print_stdout_block, print_summary_line,
 };
 use crate::cli::{
     CapturedCommandOutput, SubcommandResolver, SynthesizableSubcommand, resolve_and_capture_output,
@@ -21,8 +21,8 @@ use crate::cli::{
 pub(crate) async fn execute_check(
     resolver: &SubcommandResolver,
     fix: bool,
-    no_fmt: bool,
-    no_lint: bool,
+    no_fmt_flag: bool,
+    no_lint_flag: bool,
     no_error_on_unmatched_pattern: bool,
     paths: Vec<String>,
     envs: &Arc<FxHashMap<Arc<OsStr>, Arc<OsStr>>>,
@@ -38,6 +38,23 @@ pub(crate) async fn execute_check(
     let mut deferred_lint_pass: Option<(String, String)> = None;
     let resolved_vite_config = resolver.resolve_universal_vite_config().await?;
 
+    // A step is skipped when either the CLI flag is passed OR `check.fmt`/
+    // `check.lint` is disabled in vite.config.ts. The skip note is printed only
+    // when CONFIG (not the CLI flag) turned a step off, so existing `--no-fmt` /
+    // `--no-lint` output stays byte-identical.
+    let config_fmt_off =
+        !check_config_step_enabled(resolved_vite_config.check.as_ref(), "fmt");
+    let config_lint_off =
+        !check_config_step_enabled(resolved_vite_config.check.as_ref(), "lint");
+    if config_fmt_off && !no_fmt_flag {
+        output::note("Format skipped (check.fmt: false in vite.config.ts)");
+    }
+    if config_lint_off && !no_lint_flag {
+        output::note("Lint skipped (check.lint: false in vite.config.ts)");
+    }
+    let no_fmt = no_fmt_flag || config_fmt_off;
+    let no_lint = no_lint_flag || config_lint_off;
+
     let type_check_enabled = lint_config_type_check_enabled(resolved_vite_config.lint.as_ref());
     let lint_enabled = !no_lint;
     let run_lint_phase = lint_enabled || type_check_enabled;
@@ -45,7 +62,7 @@ pub(crate) async fn execute_check(
     if no_fmt && !run_lint_phase {
         output::error("No checks enabled");
         print_summary_line(
-            "Enable `lint.options.typeCheck` in vite.config.ts to use `vp check --no-fmt --no-lint` for type-check only, or drop a flag to re-enable fmt/lint.",
+            "Enable `lint.options.typeCheck` in vite.config.ts for type-check only, drop a `--no-fmt`/`--no-lint` flag, or re-enable `check.fmt`/`check.lint` in vite.config.ts.",
         );
         return Ok(ExitStatus(1));
     }
diff --git a/packages/cli/binding/src/cli/types.rs b/packages/cli/binding/src/cli/types.rs
index b0b935af02..d857ed7ee1 100644
--- a/packages/cli/binding/src/cli/types.rs
+++ b/packages/cli/binding/src/cli/types.rs
@@ -15,6 +15,7 @@ pub(crate) struct ResolvedUniversalViteConfig {
     pub(crate) config_file: Option<String>,
     pub(crate) lint: Option<serde_json::Value>,
     pub(crate) fmt: Option<serde_json::Value>,
+    pub(crate) check: Option<serde_json::Value>,
     pub(crate) run: Option<serde_json::Value>,
 }
 
diff --git a/packages/cli/snap-tests/check-config-flag-precedence/package.json b/packages/cli/snap-tests/check-config-flag-precedence/package.json
new file mode 100644
index 0000000000..7b073ab646
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-flag-precedence/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "check-config-flag-precedence",
+  "version": "0.0.0",
+  "private": true
+}
diff --git a/packages/cli/snap-tests/check-config-flag-precedence/snap.txt b/packages/cli/snap-tests/check-config-flag-precedence/snap.txt
new file mode 100644
index 0000000000..81f5967558
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-flag-precedence/snap.txt
@@ -0,0 +1,2 @@
+> vp check --no-fmt
+pass: Found no warnings or lint errors in 2 files (<variable>ms, <variable> threads)
diff --git a/packages/cli/snap-tests/check-config-flag-precedence/src/index.js b/packages/cli/snap-tests/check-config-flag-precedence/src/index.js
new file mode 100644
index 0000000000..13305bd3e9
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-flag-precedence/src/index.js
@@ -0,0 +1,5 @@
+function hello() {
+  return "hello";
+}
+
+export { hello };
diff --git a/packages/cli/snap-tests/check-config-flag-precedence/steps.json b/packages/cli/snap-tests/check-config-flag-precedence/steps.json
new file mode 100644
index 0000000000..aba7793b58
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-flag-precedence/steps.json
@@ -0,0 +1,6 @@
+{
+  "env": {
+    "VITE_DISABLE_AUTO_INSTALL": "1"
+  },
+  "commands": ["vp check --no-fmt"]
+}
diff --git a/packages/cli/snap-tests/check-config-flag-precedence/vite.config.ts b/packages/cli/snap-tests/check-config-flag-precedence/vite.config.ts
new file mode 100644
index 0000000000..f3f231d736
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-flag-precedence/vite.config.ts
@@ -0,0 +1,5 @@
+export default {
+  check: {
+    fmt: true,
+  },
+};
diff --git a/packages/cli/snap-tests/check-config-no-fmt/package.json b/packages/cli/snap-tests/check-config-no-fmt/package.json
new file mode 100644
index 0000000000..b9c2ead40e
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-no-fmt/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "check-config-no-fmt",
+  "version": "0.0.0",
+  "private": true
+}
diff --git a/packages/cli/snap-tests/check-config-no-fmt/snap.txt b/packages/cli/snap-tests/check-config-no-fmt/snap.txt
new file mode 100644
index 0000000000..6f48cac073
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-no-fmt/snap.txt
@@ -0,0 +1,3 @@
+> vp check
+note: Format skipped (check.fmt: false in vite.config.ts)
+pass: Found no warnings or lint errors in 2 files (<variable>ms, <variable> threads)
diff --git a/packages/cli/snap-tests/check-config-no-fmt/src/index.js b/packages/cli/snap-tests/check-config-no-fmt/src/index.js
new file mode 100644
index 0000000000..13305bd3e9
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-no-fmt/src/index.js
@@ -0,0 +1,5 @@
+function hello() {
+  return "hello";
+}
+
+export { hello };
diff --git a/packages/cli/snap-tests/check-config-no-fmt/steps.json b/packages/cli/snap-tests/check-config-no-fmt/steps.json
new file mode 100644
index 0000000000..d9c26d5a29
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-no-fmt/steps.json
@@ -0,0 +1,6 @@
+{
+  "env": {
+    "VITE_DISABLE_AUTO_INSTALL": "1"
+  },
+  "commands": ["vp check"]
+}
diff --git a/packages/cli/snap-tests/check-config-no-fmt/vite.config.ts b/packages/cli/snap-tests/check-config-no-fmt/vite.config.ts
new file mode 100644
index 0000000000..88226e94aa
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-no-fmt/vite.config.ts
@@ -0,0 +1,5 @@
+export default {
+  check: {
+    fmt: false,
+  },
+};
diff --git a/packages/cli/snap-tests/check-config-no-lint/package.json b/packages/cli/snap-tests/check-config-no-lint/package.json
new file mode 100644
index 0000000000..1af4f130a2
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-no-lint/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "check-config-no-lint",
+  "version": "0.0.0",
+  "private": true
+}
diff --git a/packages/cli/snap-tests/check-config-no-lint/snap.txt b/packages/cli/snap-tests/check-config-no-lint/snap.txt
new file mode 100644
index 0000000000..c5d4e8f5fe
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-no-lint/snap.txt
@@ -0,0 +1,3 @@
+> vp check
+note: Lint skipped (check.lint: false in vite.config.ts)
+pass: All 4 files are correctly formatted (<variable>ms, <variable> threads)
diff --git a/packages/cli/snap-tests/check-config-no-lint/src/index.js b/packages/cli/snap-tests/check-config-no-lint/src/index.js
new file mode 100644
index 0000000000..13305bd3e9
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-no-lint/src/index.js
@@ -0,0 +1,5 @@
+function hello() {
+  return "hello";
+}
+
+export { hello };
diff --git a/packages/cli/snap-tests/check-config-no-lint/steps.json b/packages/cli/snap-tests/check-config-no-lint/steps.json
new file mode 100644
index 0000000000..d9c26d5a29
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-no-lint/steps.json
@@ -0,0 +1,6 @@
+{
+  "env": {
+    "VITE_DISABLE_AUTO_INSTALL": "1"
+  },
+  "commands": ["vp check"]
+}
diff --git a/packages/cli/snap-tests/check-config-no-lint/vite.config.ts b/packages/cli/snap-tests/check-config-no-lint/vite.config.ts
new file mode 100644
index 0000000000..6ba8f85d81
--- /dev/null
+++ b/packages/cli/snap-tests/check-config-no-lint/vite.config.ts
@@ -0,0 +1,5 @@
+export default {
+  check: {
+    lint: false,
+  },
+};
diff --git a/packages/cli/src/define-config.ts b/packages/cli/src/define-config.ts
index eefe03e824..7a6b02be6b 100644
--- a/packages/cli/src/define-config.ts
+++ b/packages/cli/src/define-config.ts
@@ -31,6 +31,26 @@ declare module '@voidzero-dev/vite-plus-core' {
 
     fmt?: OxfmtConfig;
 
+    /**
+     * Defaults for the `vp check` composite command. Each flag mirrors the
+     * matching CLI option (`--no-fmt` / `--no-lint`) and only affects
+     * `vp check`; standalone `vp fmt` / `vp lint` are unaffected.
+     */
+    check?: {
+      /**
+       * Run the format step in `vp check`.
+       * @default true
+       */
+      fmt?: boolean;
+
+      /**
+       * Run the lint step in `vp check`. Type-check still runs when
+       * `lint.options.typeCheck` is enabled.
+       * @default true
+       */
+      lint?: boolean;
+    };
+
     pack?: PackUserConfig | PackUserConfig[];
 
     run?: RunConfig;
diff --git a/packages/cli/src/resolve-vite-config.ts b/packages/cli/src/resolve-vite-config.ts
index 8cafa5bb6a..52d24619ce 100644
--- a/packages/cli/src/resolve-vite-config.ts
+++ b/packages/cli/src/resolve-vite-config.ts
@@ -126,6 +126,7 @@ export async function resolveUniversalViteConfig(err: null | Error, viteConfigCw
       configFile: config.configFile,
       lint: config.lint,
       fmt: config.fmt,
+      check: config.check,
       run: config.run,
       staged: config.staged,
     });

From 9dda1de344121c5527510b288d5a03da0a1fd7dc Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Mon, 29 Jun 2026 13:33:40 +0800
Subject: [PATCH 2/5] style(check): rustfmt single-line config bindings

---
 packages/cli/binding/src/check/mod.rs | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/packages/cli/binding/src/check/mod.rs b/packages/cli/binding/src/check/mod.rs
index f149a9b7b2..358d757c13 100644
--- a/packages/cli/binding/src/check/mod.rs
+++ b/packages/cli/binding/src/check/mod.rs
@@ -42,10 +42,8 @@ pub(crate) async fn execute_check(
     // `check.lint` is disabled in vite.config.ts. The skip note is printed only
     // when CONFIG (not the CLI flag) turned a step off, so existing `--no-fmt` /
     // `--no-lint` output stays byte-identical.
-    let config_fmt_off =
-        !check_config_step_enabled(resolved_vite_config.check.as_ref(), "fmt");
-    let config_lint_off =
-        !check_config_step_enabled(resolved_vite_config.check.as_ref(), "lint");
+    let config_fmt_off = !check_config_step_enabled(resolved_vite_config.check.as_ref(), "fmt");
+    let config_lint_off = !check_config_step_enabled(resolved_vite_config.check.as_ref(), "lint");
     if config_fmt_off && !no_fmt_flag {
         output::note("Format skipped (check.fmt: false in vite.config.ts)");
     }

From dbae767805b7ba453de5fab12df3ec08f9403e63 Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Mon, 29 Jun 2026 13:48:09 +0800
Subject: [PATCH 3/5] refactor(check): extract shared json_bool helper

Dedup the JSON-bool accessor chain shared by the new check.fmt/check.lint
reader and lint_config_type_check_enabled into a single json_bool(value, key,
default) helper.
---
 packages/cli/binding/src/check/analysis.rs | 53 ++++++++--------------
 packages/cli/binding/src/check/mod.rs      | 10 ++--
 2 files changed, 25 insertions(+), 38 deletions(-)

diff --git a/packages/cli/binding/src/check/analysis.rs b/packages/cli/binding/src/check/analysis.rs
index b2ce4cb42c..e02d26fb54 100644
--- a/packages/cli/binding/src/check/analysis.rs
+++ b/packages/cli/binding/src/check/analysis.rs
@@ -83,27 +83,13 @@ impl LintMessageKind {
 /// analysis must be on for TypeScript diagnostics to surface.
 pub(super) fn lint_config_type_check_enabled(lint_config: Option<&serde_json::Value>) -> bool {
     let options = lint_config.and_then(|config| config.get("options"));
-    let type_aware = options
-        .and_then(|options| options.get("typeAware"))
-        .and_then(serde_json::Value::as_bool)
-        .unwrap_or(false);
-    let type_check = options
-        .and_then(|options| options.get("typeCheck"))
-        .and_then(serde_json::Value::as_bool)
-        .unwrap_or(false);
-    type_aware && type_check
+    json_bool(options, "typeAware", false) && json_bool(options, "typeCheck", false)
 }
 
-/// Read `check.<key>` from vite.config.ts. An absent block, an absent key, or a
-/// non-boolean value all default to `true` (the step runs).
-pub(super) fn check_config_step_enabled(
-    check_config: Option<&serde_json::Value>,
-    key: &str,
-) -> bool {
-    check_config
-        .and_then(|config| config.get(key))
-        .and_then(serde_json::Value::as_bool)
-        .unwrap_or(true)
+/// Read a boolean `key` from a JSON object, falling back to `default` when the
+/// object is absent, the key is missing, or the value is not a boolean.
+pub(super) fn json_bool(value: Option<&serde_json::Value>, key: &str, default: bool) -> bool {
+    value.and_then(|value| value.get(key)).and_then(serde_json::Value::as_bool).unwrap_or(default)
 }
 
 fn parse_check_summary(line: &str) -> Option<CheckSummary> {
@@ -259,7 +245,7 @@ pub(super) fn analyze_lint_output(output: &str) -> Option<Result<LintSuccess, Li
 mod tests {
     use serde_json::json;
 
-    use super::{LintMessageKind, check_config_step_enabled, lint_config_type_check_enabled};
+    use super::{LintMessageKind, json_bool, lint_config_type_check_enabled};
 
     #[test]
     fn lint_message_kind_defaults_to_lint_only_without_typecheck() {
@@ -309,22 +295,23 @@ mod tests {
     }
 
     #[test]
-    fn check_config_step_defaults_to_enabled() {
-        // No `check` block, an absent key, or a non-bool value all default to true.
-        assert!(check_config_step_enabled(None, "fmt"));
-        assert!(check_config_step_enabled(Some(&json!({})), "fmt"));
-        assert!(check_config_step_enabled(Some(&json!({ "lint": false })), "fmt"));
-        assert!(check_config_step_enabled(Some(&json!({ "fmt": "false" })), "fmt"));
-        assert!(check_config_step_enabled(Some(&json!({ "fmt": 0 })), "fmt"));
-        assert!(check_config_step_enabled(Some(&json!({ "fmt": null })), "fmt"));
+    fn json_bool_falls_back_for_absent_or_non_bool() {
+        // An absent object, an absent key, or a non-bool value all use the default.
+        assert!(json_bool(None, "fmt", true));
+        assert!(json_bool(Some(&json!({})), "fmt", true));
+        assert!(json_bool(Some(&json!({ "lint": false })), "fmt", true));
+        assert!(json_bool(Some(&json!({ "fmt": "false" })), "fmt", true));
+        assert!(json_bool(Some(&json!({ "fmt": 0 })), "fmt", true));
+        assert!(json_bool(Some(&json!({ "fmt": null })), "fmt", true));
+        assert!(!json_bool(None, "fmt", false));
     }
 
     #[test]
-    fn check_config_step_respects_explicit_booleans() {
-        assert!(!check_config_step_enabled(Some(&json!({ "fmt": false })), "fmt"));
-        assert!(check_config_step_enabled(Some(&json!({ "fmt": true })), "fmt"));
-        assert!(!check_config_step_enabled(Some(&json!({ "lint": false })), "lint"));
-        assert!(check_config_step_enabled(Some(&json!({ "lint": true })), "lint"));
+    fn json_bool_respects_explicit_booleans() {
+        assert!(!json_bool(Some(&json!({ "fmt": false })), "fmt", true));
+        assert!(json_bool(Some(&json!({ "fmt": true })), "fmt", false));
+        assert!(!json_bool(Some(&json!({ "lint": false })), "lint", true));
+        assert!(json_bool(Some(&json!({ "lint": true })), "lint", false));
     }
 
     #[test]
diff --git a/packages/cli/binding/src/check/mod.rs b/packages/cli/binding/src/check/mod.rs
index 358d757c13..1272be9460 100644
--- a/packages/cli/binding/src/check/mod.rs
+++ b/packages/cli/binding/src/check/mod.rs
@@ -9,9 +9,9 @@ use vite_shared::output;
 use vite_task::ExitStatus;
 
 use self::analysis::{
-    LintMessageKind, analyze_fmt_check_output, analyze_lint_output, check_config_step_enabled,
-    format_count, format_elapsed, lint_config_type_check_enabled, print_error_block,
-    print_pass_line, print_stdout_block, print_summary_line,
+    LintMessageKind, analyze_fmt_check_output, analyze_lint_output, format_count, format_elapsed,
+    json_bool, lint_config_type_check_enabled, print_error_block, print_pass_line,
+    print_stdout_block, print_summary_line,
 };
 use crate::cli::{
     CapturedCommandOutput, SubcommandResolver, SynthesizableSubcommand, resolve_and_capture_output,
@@ -42,8 +42,8 @@ pub(crate) async fn execute_check(
     // `check.lint` is disabled in vite.config.ts. The skip note is printed only
     // when CONFIG (not the CLI flag) turned a step off, so existing `--no-fmt` /
     // `--no-lint` output stays byte-identical.
-    let config_fmt_off = !check_config_step_enabled(resolved_vite_config.check.as_ref(), "fmt");
-    let config_lint_off = !check_config_step_enabled(resolved_vite_config.check.as_ref(), "lint");
+    let config_fmt_off = !json_bool(resolved_vite_config.check.as_ref(), "fmt", true);
+    let config_lint_off = !json_bool(resolved_vite_config.check.as_ref(), "lint", true);
     if config_fmt_off && !no_fmt_flag {
         output::note("Format skipped (check.fmt: false in vite.config.ts)");
     }

From de605c5971c42e79c7d24d8151ff6620bbd3ed3f Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Mon, 29 Jun 2026 13:53:48 +0800
Subject: [PATCH 4/5] fix(check): address review feedback

- Update stale check-all-skipped snapshot for the reworded summary line
- Clarify docs: check.fmt/check.lint defaults apply to any vp check run,
  including one invoked from a pre-commit/staged hook
- Note the typeAware prerequisite alongside typeCheck in check.lint guidance
---
 docs/config/check.md                               | 7 ++++---
 docs/guide/check.md                                | 2 +-
 packages/cli/snap-tests/check-all-skipped/snap.txt | 2 +-
 packages/cli/src/define-config.ts                  | 4 ++--
 4 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/docs/config/check.md b/docs/config/check.md
index 83e35b141d..25c537d590 100644
--- a/docs/config/check.md
+++ b/docs/config/check.md
@@ -13,8 +13,9 @@ export default defineConfig({
   check: {
     // Skip the format step in `vp check`. Defaults to true.
     fmt: false,
-    // Skip lint rules in `vp check`. Type-check still runs when
-    // `lint.options.typeCheck` is enabled. Defaults to true.
+    // Skip lint rules in `vp check`. Type-check still runs when both
+    // `lint.options.typeAware` and `lint.options.typeCheck` are enabled.
+    // Defaults to true.
     lint: true,
   },
 });
@@ -24,5 +25,5 @@ When a step is disabled here, `vp check` prints a short `note:` line so it is cl
 
 ## Scope and precedence
 
-- These options only affect the composite `vp check`. Standalone [`vp fmt`](/config/fmt), [`vp lint`](/config/lint), and the git-hook [`staged`](/config/staged) flow are unaffected, so you can still run a disabled tool directly when you need it once.
+- These options only affect the composite `vp check`. Standalone [`vp fmt`](/config/fmt) and [`vp lint`](/config/lint) are unaffected, so you can still run a disabled tool directly when you need it once. Note that any `vp check` invocation honors these defaults, including one run from a pre-commit hook: if your [`staged`](/config/staged) tasks call `vp check`, that step is skipped there too.
 - A step is skipped if the config disables it **or** the matching CLI flag is passed. There is no flag to re-enable a step disabled in config; run `vp fmt` or `vp lint` directly instead.
diff --git a/docs/guide/check.md b/docs/guide/check.md
index efdc96d28d..0d04c3e58e 100644
--- a/docs/guide/check.md
+++ b/docs/guide/check.md
@@ -57,4 +57,4 @@ export default defineConfig({
 });
 ```
 
-These options only affect `vp check`; standalone `vp fmt` and `vp lint` still run normally. A step is skipped if it is disabled in config or the matching `--no-fmt` / `--no-lint` flag is passed.
+These options only affect `vp check`; standalone `vp fmt` and `vp lint` still run normally. A step is skipped if it is disabled in config or the matching `--no-fmt` / `--no-lint` flag is passed. Because the defaults apply to every `vp check` run, a pre-commit hook that calls `vp check` will skip the disabled step too. See [Check config](/config/check) for the full reference.
diff --git a/packages/cli/snap-tests/check-all-skipped/snap.txt b/packages/cli/snap-tests/check-all-skipped/snap.txt
index c462f68156..5d67c4b8ed 100644
--- a/packages/cli/snap-tests/check-all-skipped/snap.txt
+++ b/packages/cli/snap-tests/check-all-skipped/snap.txt
@@ -1,4 +1,4 @@
 [1]> vp check --no-fmt --no-lint
 error: No checks enabled
 
-Enable `lint.options.typeCheck` in vite.config.ts to use `vp check --no-fmt --no-lint` for type-check only, or drop a flag to re-enable fmt/lint.
+Enable `lint.options.typeCheck` in vite.config.ts for type-check only, drop a `--no-fmt`/`--no-lint` flag, or re-enable `check.fmt`/`check.lint` in vite.config.ts.
diff --git a/packages/cli/src/define-config.ts b/packages/cli/src/define-config.ts
index 7a6b02be6b..4dcd5ec5e8 100644
--- a/packages/cli/src/define-config.ts
+++ b/packages/cli/src/define-config.ts
@@ -44,8 +44,8 @@ declare module '@voidzero-dev/vite-plus-core' {
       fmt?: boolean;
 
       /**
-       * Run the lint step in `vp check`. Type-check still runs when
-       * `lint.options.typeCheck` is enabled.
+       * Run the lint step in `vp check`. Type-check still runs when both
+       * `lint.options.typeAware` and `lint.options.typeCheck` are enabled.
        * @default true
        */
       lint?: boolean;

From 0422f4cda05c86a59a17c67ec050262926956fff Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Mon, 29 Jun 2026 14:01:43 +0800
Subject: [PATCH 5/5] docs(check): add vp check output example for disabled
 step

---
 docs/config/check.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/docs/config/check.md b/docs/config/check.md
index 25c537d590..81bfd6520d 100644
--- a/docs/config/check.md
+++ b/docs/config/check.md
@@ -21,7 +21,13 @@ export default defineConfig({
 });
 ```
 
-When a step is disabled here, `vp check` prints a short `note:` line so it is clear why the step did not run.
+When a step is disabled here, `vp check` prints a short `note:` line so it is clear why the step did not run. With the `check.fmt: false` config above:
+
+```bash
+$ vp check
+note: Format skipped (check.fmt: false in vite.config.ts)
+pass: Found no warnings or lint errors in 1 file (12ms, 8 threads)
+```
 
 ## Scope and precedence