(lambda-nodejs): nodeModules with pnpm doesn't inherit project .npmrc for private registry authentication

[sebastianplesciuc]

Describe the bug

When using nodeModules with pnpm, CDK creates a pnpm-workspace.yaml in the bundling temp directory (added in #21911 to fix #21910). This causes pnpm to treat the bundling directory as a standalone workspace root, which prevents it from inheriting .npmrc configuration from parent directories. This breaks authentication for packages from private registries (e.g., AWS CodeArtifact).

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Library Version

No response

Expected Behavior

When nodeModules is specified, pnpm install in the bundling directory should be able to authenticate with private registries configured in the project's .npmrc.

Current Behavior

pnpm install fails with 401 Unauthorized errors when trying to fetch packages (or their dependencies) from private registries, because the bundling directory's pnpm-workspace.yaml prevents pnpm from finding the project's .npmrc with auth tokens.

Reproduction Steps

1. Create a pnpm monorepo with a private registry configured in .npmrc:

@myorg:registry=https://my-private-registry.example.com/npm/
//my-private-registry.example.com/npm/:_authToken=<token>

2. Add a NodejsFunction with nodeModules referencing a package from the private registry:

new NodejsFunction(this, 'MyFunction', {
  entry: 'src/handler.ts',
  bundling: {
    nodeModules: ['@myorg/my-private-package'],
  },
});

3. Run cdk synth

4. Observe 401 errors during bundling because pnpm can't find the auth token

Possible Solution

• Copy the project's .npmrc to the bundling directory alongside pnpm-workspace.yaml
• Or document this limitation and the workaround (use global ~/.npmrc or commandHooks.beforeInstall to copy .npmrc)

Additional Information/Context

Related: #21910, #21911

Workarounds:

• Store auth tokens in global ~/.npmrc instead of project .npmrc
• Use commandHooks.beforeInstall to copy .npmrc to the bundling directory

AWS CDK Library version (aws-cdk-lib)

2.194.0

AWS CDK CLI version

2.1015.0

Node.js Version

24

OS

MacOS 15.7.3 (24G419)

Language

TypeScript

Language Version

No response

Other information

No response

[pahud]

Hi @sebastianplesciuc,

Let me try to figure out current vs expected behavior using ASCII. Please let me know if it was wrong.

┌─────────────────────────────────────────────────────────────────────────────────┐
│                          CURRENT BEHAVIOR (Problem)                             │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   /project/                                                                     │
│   ├── .npmrc  ◄── Contains auth tokens for private registry                     │
│   ├── pnpm-workspace.yaml                                                       │
│   └── packages/                                                                 │
│       └── my-app/                                                               │
│                                                                                 │
│                          ▼ cdk synth                                            │
│                                                                                 │
│   /tmp/cdk-bundling-xxxxx/                                                      │
│   ├── pnpm-workspace.yaml  ◄── CDK creates this (empty)                         │
│   ├── package.json                                                              │
│   └── pnpm-lock.yaml                                                            │
│                                                                                 │
│                          ▼ pnpm install                                         │
│                                                                                 │
│   pnpm sees pnpm-workspace.yaml                                                 │
│        │                                                                        │
│        ▼                                                                        │
│   Treats /tmp/cdk-bundling-xxxxx/ as workspace root                             │
│        │                                                                        │
│        ▼                                                                        │
│   STOPS searching parent directories for .npmrc                                 │
│        │                                                                        │
│        ▼                                                                        │
│   ❌ 401 Unauthorized - No auth token found                                     │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────────┐
│                          EXPECTED BEHAVIOR (Fix)                                │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   /project/                                                                     │
│   ├── .npmrc  ◄── Contains auth tokens for private registry                     │
│   ├── pnpm-workspace.yaml                                                       │
│   └── packages/                                                                 │
│       └── my-app/                                                               │
│                                                                                 │
│                          ▼ cdk synth                                            │
│                                                                                 │
│   /tmp/cdk-bundling-xxxxx/                                                      │
│   ├── pnpm-workspace.yaml  ◄── CDK creates this (empty)                         │
│   ├── .npmrc               ◄── CDK ALSO copies this from project                │
│   ├── package.json                                                              │
│   └── pnpm-lock.yaml                                                            │
│                                                                                 │
│                          ▼ pnpm install                                         │
│                                                                                 │
│   pnpm sees pnpm-workspace.yaml                                                 │
│        │                                                                        │
│        ▼                                                                        │
│   Treats /tmp/cdk-bundling-xxxxx/ as workspace root                             │
│        │                                                                        │
│        ▼                                                                        │
│   Finds .npmrc IN the bundling directory                                        │
│        │                                                                        │
│        ▼                                                                        │
│   ✅ Authentication succeeds - packages installed                               │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

The root cause is in the createBundlingCommand method in bundling.ts.

When pnpm is detected and nodeModules is specified, the code creates an empty pnpm-workspace.yaml file:

// From bundling.js (compiled from bundling.ts)
const isPnpm = this.packageManager.lockFile === package_manager_1().LockFile.PNPM;

depsCommand = chain([
  // Creates empty pnpm-workspace.yaml - THIS IS THE PROBLEM
  isPnpm ? osCommand.write(pathJoin(options.outputDir, "pnpm-workspace.yaml"), "") : "",
  osCommand.writeJson(pathJoin(options.outputDir, "package.json"), { dependencies }),
  osCommand.copy(lockFilePath, pathJoin(options.outputDir, this.packageManager.lockFile)),
  osCommand.changeDirectory(options.outputDir),
  this.packageManager.installCommand.join(" "),
  isPnpm ? osCommand.remove(pathJoin(options.outputDir, "node_modules", ".modules.yaml"), true) : "",
  // ...
]);

Why This Happens

1. PR fix(lambda-nodejs): unable to use nodeModules with pnpm #21911 Context: The pnpm-workspace.yaml was added to fix issue (lambda-nodejs): Unable to use nodeModules with pnpm #21910 where pnpm workspaces would install modules in the parent workspace's node_modules instead of the bundling directory.

2. pnpm Behavior: When pnpm finds a pnpm-workspace.yaml, it treats that directory as the workspace root and:

   • Installs dependencies locally (desired behavior from fix(lambda-nodejs): unable to use nodeModules with pnpm #21911)
   • Stops searching parent directories for .npmrc (unintended side effect)

3. Result: Private registry authentication tokens stored in the project's .npmrc are not found, causing 401 Unauthorized errors.

Code Flow

NodejsFunction with nodeModules + pnpm
    │
    ▼
createBundlingCommand()
    │
    ▼
isPnpm detected from pnpm-lock.yaml
    │
    ▼
osCommand.write("pnpm-workspace.yaml", "")  ← Creates workspace root
    │
    ▼
pnpm install runs
    │
    ▼
pnpm sees pnpm-workspace.yaml
    │
    ▼
Treats bundling dir as workspace root
    │
    ▼
Does NOT inherit parent .npmrc
    │
    ▼
401 Unauthorized for private packages

Possible Fixes/Solutions

Option 1: Copy .npmrc to Bundling Directory (Recommended)

When creating pnpm-workspace.yaml, also copy the project's .npmrc (if it exists) to the bundling directory. This maintains the workspace isolation fix while preserving registry authentication.

Pros:

• Maintains the fix from PR fix(lambda-nodejs): unable to use nodeModules with pnpm #21911
• Preserves private registry authentication
• Minimal code change

Cons:

• Need to find and copy .npmrc from project root
• May need to handle multiple .npmrc locations

Option 2: Add npmrc Bundling Option

Add a new bundling option to explicitly specify the .npmrc path to copy:

new NodejsFunction(this, 'MyFunction', {
  bundling: {
    nodeModules: ['@myorg/my-private-package'],
    npmrc: '.npmrc', // New option
  },
});

Pros:

• Explicit control for users
• No magic behavior

Cons:

• Requires user action
• Breaking change for existing users

Option 3: Document Workaround

Document the limitation and existing workarounds:

• Use global ~/.npmrc instead of project .npmrc
• Use commandHooks.beforeInstall to copy .npmrc

Pros:

• No code changes needed

Cons:

• Poor user experience
• Workarounds are not intuitive

From my perspective, Option 1 is recommended as it fixes the issue transparently, maintains backward compatibility, preserves the original fix from PR #21911 and follows the principle of least surprise :)

Feel free to submit PRs and we'd love to move this forward.