string-env-interpolation

string-env-interpolation is a tiny, dependency-free TypeScript utility that interpolates environment variables into arbitrary string content. It scans a string for ${NAME}, ${NAME:default}, and ${NAME:"quoted default"} placeholders using a single regular expression, then replaces each one with the matching value from process.env (or a custom variables object passed in explicitly) — falling back to the inline default when the variable is undefined.

The library is intentionally minimal: a single exported env() function with no runtime dependencies, published as both CommonJS and ES module builds with bundled TypeScript declarations. It’s aimed at tools that need to template config files (YAML, JSON, .env-style text, or any other string content) with environment-variable substitution without pulling in a full templating engine.

What You Get

• A single env() function for interpolating environment variables into any string
• Support for bare, single-quoted, and double-quoted default values in placeholders
• An optional custom variables argument to interpolate against any string-keyed object instead of process.env
• Dual CommonJS and ES module builds with bundled TypeScript type declarations
• Zero runtime dependencies

Common Use Cases

• Templating YAML or JSON config files with ${DATABASE_URL}-style placeholders resolved at load time
• Providing environment-specific defaults (e.g. ${NAME:"Development"}) so config works locally without every variable set
• Letting CLI tools and libraries accept user-supplied config files with environment-variable substitution, without depending on a full templating engine
• Interpolating variables from a custom dictionary (not just process.env) for testing or multi-tenant configuration scenarios

Under The Hood

Architecture The entire package is a single exported function, env(), defined in src/index.ts. It takes a string and an optional variables dictionary (defaulting to process.env), applies one regular expression (/\$\{([A-Z0-9_]+(\:[^\}]+)?)\}/gi) via String.replace, and for each match splits the captured group on : to separate the variable name from an optional default, stripping surrounding single or double quotes from the default before returning the substituted string. There are no internal layers, classes, or side effects — it’s a pure, stateless transform, so there is effectively nothing to break beyond the regex itself.

Tech Stack Written in TypeScript (target ES2015, strict-ish tsconfig with noUnusedLocals/noUnusedParameters) with zero runtime dependencies. Built with bob-the-bundler, a build tool from the GraphQL Tools ecosystem, which produces dual dist/index.cjs.js (CommonJS) and dist/index.esm.js (ES module) outputs plus bundled .d.ts declarations from a single yarn build command. Package management is via Yarn (.yarnrc, yarn.lock).

Code Quality No test files or CI configuration exist in the repository — there is no automated verification of the regex’s edge cases (e.g. nested braces, malformed placeholders). The single source file is short, uses descriptive naming, and TypeScript’s strict unused-locals/params checks catch some classes of bugs, but overall test coverage is absent and should be treated as a gap by any consumer relying on this for correctness-sensitive templating.

What Makes It Unique The package doesn’t introduce a novel templating approach — ${VAR:default} shell-style interpolation with quoted defaults is a well-established pattern found in many config tools. Its value is in doing exactly this one thing as a minimal, dependency-free utility rather than pulling in a general-purpose templating engine, which suits projects that want just variable substitution without extra surface area.