From 113830d3cfa98787db7d690c114c21112791df7d Mon Sep 17 00:00:00 2001
From: robobun <robobun@oven.sh>
Date: Wed, 31 Dec 2025 01:46:37 -0800
Subject: [PATCH] docs: update npmrc.mdx with all supported .npmrc fields
 (#25783)

---
 docs/pm/npmrc.mdx | 134 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 134 insertions(+)

diff --git a/docs/pm/npmrc.mdx b/docs/pm/npmrc.mdx
index bef86d5435..fb42aaafbb 100644
--- a/docs/pm/npmrc.mdx
+++ b/docs/pm/npmrc.mdx
@@ -72,6 +72,7 @@ The following options are supported:
 - `username`
 - `_password` (base64 encoded password)
 - `_auth` (base64 encoded username:password, e.g. `btoa(username + ":" + password)`)
+- `email`
 
 The equivalent `bunfig.toml` option is to add a key in [`install.scopes`](/runtime/bunfig#install-registry):
 
@@ -109,3 +110,136 @@ The equivalent `bunfig.toml` option is [`install.exact`](/runtime/bunfig#install
 [install]
 exact = true
 ```
+
+### `ignore-scripts`: Skip lifecycle scripts
+
+Prevents running lifecycle scripts during installation:
+
+```ini .npmrc icon="npm"
+ignore-scripts=true
+```
+
+This is equivalent to using the `--ignore-scripts` flag with `bun install`.
+
+### `dry-run`: Preview changes without installing
+
+Shows what would be installed without actually installing:
+
+```ini .npmrc icon="npm"
+dry-run=true
+```
+
+The equivalent `bunfig.toml` option is [`install.dryRun`](/runtime/bunfig#install-dryrun):
+
+```toml bunfig.toml icon="settings"
+[install]
+dryRun = true
+```
+
+### `cache`: Configure cache directory
+
+Set the cache directory path, or disable caching:
+
+```ini .npmrc icon="npm"
+# set a custom cache directory
+cache=/path/to/cache
+
+# or disable caching
+cache=false
+```
+
+The equivalent `bunfig.toml` option is [`install.cache`](/runtime/bunfig#install-cache):
+
+```toml bunfig.toml icon="settings"
+[install.cache]
+# set a custom cache directory
+dir = "/path/to/cache"
+
+# or disable caching
+disable = true
+```
+
+### `ca` and `cafile`: Configure CA certificates
+
+Configure custom CA certificates for registry connections:
+
+```ini .npmrc icon="npm"
+# single CA certificate
+ca="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
+
+# multiple CA certificates
+ca[]="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
+ca[]="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
+
+# or specify a path to a CA file
+cafile=/path/to/ca-bundle.crt
+```
+
+### `omit` and `include`: Control dependency types
+
+Control which dependency types are installed:
+
+```ini .npmrc icon="npm"
+# omit dev dependencies
+omit=dev
+
+# omit multiple types
+omit[]=dev
+omit[]=optional
+
+# include specific types (overrides omit)
+include=dev
+```
+
+Valid values: `dev`, `peer`, `optional`
+
+### `install-strategy` and `node-linker`: Installation strategy
+
+Control how packages are installed in `node_modules`. Bun supports two different configuration options for compatibility with different package managers.
+
+**npm's `install-strategy`:**
+
+```ini .npmrc icon="npm"
+# flat node_modules structure (default)
+install-strategy=hoisted
+
+# symlinked structure
+install-strategy=linked
+```
+
+**pnpm/yarn's `node-linker`:**
+
+The `node-linker` option controls the installation mode. Bun supports values from both pnpm and yarn:
+
+| Value          | Description                                     | Accepted by |
+| -------------- | ----------------------------------------------- | ----------- |
+| `isolated`     | Symlinked structure with isolated dependencies  | pnpm        |
+| `hoisted`      | Flat node_modules structure                     | pnpm        |
+| `pnpm`         | Symlinked structure (same as `isolated`)        | yarn        |
+| `node-modules` | Flat node_modules structure (same as `hoisted`) | yarn        |
+
+```ini .npmrc icon="npm"
+# symlinked/isolated mode
+node-linker=isolated
+node-linker=pnpm
+
+# flat/hoisted mode
+node-linker=hoisted
+node-linker=node-modules
+```
+
+### `public-hoist-pattern` and `hoist-pattern`: Control hoisting
+
+Control which packages are hoisted to the root `node_modules`:
+
+```ini .npmrc icon="npm"
+# packages matching this pattern will be hoisted to the root
+public-hoist-pattern=*eslint*
+
+# multiple patterns
+public-hoist-pattern[]=*eslint*
+public-hoist-pattern[]=*prettier*
+
+# control general hoisting behavior
+hoist-pattern=*
+```