Source from repo
pnpm

pnpm 10.x reference skill covering workspaces, catalogs, patches, peer deps, overrides, and CI/CD caching strategies.
antfuGitHub antfuSource repo Original GitHub link Publisher page
Files
Skill
n/a
Size
54.3 KB
Entrypoint
SKILL.md
Format
git-repo
Open file
references/best-practices-ci.md

Syntax-highlighted preview of this file as included in the skill package.
Rendered Source
markdown286 linesFree
references/best-practices-ci.md
1---
2name: pnpm-ci-cd-setup
3description: Optimizing pnpm for continuous integration and deployment workflows
4---
5 
6# pnpm CI/CD Setup
7 
8Best practices for using pnpm in CI/CD environments for fast, reliable builds.
9 
10## GitHub Actions
11 
12### Basic Setup
13 
14```yaml
15name: CI
16 
17on: [push, pull_request]
18 
19jobs:
20  build:
21    runs-on: ubuntu-latest
22    steps:
23      - uses: actions/checkout@v4
24      
25      - uses: pnpm/action-setup@v4
26        with:
27          version: 9
28      
29      - uses: actions/setup-node@v4
30        with:
31          node-version: 20
32          cache: 'pnpm'
33      
34      - run: pnpm install --frozen-lockfile
35      - run: pnpm test
36      - run: pnpm build
37```
38 
39### With Store Caching
40 
41For larger projects, cache the pnpm store:
42 
43```yaml
44- uses: pnpm/action-setup@v4
45  with:
46    version: 9
47 
48- name: Get pnpm store directory
49  shell: bash
50  run: |
51    echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
52 
53- uses: actions/cache@v4
54  name: Setup pnpm cache
55  with:
56    path: ${{ env.STORE_PATH }}
57    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
58    restore-keys: |
59      ${{ runner.os }}-pnpm-store-
60 
61- run: pnpm install --frozen-lockfile
62```
63 
64### Matrix Testing
65 
66```yaml
67jobs:
68  test:
69    runs-on: ${{ matrix.os }}
70    strategy:
71      matrix:
72        os: [ubuntu-latest, windows-latest, macos-latest]
73        node: [18, 20, 22]
74    steps:
75      - uses: actions/checkout@v4
76      - uses: pnpm/action-setup@v4
77      - uses: actions/setup-node@v4
78        with:
79          node-version: ${{ matrix.node }}
80          cache: 'pnpm'
81      - run: pnpm install --frozen-lockfile
82      - run: pnpm test
83```
84 
85## GitLab CI
86 
87```yaml
88image: node:20
89 
90stages:
91  - install
92  - test
93  - build
94 
95variables:
96  PNPM_HOME: /root/.local/share/pnpm
97  PATH: $PNPM_HOME:$PATH
98 
99before_script:
100  - corepack enable
101  - corepack prepare pnpm@latest --activate
102 
103cache:
104  key: ${CI_COMMIT_REF_SLUG}
105  paths:
106    - .pnpm-store
107 
108install:
109  stage: install
110  script:
111    - pnpm config set store-dir .pnpm-store
112    - pnpm install --frozen-lockfile
113 
114test:
115  stage: test
116  script:
117    - pnpm test
118 
119build:
120  stage: build
121  script:
122    - pnpm build
123```
124 
125## Docker
126 
127### Multi-Stage Build
128 
129```dockerfile
130# Build stage
131FROM node:20-slim AS builder
132 
133# Enable corepack for pnpm
134RUN corepack enable
135 
136WORKDIR /app
137 
138# Copy package files first for layer caching
139COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
140COPY packages/*/package.json ./packages/
141 
142# Install dependencies
143RUN pnpm install --frozen-lockfile
144 
145# Copy source and build
146COPY . .
147RUN pnpm build
148 
149# Production stage
150FROM node:20-slim AS runner
151 
152RUN corepack enable
153WORKDIR /app
154 
155COPY --from=builder /app/dist ./dist
156COPY --from=builder /app/package.json ./
157COPY --from=builder /app/pnpm-lock.yaml ./
158 
159# Production install
160RUN pnpm install --frozen-lockfile --prod
161 
162CMD ["node", "dist/index.js"]
163```
164 
165### Optimized for Monorepos
166 
167```dockerfile
168FROM node:20-slim AS builder
169RUN corepack enable
170WORKDIR /app
171 
172# Copy workspace config
173COPY pnpm-lock.yaml pnpm-workspace.yaml ./
174 
175# Copy all package.json files maintaining structure
176COPY packages/core/package.json ./packages/core/
177COPY packages/api/package.json ./packages/api/
178 
179# Install all dependencies
180RUN pnpm install --frozen-lockfile
181 
182# Copy source
183COPY . .
184 
185# Build specific package
186RUN pnpm --filter @myorg/api build
187```
188 
189## Key CI Flags
190 
191### --frozen-lockfile
192 
193**Always use in CI.** Fails if `pnpm-lock.yaml` needs updates:
194 
195```bash
196pnpm install --frozen-lockfile
197```
198 
199### --prefer-offline
200 
201Use cached packages when available:
202 
203```bash
204pnpm install --frozen-lockfile --prefer-offline
205```
206 
207### --ignore-scripts
208 
209Skip lifecycle scripts for faster installs (use cautiously):
210 
211```bash
212pnpm install --frozen-lockfile --ignore-scripts
213```
214 
215## Corepack Integration
216 
217Use Corepack to manage pnpm version:
218 
219```json
220// package.json
221{
222  "packageManager": "[email protected]"
223}
224```
225 
226```yaml
227# GitHub Actions
228- run: corepack enable
229- run: pnpm install --frozen-lockfile
230```
231 
232## Monorepo CI Strategies
233 
234### Build Changed Packages Only
235 
236```yaml
237- name: Build changed packages
238  run: |
239    pnpm --filter "...[origin/main]" build
240```
241 
242### Parallel Jobs per Package
243 
244```yaml
245jobs:
246  detect-changes:
247    runs-on: ubuntu-latest
248    outputs:
249      packages: ${{ steps.changes.outputs.packages }}
250    steps:
251      - uses: actions/checkout@v4
252        with:
253          fetch-depth: 0
254      - id: changes
255        run: |
256          echo "packages=$(pnpm --filter '...[origin/main]' list --json | jq -c '[.[].name]')" >> $GITHUB_OUTPUT
257 
258  test:
259    needs: detect-changes
260    if: needs.detect-changes.outputs.packages != '[]'
261    runs-on: ubuntu-latest
262    strategy:
263      matrix:
264        package: ${{ fromJson(needs.detect-changes.outputs.packages) }}
265    steps:
266      - uses: actions/checkout@v4
267      - uses: pnpm/action-setup@v4
268      - run: pnpm install --frozen-lockfile
269      - run: pnpm --filter ${{ matrix.package }} test
270```
271 
272## Best Practices Summary
273 
2741. **Always use `--frozen-lockfile`** in CI
2752. **Cache the pnpm store** for faster installs
2763. **Use Corepack** for consistent pnpm versions
2774. **Specify `packageManager`** in package.json
2785. **Use `--filter`** in monorepos to build only what changed
2796. **Multi-stage Docker builds** for smaller images
280 
281<!-- 
282Source references:
283- https://pnpm.io/continuous-integration
284- https://github.com/pnpm/action-setup
285-->
286
Preparing the source view

pnpm

references/best-practices-ci.md
