# Add Npm Dependency

MUST be used whenever the task involves adding, installing, or upgrading an npm...

- Repository: https://github.com/elirantutia/vibeyard (1393 stars)
- Category: Design
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add elirantutia/vibeyard --skill add-npm-dependency -g -a claude-code -y`
Codex: `npx skills add elirantutia/vibeyard --skill add-npm-dependency -g -a codex -y`
Cursor: `npx skills add elirantutia/vibeyard --skill add-npm-dependency -g -a cursor -y`
Gemini CLI: `npx skills add elirantutia/vibeyard --skill add-npm-dependency -g -a gemini-cli -y`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.**

```bash
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. |

The rest: https://github.com/elirantutia/vibeyard/blob/HEAD/.claude/skills/add-npm-dependency/SKILL.md