npmrc-replace-env

1.2.1 · active · verified Sun Apr 19

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.

Common errors

```
Error: Node.js v20.x.x is not supported by this package. Please upgrade to Node.js v24.0.0 or higher.
```
cause 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.
```
cause 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.
```
cause 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.
```
cause 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.
```
cause 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`.

Warnings

gotcha Placeholders 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.
gotcha Prior 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.
breaking As 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.
gotcha It 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.
gotcha By 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.

Install

npm install npmrc-replace-env npm
yarn add npmrc-replace-env yarn
pnpm add npmrc-replace-env pnpm

Imports

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.

Quickstart

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

view raw JSON →