{"id":11468,"library":"npmrc-replace-env","title":"npmrc-replace-env","description":"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.","status":"active","version":"1.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/dennzimm/npmrc-replace-env","tags":["javascript","npmrc","npmrc-generator","config-template","configuration","config","generator","environment-variables","env","typescript"],"install":[{"cmd":"npm install npmrc-replace-env","lang":"bash","label":"npm"},{"cmd":"yarn add npmrc-replace-env","lang":"bash","label":"yarn"},{"cmd":"pnpm add npmrc-replace-env","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for parsing command-line arguments.","package":"yargs","optional":false},{"reason":"Used for loading environment variables from .env files.","package":"dotenv-flow","optional":false}],"imports":[{"note":"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'.","symbol":"CLI Execution","correct":"npx npmrc-replace-env"},{"note":"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.","symbol":"NpmrcReplaceEnvOptions","correct":"import type { NpmrcReplaceEnvOptions } from 'npmrc-replace-env';"},{"note":"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.","symbol":"NpmrcReplaceEnvError","correct":"import type { NpmrcReplaceEnvError } from 'npmrc-replace-env';"}],"quickstart":{"code":"mkdir my-project\ncd my-project\n\n# Create a configuration template\ncat <<EOF > .npmrc.config\n# .npmrc.config for my-project\n@myorg:registry=https://private.registry.com/myorg\n//private.registry.com/myorg/:_authToken=NPMRC_MY_ORG_TOKEN\n\n@otherorg:registry=https://another.registry.com/\n//another.registry.com/:_authToken=\\${OTHER_ORG_TOKEN}\nEOF\n\n# Create an .env file with your tokens (add .npmrc to .gitignore immediately!)\ncat <<EOF > .env\nNPMRC_MY_ORG_TOKEN=your_private_token_12345\nOTHER_ORG_TOKEN=your_other_token_67890\nEOF\n\n# Generate the .npmrc file\nnpx npmrc-replace-env\n\n# Verify the generated .npmrc\ncat .npmrc\n\n# Expected output in .npmrc:\n# @myorg:registry=https://private.registry.com/myorg\n# //private.registry.com/myorg/:_authToken=your_private_token_12345\n#\n# @otherorg:registry=https://another.registry.com/\n# //another.registry.com/:_authToken=your_other_token_67890\n","lang":"bash","description":"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."},"warnings":[{"fix":"Upgrade to `npmrc-replace-env@1.2.1` or newer to ensure all URL path placeholders are correctly replaced.","message":"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.","severity":"gotcha","affected_versions":"<1.2.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.2.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.1.5"},{"fix":"Add `.npmrc` to your project's `.gitignore` file. Never commit `.npmrc` files containing sensitive information.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js installation to version 24.0.0 or newer.","cause":"The installed Node.js version does not meet the minimum requirement specified in the package's `engines` field.","error":"Error: Node.js v20.x.x is not supported by this package. Please upgrade to Node.js v24.0.0 or higher."},{"fix":"Upgrade to `npmrc-replace-env@1.2.1` or newer to fix the regex for URL path placeholders.","cause":"A bug in earlier versions of the utility prevented placeholders appearing directly within URL paths from being correctly identified and replaced.","error":"Placeholder for 'NPMRC_AUTH_TOKEN' in URL path 'https://registry.example.com/NPMRC_AUTH_TOKEN' was not replaced in the generated .npmrc."},{"fix":"Upgrade to `npmrc-replace-env@1.2.0` or newer. Alternatively, use the `NPMRC_MY_TOKEN` prefix-based syntax for older versions.","cause":"Shell-style placeholder syntax (`$VAR`, `${VAR}`) was not supported in `npmrc-replace-env` versions prior to 1.2.0.","error":"Variable '${MY_TOKEN}' in .npmrc.config was not replaced, appearing as literal string in generated .npmrc."},{"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.","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).","error":"Environment variable 'MY_APP_TOKEN' was not replaced in the generated .npmrc, even though it's defined in .env."},{"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`.","cause":"The utility could not locate the `.npmrc.config` template file in the directory where it was executed.","error":"Error: .npmrc.config file not found in current directory."}],"ecosystem":"npm"}