fix: Formalize Vite startup validation guarantee and document the plugin contract

[yamcodes]

Fixes #1837

Added regression coverage for config-resolution validation and successful/failed HMR revalidation. Documented plugin-present startup validation versus plugin-absent import-driven validation across the Vite and TanStack Start guides and the plugin reference. No lazy-validation flag was introduced.

[pullfrog]

Run failed. View the logs →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1cfaa51

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@arkenv/agent-plugin

npm i https://pkg.pr.new/@arkenv/agent-plugin@1840

arkenv

npm i https://pkg.pr.new/arkenv@1840

@arkenv/build

npm i https://pkg.pr.new/@arkenv/build@1840

@arkenv/bun-plugin

npm i https://pkg.pr.new/@arkenv/bun-plugin@1840

@arkenv/core

npm i https://pkg.pr.new/@arkenv/core@1840

@arkenv/fumadocs-ui

npm i https://pkg.pr.new/@arkenv/fumadocs-ui@1840

@arkenv/nextjs

npm i https://pkg.pr.new/@arkenv/nextjs@1840

@arkenv/nuxt

npm i https://pkg.pr.new/@arkenv/nuxt@1840

@arkenv/rsbuild-plugin

npm i https://pkg.pr.new/@arkenv/rsbuild-plugin@1840

@arkenv/standard

npm i https://pkg.pr.new/@arkenv/standard@1840

@arkenv/tanstack-addon

npm i https://pkg.pr.new/@arkenv/tanstack-addon@1840

@arkenv/vite-plugin

npm i https://pkg.pr.new/@arkenv/vite-plugin@1840

commit: 1cfaa51

[yamcodes]

@pullfrog review

[pullfrog]

ℹ️ Minor suggestion only — the startup fail-fast and HMR revalidation contracts are accurately pinned by tests that pass.

Reviewed changes

• Vite / TanStack Start framework guides — added "When does validation run?" sections documenting plugin-registered startup validation during Vite config resolution, HMR revalidation of .env/schema changes, and import-driven validation without the plugin; explicitly state that no default-off lazy-validation flag is added.
• @arkenv/vite-plugin reference — new "Startup validation" section recording the plugin contract, including the same HMR/import-driven distinction.
• env-module.test.ts — three regression tests: fail-fast rejection with an ArkEnvError from configResolved for a missing value (plus a zero-pollution process.env assertion), valid schema/dotenv HMR invalidation, and invalid dotenv values propagating through handleHotUpdate.

I built the workspace and ran the full @arkenv/vite-plugin suite — all 17 tests pass, and the new tests individually exercise configResolved/handleHotUpdate against the real transform-plugin.ts implementation. The documented behavior matches the code path (configResolved → resolveEnvModulePath + loadValidatedEnv rethrow; handleHotUpdate → refreshTransformState rethrow under "Environment validation failed during HMR"). Biome and mdxlint are clean on all changed files. No changeset is needed (tests + docs only, and it was correctly removed).

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

• HMR happy-path revalidation now asserts substance — after the dotenv handleHotUpdate, the test rewrites .env.test, keeps the module-invalidation length check, then transforms the schema in a client-graph context and asserts the regenerated module inlines the updated VITE_API_URL. A regression where refreshTransformState stops re-reading values now goes red instead of passing on a bare toHaveLength(1).

This delta is the direct fix for the prior review's suggestion, and the rest of the PR (docs + the two other regression tests) was already reviewed at e2b102c1. I rebuilt the workspace and ran packages/vite-plugin/src/env-module.test.ts — all 17 tests pass, including revalidates valid schema and dotenv changes during HMR. The new assertion is falsifiable: with refresh dropped, state.clientValues would still hold https://example.com from configResolved, so the https://updated.example.com containment check would fail.

  ^{｜ View workflow run ｜ Using openrouter/deepseek/deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}