Analysis and Solutions for TypeScript ES6 Module Import Errors

Problem Background and Error Analysis

When using TypeScript 1.6 with ES6 module syntax, developers frequently encounter the Error TS2306: File 'test.ts' is not a module error message. The root cause of this error lies in the differences between TypeScript's module handling and ES6 specifications.

According to ECMAScript 6 module specifications, each file is an independent module, and modules expose interfaces to the outside through the export keyword. In the original problematic code, the test.ts file used TypeScript's module syntax to define namespaces, which does not comply with ES6 module export requirements.

ES6 Module Specification Analysis

The ES6 module system adopts a strict single-file-single-module design principle. Module exports mainly come in two forms: multiple named exports and single default exports. Multiple named exports allow a module to export multiple entities simultaneously:

// Multiple named exports example
export const sqrt = Math.sqrt;
export function square(x: number): number {
  return x * x;
}
export function diag(x: number, y: number): number {
  return sqrt(square(x) + square(y));
}

Single default exports are specifically designed for exporting the main functionality of a module:

// Single default export example
export default function myFunction(): void {
  // Function implementation
}

Solution One: Using the export Keyword

The most direct solution is to use the export keyword in test.ts. The modified code example is as follows:

// test.ts - Using export for ES6 modules
export module App {
  export class SomeClass {
    getName(): string {
      return 'name';
    }
  }
  export class OtherClass {
    getName(): string {
      return 'name';
    }
  }
}

After this modification, the module can be imported in three ways:

// Method 1: Namespace import
import * as app1 from "./test";

// Method 2: CommonJS style import
import app2 = require("./test");

// Method 3: Destructuring import
import {App} from "./test";

Usage examples:

// Using namespace import
var a1: app1.App.SomeClass = new app1.App.SomeClass();
var a2: app1.App.OtherClass = new app1.App.OtherClass();

// Using CommonJS style import
var b1: app2.App.SomeClass = new app2.App.SomeClass();
var b2: app2.App.OtherClass = new app2.App.OtherClass();

// Using destructuring import
var c1: App.SomeClass = new App.SomeClass();
var c2: App.OtherClass = new App.OtherClass();

// Calling methods
console.log(a1.getName());
console.log(a2.getName());
console.log(b1.getName());
console.log(b2.getName());
console.log(c1.getName());
console.log(c2.getName());

Solution Two: Simplifying Module Structure

In actual development, it is strongly recommended to avoid using namespaces in external modules. TypeScript official documentation explicitly states: Do not use namespaces in external modules. This design pattern adds unnecessary complexity.

Recommended simplified solution:

// test.ts - Simplified version
export class SomeClass {
  getName(): string {
    return 'name';
  }
}

export class OtherClass {
  getName(): string {
    return 'name';
  }
}

Corresponding import method:

import { SomeClass, OtherClass } from './test';

var sc: SomeClass = new SomeClass();
var oc: OtherClass = new OtherClass();

console.log(sc.getName());
console.log(oc.getName());

export = Syntax Detailed Explanation

When a module only needs to export one main entity, the export = syntax can be used. This syntax is particularly suitable for exporting single classes, interfaces, or functions:

// Using export = syntax
class SomeClass {
  getName(): string {
    return 'name';
  }
}

export = SomeClass;

Import method:

import SomeClass = require('./test');

var sc: SomeClass = new SomeClass();
sc.getName();

Advanced Module Loading Scenarios

TypeScript supports conditional module loading, which is very useful when performance optimization or dynamic loading is required. The compiler automatically detects module usage and only generates require calls for actually used modules.

Conditional loading example:

// Type declaration import
import SomeModule = require('./some-module');

// Conditional loading
if (condition) {
  // Dynamic module loading
  const loadedModule: typeof SomeModule = require('./some-module');
  const instance = new loadedModule();
}

Related Tool Integration Considerations

In actual project development, the module system needs to integrate well with build tools. The problems mentioned in the reference article demonstrate module initialization issues that may occur when using third-party libraries like recast-detour.

Correct third-party library usage pattern:

// Correct module initialization
import * as Recast from "recast-detour";

// Asynchronous initialization
async function initializeModule() {
  const recast = await Recast();
  // Using the initialized module
}

This pattern ensures that modules are used only after proper initialization, avoiding runtime errors.

Best Practices Summary

Based on the above analysis, summarize the best practices for TypeScript ES6 module usage:

1. Always use the export keyword to explicitly export module interfaces
2. Avoid using namespaces in external modules
3. Choose appropriate export methods based on module functionality (multiple named exports or single default export)
4. Use export = syntax to simplify single entity exports
5. Reasonably utilize conditional module loading for performance optimization
6. Ensure proper initialization and usage of third-party libraries

By following these best practices, developers can effectively avoid File is not a module errors and build well-structured, maintainable TypeScript applications.