Comprehensive Analysis and Solutions for TypeScript TS2304 Error: Cannot Find Name 'require'

Problem Background and Error Analysis

In TypeScript development with Node.js, TS2304: Cannot find name 'require' is a frequently encountered compilation error. The essence of this error lies in TypeScript's static type checking mechanism being unable to recognize the global require function, as require is provided by the Node.js runtime environment rather than being a built-in feature of the TypeScript language itself.

From the problem description, we can see the developer is attempting to compile a simple TypeScript file using Node.js module import syntax:

var mongoose = require('mongoose');

Although the generated JavaScript file executes correctly, the TypeScript compiler cannot find the definition of require during the type checking phase, thus throwing the TS2304 error. This situation is particularly common when migrating from JavaScript projects to TypeScript or when initially setting up a TypeScript environment.

TypeScript Type System and Module Resolution

To understand the root cause of this error, we must first comprehend how TypeScript's type system works. TypeScript uses type definition files (.d.ts) to recognize type information provided by JavaScript libraries and runtime environments. When code uses the require function, TypeScript needs to find the corresponding declaration in type definitions.

In early TypeScript 1.x versions, developers typically used tsd or typings tools to manage type definitions:

tsd install node --save
tsd install require --save

These commands would download corresponding type definition files and include them in code through reference path directives:

/// <reference path="typings/tsd.d.ts" />

However, this approach suffered from maintenance complexity and version conflicts, especially in large projects.

Quick Solutions

For simple projects or demonstration purposes, the most direct solution is to declare the require variable at the top of the TypeScript file:

declare var require: any;

While this method is simple and effective, it sacrifices type safety. TypeScript will treat require as any type, meaning no type checking will be performed on require calls, thus losing TypeScript's core advantage.

Another similar quick fix is to declare it globally:

declare function require(path: string): any;

This approach provides basic function signatures but still lacks detailed type information.

Modern Solutions for TypeScript 2.x and Later

Starting from TypeScript 2.0, the @types mechanism was introduced, greatly simplifying type definition management. For Node.js projects, the correct approach is:

npm install @types/node --save-dev

This command installs complete Node.js type definitions, including type information for require function, process, Buffer, and all other Node.js built-in modules.

After installation, corresponding configuration in tsconfig.json is required:

{
  "compilerOptions": {
    "types": ["node"],
    "typeRoots": ["../node_modules/@types"]
  }
}

The types array here specifies type packages to include, while typeRoots specifies the root directory for type definitions. By default, all packages under @types are automatically included in compilation unless types or typeRoots options are explicitly specified.

Detailed tsconfig.json Configuration

Proper tsconfig.json configuration is crucial for resolving TS2304 errors. Here's a complete configuration example:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "lib": ["es2016"],
    "types": ["node"],
    "typeRoots": ["node_modules/@types"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

Key configuration items explained:

• target: Specifies compilation target JavaScript version, recommended es2016 or higher
• module: Module system, typically commonjs for Node.js projects
• lib: Included library definitions, ensure necessary JavaScript features are included
• types: Explicitly included type definition packages
• typeRoots: Lookup paths for type definition files

Build Tool Integration Solutions

Solutions may vary across different build tool environments.

Webpack Environment:

npm install --save-dev @types/webpack-env

Then configure in tsconfig.json:

{
  "compilerOptions": {
    "types": ["webpack-env"]
  }
}

This enables Webpack-specific features like require.ensure.

Angular CLI Projects:

In Angular CLI generated projects, edit the src/tsconfig.app.json file:

{
  "compilerOptions": {
    "types": ["node"]
  }
}

Be careful not to add node types to the root tsconfig.json, as this would leak Node.js types to browser-side code.

Common Pitfalls and Debugging Techniques

Several common pitfalls require attention in practical development:

Empty Types Array Issue: Some tools (like NX) might generate configurations containing empty types arrays:

"types": []

This prevents automatic inclusion of all @types packages, causing TS2304 errors. The solution is to remove empty types arrays or explicitly add required types.

Testing Framework Conflicts: In some cases, installed testing framework type definitions (like @types/jasmine) might conflict with project configuration. If require is genuinely not used in the project but TS2304 errors persist, try removing unnecessary type definitions.

Target Library Version Mismatch: As mentioned in reference article 3, when using libraries that depend on newer JavaScript features (like Map, Set, Iterator, etc.) but TypeScript configuration targets lower versions, similar name not found errors occur. The solution is to adjust lib configuration or upgrade target version.

Best Practice Recommendations

Based on years of TypeScript development experience, we recommend the following best practices:

1. Use ES Module Syntax: Prefer import/export syntax over require where possible, as this aligns better with TypeScript's design philosophy
2. Maintain Updated Type Definitions: Regularly update @types packages to ensure compatibility with runtime versions
3. Configure Strict Type Checking: Enable strict mode to detect type issues early
4. Use Type-Safe Alternatives: For dynamic imports, consider using import() function instead of require
5. Unified Build Configuration: Maintain consistent tsconfig.json configuration across team projects

Migration Strategies and Compatibility Considerations

For migration scenarios from older TypeScript versions or JavaScript projects, reasonable migration strategies are essential:

Progressive Migration: Temporarily use declare var require: any as a transitional solution, gradually replacing it with type-safe alternatives

Mixed Mode Support: In large projects, both CommonJS and ES modules might coexist, requiring proper moduleResolution configuration

Backward Compatibility: Ensure solutions work correctly across different TypeScript versions, particularly when supporting older Node.js versions

By systematically understanding the root causes of TS2304 errors and adopting appropriate solutions, developers can fully leverage TypeScript's type safety advantages while maintaining good compatibility with the existing Node.js ecosystem. Proper type definition management and build configuration are key factors for successful TypeScript projects.