Export Assignment

TypeScript’s export assignment (export =) is a module syntax designed to model the CommonJS module.exports and AMD return patterns. It specifies a single entity or expression as the exact exported value of a module, replacing the module object entirely.

Unlike standard ECMAScript modules (ESM) where export default creates a specific default export binding, the export = syntax binds the exported value directly to the module root.

Syntax

The export assignment is declared using the export = keywords followed by any valid expression. This can be an identifier, an inline object, an anonymous class, or a primitive value.

// calculator.ts
class Calculator {
    add(a: number, b: number): number {
        return a + b;
    }
}

export = Calculator;

// config.ts
export = { 
    port: 8080, 
    host: "localhost" 
};

When compiled to CommonJS, the TypeScript compiler emits this directly as a module.exports assignment:

// Compiled JavaScript (CommonJS)
class Calculator {
    add(a, b) {
        return a + b;
    }
}
module.exports = Calculator;

Import Requirements

Modules exporting a value via export = cannot be imported using standard ES6 import syntax (e.g., import Calc from "./calculator") under default compiler settings.

By default, TypeScript requires a corresponding, TypeScript-specific import syntax: import ... = require(...).

// app.ts
import Calculator = require("./calculator");
import config = require("./config");

const calc = new Calculator();
calc.add(2, 3);

Compiler Flags and Default Imports: To consume an export = assignment using standard ES6 default imports (import Calculator from "./calculator"), specific compiler flags in tsconfig.json must be utilized:

• allowSyntheticDefaultImports: Setting this to true instructs the TypeScript typechecker to allow the ES6 default import syntax. However, it does not change the emitted JavaScript. If the code is compiled to CommonJS and executed in Node.js without a bundler, it will crash at runtime because the emitted JavaScript will attempt to access a .default property that does not exist.
• esModuleInterop: To safely execute this pattern in CommonJS, this flag must be enabled. It automatically enables allowSyntheticDefaultImports for the typechecker and instructs the compiler to emit the __importDefault runtime helper. This helper ensures the emitted JavaScript correctly resolves the module root at runtime, preventing crashes.

Technical Constraints

1. Mutual Exclusivity: A module utilizing export = cannot contain any other ES6 exports (named or default). The export assignment claims the entire module namespace.

export = { add: (a: number, b: number) => a + b };
export const PI = 3.14; // Error: An export assignment cannot be used in a module with other exported elements.

2. Declaration Merging: To export multiple entities using export = via identifiers, developers must leverage TypeScript’s declaration merging (e.g., merging a namespace with a class or function) or export a single aggregate object expression.

function Logger(msg: string) {}

namespace Logger {
    export const level = "info";
}

export = Logger; // Exports both the callable function and the attached namespace properties

Master TypeScript with Deep Grasping Methodology!

Learn More