Resolving TypeORM Entity Import Error in NestJS: Cannot use import statement outside a module

Problem Background and Error Analysis

When integrating TypeORM into the NestJS framework, developers often encounter a typical error: SyntaxError: Cannot use import statement outside a module. This error usually occurs during project startup when attempting to load TypeORM entity files. The error message clearly indicates that the issue lies in the import statement being executed in a non-module environment, pointing directly to compatibility problems between TypeScript and JavaScript module systems.

From a technical perspective, the root cause of this error is that TypeORM incorrectly tries to treat TypeScript source files (.ts) as JavaScript modules when loading entities. In the Node.js environment, import statements are standard syntax for ES6 modules, but require files to be explicitly recognized as modules. When TypeORM configuration uses relative path patterns (e.g., src/**/*.entity.{ts,js}), it may resolve to TypeScript source files at runtime, and Node.js does not natively support executing TypeScript import statements unless processed by tools like ts-node.

Core Solution: Correct Entity Path Configuration

The key to resolving this issue is ensuring that TypeORM loads compiled JavaScript files, not TypeScript source files. Here are several effective configuration methods:

First, if configuring via TypeOrmModule.forRoot() in code, it is recommended to use absolute paths to explicitly specify entity file locations. Using Node.js's path module and the __dirname variable allows dynamic construction of the correct path:

import { join } from 'path';
import { TypeOrmModule } from '@nestjs/typeorm';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      entities: [join(__dirname, '**', '*.entity.{ts,js}')]
    })
  ]
})
export class AppModule {}

This approach benefits from __dirname automatically resolving based on the current execution environment (the src directory during development or dist in production), ensuring the correct files are loaded. In development, it might find .ts files, but these are properly handled through NestJS's build process; in production, it directly loads .js files.

Second, if using an ormconfig.json file for configuration, directly specify the path to compiled JavaScript files:

{
  "entities": ["dist/**/*.entity.js"]
}

This completely avoids loading TypeScript source files, ensuring all entities are compiled JavaScript modules. This method is straightforward but requires that the build command (e.g., npm run build) has been executed before running.

Advanced Configuration Option: autoLoadEntities

For more simplified configuration, TypeORM and NestJS provide the autoLoadEntities option. When set to true, TypeORM automatically scans and loads all entities registered via TypeOrmModule.forFeature(), eliminating the need for manual path specification:

TypeOrmModule.forRoot({
  autoLoadEntities: true
})

This option is particularly suitable for large projects, as it reduces configuration complexity and prevents path errors. It dynamically registers entities through NestJS's dependency injection system, ensuring only actually used modules are loaded, which improves performance.

Supplementary Solutions and Considerations

Referencing other answers, if the project involves TypeORM CLI operations (e.g., generating migrations), it may be necessary to install ts-node globally and configure scripts in package.json:

"scripts": {
  "typeorm": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js"
}

This ensures CLI commands properly handle TypeScript files. Note, however, that this primarily affects command-line tools, not runtime errors.

In practical development, it is advisable to choose a configuration method based on project needs. For new projects, using autoLoadEntities is best practice; for existing projects, gradually migrating to absolute or compiled paths can avoid disruptions. Always ensure consistency between testing and production environment configurations to prevent unexpected errors during deployment.