feat(types): make ImportMetaEnv strictly available (#19077)

Co-authored-by: Bjorn Lu <[email protected]>
Co-authored-by: sapphi-red <[email protected]>

Author: 3 people

docs/guide/env-and-mode.md

@@ -108,6 +108,12 @@ To achieve this, you can create an `vite-env.d.ts` in `src` directory, then augm
 ```typescript [vite-env.d.ts]
 /// <reference types="vite/client" />
 
+interface ViteTypeOptions {
+  // By adding this line, you can make the type of ImportMetaEnv strict
+  // to disallow unknown keys.
+  // strictImportMetaEnv: unknown
+}
+
 interface ImportMetaEnv {
   readonly VITE_APP_TITLE: string
   // more env variables...

packages/vite/src/node/__tests_dts__/typeOptions.ts

@@ -0,0 +1,21 @@
+// This file tests `ViteTypeOptions` in `packages/vite/types/importMeta.d.ts`
+import type { ExpectFalse, ExpectTrue } from '@type-challenges/utils'
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+interface TypeOptions1 {}
+interface TypeOptions2 {
+  strictImportMetaEnv: unknown
+}
+interface TypeOptions3 {
+  unknownKey: unknown
+}
+
+type IsEnabled<Opts, Key extends string> = Key extends keyof Opts ? true : false
+
+export type cases = [
+  ExpectFalse<IsEnabled<TypeOptions1, 'strictImportMetaEnv'>>,
+  ExpectTrue<IsEnabled<TypeOptions2, 'strictImportMetaEnv'>>,
+  ExpectFalse<IsEnabled<TypeOptions3, 'strictImportMetaEnv'>>,
+]
+
+export {}

packages/vite/types/importMeta.d.ts

@@ -2,8 +2,17 @@
 // Thus cannot contain any top-level imports
 // <https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation>
 
+// This is tested in `packages/vite/src/node/__tests_dts__/typeOptions.ts`
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- to allow extending by users
+interface ViteTypeOptions {
+  // strictImportMetaEnv: unknown
+}
+
+type ImportMetaEnvFallbackKey =
+  'strictImportMetaEnv' extends keyof ViteTypeOptions ? never : string
+
 interface ImportMetaEnv {
-  [key: string]: any
+  [key: ImportMetaEnvFallbackKey]: any
   BASE_URL: string
   MODE: string
   DEV: boolean