## TL;DR

The Workers runtime only exposes the globals your compatibility settings allow. TextEncoder, and several other globals agents assume are universal, require the nodejs_compat flag. Add the flag to wrangler.toml, redeploy, and the global exists.

## The query

```text
workerd error: TextEncoder is not defined without nodejs_compat
```

## Use this when

- The worker throws that a standard global is not defined.
- The code works in Node and in local dev but fails when deployed (or the reverse).
- You recently removed or never set compatibility flags.

## Not for

- 'Cannot find module' bundler errors (import problem).
- Missing npm packages (dependency problem).
- Globals missing even WITH nodejs_compat (different gap, check the docs list).

## Steps

### Step 1: Check the current compatibility flags

```toml
compatibility_date = "2024-01-01"
# compatibility_flags = [ "nodejs_compat" ]  # is this line present?
```

Expected result: you see whether nodejs_compat is set. Its absence with Node-style code is the diagnosis.

### Step 2: Enable nodejs_compat

```toml
compatibility_flags = [ "nodejs_compat" ]
```

Expected result: the config requests Node.js compatibility. The runtime exposes the Node globals list on the next deploy.

### Step 3: Check the compatibility date too

Some globals are gated by date as well as flags. A very old compatibility_date can hide globals even with the flag set.

Expected result: the date is recent enough for the globals you use. Bump it deliberately, not blindly; date changes alter runtime behavior.

### Step 4: Redeploy and verify

```bash
npx wrangler deploy
```

Expected result: the worker runs without the 'not defined' error. Test the exact code path that threw.

### Step 5: Audit for other Node-isms

Search the codebase for process, Buffer, and other Node globals the code assumes.

Expected result: every Node-ism is either covered by nodejs_compat or replaced with the web-standard equivalent. One flag fixes the reported error; the audit prevents the next five.

## Why it happens

Workers are not Node.js. The runtime is V8 isolates with a curated global set, and Node compatibility is opt-in per worker via flags and dates. Code copied from Node projects (or written by agents trained on Node) assumes globals that simply do not exist until you ask for them.

## Edge cases

- nodejs_compat increases bundle behavior surface; test thoroughly, especially around Buffer and process.env semantics.
- Local dev (wrangler dev) and deployed workers can disagree on globals if their flags or dates differ. Keep one wrangler.toml as the source of truth.
- Some Node APIs remain unavailable even with the flag. Check the runtime docs before assuming coverage.
- Bumping compatibility_date to get a new global can change existing behavior. Read the change notes for the date you jump to.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_L5LcDXVQD-JTaRgQVmsANA