add-npm-dependency

name	add-npm-dependency
description	This skill MUST be used whenever the task involves adding, installing, or upgrading an npm package/library/dependency in this project. Use when the user asks to "add a library", "install <package>", "use <package>", "add a dependency", "bump/upgrade a package", or any change to package.json dependencies. Covers the latest-version policy, esbuild renderer bundling, manual CSS copy, native module rebuilds, and the three build targets. Use when this capability is needed.
metadata	{"author":"elirantutia"}

Adding an npm Library

This is an Electron app with three separate build targets (main, preload, renderer) and a few non-obvious bundling rules. Adding a dependency the wrong way silently breaks CSS, native modules, or the renderer bundle. Follow this guide every time.

Golden Rule: install the latest, caret-pinned

Always install the newest published version. Never hand-edit package.json to set or downgrade a version.

npm install <pkg>@latest          # runtime dependency
npm install -D <pkg>@latest       # dev / build-only tool (types, bundlers, test libs)

• This records a caret range ^x.y.z — the repo convention (every dep in package.json uses ^). Leave it as a caret range.
• package-lock.json is committed and gets updated by the install. Both package.json and package-lock.json are part of your change — stage both.
• Use npm only (the lockfile is package-lock.json — not yarn, not pnpm).
• Node v24 is pinned in .nvmrc; engines.node is >=18. Run nvm use first if needed.

Step 1 — Decide which build target consumes the package

This determines every gotcha that follows.

Target	Source dirs	How it's built	What's allowed
Renderer	src/renderer/**	Bundled by esbuild into one IIFE (build:renderer)	Plain JS/TS deps only. No Node built-ins, no native modules.
Main	src/main/**, src/shared/**	tsc → CommonJS (dist/main/)	Any Node dep, including native modules. Resolved via require at runtime against node_modules — not bundled.
Preload	src/preload/**, src/shared/**	tsc → CommonJS (dist/preload/)	Runs in Node/Electron context; same rules as main.

• A pure JS/TS library used in the UI (like marked, dompurify, gridstack, @xterm/*) just gets imported in renderer code and esbuild bundles it. Nothing else to do (except CSS — see Step 2).
• A library that touches the filesystem, spawns processes, or has a .node binary belongs in main/preload only.

Step 2 — CSS / static assets gotcha (esbuild has NO CSS loader)

esbuild only has the .ts loader configured. It will not bundle any CSS the package ships. If the library needs a stylesheet to work (the way gridstack and @xterm/xterm do):

1. Add a copy step in scripts/copy-assets.js — copy from node_modules/<pkg>/.../file.css to dist/renderer/vendor/<file>.css. Mirror the existing gridstack precedent in that file.
2. Add a <link rel="stylesheet" href="vendor/<file>.css"> to src/renderer/index.html (gridstack/xterm links are already there as examples).

If you skip this, the JS bundles fine but the component renders unstyled. (CLAUDE.md documents this: "esbuild has no CSS loader" — gridstack CSS is copied manually.)

Step 3 — Native module gotcha (.node binaries)

Examples already in the repo: better-sqlite3, node-pty.

• Must be a regular dependency (never imported from the renderer — main/preload only).
• npm install triggers the postinstall hook → electron-builder install-app-deps, which rebuilds the .node binary against the pinned Electron ABI. If the module fails to load at runtime ("NODE_MODULE_VERSION mismatch"), re-run npm install and check the postinstall output.
• If the binary can't load from inside the asar archive, add the package to electron-builder's asarUnpack in package.json (precedent: **/node_modules/better-sqlite3/**).
• Native modules must compile on macOS, Linux, and Windows — CI builds all three. Flag the cross-platform risk to the user; see src/main/platform.ts for the platform-detection helpers.

Step 4 — Types

• If the package ships its own type declarations, you're done.
• Otherwise add the community types as a devDependency: npm install -D @types/<pkg>@latest (precedent: @types/better-sqlite3, @types/dompurify, @types/picomatch).

Step 5 — Verify (required, not optional)

There is no hot reload — every change needs a rebuild.

npm run build    # must pass: tsc main + tsc preload + esbuild renderer + copy-assets
npm test         # Vitest suite

Then confirm the dependency actually works end to end:

• Renderer / UI / CSS dep: npm start, and visually confirm the feature renders and styles load.
• Native / main dep: launch the app and exercise the feature that uses it.

Step 6 — Packaging sanity check

electron-builder packages only dist/main/**, dist/preload/**, dist/renderer/**:

• Renderer deps are safe — they're bundled into dist/renderer/index.js.
• Main/preload deps resolve from the packaged production node_modules at runtime, so they must be in dependencies (not devDependencies). Keep build-only tooling (bundlers, types, test libs) in devDependencies.

Do / Don't

Do:

• npm install <pkg>@latest, leave the caret range, commit package.json + package-lock.json.
• Pick the right target (renderer vs main/preload) before importing.
• Add the CSS copy step + <link> for any styled renderer library.
• Run npm run build and npm test before declaring done.

Don't:

• Pin an exact version or hand-edit a version in package.json.
• Import Node built-ins or native modules from the renderer.
• Forget the scripts/copy-assets.js step for CSS (esbuild won't bundle it).
• Put a native module in devDependencies or assume it works without the postinstall rebuild.

$ARGUMENTS

---

Source: elirantutia/vibeyard — distributed by TomeVault.