ReviewOS

also looking at this

loghqorg/loghq

Deploy: uniform auth session model (main → production)

#7
Merged glennmichael123 wants to merge main into production
282 files +3028 -64856
docs/bootcamp/how-to/bun-lock.mddeleted+0-488
Changes to docs/bootcamp/how-to/bun-lock.md
@@ -1,488 +0,0 @@
1# Bun Lockfile Management
2
3This guide covers managing Bun's lockfile (`bun.lock`) in your Stacks application, including best practices for version control, troubleshooting, and team collaboration.
4
5## Understanding bun.lock
6
7Bun uses a text-based lockfile format (`bun.lock`) that is human-readable and git-friendly. This format provides:
8
9- **Human-readable** - Text-based JSONC format that can be inspected and diffed
10- **Git-friendly** - Easy to review changes in pull requests
11- **Integrity** - Contains checksums for all packages
12- **Deterministic installs** - Ensures consistent dependencies across environments
13- **Faster parsing** - Optimized for Bun's package resolution
14
15::: tip Migration Note
16If you have an older project with `bun.lockb` (binary format), Bun will automatically migrate to `bun.lock` when you run `bun install`. You can safely delete the old `bun.lockb` file after migration.
17:::
18
19## Basic Commands
20
21### Installing Dependencies
22
23```bash
24# Install all dependencies from bun.lock
25bun install
26
27# Install with frozen lockfile (CI/CD)
28bun install --frozen-lockfile
29
30# Install and update lockfile
31bun install
32
33# Force fresh install (regenerate lockfile)
34rm -rf node_modules bun.lock && bun install
35```
36
37### Updating Dependencies
38
39```bash
40# Update all dependencies
41bun update
42
43# Update specific package
44bun update package-name
45
46# Update to latest (ignore semver)
47bun update package-name --latest
48```
49
50### Adding Dependencies
51
52```bash
53# Add production dependency
54bun add package-name
55
56# Add dev dependency
57bun add -d package-name
58
59# Add exact version
60bun add package-name@1.2.3
61
62# Add from git
63bun add github:user/repo
64```
65
66### Removing Dependencies
67
68```bash
69# Remove package
70bun remove package-name
71```
72
73## Version Control
74
75### Git Configuration
76
77Add to `.gitignore`:
78
79```gitignore
80# Node modules
81node_modules/
82
83# DO NOT ignore bun.lock - it should be committed
84# bun.lock
85```
86
87::: info
88Since `bun.lock` is now a text-based format, you no longer need special `.gitattributes` configuration. Git will handle it like any other text file.
89:::
90
91### Committing the Lockfile
92
93Always commit `bun.lock` to version control:
94
95```bash
96git add bun.lock
97git commit -m "chore: update dependencies"
98```
99
100### Viewing Lockfile Changes
101
102Since `bun.lock` is text-based JSONC format, you can view changes directly:
103
104```bash
105# View lockfile changes
106git diff bun.lock
107
108# View lockfile changes in a PR
109gh pr diff --name-only | grep bun.lock
110```
111
112The text format makes code review much easier - you can see exactly which packages changed and to what versions.
113
114## CI/CD Configuration
115
116### GitHub Actions
117
118```yaml
119# .github/workflows/ci.yml
120name: CI
121
122on:
123 push:
124 branches: [main]
125 pull_request:
126 branches: [main]
127
128jobs:
129 test:
130 runs-on: ubuntu-latest
131 steps:
132
133 - uses: actions/checkout@v4
134
135 - name: Setup Bun
136
137 uses: oven-sh/setup-bun@v1
138 with:
139 bun-version: latest
140
141 - name: Install dependencies
142
143 run: bun install --frozen-lockfile
144
145 - name: Run tests
146
147 run: bun test
148
149 - name: Build
150
151 run: bun run build
152```
153
154### Caching Dependencies
155
156```yaml
157
158- name: Cache Bun dependencies
159
160 uses: actions/cache@v4
161 with:
162 path: ~/.bun/install/cache
163 key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
164 restore-keys: |
165 ${{ runner.os }}-bun-
166```
167
168### Docker
169
170```dockerfile
171# Dockerfile
172FROM oven/bun:1 as base
173
174WORKDIR /app
175
176# Copy lockfile and package.json for caching
177COPY package.json bun.lock ./
178
179# Install dependencies
180RUN bun install --frozen-lockfile
181
182# Copy source
183COPY . .
184
185# Build
186RUN bun run build
187
188# Production
189FROM oven/bun:1-slim
190WORKDIR /app
191COPY --from=base /app/dist ./dist
192COPY --from=base /app/node_modules ./node_modules
193CMD ["bun", "run", "start"]
194```
195
196## Troubleshooting
197
198### Lockfile Out of Sync
199
200When lockfile doesn't match package.json:
201
202```bash
203# Error: lockfile does not match package.json
204# Solution: Regenerate lockfile
205bun install
206```
207
208### Corrupted or Invalid Lockfile
209
210If the lockfile appears corrupted or has syntax errors:
211
212```bash
213# Remove and regenerate
214rm bun.lock
215bun install
216```
217
218::: tip
219Since `bun.lock` is now text-based, you can often fix minor issues by editing the file directly. However, regenerating is usually safer.
220:::
221
222### Dependency Conflicts
223
224When packages have conflicting versions:
225
226```bash
227# Check for conflicts
228bun pm ls
229
230# Use overrides in package.json
231{
232 "overrides": {
233 "conflicting-package": "^1.0.0"
234 }
235}
236
237# Regenerate lockfile
238bun install
239```
240
241### Platform-Specific Issues
242
243If lockfile works on one platform but not another:
244
245```bash
246# Install without optional dependencies
247bun install --ignore-scripts
248
249# Or specify platform
250{
251 "supportedArchitectures": {
252 "os": ["darwin", "linux", "win32"],
253 "cpu": ["x64", "arm64"]
254 }
255}
256```
257
258### Cache Issues
259
260Clear Bun's cache if experiencing issues:
261
262```bash
263# Clear Bun cache
264bun pm cache rm
265
266# Fresh install
267rm -rf node_modules
268bun install
269```
270
271## Team Collaboration
272
273### Synchronizing Dependencies
274
275When pulling changes with lockfile updates:
276
277```bash
278# Always run install after pulling
279git pull
280bun install
281```
282
283### Resolving Merge Conflicts
284
285When lockfile has merge conflicts:
286
287```bash
288# Accept one version and regenerate
289git checkout --theirs bun.lock # or --ours
290bun install
291git add bun.lock
292git commit -m "resolve lockfile conflict"
293```
294
295Or regenerate fresh:
296
297```bash
298# Remove conflicted file
299rm bun.lock
300
301# Regenerate
302bun install
303
304# Commit
305git add bun.lock
306git commit -m "regenerate lockfile after merge"
307```
308
309::: tip
310Since `bun.lock` is text-based, you can sometimes manually resolve conflicts by editing the file. However, regenerating is usually safer and faster.
311:::
312
313### Dependency Update Workflow
314
315Recommended workflow for updating dependencies:
316
317```bash
318# 1. Create branch
319git checkout -b deps/update-dependencies
320
321# 2. Update dependencies
322bun update
323
324# 3. Run tests
325bun test
326
327# 4. Build to verify
328bun run build
329
330# 5. Commit changes
331git add package.json bun.lock
332git commit -m "chore: update dependencies"
333
334# 6. Create PR
335gh pr create
336```
337
338## Best Practices
339
340### DO
341
342- **Commit bun.lock** - Always include in version control
343- **Use frozen lockfile in CI** - Ensures reproducible builds
344- **Update regularly** - Keep dependencies current for security
345- **Review lockfile changes** - Check what's being updated in PRs
346- **Use exact versions for critical deps** - Avoid unexpected updates
347
348### DON'T
349
350- **Don't ignore the lockfile** - It ensures consistent installs
351- **Don't delete without reinstalling** - Can cause version drift
352- **Don't mix package managers** - Stick with Bun
353
354::: tip
355Unlike the old binary format, you can now safely inspect and even manually edit `bun.lock` if needed. The text-based format makes debugging dependency issues much easier.
356:::
357
358### Security
359
360```bash
361# Audit dependencies
362bun pm audit
363
364# Check for outdated packages
365bun pm outdated
366```
367
368## Converting From Other Package Managers
369
370### From npm
371
372```bash
373# Remove npm artifacts
374rm -rf node_modules package-lock.json
375
376# Install with Bun
377bun install
378```
379
380### From yarn
381
382```bash
383# Remove yarn artifacts
384rm -rf node_modules yarn.lock .yarn
385
386# Install with Bun
387bun install
388```
389
390### From pnpm
391
392```bash
393# Remove pnpm artifacts
394rm -rf node_modules pnpm-lock.yaml
395
396# Install with Bun
397bun install
398```
399
400## Inspecting the Lockfile
401
402### List Installed Packages
403
404```bash
405# List all packages
406bun pm ls
407
408# List specific package
409bun pm ls package-name
410
411# Show why a package is installed
412bun pm why package-name
413```
414
415### Package Information
416
417```bash
418# Get package info
419bun pm info package-name
420
421# Check package versions
422bun pm pack package-name
423```
424
425## Performance Tips
426
427### Faster Installs
428
429```bash
430# Use concurrency (default)
431bun install
432
433# Skip optional dependencies
434bun install --ignore-optional
435
436# Skip postinstall scripts
437bun install --ignore-scripts
438```
439
440### CI Optimization
441
442```yaml
443# Use caching and frozen lockfile
444
445- run: bun install --frozen-lockfile
446
447 env:
448 BUN_INSTALL_CACHE_DIR: ~/.bun/install/cache
449```
450
451## Configuration
452
453### bunfig.toml
454
455```toml
456# bunfig.toml
457
458[install]
459# Use exact versions by default
460exact = true
461
462# Registry configuration
463registry = "https://registry.npmjs.org"
464
465# Scoped registries
466[install.scopes]
467"@mycompany" = "https://npm.mycompany.com"
468
469[install.cache]
470# Cache directory
471dir = "~/.bun/install/cache"
472
473# Disable cache
474# disable = true
475```
476
477### package.json Scripts
478
479```json
480{
481 "scripts": {
482 "preinstall": "npx only-allow bun",
483 "postinstall": "bun run prepare"
484 }
485}
486```
487
488This documentation covers Bun lockfile management for Stacks applications. Each section is designed for reliable dependency management across development and production environments.