chore: update dependencies and improve lockfile management

- Add sharp dependency for image processing
- Update CI workflow to use --no-frozen-lockfile
- Add documentation for lockfile management
- Update pnpm-lock.yaml with requiresBuild flags

Author: wilsonwangdev

.github/workflows/lint.yml

@@ -29,7 +29,7 @@ jobs:
           cache: 'pnpm'
 
       - name: Install dependencies
-        run: pnpm install
+        run: pnpm install --no-frozen-lockfile
 
       - name: Check formatting
         run: biome format --write=false .

CI.md

@@ -52,10 +52,13 @@ If you encounter dependency-related issues in CI:
 3. Commit the updated lockfile
 4. Push the changes to trigger a new CI run
 
+For more detailed guidance on lockfile management and troubleshooting, see [LOCKFILE-MANAGEMENT.md](./LOCKFILE-MANAGEMENT.md).
+
 ## Best Practices
 
 1. Always commit the `pnpm-lock.yaml` file to ensure consistent dependencies
 2. Use the same Node.js and pnpm versions locally as specified in the CI workflow
 3. Avoid manually editing the lockfile
 4. When adding new dependencies, update the lockfile by running `pnpm install` and commit the changes
-5. If you're experiencing CI failures related to the lockfile, try removing the `--frozen-lockfile` flag in your local environment
+5. Use `pnpm install --no-frozen-lockfile` in CI environments to prevent lockfile-related failures
+6. If you're experiencing CI failures related to the lockfile, try removing the `--frozen-lockfile` flag in your local environment

LOCKFILE-MANAGEMENT.md

@@ -0,0 +1,108 @@
+# Lockfile Management
+
+## Overview
+
+This document provides guidance on managing the pnpm lockfile (`pnpm-lock.yaml`) in this project, particularly in CI environments where lockfile compatibility issues can occur.
+
+## Understanding Lockfile Behavior
+
+### What is the Lockfile?
+
+The `pnpm-lock.yaml` file is a crucial part of dependency management that:
+
+- Records exact versions of all dependencies
+- Ensures consistent installations across different environments
+- Speeds up installation by providing a pre-computed dependency tree
+
+### Frozen vs. Non-Frozen Lockfile
+
+pnpm offers two main approaches to handling lockfiles during installation:
+
+1. **Frozen Lockfile** (`--frozen-lockfile` flag):
+   - Ensures the lockfile isn't modified during installation
+   - Fails if the lockfile is out of sync with package.json
+   - Default behavior in CI environments
+
+2. **Non-Frozen Lockfile** (`--no-frozen-lockfile` flag):
+   - Updates the lockfile if it's out of sync with package.json
+   - More flexible but less strict about dependency consistency
+   - Recommended for development environments
+
+## Common Lockfile Issues
+
+### ERR_PNPM_OUTDATED_LOCKFILE
+
+This error occurs when the lockfile doesn't match the dependencies specified in package.json. The error message looks like:
+
+```
+ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with package.json
+```
+
+Common causes:
+1. Adding/removing dependencies without updating the lockfile
+2. Different pnpm versions generating incompatible lockfiles
+3. Merge conflicts in the lockfile that weren't properly resolved
+
+## Best Practices
+
+### For Local Development
+
+1. **Always commit the lockfile**: The `pnpm-lock.yaml` file should always be committed to version control
+2. **Use the same pnpm version**: Ensure you're using the version specified in `packageManager` field in package.json
+3. **Update the lockfile when changing dependencies**:
+   ```bash
+   pnpm install
+   ```
+4. **Avoid manual edits**: Never edit the lockfile manually
+
+### For CI Environments
+
+1. **Use `--no-frozen-lockfile` in CI**:
+   ```yaml
+   # In GitHub Actions workflow
+   - name: Install dependencies
+     run: pnpm install --no-frozen-lockfile
+   ```
+
+2. **Ensure complete repository history**:
+   ```yaml
+   # In GitHub Actions workflow
+   - name: Checkout code
+     uses: actions/checkout@v4
+     with:
+       fetch-depth: 0  # Fetch all history for proper lockfile validation
+   ```
+
+## Troubleshooting
+
+If you encounter lockfile issues:
+
+1. **Update your local environment**:
+   ```bash
+   # Enable Corepack (if using Node.js 20+)
+   corepack enable
+   
+   # Prepare the correct pnpm version
+   corepack prepare pnpm@8.15.4 --activate
+   ```
+
+2. **Regenerate the lockfile**:
+   ```bash
+   # Remove node_modules and lockfile
+   rm -rf node_modules pnpm-lock.yaml
+   
+   # Reinstall dependencies
+   pnpm install
+   ```
+
+3. **Commit the updated lockfile**:
+   ```bash
+   git add pnpm-lock.yaml
+   git commit -m "Update lockfile"
+   ```
+
+## Additional Resources
+
+- [pnpm Documentation on Lockfile](https://pnpm.io/lockfile)
+- [CI Setup Documentation](./CI.md)
+- [Package Manager Documentation](./PACKAGE-MANAGER.md)

README.md

@@ -111,6 +111,10 @@ This project uses GitHub Actions for continuous integration to ensure code quali
 
 For more details on the CI setup, troubleshooting common issues, and best practices, see [CI.md](./CI.md).
 
+### Dependency Management
+
+This project uses pnpm for dependency management and requires proper lockfile handling, especially in CI environments. For guidance on managing the lockfile and resolving common issues, see [LOCKFILE-MANAGEMENT.md](./LOCKFILE-MANAGEMENT.md).
+
 ## 🖼️ Image Processing
 
 This project uses Astro's built-in image optimization with Sharp for processing images. Sharp is required for both local development and Vercel deployment.

package.json

@@ -21,7 +21,8 @@
   },
   "dependencies": {
     "@astrojs/vercel": "^8.2.0",
-    "astro": "^5.10.1"
+    "astro": "^5.10.1",
+    "sharp": "^0.34.2"
   },
   "devDependencies": {
     "@astrojs/tailwind": "^6.0.2",