feat(): support loading multiple env files

lib/config.module.ts

@@ -150,22 +150,22 @@ export class ConfigModule {
   private static loadEnvFile(
     options: ConfigModuleOptions,
   ): Record<string, any> {
-    try {
-      const envFilePath = options.envFilePath || resolve(process.cwd(), '.env');
-      const config = dotenv.parse(fs.readFileSync(envFilePath));
-      if (options.expandVariables) {
-        const configExpandedVars = {
-          parsed: config,
-        };
-        return dotenvExpand(configExpandedVars).parsed || {};
-      }
-      return config;
-    } catch (err) {
-      if (options.envFilePath || (err && err.code !== 'ENOENT')) {
-        throw err;
+    const envFilePaths = Array.isArray(options.envFilePath)
+      ? options.envFilePath
+      : [options.envFilePath || resolve(process.cwd(), '.env')];
+    let config: ReturnType<typeof dotenv.parse> = {};
+    for (const envFilePath of envFilePaths) {
+      if (fs.existsSync(envFilePath)) {
+        config = Object.assign(
+          dotenv.parse(fs.readFileSync(envFilePath)),
+          config,
+        );
+        if (options.expandVariables) {
+          config = dotenvExpand({ parsed: config }).parsed || config;
+        }
       }
-      return {};
     }
+    return config;
   }
 
   private static assignVariablesToProcess(config: Record<string, any>) {

lib/interfaces/config-module-options.interface.ts

@@ -18,9 +18,9 @@ export interface ConfigModuleOptions {
   ignoreEnvVars?: boolean;
 
   /**
-   * Path to the environment file to be loaded.
+   * Path to the environment file(s) to be loaded.
    */
-  envFilePath?: string;
+  envFilePath?: string | string[];
 
   /**
    * Environment file encoding.

tests/e2e/load-multiple-env.spec.ts

@@ -0,0 +1,26 @@
+import { INestApplication } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import { AppModule } from '../src/app.module';
+
+describe('Environment variables (multiple env files)', () => {
+  let app: INestApplication;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      imports: [AppModule.withMultipleEnvFiles()],
+    }).compile();
+
+    app = module.createNestApplication();
+    await app.init();
+  });
+
+  it(`should return loaded env variables`, () => {
+    const envVars = app.get(AppModule).getEnvVariables();
+    expect(envVars.PORT).toEqual('3000');
+    expect(envVars.TIMEOUT).toEqual('5000');
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+});

tests/src/.env

@@ -1 +1,2 @@
-PORT=4000
+PORT=4000
+TIMEOUT=5000

tests/src/.env.local

@@ -0,0 +1 @@
+PORT=3000

tests/src/app.module.ts

@@ -39,6 +39,17 @@ export class AppModule {
     };
   }
 
+  static withMultipleEnvFiles(): DynamicModule {
+    return {
+      module: AppModule,
+      imports: [
+        ConfigModule.forRoot({
+          envFilePath: [join(__dirname, '.env.local'), join(__dirname, '.env')],
+        }),
+      ],
+    };
+  }
+
   static withLoadedConfigurations(): DynamicModule {
     return {
       module: AppModule,