Avoid TypeScript namespace Declarations

ID

javascript.ts_no_namespace

Severity

low

Remediation Complexity

medium

Remediation Risk

low

Remediation Effort

medium

Resource

Code Smell

Language

JavaScript

Tags

modules, typescript

Description

Reports TypeScript namespace (formerly module) declarations. The keyword is a remnant of TypeScript’s pre-ES-modules era; it conflates code organisation with type and value scoping in a way that bundlers, tree-shakers and IDEs handle poorly. ES modules — one declaration per file with import / export — cover every organisational use case more cleanly.

Ambient module declarations (declare namespace X {}) inside .d.ts type-only files are sometimes still required to type third-party globals; the rule fires on the syntactic form, and you can suppress it for those specific files via configuration.

Rationale

// Bad — pre-ES-modules style.
namespace Geometry {
  export class Point { x = 0; y = 0; }
  export function distance(a: Point, b: Point) {
    return Math.hypot(a.x - b.x, a.y - b.y);
  }
}

Tree-shaking can’t statically prove which exports of a namespace are unused, so bundlers drag in the whole namespace even when only one symbol is consumed.

Remediation

Rewrite the namespace as a regular ES module:

// Good — geometry.ts
export class Point { x = 0; y = 0; }
export function distance(a: Point, b: Point) {
  return Math.hypot(a.x - b.x, a.y - b.y);
}

// Consumers
import { Point, distance } from "./geometry";

For a tightly-scoped grouping of constants or types, a plain const-as-namespace pattern works without the namespace keyword:

export const Geometry = {
  PI_OVER_TWO: Math.PI / 2,
  EPSILON: 1e-9,
} as const;

References