How to fix Cannot find name 'Buffer' in TypeScript

TypeScriptBEGINNERMEDIUM

This TypeScript error occurs when you try to use the Node.js Buffer class without installing @types/node type definitions. Buffer is a global Node.js API, but TypeScript doesn't recognize it by default without proper type declarations.

What this error means

The Buffer class is a fundamental Node.js global that provides a way to work with binary data directly. However, TypeScript does not include Node.js type definitions in its default type library. When you try to use Buffer in a TypeScript project without the proper type declarations, the compiler cannot find its definition and throws error TS2304. This error is particularly common when: 1. **Starting a new Node.js project with TypeScript**: The initial setup lacks Node.js type definitions 2. **Migrating JavaScript to TypeScript**: Existing Node.js code uses Buffer but types aren't configured 3. **Using libraries that depend on Node.js APIs**: Third-party packages reference Buffer but your project hasn't installed @types/node TypeScript treats Browser and Node.js as separate environments. By default, it assumes a browser context where Buffer doesn't exist. You must explicitly tell TypeScript you're in a Node.js environment by installing and configuring the appropriate type definitions.

How to fix "Cannot find name 'Buffer'"

1Install @types/node package

The @types/node package contains TypeScript definitions for all Node.js built-in modules and globals, including Buffer. Install it as a development dependency:

bash

npm install --save-dev @types/node

Or if you're using yarn:

bash

yarn add --dev @types/node

Or with pnpm:

bash

pnpm add -D @types/node

After installation, TypeScript will automatically pick up the Buffer type definition. Verify the installation:

bash

npm list @types/node

You should see the installed version (e.g., @types/[email protected] or similar).

2Configure tsconfig.json to include Node.js types

After installing @types/node, ensure your tsconfig.json is configured to use it. Add "node" to the types array:

json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "types": ["node"],
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Key settings:

- "types": ["node"]: Explicitly includes Node.js type definitions
- "lib": ["ES2020"]: Use ES2020 features (adjust to your target)
- "module": "commonjs": Standard for Node.js (or use "NodeNext" for modern Node)

If you don't have a tsconfig.json file, create one:

bash

npx tsc --init

Then modify it with the settings above.

3Use Buffer in your TypeScript code

After installing types and configuring tsconfig.json, you can use Buffer without errors:

typescript

// Create a Buffer from a string
const buf1 = Buffer.from("Hello World", "utf8");
console.log(buf1); // <Buffer 48 65 6c 6c 6f 20 57 6f 72 6c 64>

// Allocate a buffer with size
const buf2 = Buffer.alloc(10);
buf2.write("test");
console.log(buf2.toString()); // "test"

// Working with binary data
const data = Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
console.log(data.toString()); // "Hello"

TypeScript will now provide full autocomplete and type checking for all Buffer methods:

typescript

const buffer: Buffer = Buffer.from("data");
const length: number = buffer.length;
const hex: string = buffer.toString("hex");

4Verify TypeScript compilation works

Test that your TypeScript project compiles without errors:

bash

npx tsc --noEmit

The --noEmit flag checks types without generating JavaScript files. If successful, you'll see no output. If errors remain:

1. Restart your IDE/editor: VS Code sometimes needs a reload (Ctrl+Shift+P → "Reload Window")
2. Clear TypeScript cache: Delete .tsbuildinfo files
3. Reinstall node_modules: Sometimes type definitions get corrupted

bash

rm -rf node_modules package-lock.json
npm install

Run your TypeScript code with ts-node or build and run:

bash

# Using ts-node (development)
npx ts-node src/index.ts

# Or build and run (production)
npx tsc
node dist/index.js

Advanced notes

### TypeScript 5.9+ and Buffer Type Changes

In TypeScript 5.9, the Buffer type hierarchy changed. Buffer is no longer treated as a direct supertype of all TypedArray types. This can cause additional type compatibility issues with older code:

typescript

// May have issues in TypeScript 5.9+
function processData(data: Uint8Array) {
  // Buffer extends Uint8Array, but type checking is stricter now
}

const buf = Buffer.from("test");
processData(buf); // May require explicit type assertion in TS 5.9+

If you encounter this, you may need to use type assertions or update your type definitions to handle Buffer more explicitly.

### Using Triple-Slash Directives

Instead of modifying tsconfig.json, you can add a reference directive at the top of individual files:

typescript

/// <reference types="node" />

const buffer = Buffer.from("Hello");

This approach is useful for scripts or standalone files, but tsconfig.json configuration is preferred for full projects.

### Browser vs Node.js Environment

Buffer is only available in Node.js, not in browsers. If you're working on a frontend project and seeing this error, it might indicate you're trying to use Node.js APIs in browser code, which won't work at runtime.

For browser environments needing Buffer-like functionality, use:

bash

npm install buffer

This is a polyfill that provides Buffer in browsers:

typescript

import { Buffer } from "buffer";

const buf = Buffer.from("data");

However, this is different from the Node.js Buffer and has limitations.

### Monorepo and Path Mapping

In monorepo setups (Nx, Turborepo, etc.), ensure each package that uses Buffer has @types/node installed. Path mapping in tsconfig.json can sometimes interfere with type resolution:

json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@app/*": ["src/*"]
    },
    "types": ["node"]
  }
}

Make sure "types": ["node"] is present in the root tsconfig.json and any project-specific configs.

### Conflicts with @types/buffer

There's a separate @types/buffer package for the browser polyfill. If you have both @types/node and @types/buffer installed, they can conflict:

bash

# Check for conflicts
npm ls @types/buffer @types/node

Generally, for Node.js projects, you only need @types/node. Remove @types/buffer if it's causing issues:

bash

npm uninstall @types/buffer

### CommonJS vs ES Modules

Modern Node.js supports ES modules. If using ES modules with TypeScript:

json

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "types": ["node"]
  }
}

Buffer works the same in both module systems—the key is having @types/node installed.

How to fix Cannot find name 'Buffer' in TypeScript

What this error means

Typical symptoms

Common causes

How to fix "Cannot find name 'Buffer'"

Advanced notes

Related errors

Official resources & further reading