How to fix Namespace 'X' cannot be redeclared in ambient context in TypeScript

If your file doesn't need to be ambient (global), add an import or export statement to make it a module:

// BEFORE - ambient context (problematic)
declare namespace MyLibrary {
  export interface Config {
    timeout: number;
  }
}

// AFTER - module context (isolated)
declare namespace MyLibrary {
  export interface Config {
    timeout: number;
  }
}

// Add this line to make it a module
export {};

The export {} statement tells TypeScript this is a module, not an ambient context. This isolates the namespace declaration to this file only.

If you need to extend an existing namespace from a third-party library, use module augmentation:

// WRONG - redeclaring ambient namespace
declare namespace Express {
  interface Request {
    user?: User;
  }
}

// CORRECT - module augmentation
declare module "express" {
  interface Request {
    user?: User;
  }
}

// OR for global namespace augmentation
declare global {
  namespace Express {
    interface Request {
      user?: User;
    }
  }
}

Module augmentation uses declare module "module-name" syntax instead of redeclaring the entire namespace.

If you have multiple files declaring parts of the same namespace, consolidate them into one declaration file:

// types.d.ts - Single consolidated file
declare namespace MyApp {
  export interface User {
    name: string;
    email: string;
  }

  export interface Config {
    apiUrl: string;
    timeout: number;
  }

  export type Status = "active" | "inactive" | "pending";
}

TypeScript supports declaration merging for namespaces, but it's cleaner to have a single source of truth. Remove duplicate namespace declarations from other files.

Duplicate namespace declarations often come from conflicting type definition packages:

# List all @types packages
npm ls @types

# Check for multiple versions of the same package
npm ls @types/node
npm ls @types/express

# Remove and reinstall to deduplicate
rm -rf node_modules package-lock.json
npm install

Common conflicts occur with:
- @types/node (declares global NodeJS namespace)
- @types/express (declares Express namespace)
- Library-specific type definitions that declare global namespaces

If the conflict comes from third-party type definitions you can't control, enable skipLibCheck in tsconfig.json:

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

This skips type-checking for all declaration files, which can resolve namespace conflicts. However, this is a workaround—prefer fixing the root cause.

Warning: skipLibCheck disables type checking for all .d.ts files, which might hide other type errors.

Modern TypeScript projects should use ES modules instead of namespaces:

// OLD - namespace pattern
namespace Utilities {
  export function formatDate(date: Date): string {
    return date.toISOString();
  }
}

// NEW - module pattern
// utilities.ts
export function formatDate(date: Date): string {
  return date.toISOString();
}

// consumer.ts
import { formatDate } from "./utilities";

Benefits of ES modules:
- No global namespace pollution
- Better tree-shaking and bundling
- Standard JavaScript module system
- Clearer dependency graph