✨ Unlock the potential of dotenv (#44)

* ✨ Unlock the potential of dotenv

* ✅ Test without NODE_ENV

* 📝 Change wording for path

Author: NatoBoram

.env

@@ -30,3 +30,5 @@ EXAMPLE_NO_UUID=
 EXAMPLE_DATE=2025-05-28T00:50:58.816Z
 EXAMPLE_INVALID_DATE=EXAMPLE_INVALID_DATE
 EXAMPLE_NO_DATE=
+
+ENV_FILE=cwd

.env.development

@@ -0,0 +1 @@
+ENV_FILE=development

.github/dependabot.yaml

@@ -22,6 +22,7 @@ updates:
       eslint:
         patterns:
           - "*eslint*"
+          - jiti
       prettier:
         patterns:
           - "*prettier*"

src/env.test.ts

@@ -19,7 +19,7 @@ import {
 } from "./env.ts"
 import { loadEnv } from "./load_env.ts"
 
-beforeAll(loadEnv)
+beforeAll(() => loadEnv())
 
 describe("envBool", () => {
 	test("valid", ({ expect }) => {

src/load_env.test.ts

@@ -0,0 +1,37 @@
+import { afterEach, describe, test } from "vitest"
+import { envString } from "./env.ts"
+import { loadEnv } from "./load_env.ts"
+
+describe("loadEnv", () => {
+	test("cwd", ({ expect }) => {
+		loadEnv()
+
+		const ENV_FILE = envString("ENV_FILE")
+		expect(ENV_FILE).toBe("cwd")
+	})
+
+	test("path", ({ expect }) => {
+		loadEnv({ path: "test" })
+
+		const ENV_FILE = envString("ENV_FILE")
+		expect(ENV_FILE).toBe("test")
+	})
+
+	test("development", ({ expect }) => {
+		delete process.env["NODE_ENV"]
+		loadEnv()
+
+		const ENV_FILE = envString("ENV_FILE")
+		expect(ENV_FILE).toBe("development")
+	})
+})
+
+afterEach(() => {
+	for (const key of Object.keys(process.env)) {
+		// eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+		if (key.startsWith("EXAMPLE_")) delete process.env[key]
+	}
+
+	delete process.env["ENV_FILE"]
+	process.env["NODE_ENV"] = "test"
+})

src/load_env.ts

@@ -1,9 +1,10 @@
+import type { DotenvConfigOptions } from "dotenv"
 import { config } from "dotenv"
 import { join } from "path"
 import type { LoadedEnv } from "./loaded_env.ts"
 
-/** Loads environment variables from the `.env` files. `NODE_ENV` has to be
- * set in the environment and will not be picked up from the filesystem.
+/** Loads environment variables from the `.env` files. `NODE_ENV` has to be set
+ * in the environment and will not be picked up from the filesystem.
  *
  * If `NODE_ENV` is not set, it defaults to `development`.
  *
@@ -13,19 +14,21 @@ import type { LoadedEnv } from "./loaded_env.ts"
  * 2. `.env.${NODE_ENV}`
  * 3. `.env.local`
  * 4. `.env`
+ *
+ * @param options Additional options to be passed to `dotenv.config` where
+ * `path` is where to find `.env` files.
  */
-export function loadEnv(): LoadedEnv {
-	const cwd = process.cwd()
+export function loadEnv(options?: LoadEnvOptions): LoadedEnv {
 	const NODE_ENV = process.env["NODE_ENV"]?.trim() || "development"
 
-	const { parsed, error } = config({
-		path: [
-			join(cwd, `.env.${NODE_ENV}.local`),
-			join(cwd, `.env.${NODE_ENV}`),
-			join(cwd, ".env.local"),
-			join(cwd, ".env"),
-		],
-	})
+	const paths = [
+		`.env.${NODE_ENV}.local`,
+		`.env.${NODE_ENV}`,
+		".env.local",
+		".env",
+	].map(file => prepend(file, options?.path))
+
+	const { parsed, error } = config({ ...options, path: paths })
 
 	if (!parsed)
 		throw new Error("Environment variables could not be loaded.", {
@@ -36,3 +39,12 @@ export function loadEnv(): LoadedEnv {
 	process.env = merged
 	return merged
 }
+
+function prepend(file: string, path: string | undefined): string {
+	return path ? join(path, file) : file
+}
+
+export interface LoadEnvOptions extends Omit<DotenvConfigOptions, "path"> {
+	/** Where to find `.env` files. */
+	readonly path?: string | undefined
+}

test/.env

@@ -0,0 +1 @@
+ENV_FILE=test

vitest.config.ts

@@ -3,7 +3,6 @@ import { defineConfig } from "vitest/config"
 
 const config: ViteUserConfig = defineConfig({
 	test: {
-		reporters: ["default", "github-actions"],
 		include: ["src/**/*.test.ts"],
 		coverage: {
 			include: ["src/**/*.ts"],