also looking at this
Deploy: uniform auth session model (main → production)
#7
282 files
+3028
-64856
| @@ -1,488 +0,0 @@ | ||
| 1 | # Bun Lockfile Management | |
| 2 | ||
| 3 | This 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 | ||
| 7 | Bun 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 | |
| 16 | If 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 | |
| 25 | bun install | |
| 26 | ||
| 27 | # Install with frozen lockfile (CI/CD) | |
| 28 | bun install --frozen-lockfile | |
| 29 | ||
| 30 | # Install and update lockfile | |
| 31 | bun install | |
| 32 | ||
| 33 | # Force fresh install (regenerate lockfile) | |
| 34 | rm -rf node_modules bun.lock && bun install | |
| 35 | ``` | |
| 36 | ||
| 37 | ### Updating Dependencies | |
| 38 | ||
| 39 | ```bash | |
| 40 | # Update all dependencies | |
| 41 | bun update | |
| 42 | ||
| 43 | # Update specific package | |
| 44 | bun update package-name | |
| 45 | ||
| 46 | # Update to latest (ignore semver) | |
| 47 | bun update package-name --latest | |
| 48 | ``` | |
| 49 | ||
| 50 | ### Adding Dependencies | |
| 51 | ||
| 52 | ```bash | |
| 53 | # Add production dependency | |
| 54 | bun add package-name | |
| 55 | ||
| 56 | # Add dev dependency | |
| 57 | bun add -d package-name | |
| 58 | ||
| 59 | # Add exact version | |
| 60 | bun add package-name@1.2.3 | |
| 61 | ||
| 62 | # Add from git | |
| 63 | bun add github:user/repo | |
| 64 | ``` | |
| 65 | ||
| 66 | ### Removing Dependencies | |
| 67 | ||
| 68 | ```bash | |
| 69 | # Remove package | |
| 70 | bun remove package-name | |
| 71 | ``` | |
| 72 | ||
| 73 | ## Version Control | |
| 74 | ||
| 75 | ### Git Configuration | |
| 76 | ||
| 77 | Add to `.gitignore`: | |
| 78 | ||
| 79 | ```gitignore | |
| 80 | # Node modules | |
| 81 | node_modules/ | |
| 82 | ||
| 83 | # DO NOT ignore bun.lock - it should be committed | |
| 84 | # bun.lock | |
| 85 | ``` | |
| 86 | ||
| 87 | ::: info | |
| 88 | Since `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 | ||
| 93 | Always commit `bun.lock` to version control: | |
| 94 | ||
| 95 | ```bash | |
| 96 | git add bun.lock | |
| 97 | git commit -m "chore: update dependencies" | |
| 98 | ``` | |
| 99 | ||
| 100 | ### Viewing Lockfile Changes | |
| 101 | ||
| 102 | Since `bun.lock` is text-based JSONC format, you can view changes directly: | |
| 103 | ||
| 104 | ```bash | |
| 105 | # View lockfile changes | |
| 106 | git diff bun.lock | |
| 107 | ||
| 108 | # View lockfile changes in a PR | |
| 109 | gh pr diff --name-only | grep bun.lock | |
| 110 | ``` | |
| 111 | ||
| 112 | The 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 | |
| 120 | name: CI | |
| 121 | ||
| 122 | on: | |
| 123 | push: | |
| 124 | branches: [main] | |
| 125 | pull_request: | |
| 126 | branches: [main] | |
| 127 | ||
| 128 | jobs: | |
| 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 | |
| 172 | FROM oven/bun:1 as base | |
| 173 | ||
| 174 | WORKDIR /app | |
| 175 | ||
| 176 | # Copy lockfile and package.json for caching | |
| 177 | COPY package.json bun.lock ./ | |
| 178 | ||
| 179 | # Install dependencies | |
| 180 | RUN bun install --frozen-lockfile | |
| 181 | ||
| 182 | # Copy source | |
| 183 | COPY . . | |
| 184 | ||
| 185 | # Build | |
| 186 | RUN bun run build | |
| 187 | ||
| 188 | # Production | |
| 189 | FROM oven/bun:1-slim | |
| 190 | WORKDIR /app | |
| 191 | COPY --from=base /app/dist ./dist | |
| 192 | COPY --from=base /app/node_modules ./node_modules | |
| 193 | CMD ["bun", "run", "start"] | |
| 194 | ``` | |
| 195 | ||
| 196 | ## Troubleshooting | |
| 197 | ||
| 198 | ### Lockfile Out of Sync | |
| 199 | ||
| 200 | When lockfile doesn't match package.json: | |
| 201 | ||
| 202 | ```bash | |
| 203 | # Error: lockfile does not match package.json | |
| 204 | # Solution: Regenerate lockfile | |
| 205 | bun install | |
| 206 | ``` | |
| 207 | ||
| 208 | ### Corrupted or Invalid Lockfile | |
| 209 | ||
| 210 | If the lockfile appears corrupted or has syntax errors: | |
| 211 | ||
| 212 | ```bash | |
| 213 | # Remove and regenerate | |
| 214 | rm bun.lock | |
| 215 | bun install | |
| 216 | ``` | |
| 217 | ||
| 218 | ::: tip | |
| 219 | Since `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 | ||
| 224 | When packages have conflicting versions: | |
| 225 | ||
| 226 | ```bash | |
| 227 | # Check for conflicts | |
| 228 | bun pm ls | |
| 229 | ||
| 230 | # Use overrides in package.json | |
| 231 | { | |
| 232 | "overrides": { | |
| 233 | "conflicting-package": "^1.0.0" | |
| 234 | } | |
| 235 | } | |
| 236 | ||
| 237 | # Regenerate lockfile | |
| 238 | bun install | |
| 239 | ``` | |
| 240 | ||
| 241 | ### Platform-Specific Issues | |
| 242 | ||
| 243 | If lockfile works on one platform but not another: | |
| 244 | ||
| 245 | ```bash | |
| 246 | # Install without optional dependencies | |
| 247 | bun 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 | ||
| 260 | Clear Bun's cache if experiencing issues: | |
| 261 | ||
| 262 | ```bash | |
| 263 | # Clear Bun cache | |
| 264 | bun pm cache rm | |
| 265 | ||
| 266 | # Fresh install | |
| 267 | rm -rf node_modules | |
| 268 | bun install | |
| 269 | ``` | |
| 270 | ||
| 271 | ## Team Collaboration | |
| 272 | ||
| 273 | ### Synchronizing Dependencies | |
| 274 | ||
| 275 | When pulling changes with lockfile updates: | |
| 276 | ||
| 277 | ```bash | |
| 278 | # Always run install after pulling | |
| 279 | git pull | |
| 280 | bun install | |
| 281 | ``` | |
| 282 | ||
| 283 | ### Resolving Merge Conflicts | |
| 284 | ||
| 285 | When lockfile has merge conflicts: | |
| 286 | ||
| 287 | ```bash | |
| 288 | # Accept one version and regenerate | |
| 289 | git checkout --theirs bun.lock # or --ours | |
| 290 | bun install | |
| 291 | git add bun.lock | |
| 292 | git commit -m "resolve lockfile conflict" | |
| 293 | ``` | |
| 294 | ||
| 295 | Or regenerate fresh: | |
| 296 | ||
| 297 | ```bash | |
| 298 | # Remove conflicted file | |
| 299 | rm bun.lock | |
| 300 | ||
| 301 | # Regenerate | |
| 302 | bun install | |
| 303 | ||
| 304 | # Commit | |
| 305 | git add bun.lock | |
| 306 | git commit -m "regenerate lockfile after merge" | |
| 307 | ``` | |
| 308 | ||
| 309 | ::: tip | |
| 310 | Since `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 | ||
| 315 | Recommended workflow for updating dependencies: | |
| 316 | ||
| 317 | ```bash | |
| 318 | # 1. Create branch | |
| 319 | git checkout -b deps/update-dependencies | |
| 320 | ||
| 321 | # 2. Update dependencies | |
| 322 | bun update | |
| 323 | ||
| 324 | # 3. Run tests | |
| 325 | bun test | |
| 326 | ||
| 327 | # 4. Build to verify | |
| 328 | bun run build | |
| 329 | ||
| 330 | # 5. Commit changes | |
| 331 | git add package.json bun.lock | |
| 332 | git commit -m "chore: update dependencies" | |
| 333 | ||
| 334 | # 6. Create PR | |
| 335 | gh 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 | |
| 355 | Unlike 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 | |
| 362 | bun pm audit | |
| 363 | ||
| 364 | # Check for outdated packages | |
| 365 | bun pm outdated | |
| 366 | ``` | |
| 367 | ||
| 368 | ## Converting From Other Package Managers | |
| 369 | ||
| 370 | ### From npm | |
| 371 | ||
| 372 | ```bash | |
| 373 | # Remove npm artifacts | |
| 374 | rm -rf node_modules package-lock.json | |
| 375 | ||
| 376 | # Install with Bun | |
| 377 | bun install | |
| 378 | ``` | |
| 379 | ||
| 380 | ### From yarn | |
| 381 | ||
| 382 | ```bash | |
| 383 | # Remove yarn artifacts | |
| 384 | rm -rf node_modules yarn.lock .yarn | |
| 385 | ||
| 386 | # Install with Bun | |
| 387 | bun install | |
| 388 | ``` | |
| 389 | ||
| 390 | ### From pnpm | |
| 391 | ||
| 392 | ```bash | |
| 393 | # Remove pnpm artifacts | |
| 394 | rm -rf node_modules pnpm-lock.yaml | |
| 395 | ||
| 396 | # Install with Bun | |
| 397 | bun install | |
| 398 | ``` | |
| 399 | ||
| 400 | ## Inspecting the Lockfile | |
| 401 | ||
| 402 | ### List Installed Packages | |
| 403 | ||
| 404 | ```bash | |
| 405 | # List all packages | |
| 406 | bun pm ls | |
| 407 | ||
| 408 | # List specific package | |
| 409 | bun pm ls package-name | |
| 410 | ||
| 411 | # Show why a package is installed | |
| 412 | bun pm why package-name | |
| 413 | ``` | |
| 414 | ||
| 415 | ### Package Information | |
| 416 | ||
| 417 | ```bash | |
| 418 | # Get package info | |
| 419 | bun pm info package-name | |
| 420 | ||
| 421 | # Check package versions | |
| 422 | bun pm pack package-name | |
| 423 | ``` | |
| 424 | ||
| 425 | ## Performance Tips | |
| 426 | ||
| 427 | ### Faster Installs | |
| 428 | ||
| 429 | ```bash | |
| 430 | # Use concurrency (default) | |
| 431 | bun install | |
| 432 | ||
| 433 | # Skip optional dependencies | |
| 434 | bun install --ignore-optional | |
| 435 | ||
| 436 | # Skip postinstall scripts | |
| 437 | bun 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 | |
| 460 | exact = true | |
| 461 | ||
| 462 | # Registry configuration | |
| 463 | registry = "https://registry.npmjs.org" | |
| 464 | ||
| 465 | # Scoped registries | |
| 466 | [install.scopes] | |
| 467 | "@mycompany" = "https://npm.mycompany.com" | |
| 468 | ||
| 469 | [install.cache] | |
| 470 | # Cache directory | |
| 471 | dir = "~/.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 | ||
| 488 | This documentation covers Bun lockfile management for Stacks applications. Each section is designed for reliable dependency management across development and production environments. | |