Description

InlineConfig.envFile is marked as @deprecated in the TypeScript definition, but no runtime deprecation warning is emitted when it is used. This means users calling the programmatic API with { envFile: false } receive no guidance to migrate to { envDir: false }.

Affected version

[email protected] and current main branch.

Affected file

packages/vite/src/node/config.ts

The type definition carries the deprecation annotation (L637–638):

/** @deprecated */
envFile?: false

But the usage site silently converts it without any warning (L1677–1678):

// Backward compatibility: set envDir to false when envFile is false
let envDir = config.envFile === false ? false : config.envDir

Inconsistency with other deprecated options

Other deprecated options in the same file emit a logger.warn() when used:

Additionally, the migration guide (docs/guide/migration.md) documents esbuild and esbuildOptions deprecations in detail, but has no entry for envFile: false → envDir: false.

Background

InlineConfig.envFile?: false was added in #2475 for the programmatic API. It was deprecated in #19503 (merged 2025-03-31), which introduced envDir: false as the recommended replacement. The deprecation annotation was added as a side-effect of that PR; no runtime warning was included.

Proposed direction and open question

The straightforward fix would be to add a logger.warn() call when config.envFile === false is detected, consistent with how other deprecated options are handled:

// load .env files
if (config.envFile === false) {
  logger.warn(
    colors.yellow(
      '`envFile: false` is deprecated. Use `envDir: false` instead.',
    ),
  )
}
let envDir = config.envFile === false ? false : config.envDir

However, InlineConfig is the programmatic API used by framework integrations such as Astro, Nuxt, and SvelteKit. If any of these currently pass { envFile: false } to createServer() or build(), adding this warning would surface in end-user output without those frameworks having made any change.

Would this direction be acceptable? If so, I'd also propose adding a short migration note to docs/guide/migration.md. Happy to submit a PR once the approach is confirmed.