Envify: Environment Variable Replacement

Common errors

• ReferenceError: process is not defined

  cause The `process` object is a Node.js global. In a browser environment without `envify` replacing `process.env` references, Browserify includes a shim for `process` by default. If `envify` hasn't fully replaced all `process.env` references and the `purge` option isn't used, or if `process` is accessed directly for non-environment variables, this error can occur.
  fix Ensure `envify` is correctly applied as a Browserify transform. Use the `purge` option (e.g., `-t [ envify purge --NODE_ENV production ]` or `{ _: 'purge' }` in the API) to replace any remaining `process.env.VAR` references with `undefined`. Avoid direct references to `process` in browser code unless specifically polyfilled.

• Error: Cannot find module 'envify'

  cause The `envify` package is not installed or not discoverable in your project's `node_modules`.
  fix Run `npm install envify` or `yarn add envify` in your project directory. If using it globally via CLI, run `npm install -g envify`.

Warnings

• breaking Older versions of Browserify might not support the subarg syntax for passing custom environment variables or the `purge` option directly via the CLI. Ensure Browserify is at least v3.25.0 for full CLI feature support.
  Fix: Upgrade Browserify to version 3.25.0 or higher, or use the module API for programmatic control over environment variables and purging.
• gotcha By default, `envify` only replaces environment variables that are explicitly defined in the `process.env` object or passed to `envify/custom`. Undefined variables are left as `process.env.VAR_NAME`, potentially causing Browserify to include its ~2KB `process` shim in the bundle.
  Fix: To prevent the `process` shim from being included for undefined variables, use the `purge` option by passing `_:'purge'` to the module API or `envify purge` to the CLI command (e.g., `browserify -t [ envify purge --NODE_ENV production ]`).
• gotcha Environment variables are replaced with their *string* values. Comparisons like `process.env.VAR === 1` will become `'value' === 1`, which evaluates differently than `undefined === 1`. Always ensure your comparisons match the string replacement behavior.
  Fix: Use string comparisons (e.g., `process.env.VAR === 'true'`) or parse the environment variable string to the desired type (e.g., `parseInt(process.env.VAR, 10)`) before comparison, ensuring consistency with the expected string literal replacement.
• gotcha Envify only processes `process.env.VAR_NAME` syntax. If you are accessing environment variables in other ways (e.g., `process.env['VAR_NAME']` or `const env = process.env; env.VAR_NAME`), these patterns might not be transformed, leading to unexpected behavior or larger bundle sizes.
  Fix: Consistently use the `process.env.VAR_NAME` dot notation for all environment variable accesses that you intend `envify` to transform. For more complex access patterns, consider pre-processing your code or ensuring `envify` is the last transform before minification to catch any remaining `process.env` references for purging.

Install

• npm install envify npm
• yarn add envify yarn
• pnpm add envify pnpm

Imports

• envify
  wrong:

  const envify = require('envify');

  correct:

  import envify from 'envify';

  While Browserify itself supports CJS, `envify`'s module usage (when passed as a transform) is often done via `require`. For direct module imports in modern JS, `import` is preferred, though direct programmatic usage with Browserify typically involves `require` for transforms. The `envify` package itself exports a default function for the transform stream.
• customEnvify
  wrong:

  const customEnvify = require('envify').custom;

  correct:

  import customEnvify from 'envify/custom';

  To provide a custom environment object instead of relying on `process.env`, import from the `envify/custom` submodule. This is a named export from the perspective of modern module systems, but a direct path in CJS.
• EnvifyTransform
  wrong:

  b.transform('envify');

  correct:

  b.transform(envify());

  When using `envify` programmatically with Browserify, you usually call `envify()` (or `envify/custom(opts)`) to get the transform function/stream, rather than passing the string name 'envify'.

Quickstart

This quickstart demonstrates how to use `envify` programmatically with Browserify to replace environment variables. It shows both a production build (where `NODE_ENV` is 'production' and a feature flag is 'disabled', leading to dead-code elimination) and a development build (where specific code paths are retained).

import browserify from 'browserify';
import envify from 'envify';
import fs from 'node:fs';
import path from 'node:path';

const mainJsContent = `
if (process.env.NODE_ENV === "development") {
  console.log('development only debug log');
}

if (process.env.FEATURE_FLAG === "enabled") {
  console.log('Feature A is enabled!');
}

console.log('This always runs.');
`;

const outputDir = path.join(process.cwd(), 'temp_build');
if (!fs.existsSync(outputDir)) {
  fs.mkdirSync(outputDir);
}
const mainJsPath = path.join(outputDir, 'main.js');
fs.writeFileSync(mainJsPath, mainJsContent);

// Bundle for production
const b = browserify(mainJsPath);
b.transform(envify({ 
  NODE_ENV: 'production',
  FEATURE_FLAG: 'disabled',
  _: 'purge' // Purge undefined process.env references
}));

const productionBundlePath = path.join(outputDir, 'bundle.production.js');
b.bundle().pipe(fs.createWriteStream(productionBundlePath))
  .on('finish', () => {
    console.log(`Production bundle created at: ${productionBundlePath}`);
    console.log('Content (simplified):');
    console.log(fs.readFileSync(productionBundlePath, 'utf8').substring(0, 200) + '...');
    // Expected: console.log('This always runs.'); without development/feature logs
  });

// Example of development bundle (for demonstration, showing code NOT removed)
const bDev = browserify(mainJsPath);
bDev.transform(envify({ 
  NODE_ENV: 'development',
  FEATURE_FLAG: 'enabled'
}));

const developmentBundlePath = path.join(outputDir, 'bundle.development.js');
bDev.bundle().pipe(fs.createWriteStream(developmentBundlePath))
  .on('finish', () => {
    console.log(`\nDevelopment bundle created at: ${developmentBundlePath}`);
    console.log('Content (simplified):');
    console.log(fs.readFileSync(developmentBundlePath, 'utf8').substring(0, 200) + '...');
    // Expected: both console.logs visible
  });