How to fix Cannot find name 'Buffer' in TypeScript

TypeScriptBEGINNERMEDIUMUpdated Dec 8, 2025· 167 views

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.

Quick fix

Fixes TS2304

npm install --save-dev @types/node
  1. Install @types/node package
  2. Configure tsconfig.json to include Node.js types
  3. Use Buffer in your TypeScript code
  4. Verify TypeScript compilation works
typescript — error
npm install --save-dev @types/node
Cannot find name 'Buffer'
shell
npm install --save-dev @types/node

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.

Typical symptoms

  • Red underline in VS Code or other IDEs beneath 'Buffer' references
  • TypeScript compilation fails with error TS2304: Cannot find name 'Buffer'
  • Code runs fine in JavaScript but breaks when migrating to TypeScript
  • Error appears when using Buffer.from(), Buffer.alloc(), or other Buffer methods
  • Libraries like AWS SDK, crypto, or stream utilities trigger the error
  • Works in Node.js runtime but TypeScript type checking fails at compile time

Common causes

  1. @types/node package is not installed in your project dependencies
  2. tsconfig.json does not include 'node' in the types array
  3. Using Buffer in a frontend/browser TypeScript project where Node.js types shouldn't be used
  4. Outdated or conflicting type definitions from multiple @types packages
  5. Project is missing a proper tsconfig.json file with Node.js configuration
  6. TypeScript is configured for browser environment (DOM types) but not Node.js

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/node@20.10.0 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.

Frequently asked questions

What does "TS2304" mean?
js global that provides a way to work with binary data directly. 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.
How do I fix "TS2304"?
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 causes "TS2304"?
@types/node package is not installed in your project dependencies tsconfig.json does not include 'node' in the types array Using Buffer in a frontend/browser TypeScript project where Node.js types shouldn't be used
Is the "TS2304" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading