dotenv-esbuild

1.1.0 verified Fri May 01 auth: no javascript

A simple esbuild plugin that integrates dotenv to load environment variables during the build process. Version 1.1.0, released as a stable package with TypeScript type definitions. It replaces traditional dotenv usage by injecting variables at build time, ensuring consistency across environments. The plugin supports custom .env file paths and is designed for projects using esbuild. It has minimal configuration and is actively maintained.

Common errors

error TypeError: Dotenv is not a constructor ↓

cause Using an older import pattern or not using `new` with the default export.

fix

Use import Dotenv from 'dotenv-esbuild' and then new Dotenv().

error Error: [plugin: dotenv-esbuild] Cannot find module 'dotenv' ↓

cause The package expects dotenv to be installed or bundled incorrectly.

fix

Install dotenv as a dependency: npm install dotenv.

error Module not found: Error: Can't resolve 'dotenv-esbuild' ↓

cause Package not installed or npm/node_modules not found.

fix

Run npm install dotenv-esbuild --save-dev and ensure it's in node_modules.

Warnings

breaking v1.0.0 changed from default export being an object to a class constructor ↓

fix Use `new Dotenv()` or `{ Dotenv }` named import.

deprecated Option `systemvars` was removed in v1.0.0 ↓

fix Access process.env directly in code instead.

gotcha Plugin only works with esbuild's `build` and `buildSync` API, not `transform` ↓

fix Ensure you use the build API, not transform.

gotcha Environment variables are injected at build time; runtime changes to .env will be ignored ↓

fix Rebuild project to pick up new env values.

Install

npm install dotenv-esbuild

yarn add dotenv-esbuild

pnpm add dotenv-esbuild

Imports

Dotenv
wrong
```
const Dotenv = require('dotenv-esbuild')
```
correct
```
import Dotenv from 'dotenv-esbuild'
```
ESM-only package, default export is a class constructor. CommonJS require will fail.
Dotenv
wrong
```
import Dotenv from 'dotenv-esbuild'
```
correct
```
import { Dotenv } from 'dotenv-esbuild'
```
Named export is available since v1.0.0, but default export is the same class. Both work.

DotenvPluginOptions

wrong

import { DotenvPluginOptions } from 'dotenv-esbuild'

correct

import type { DotenvPluginOptions } from 'dotenv-esbuild'

Type import only, cannot be used at runtime.

Quickstart

Shows minimal configuration to use dotenv-esbuild plugin with esbuild.

import esbuild from 'esbuild';
import Dotenv from 'dotenv-esbuild';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    new Dotenv({
      path: './.env',
    }),
  ],
});

console.log('Build complete with environment variables injected.');