Disentinel/grafema / .claude/skills/docker-node-version-compat-modules
docker-node-version-compat-modules
VerifiedFix Node.js CLI tools crashing inside Docker containers when host-installed node_modules require a newer Node version than the container provides. Use when: (1) "SyntaxError: Invalid regular expression flags" with /v flag in string-width or similar packages, (2) node_modules installed on host with Node 20+ but container has Node 18, (3) `npm install` with file: protocol creates symlinks that break inside Docker, (4) pnpm workspace packages become broken symlinks in containers. Covers version detection, Node binary mounting, and npm install strategies for cross-version compatibility.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.8 KB |
SKILL.md
View on GitHub---
name: docker-node-version-compat-modules
description: |
Fix Node.js CLI tools crashing inside Docker containers when host-installed node_modules
require a newer Node version than the container provides. Use when: (1) "SyntaxError: Invalid
regular expression flags" with /v flag in string-width or similar packages, (2) node_modules
installed on host with Node 20+ but container has Node 18, (3) `npm install` with file:
protocol creates symlinks that break inside Docker, (4) pnpm workspace packages become
broken symlinks in containers. Covers version detection, Node binary mounting, and
npm install strategies for cross-version compatibility.
author: Claude Code
version: 1.0.0
date: 2026-02-10
---
# Docker Node Version Compatibility for Mounted node_modules
## Problem
When mounting host-installed `node_modules` into a Docker container, packages may require
a newer Node.js version than what's available in the container. This causes cryptic runtime
errors (not install-time errors) because npm doesn't enforce `engines` constraints by default.
## Context / Trigger Conditions
- **Primary symptom**: `SyntaxError: Invalid regular expression flags` on the `/v` flag
(Unicode Sets, requires Node 20+)
- **Affected packages**: `string-width@8.x`, `ink@6.x`, and their dependents
- **Scenario**: Host has Node 20+, Docker container has Node 18 (common in SWE-bench images)
- **Also triggers when**: `npm install` with `file:` protocol creates symlinks to host paths
that don't exist inside the container
- **Also triggers when**: pnpm workspace `@scope/pkg` entries are symlinks to
`../../../../workspace/packages/pkg` — broken inside Docker
## Root Cause
1. **npm doesn't enforce `engines` by default**: Even with `--engine-strict`, it only checks
direct dependencies, not transitive ones. Packages like `string-width@8.x` declare
`"engines": {"node": ">=20"}` but npm happily installs them on any Node version.
2. **`file:` protocol creates symlinks**: `npm install file:../path` creates a symlink in
`node_modules/` pointing to the host path. Inside Docker, that host path doesn't exist.
3. **pnpm workspace symlinks**: In pnpm monorepos, `node_modules/@scope/pkg` is a symlink
to `../../packages/pkg`. These are relative to the workspace root, not the mount point.
## Diagnostic Steps
**CRITICAL: Before attempting any fix, verify these first:**
1. Check Node version in the target container:
```bash
docker run --rm <image> node --version
```
2. Check if the tool actually worked before (don't assume — **read the trajectory/logs**):
```bash
# Look for actual command outputs, not just references in prompts
grep '"returncode": 0' trajectory.json | grep grafema
```
3. Check for symlinks in mounted node_modules:
```bash
docker exec <container> bash -c "ls -la /opt/node_modules/@scope/"
```
## Solutions
### Solution A: Mount Node 20+ Binary (Recommended)
Download a Node.js binary for Linux and mount it alongside node_modules:
```bash
# Download once
curl -sL https://nodejs.org/dist/v20.18.0/node-v20.18.0-linux-x64.tar.xz | \
tar -xJ -C /path/to/node20 --strip-components=1
# Mount and use in container
docker run -v /path/to/node20:/opt/node20:ro \
-v /path/to/node_modules:/opt/modules:ro \
<image> bash -c "
export PATH=/opt/node20/bin:\$PATH
# Create wrapper script for the CLI tool
echo '#!/bin/bash' > /usr/local/bin/mytool
echo 'exec /opt/node20/bin/node /opt/modules/.bin/mytool \"\$@\"' >> /usr/local/bin/mytool
chmod +x /usr/local/bin/mytool
"
```
### Solution B: Install with Version Constraints
Install inside a container matching the target Node version with overrides:
```bash
docker run --rm -v /path/to/install:/install node:18 bash -c '
cd /install
npm install --engine-strict # Will fail if deps need Node 20+
'
```
If this fails (because core deps like ink require Node 20+), Solution A is the only option.
### Solution C: pnpm pack + npm install (Flat Layout)
For pnpm monorepos, create tarballs first to eliminate workspace symlinks:
```bash
# On host (resolves workspace:* protocol)
pnpm -C packages/cli pack --pack-destination /tmp/packs
# Install from tarballs (creates real directories, not symlinks)
# Do this inside a Docker container matching target Node version
docker run --rm -v /tmp/packs:/packs:ro -v /path/to/install:/install node:20 bash -c '
cd /install
cat > package.json << EOF
{"dependencies": {"@scope/cli": "file:/packs/cli-1.0.0.tgz"}}
EOF
npm install
'
```
**Important**: Use `pnpm pack` (not `npm pack`) to resolve `workspace:*` protocol.
## Anti-Patterns
1. **Don't dereference symlinks with `cp -RL`**: This copies files but npm still resolves
the latest dependency versions, which may require newer Node.
2. **Don't use `pnpm deploy` for Docker mounts**: It creates `.pnpm/` layout with internal
symlinks that cause ESM resolution errors in some Node versions.
3. **Don't debug Docker setup without checking if it ever worked**: Verify in actual
trajectory outputs, not by counting keyword references in prompts/logs.
4. **Don't try multiple fixes in sequence without diagnosing**: Check Node version
compatibility FIRST before attempting any fix.
## Verification
```bash
# Test the full command, not just the binary path
docker exec <container> bash -c "export PATH=/opt/node20/bin:\$PATH; mytool --version"
# Test a command that exercises dependency loading (not just the entry point)
docker exec <container> bash -c "export PATH=/opt/node20/bin:\$PATH; mytool impact 'someFunction'"
```
## Notes
- SWE-bench Docker images use different Node versions: axios=Node 20, preact=Node 18
- `grafema overview` may work while `grafema impact` fails because they load different modules
- The `/v` regex flag (Unicode Sets) is the most common Node 20 breakage point
- `ink` (terminal UI framework) switched to Node 20+ requirement starting from v6.0.0
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |