Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Uncaught ReferenceError: process is not defined in a Vite app

ErrorUncaught ReferenceError: process is not defined

Short answer

Vite does not provide Node.js globals such as process to browser code. Code written for Create React App or webpack reads process.env and breaks. Use import.meta.env with a VITE_ prefix in your own code. For a library that needs a constant, supply it through the define option.

  • Applies to Vite 8, React 19, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find every place that touches process in the code that ships to the browser.

    grep -rn "process\.env" src/
  2. 2Match what you see, then jump to its fix

    1. 1The stack trace points into src/Your own code reads process.envFix
    2. 2The trace points into node_modules, or you cannot edit the fileA dependency or an old snippet needs a replaced constantFix

What does the error look like?

  • Uncaught ReferenceError: process is not defined

Cause 1 of 2

Your own code reads process.env

1Check

The grep output lists lines such as process.env.REACT_APP_API_URL, copied from a Create React App project.

grep -rn "REACT_APP_\|process\.env" src/

2Fix

Rename the variable with a VITE_ prefix in the env file and read it through import.meta.env. Only prefixed variables are exposed to client code.

// before
const url = process.env.REACT_APP_API_URL
// after
const url = import.meta.env.VITE_API_URL

# .env
VITE_API_URL=https://api.example.com

3Verify

Restart the dev server so the env file is read again, then reload the page.

npm run dev

Confirmed by vite.dev

Did this fix it?

Cause 2 of 2

A dependency or an old snippet needs a replaced constant

1Check

Search the stack frame's file for the exact expression, for example process.env.SOME_FLAG.

grep -rn "process\.env\.SOME_FLAG" node_modules/some-package | head

2Fix

Replace the exact expression at build time with the define option. Values must be JSON-serializable, so wrap strings in JSON.stringify.

// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  define: {
    'process.env.SOME_FLAG': JSON.stringify('on'),
  },
})

3Verify

Restart the dev server and reload.

npm run dev

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Use only import.meta.env in browser code, and keep process for vite.config and Node scripts.
  • Search for process.env after moving a project from another bundler.

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

Next step

Want this handled for good?

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