Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

TypeScript cannot find import.meta.env in a Vite project

ErrorProperty 'env' does not exist on type 'ImportMeta'.ts(2339)

Short answer

TypeScript only knows import.meta.env after Vite's client types are loaded. Add vite/client to compilerOptions.types in tsconfig.json, or a vite-env.d.ts file with a triple-slash reference to it. For your own VITE_ variables, augment ImportMetaEnv in a d.ts file that has no import statements.

  • Applies to Vite 7, Vite 8, TypeScript 5.9
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask TypeScript which files it loads. If no file that references vite/client is in the list, the types are missing.

    npx tsc --noEmit --listFiles | grep -E 'vite/client|vite-env'
  2. 2Match what you see, then jump to its fix

    1. 1TS2339 on every import.meta.env use, including import.meta.env.MODEVite's client types are not loadedFix
    2. 2vite-env.d.ts exists, but the error staysThe d.ts file with the reference is not part of the programFix
    3. 3The error names your variable, such as Property 'VITE_API_URL' does not exist on type 'ImportMetaEnv'Your own VITE_ variable is not declared, or the augmentation is ignoredFix

What does the error look like?

  • Property 'env' does not exist on type 'ImportMeta'.ts(2339)
  • Property 'VITE_API_URL' does not exist on type 'ImportMetaEnv'

Cause 1 of 3

Vite's client types are not loaded

1Check

Look for a vite-env.d.ts file in src and for a types list in tsconfig.json. A project created by hand, or one where the file was deleted, has neither.

ls src/vite-env.d.ts
grep -n "types" tsconfig.json

2Fix

Add vite/client to compilerOptions.types. Note that once types is set, only the listed packages join the global scope, so keep any other global type packages in the same array.

{
  "compilerOptions": {
    "types": ["vite/client"]
  }
}

3Verify

Run the type check again; the error on import.meta.env is gone.

npx tsc --noEmit

Confirmed by vite.dev

Did this fix it?

Cause 2 of 3

The d.ts file with the reference is not part of the program

1Check

A tsconfig include list only picks up the folders it names. If the d.ts file sits outside those patterns, TypeScript never reads it.

grep -n -A3 "include" tsconfig.json

2Fix

Put the file where include reaches it (src by default), then give it the reference line.

// src/vite-env.d.ts
/// <reference types="vite/client" />

3Verify

The file now shows up in the list of loaded files.

npx tsc --noEmit --listFiles | grep vite-env

Confirmed by typescriptlang.org

Did this fix it?

Cause 3 of 3

Your own VITE_ variable is not declared, or the augmentation is ignored

1Check

Open the d.ts file where you declared ImportMetaEnv. If it has any import statement at the top, TypeScript treats it as a module and the augmentation does not apply.

grep -n "^import" src/vite-env.d.ts

2Fix

Remove the import lines from that file and declare the variables there. Keep the VITE_ prefix, because Vite only exposes variables with it to client code.

// src/vite-env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_URL: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

3Verify

Type check again, then read the value in code.

npx tsc --noEmit
# in code: const url = import.meta.env.VITE_API_URL

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Keep src/vite-env.d.ts in version control; scaffolded projects include it for this reason.
  • Declare every VITE_ variable the code reads in ImportMetaEnv, so a typo fails at type check instead of at runtime.
  • Never put secrets in VITE_ variables; they are bundled into client code.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.