AGENT SKILL

ams-pnpm-pro

暂无简介

License 许可
MIT
所属仓库
TanNhatCMS/jarvis
最近更新
2026-11-07
Stars
★ 0
Forks
1

03 SKILL.md 正文

pnpm Pro

A practical guide to pnpm: the content-addressable store, strict node_modules layout, workspaces, catalogs, and the commands and config that make pnpm fast and correct in single repos and monorepos.

Overview

pnpm's headline features are speed and disk efficiency (one global content-addressable store, hard links into projects), but its most important property is strictness: packages can only access their declared dependencies — no phantom dependencies from hoisting. Code that works under npm/yarn's flat node_modules often breaks under pnpm, and that's pnpm telling you about a real bug in your dependency declarations.

When to use

  • Any JS/TS project where install speed and disk usage matter.
  • Monorepos (pnpm workspaces are the best-in-class workspace implementation).
  • Eliminating phantom dependencies and enforcing correct dependency declarations.
  • CI optimization via store caching.

Core concepts

  • Content-addressable store. One copy of each package version on disk (~/.pnpm-store), hard-linked into projects. Installs are fast; disk usage stays flat across projects.
  • Strict node_modules. node_modules/.pnpm holds isolated package dirs; your project's node_modules contains only direct dependencies (symlinked). require('undeclared-dep') fails — by design.
  • Workspaces. pnpm-workspace.yaml defines packages; workspace:* protocol links internal deps. pnpm -r / --filter run across packages.
  • Catalogs. pnpm-workspace.yaml catalogs: pin shared versions (e.g., all packages use typescript@catalog:) — one place to bump React/TypeScript across the monorepo.
  • pnpm-lock.yaml. Single lockfile at the workspace root. Commit it; CI uses pnpm install --frozen-lockfile.
  • package-manager field. "packageManager": "pnpm@9.x" in root package.json + corepack pins the version for everyone.
  • Side-effects cache. pnpm tracks packages with install scripts; configurable allowlists keep installs reproducible.

Practical workflow

1. Setup.

corepack enable && corepack prepare pnpm@latest --activate
pnpm init
# package.json: "packageManager": "pnpm@9.12.0"

2. Daily commands.

pnpm add react                 # dependency
pnpm add -D typescript         # devDependency
pnpm add -w lodash             # workspace root
pnpm --filter web add ../ui    # internal dep via workspace:*
pnpm -r run build               # recursive
pnpm --filter "...[main]" test # changed since main (with git)
pnpm dedupe                    # minimize duplicate versions
pnpm why react                 # who depends on react
pnpm store prune               # clean unused store entries

3. Workspaces.

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
catalog:
  react: ^18.3.1
  typescript: ^5.5.0
// packages/ui/package.json
{ "dependencies": { "react": "catalog:" } }

4. CI.

- uses: pnpm/action-setup@v4
- uses: actions/cache@v4
  with: { path: ~/.pnpm-store, key: pnpm-store-${{ hashFiles('pnpm-lock.yaml') }} }
- run: pnpm install --frozen-lockfile

5. Fixing strictness errors. Cannot find module 'x' under pnpm usually means: add x to that package's dependencies (it was a phantom dep before). Use pnpm add x in the right package — don't fight the strictness.

Common pitfalls

  • Phantom dependencies. Code importing undeclared packages worked under npm/yarn, breaks under pnpm. Fix by declaring, not by shamefully-hoist.
  • shamefully-hoist=true as a crutch. It reintroduces the flat layout and its bugs. Use public-hoist-pattern surgically for the rare tool that needs it (or fix the tool's packaging).
  • Lockfile drift. Editing package.json by hand without running pnpm install leaves the lockfile stale; CI --frozen-lockfile then fails. Always install after edits.
  • Forgetting --frozen-lockfile in CI. Without it, CI can silently resolve different versions than local. Always frozen in CI.
  • Peer dependency surprises. pnpm is strict about peers; auto-install-peers defaults help, but conflicting peer ranges need explicit overrides (pnpm.overrides).
  • Scripts needing hoisted bins. Tools expecting their binaries hoisted: pnpm links .bin for direct deps only. Declare the tool as a dependency where it's used.
  • Store bloat. The global store grows forever; pnpm store prune periodically, especially on CI runners with persistent disks.
  • Node version mismatch. pnpm doesn't manage Node. Pair with .nvmrc/volta or a container so everyone (and CI) runs the same Node.

04 同仓库更多 Skills

TanNhatCMS
TanNhatCMS/jarvis

web-scrape

Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

design-taste-frontend

tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

★ 0
TanNhatCMS
TanNhatCMS/jarvis

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

★ 0
TanNhatCMS
TanNhatCMS/jarvis

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

★ 0
TanNhatCMS
TanNhatCMS/jarvis

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).

★ 0