ams-pnpm-pro
暂无简介
- License 许可
- MIT
- 最近更新
- 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/.pnpmholds isolated package dirs; your project'snode_modulescontains only direct dependencies (symlinked).require('undeclared-dep')fails — by design. - Workspaces.
pnpm-workspace.yamldefines packages;workspace:*protocol links internal deps.pnpm -r/--filterrun across packages. - Catalogs.
pnpm-workspace.yamlcatalogs:pin shared versions (e.g., all packages usetypescript@catalog:) — one place to bump React/TypeScript across the monorepo. pnpm-lock.yaml. Single lockfile at the workspace root. Commit it; CI usespnpm install --frozen-lockfile.package-managerfield."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=trueas a crutch. It reintroduces the flat layout and its bugs. Usepublic-hoist-patternsurgically for the rare tool that needs it (or fix the tool's packaging).- Lockfile drift. Editing package.json by hand without running
pnpm installleaves the lockfile stale; CI--frozen-lockfilethen fails. Always install after edits. - Forgetting
--frozen-lockfilein 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
.binfor direct deps only. Declare the tool as a dependency where it's used. - Store bloat. The global store grows forever;
pnpm store pruneperiodically, 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
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.
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.
test-driven-development
Use when implementing any feature or bugfix, before writing implementation code
systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
requesting-code-review
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
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).