0
# Cache Management
1

2
Commands for managing yarn's package cache system, which stores downloaded packages for offline installation and performance optimization.
3

4
## Capabilities
5

6
### Show Cache Directory
7

8
Display the location of yarn's cache directory.
9

10
```bash { .api }
11
yarn cache dir
12
```
13

14
**Usage Examples:**
15

16
```bash
17
# Show cache directory path
18
yarn cache dir
19

20
# Use in scripts
21
CACHE_DIR=$(yarn cache dir)
22
echo "Cache is located at: $CACHE_DIR"
23

24
# Check cache size
25
du -sh $(yarn cache dir)
26
```
27

28
**Default Cache Locations:**
29
- **Linux**: `~/.cache/yarn`
30
- **macOS**: `~/Library/Caches/yarn`
31
- **Windows**: `%LOCALAPPDATA%\Yarn\cache`
32

33
### List Cached Packages
34

35
Display all packages stored in the cache.
36

37
```bash { .api }
38
yarn cache list [pattern] [options]
39

40
# Options:
41
--pattern <pattern>      # Filter packages by pattern
42
```
43

44
**Usage Examples:**
45

46
```bash
47
# List all cached packages
48
yarn cache list
49

50
# Filter by pattern
51
yarn cache list --pattern "react*"
52
yarn cache list --pattern "@types/*"
53

54
# List specific package versions
55
yarn cache list lodash
56
yarn cache list react
57
```
58

59
**Output Format:**
60
```
61
react@16.14.0
62
react@17.0.2
63
react@18.2.0
64
react-dom@16.14.0
65
react-dom@17.0.2
66
react-dom@18.2.0
67
```
68

69
### Clean Cache
70

71
Remove packages from the cache.
72

73
```bash { .api }
74
yarn cache clean [package] [options]
75

76
# Options:
77
--all                    # Clean entire cache
78
--pattern <pattern>      # Clean packages matching pattern
79
```
80

81
**Usage Examples:**
82

83
```bash
84
# Clean specific package
85
yarn cache clean react
86

87
# Clean all versions of a package
88
yarn cache clean lodash
89

90
# Clean packages matching pattern
91
yarn cache clean --pattern "react*"
92
yarn cache clean --pattern "@babel/*"
93

94
# Clean entire cache
95
yarn cache clean --all
96
yarn cache clean
97

98
# Force clean (skip confirmation)
99
yarn cache clean --all --force
100
```
101

102
**Clean Process:**
103
1. Identifies packages to remove
104
2. Shows confirmation prompt (unless `--force` used)
105
3. Removes package tarballs and metadata
106
4. Updates cache index
107

108
## Cache Structure
109

110
### Cache Organization
111

112
```
113
~/.cache/yarn/
114
├── v6/                          # Cache version
115
│   ├── npm-react-18.2.0-<hash>  # Package tarball
116
│   ├── npm-lodash-4.17.21-<hash>
117
│   └── npm-@types-node-18.7.14-<hash>
118
├── .tmp/                        # Temporary files during download
119
└── .yarnclean                   # Auto-clean rules (if enabled)
120
```
121

122
### Cache Metadata
123

124
Each cached package includes:
125
- **Tarball**: Compressed package contents
126
- **Metadata**: Package.json and registry information
127
- **Integrity hash**: For verification
128
- **Download timestamp**: For cache management
129

130
### Cache Versioning
131

132
Yarn uses versioned caches:
133
- **v4**: Yarn Classic (1.x) cache format
134
- **v6**: Current cache format
135
- **Migration**: Automatic when upgrading Yarn versions
136

137
## Cache Configuration
138

139
### Cache Directory
140

141
```bash
142
# Set custom cache directory
143
yarn config set cache-folder /custom/cache/path
144

145
# Use environment variable
146
export YARN_CACHE_FOLDER=/tmp/yarn-cache
147

148
# Temporary cache directory
149
YARN_CACHE_FOLDER=/tmp/cache yarn install
150
```
151

152
### Cache Behavior
153

154
```bash
155
# Disable cache (force download)
156
yarn install --no-cache
157

158
# Use cache only (offline mode)
159
yarn install --offline
160

161
# Clear cache before download
162
yarn install --force
163
```
164

165
### Cache Size Management
166

167
```bash
168
# Check cache size
169
du -sh $(yarn cache dir)
170

171
# Set cache size limit (not directly supported, but can script)
172
find $(yarn cache dir) -type f -atime +30 -delete  # Remove files older than 30 days
173
```
174

175
## Offline Mode
176

177
### Offline Mirror
178

179
Create an offline mirror for package distribution:
180

181
```bash
182
# Set offline mirror directory
183
yarn config set offline-mirror ./offline-packages
184

185
# Install packages (populates offline mirror)
186
yarn install
187

188
# Use offline mirror
189
yarn install --offline
190
```
191

192
**Offline Mirror Structure:**
193
```
194
offline-packages/
195
├── lodash-4.17.21.tgz
196
├── react-18.2.0.tgz
197
├── react-dom-18.2.0.tgz
198
└── ...
199
```
200

201
### Offline Installation
202

203
```bash
204
# Install from cache only
205
yarn install --offline
206

207
# Install with offline fallback
208
yarn install --prefer-offline
209

210
# Check if package exists in cache
211
yarn cache list react | grep "react@18.2.0"
212
```
213

214
## Cache Optimization
215

