Maaz Zindani

Loading the index…

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

import.meta.env breaks or is undefined when I run my tests

ErrorTest suite failed to run

Short answer

import.meta.env is a Vite feature: Vite exposes the values and replaces them at build time. Jest is a separate tool with only experimental ESM support. Run the tests with Vitest instead, and set variables with its env option or vi.stubEnv. Only names starting with VITE_ reach client code.

  • Applies to Vite 7, Vitest 3, Jest 29, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check which test runner your npm test script uses. Jest means cause 1; Vitest means look at causes 2 and 3.

    grep -n "\"test\"" package.json
    npm ls jest vitest
  2. 2Match what you see, then jump to its fix

    1. 1The failure comes from Jest, and npm ls shows jest but not vitestJest runs the code without Vite, so import.meta.env has nothing behind itFix
    2. 2VITE_API_URL works but API_URL is undefined in client codeThe variable has no VITE_ prefixFix
    3. 3undefined inside one test only, or a different value is needed per testThe test needs a value that no file or config providesFix

What does the error look like?

  • Test suite failed to run
  • import.meta.env.VITE_API_URL is undefined in a test

Cause 1 of 3

Jest runs the code without Vite, so import.meta.env has nothing behind it

1Check

Vite exposes env values on import.meta.env and replaces them at build time. Nothing in Jest's documentation provides that step, and its ESM support is experimental and needs transforms emitting ESM.

cat jest.config.* 2>/dev/null

2Fix

Switch the test runner to Vitest, whose env option and vi.stubEnv work on import.meta.env.

npm uninstall jest
npm install -D vitest
# package.json
# "scripts": { "test": "vitest" }

3Verify

Run the suite once.

npx vitest run

Confirmed by vite.dev

Did this fix it?

Cause 2 of 3

The variable has no VITE_ prefix

1Check

Only variables starting with VITE_ are exposed to client code; others come back undefined.

grep -rn "import.meta.env\." src/

2Fix

Rename the variable to start with VITE_ everywhere it is defined and read.

# .env
VITE_API_URL=http://localhost:3000

3Verify

Read the value in a one-line test.

npx vitest run

Confirmed by vite.dev

Did this fix it?

Cause 3 of 3

The test needs a value that no file or config provides

1Check

Vitest's env option sets variables for the test run on both process.env and import.meta.env, and vi.stubEnv changes them inside a test.

cat vite.config.* vitest.config.* 2>/dev/null

2Fix

Set the variable in the test config for the whole run, or stub it per test and restore it afterwards.

// vitest.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({
  test: { env: { VITE_API_URL: 'http://localhost:3000' } },
})

// in a test file
import { vi, afterEach } from 'vitest'
vi.stubEnv('VITE_API_URL', 'http://test.local')
afterEach(() => vi.unstubAllEnvs())

3Verify

Assert on the value in the test and run it.

npx vitest run

Confirmed by vitest.dev

Did this fix it?

How do I stop it coming back?

  • Pick the test runner that matches the bundler: Vitest for Vite projects.
  • Read import.meta.env in one small config module, so tests stub one place.
  • Always restore stubbed values with vi.unstubAllEnvs in afterEach.

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.