Registry / devops / npmrc-replace-env

npmrc-replace-env

library1.2.1jsnpmunverified

npmrc-replace-env is a Node.js utility designed to simplify the management of npm registry configurations and authentication tokens across various projects and environments. It dynamically generates or updates a `.npmrc` file based on a user-defined `.npmrc.config` template and corresponding environment variables, which can be loaded from `.env` files. The current stable version is 1.2.1. The project follows a regular release cadence with frequent patch releases addressing bug fixes and dependency updates, alongside minor releases introducing new features like shell-style variable syntax support. Its primary differentiator is its focus on securely managing sensitive npm configuration details by preventing their exposure in version control, leveraging environment variables for token replacement. It supports both prefix-based (`NPMRC_TOKEN`) and shell-style (`$TOKEN`, `${TOKEN}`) placeholder syntax, offering flexibility for different CI/CD environments, including GitHub Actions. The tool is primarily used via its command-line interface with `npx` and requires Node.js version 24.0.0 or higher for current versions.

devops auth-security

npm install npmrc-replace-env

github ↗package ↗

INSTALL

IMPORT

SIG · NPMRC-REPLACE-ENV

npmrc-replace-env

devopsjavascriptv1.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CLI Execution

✓ npx npmrc-replace-env

This package is primarily a command-line utility. Direct programmatic imports for general usage are not documented or commonly employed. The main interaction pattern is via 'npx'.

NpmrcReplaceEnvOptions

✓ import type { NpmrcReplaceEnvOptions } from 'npmrc-replace-env';

While primarily a CLI tool, it ships TypeScript types. This is a hypothetical type for potential programmatic configuration, though a public programmatic API isn't explicitly documented in the README.

NpmrcReplaceEnvError

✓ import type { NpmrcReplaceEnvError } from 'npmrc-replace-env';

A hypothetical type for custom error classes that might be exposed, as the package ships TypeScript types. Direct error handling through imported types is not common for CLI tools.

Demonstrates how to set up a `.npmrc.config` and `.env` file, then use `npx npmrc-replace-env` to generate a `.npmrc` with environment variables replaced.

mkdir my-project cd my-project # Create a configuration template cat <<EOF > .npmrc.config # .npmrc.config for my-project @myorg:registry=https://private.registry.com/myorg //private.registry.com/myorg/:_authToken=NPMRC_MY_ORG_TOKEN @otherorg:registry=https://another.registry.com/ //another.registry.com/:_authToken=\${OTHER_ORG_TOKEN} EOF # Create an .env file with your tokens (add .npmrc to .gitignore immediately!) cat <<EOF > .env NPMRC_MY_ORG_TOKEN=your_private_token_12345 OTHER_ORG_TOKEN=your_other_token_67890 EOF # Generate the .npmrc file npx npmrc-replace-env # Verify the generated .npmrc cat .npmrc # Expected output in .npmrc: # @myorg:registry=https://private.registry.com/myorg # //private.registry.com/myorg/:_authToken=your_private_token_12345 # # @otherorg:registry=https://another.registry.com/ # //another.registry.com/:_authToken=your_other_token_67890

npx --version

Debug

Known issues

gotchaPlaceholders embedded within URL paths (e.g., `https://example.com/NPMRC_MY_ORG`) were silently skipped due to a regex limitation, leading to incomplete token replacement.

fix

Upgrade to `npmrc-replace-env@1.2.1` or newer to ensure all URL path placeholders are correctly replaced.

affects: <1.2.1

gotchaPrior to version 1.2.0, the utility only recognized prefix-based placeholders (e.g., `NPMRC_TOKEN`). Shell-style syntax (`$TOKEN` or `${TOKEN}`) was not supported, causing such placeholders to be ignored.

fix

Upgrade to `npmrc-replace-env@1.2.0` or newer to utilize shell-style placeholder syntax. For older versions, ensure placeholders use the `NPMRC_` prefix (or a custom prefix) and avoid shell syntax.

affects: <1.2.0

breakingAs of recent versions, `npmrc-replace-env` requires Node.js version 24.0.0 or higher. Running on older Node.js versions will result in an error.

fix

Upgrade your Node.js environment to version 24.0.0 or newer. Check the package's `engines` field in `package.json` for the exact requirement.

affects: >=1.1.5

gotchaIt is critical to add `.npmrc` to your `.gitignore` file immediately after generating it to prevent sensitive authentication tokens or registry configurations from being accidentally committed to version control.

fix

Add `.npmrc` to your project's `.gitignore` file. Never commit `.npmrc` files containing sensitive information.

affects: all

gotchaBy default, the utility expects environment variables used as placeholders to begin with the `NPMRC_` prefix. Variables without this prefix will not be recognized or replaced unless explicit CLI options are used.

fix

Ensure your environment variables are named with the `NPMRC_` prefix (e.g., `NPMRC_MY_TOKEN`) or utilize the `--prefix <YOUR_PREFIX>` or `--no-prefix` command-line options when running the utility.

affects: all

Errors

Common errors & fixes

Error: Node.js v20.x.x is not supported by this package. Please upgrade to Node.js v24.0.0 or higher.

The installed Node.js version does not meet the minimum requirement specified in the package's `engines` field.

fix

Upgrade your Node.js installation to version 24.0.0 or newer.

Placeholder for 'NPMRC_AUTH_TOKEN' in URL path 'https://registry.example.com/NPMRC_AUTH_TOKEN' was not replaced in the generated .npmrc.

A bug in earlier versions of the utility prevented placeholders appearing directly within URL paths from being correctly identified and replaced.

fix

Upgrade to `npmrc-replace-env@1.2.1` or newer to fix the regex for URL path placeholders.

Variable '${MY_TOKEN}' in .npmrc.config was not replaced, appearing as literal string in generated .npmrc.

Shell-style placeholder syntax (`$VAR`, `${VAR}`) was not supported in `npmrc-replace-env` versions prior to 1.2.0.

fix

Upgrade to `npmrc-replace-env@1.2.0` or newer. Alternatively, use the `NPMRC_MY_TOKEN` prefix-based syntax for older versions.

Environment variable 'MY_APP_TOKEN' was not replaced in the generated .npmrc, even though it's defined in .env.

By default, environment variables must start with the `NPMRC_` prefix to be recognized, or the variable might not be correctly loaded (e.g., missing from `.env` or `.env` not present).

fix

Rename your environment variable to `NPMRC_MY_APP_TOKEN` in both `.env` and `.npmrc.config`, or use the `--prefix <YOUR_PREFIX>` or `--no-prefix` command-line options to customize recognition.

Error: .npmrc.config file not found in current directory.

The utility could not locate the `.npmrc.config` template file in the directory where it was executed.

fix

Ensure that a file named `.npmrc.config` exists in the root of your project or the directory from which you are running `npx npmrc-replace-env`.

Upgrade

Version history

1.2.1latest on npm

Audit

Dependencies

yargsrequiredUsed for parsing command-line arguments.

dotenv-flowrequiredUsed for loading environment variables from .env files.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dennzimm/npmrc-replace-env ↗

packagehttps://www.npmjs.com/package/npmrc-replace-env ↗