216
### Preloading Cache
217

218
```bash
219
# Pre-populate cache for project
220
yarn install --cache-folder /shared/cache
221

222
# Share cache between projects
223
export YARN_CACHE_FOLDER=/shared/yarn-cache
224
cd project1 && yarn install
225
cd project2 && yarn install  # Uses same cache
226
```
227

228
### Cache Sharing
229

230
**CI/CD Cache Sharing:**
231
```bash
232
# Save cache
233
tar -czf yarn-cache.tar.gz $(yarn cache dir)
234

235
# Restore cache
236
tar -xzf yarn-cache.tar.gz -C $(dirname $(yarn cache dir))
237

238
# Docker cache sharing
239
COPY yarn-cache.tar.gz /tmp/
240
RUN tar -xzf /tmp/yarn-cache.tar.gz -C ~/.cache/
241
```
242

243
**Team Cache Sharing:**
244
```bash
245
# Network cache location
246
yarn config set cache-folder /nfs/shared/yarn-cache
247

248
# Or use offline mirror
249
yarn config set offline-mirror /nfs/shared/offline-packages
250
```
251

252
### Cache Maintenance
253

254
```bash
255
# Automated cache cleanup script
256
#!/bin/bash
257
CACHE_DIR=$(yarn cache dir)
258
OLD_SIZE=$(du -sh "$CACHE_DIR" | cut -f1)
259

260
# Remove packages older than 60 days
261
find "$CACHE_DIR" -type f -mtime +60 -delete
262

263
# Remove empty directories
264
find "$CACHE_DIR" -type d -empty -delete
265

266
NEW_SIZE=$(du -sh "$CACHE_DIR" | cut -f1)
267
echo "Cache cleaned: $OLD_SIZE -> $NEW_SIZE"
268
```
269

270
## Cache Performance
271

272
### Cache Benefits
273

274
1. **Faster Installs**: Packages downloaded once, reused everywhere
275
2. **Offline Capability**: Install without internet connection
276
3. **Bandwidth Savings**: Avoid redundant downloads
277
4. **Reliability**: Local copies immune to network issues
278

279
### Cache Statistics
280

281
```bash
282
# Cache hit rate analysis
283
yarn install --verbose 2>&1 | grep -E "(fetch|cache)"
284

285
# Cache size analysis
286
find $(yarn cache dir) -name "*.tgz" | wc -l  # Number of cached packages
287
du -sh $(yarn cache dir)                       # Total cache size
288
```
289

290
### Performance Tuning
291

292
```bash
293
# Optimize network settings for cache population
294
yarn config set network-concurrency 16       # More concurrent downloads
295
yarn config set network-timeout 300000       # Longer timeout for large packages
296

297
# Optimize for SSD storage
298
yarn config set cache-folder /fast/ssd/yarn-cache
299
```
300

301
## Troubleshooting Cache Issues
302

303
### Cache Corruption
304

305
```bash
306
# Symptoms: Installation failures, integrity check errors
307
# Solution: Clean and rebuild cache
308
yarn cache clean --all
309
yarn install --force
310
```
311

312
### Disk Space Issues
313

314
```bash
315
# Check cache size
316
du -sh $(yarn cache dir)
317

318
# Clean old packages
319
yarn cache clean --pattern "*" --older-than 30d  # If supported
320
find $(yarn cache dir) -type f -mtime +30 -delete
321

322
# Move cache to larger disk
323
yarn config set cache-folder /path/to/larger/disk/yarn-cache
324
```
325

326
### Permission Issues
327

328
```bash
329
# Fix cache permissions
330
sudo chown -R $(whoami) $(yarn cache dir)
331
chmod -R 755 $(yarn cache dir)
332

333
# Use user-specific cache
334
yarn config set cache-folder ~/.local/share/yarn-cache
335
```
336

337
### Network Issues
338

339
```bash
340
# Bypass cache for network debugging
341
yarn install --no-cache --verbose
342

343
# Use offline mode to test cache
344
yarn install --offline
345

346
# Clear and repopulate cache
347
yarn cache clean --all
348
yarn install --force
349
```
350

351
## Cache Integration
352

353
### CI/CD Integration
354

355
```bash
356
# GitHub Actions cache example
357
- name: Cache Yarn dependencies
358
  uses: actions/cache@v3
359
  with:
360
    path: $(yarn cache dir)
361
    key: yarn-${{ hashFiles('**/yarn.lock') }}
362
    restore-keys: |
363
      yarn-
364

365
# GitLab CI cache example
366
cache:
367
  key: yarn-$CI_COMMIT_REF_SLUG
368
  paths:
369
    - $(yarn cache dir)
370
```
371

372
### Docker Integration
373

374
```dockerfile
375
# Multi-stage cache optimization
376
FROM node:18 as cache
377
WORKDIR /app
378
COPY package.json yarn.lock ./
379
RUN yarn install --frozen-lockfile
380

381
FROM node:18 as production
382
WORKDIR /app
383
COPY --from=cache /app/node_modules ./node_modules
384
COPY . .
385
RUN yarn build
386
```
387

388
### Development Workflow
389

390
```bash
391
# Team development setup
392
echo "cache-folder /shared/yarn-cache" >> .yarnrc
393
git add .yarnrc
394

395
# Local development optimization
396
yarn config set cache-folder ~/.cache/yarn
397
yarn config set network-concurrency 8
398
```