Side Effect Import

A side-effect import is an import declaration that executes a module’s code for its global side effects without binding any of its exported members to the current module’s scope.

import "module-name";
import "./local-module.js";

Mechanics and Behavior

Scope and Binding Unlike standard import declarations, a side-effect import does not introduce any local variables, functions, or types into the importing module’s namespace. The target module is evaluated, but its export statements are ignored by the importing file.

Compiler Emit and Elision The TypeScript compiler (tsc) performs import elision: it removes import statements from the emitted JavaScript if it determines the imported members are only used in type positions. However, side-effect imports are strictly exempt from this process. The compiler guarantees that a side-effect import is never elided and will always be preserved in the compiled JavaScript output.

Type System Integration During the compilation phase, TypeScript parses the target module of a side-effect import. If the target module contains ambient declarations or global type augmentations, the compiler applies them to the global type environment.

// global-types.ts
declare global {
  interface Window {
    customProperty: string;
  }
}
export {};

// main.ts
import "./global-types.js"; // Side-effect import

// The compiler now recognizes 'customProperty' on the global Window interface
window.customProperty = "value"; 

Evaluation Order In accordance with the ECMAScript Modules (ESM) specification, import declarations are hoisted. The JavaScript runtime resolves the module graph and evaluates the side-effect module before the importing module’s own code begins executing. It is not evaluated inline at the lexical position of the import statement. Per the specification, the module is evaluated exactly once, regardless of how many times it is imported across the application.

Master TypeScript with Deep Grasping Methodology!

Learn More