process is not defined — What It Means and How to Fix It

Q: When Should You Worry About This?

You should worry when this error appears in production on a client-side route. A dev-only error is annoying; a production crash means users see a blank page. If it shows up in server-side Node.js code (like an Express API), that's a different problem — you're likely using a bundler that strips Node globals. Check your tsconfig.json and bundler config first. Next time this error appears, check whether you're in a browser or Node environment first — then look at how your framework exposes environment variables before touching any other config.

The error process is not defined means JavaScript code is trying to access Node.js's global process object in an environment that doesn't have it, like a browser or a client-side bundle.

What "process is not defined" Means

This error fires when your code references process.env or process.cwd() outside a Node.js runtime. The process object simply doesn't exist in browsers, so JavaScript throws a ReferenceError the moment you touch it.

Why It Happens

The two most common causes are:

You're running browser-side code — any script executed by Chrome, Firefox, or Safari has no process global. If you bundle server code with Vite, Webpack, or Parcel without proper shims, this error appears instantly.
You're using Next.js or similar frameworks incorrectly — Next.js runs code on both server and client. If you call process.env in a component without the NEXT_PUBLIC_ prefix, the client bundle will try to access process and crash.

Example Code That Triggers It

Here's a minimal TypeScript file that will fail in a browser:

// app.ts — this runs in the browser
const apiKey = process.env.API_KEY;
console.log(apiKey);

If you compile this with tsc and load it via a <script> tag, you'll get:

Uncaught ReferenceError: process is not defined
    at app.ts:1:17

The same happens in Next.js if you write process.env.SECRET inside a React component without the NEXT_PUBLIC_ prefix.

How to Fix It

The fix depends on where the code runs. For a browser, replace process.env with a compile-time constant:

// Fixed: use a build-time variable or hardcode the value
const apiKey = "your-public-key";
console.log(apiKey);

For Next.js, prefix the variable so it's exposed to the client:

// In .env.local
NEXT_PUBLIC_API_KEY=your-public-key

// In your component
const apiKey = process.env.NEXT_PUBLIC_API_KEY;

For Vite, use import.meta.env instead:

const apiKey = import.meta.env.VITE_API_KEY;

The fix works because you're either eliminating the reference to process or replacing it with an environment-specific global that actually exists in that runtime.

Common Mistakes That Cause This

Mistake 1: Assuming process is universal. Developers coming from Node.js often write process.env in shared utility files without checking the runtime. That file then gets imported by both server and client code.

Mistake 2: Skipping the framework's environment variable conventions. In Next.js, forgetting NEXT_PUBLIC_ is the #1 cause. In Vite, it's using process.env instead of import.meta.env. Each framework has its own contract — ignoring it breaks the build.

When Should You Worry About This?

You should worry when this error appears in production on a client-side route. A dev-only error is annoying; a production crash means users see a blank page. If it shows up in server-side Node.js code (like an Express API), that's a different problem — you're likely using a bundler that strips Node globals. Check your tsconfig.json and bundler config first.

Next time this error appears, check whether you're in a browser or Node environment first — then look at how your framework exposes environment variables before touching any other config.