Initial commit

2025-11-29 17:59:44 +08:00
commit 7e2a535be7
8 changed files with 2972 additions and 0 deletions
--- a/skills/wrangler-deployment/SKILL.md
+++ b/skills/wrangler-deployment/SKILL.md
@@ -0,0 +1,755 @@
+# Wrangler Deployment Skill
+
+Expert knowledge for deploying static sites to Cloudflare Pages using Wrangler CLI.
+
+## Overview
+
+This skill provides comprehensive patterns, best practices, and troubleshooting guidance for deploying web applications to Cloudflare Pages using the official Wrangler CLI tool.
+
+## Prerequisites
+
+### Required Tools
+
+1. **Wrangler CLI** (>= 3.0.0)
+   ```bash
+   npm install -g wrangler
+   ```
+
+2. **Node.js** (>= 18.0.0)
+   ```bash
+   node --version  # Should be >= v18.0.0
+   ```
+
+3. **Cloudflare Account**
+   - Free account sufficient for most use cases
+   - Pages included in all plans
+   - Sign up: https://dash.cloudflare.com/sign-up
+
+### Authentication Setup
+
+```bash
+# Method 1: OAuth (recommended for local development)
+wrangler login
+# Opens browser for authentication
+
+# Method 2: API Token (recommended for CI/CD)
+export CLOUDFLARE_API_TOKEN=your-token-here
+wrangler whoami  # Verify authentication
+
+# Verify authentication
+wrangler whoami
+# Output should show: "You are logged in as user@example.com"
+```
+
+## Core Concepts
+
+### Cloudflare Pages Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│           Your Source Code                  │
+│  (React, Vue, Svelte, Next.js, etc.)       │
+└────────────────┬────────────────────────────┘
+                 │
+                 ▼
+┌─────────────────────────────────────────────┐
+│         Build Process (Local)               │
+│  npm run build → generates static files     │
+└────────────────┬────────────────────────────┘
+                 │
+                 ▼
+┌─────────────────────────────────────────────┐
+│       Wrangler CLI Upload                   │
+│  wrangler pages deploy ./dist               │
+└────────────────┬────────────────────────────┘
+                 │
+                 ▼
+┌─────────────────────────────────────────────┐
+│     Cloudflare Global CDN                   │
+│  300+ Edge locations worldwide              │
+│  Automatic HTTPS, DDoS protection           │
+└─────────────────────────────────────────────┘
+```
+
+### Deployment Types
+
+**1. Production Deployment**
+- Triggered from main/master branch
+- Gets production URL: `https://project-name.pages.dev`
+- Visible to all users
+- Should be stable and tested
+
+**2. Preview Deployment**
+- Triggered from any other branch
+- Gets unique preview URL: `https://abc123.project-name.pages.dev`
+- Used for testing before production
+- Automatically cleaned up after branch deletion
+
+## Deployment Patterns
+
+### Pattern 1: Basic Deployment
+
+```bash
+# Step 1: Build your project
+npm run build
+
+# Step 2: Deploy to Cloudflare Pages
+wrangler pages deploy ./dist --project-name=my-website
+```
+
+**When to use:**
+- First deployment
+- Simple static sites
+- Quick prototyping
+- Manual deployments
+
+### Pattern 2: Branch-Based Deployment
+
+```bash
+# Production deployment (main branch)
+git checkout main
+npm run build
+wrangler pages deploy ./dist \
+  --project-name=my-website \
+  --branch=main
+
+# Preview deployment (feature branch)
+git checkout feature/new-design
+npm run build
+wrangler pages deploy ./dist \
+  --project-name=my-website \
+  --branch=feature/new-design
+```
+
+**When to use:**
+- Git-based workflows
+- Multiple environments
+- Preview before production
+- Team collaboration
+
+### Pattern 3: CI/CD Deployment
+
+```yaml
+# GitHub Actions example
+name: Deploy to Cloudflare Pages
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Deploy to Cloudflare Pages
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          command: pages deploy ./dist --project-name=my-website --branch=${{ github.ref_name }}
+```
+
+**When to use:**
+- Automated deployments
+- Continuous deployment
+- Team workflows
+- Production systems
+
+### Pattern 4: Monorepo Deployment
+
+```bash
+# Deploy specific workspace from monorepo
+cd packages/website
+npm run build
+wrangler pages deploy ./dist \
+  --project-name=my-website-frontend \
+  --branch=main
+
+cd ../admin
+npm run build
+wrangler pages deploy ./dist \
+  --project-name=my-website-admin \
+  --branch=main
+```
+
+**When to use:**
+- Multiple related projects
+- Shared dependencies
+- Coordinated deployments
+- Large applications
+
+## Build Configuration
+
+### Common Framework Patterns
+
+#### React (Create React App)
+
+```json
+{
+  "scripts": {
+    "build": "react-scripts build"
+  }
+}
+```
+
+Build output: `build/`
+
+```bash
+npm run build
+wrangler pages deploy ./build --project-name=my-react-app
+```
+
+#### Vue.js
+
+```json
+{
+  "scripts": {
+    "build": "vue-cli-service build"
+  }
+}
+```
+
+Build output: `dist/`
+
+```bash
+npm run build
+wrangler pages deploy ./dist --project-name=my-vue-app
+```
+
+#### Next.js (Static Export)
+
+```json
+{
+  "scripts": {
+    "build": "next build && next export"
+  }
+}
+```
+
+Build output: `out/`
+
+```bash
+npm run build
+wrangler pages deploy ./out --project-name=my-nextjs-app
+```
+
+#### Svelte
+
+```json
+{
+  "scripts": {
+    "build": "vite build"
+  }
+}
+```
+
+Build output: `dist/`
+
+```bash
+npm run build
+wrangler pages deploy ./dist --project-name=my-svelte-app
+```
+
+#### Astro
+
+```json
+{
+  "scripts": {
+    "build": "astro build"
+  }
+}
+```
+
+Build output: `dist/`
+
+```bash
+npm run build
+wrangler pages deploy ./dist --project-name=my-astro-app
+```
+
+#### Hugo
+
+```bash
+# Hugo generates static files directly
+hugo --minify
+
+# Deploy
+wrangler pages deploy ./public --project-name=my-hugo-blog
+```
+
+Build output: `public/`
+
+## Advanced Deployment Options
+
+### Include Git Metadata
+
+```bash
+wrangler pages deploy ./dist \
+  --project-name=my-website \
+  --branch=$(git branch --show-current) \
+  --commit-hash=$(git rev-parse HEAD) \
+  --commit-message="$(git log -1 --pretty=%B)"
+```
+
+**Benefits:**
+- Trace deployments to source code
+- Better deployment history
+- Easier debugging
+- Audit trail
+
+### Specify Compatibility Date
+
+```bash
+wrangler pages deploy ./dist \
+  --project-name=my-website \
+  --compatibility-date=2025-01-15
+```
+
+**Use when:**
+- Using Cloudflare-specific features
+- Ensuring consistent behavior
+- Testing new platform features
+
+### Custom Headers
+
+Create `_headers` file in your build output:
+
+```
+# _headers file
+/*
+  X-Frame-Options: DENY
+  X-Content-Type-Options: nosniff
+  Referrer-Policy: strict-origin-when-cross-origin
+
+/api/*
+  Access-Control-Allow-Origin: *
+
+/assets/*
+  Cache-Control: public, max-age=31536000, immutable
+```
+
+Then deploy normally - Cloudflare Pages automatically applies headers.
+
+### Redirects & Rewrites
+
+Create `_redirects` file in your build output:
+
+```
+# _redirects file
+
+# Redirect old blog to new location
+/blog/* https://blog.example.com/:splat 301
+
+# SPA fallback
+/* /index.html 200
+
+# Temporary redirect
+/old-page /new-page 302
+
+# Domain redirect
+https://www.example.com/* https://example.com/:splat 301
+```
+
+## Environment Variables & Secrets
+
+### Setting Secrets
+
+```bash
+# Interactive prompt (recommended for sensitive data)
+wrangler pages secret put API_KEY --project-name=my-website
+
+# From file
+cat api-key.txt | wrangler pages secret put API_KEY --project-name=my-website
+
+# From environment variable
+echo "$MY_SECRET" | wrangler pages secret put API_KEY --project-name=my-website
+```
+
+### Listing Secrets
+
+```bash
+# List all secrets (values are hidden)
+wrangler pages secret list --project-name=my-website
+```
+
+Output:
+```
+Secret Name       Uploaded At
+API_KEY           2025-01-15T10:30:00Z
+DATABASE_URL      2025-01-14T15:20:00Z
+STRIPE_KEY        2025-01-13T09:45:00Z
+```
+
+### Accessing Secrets in Pages Functions
+
+```javascript
+// functions/api/hello.js
+export async function onRequest(context) {
+  const apiKey = context.env.API_KEY;
+
+  return new Response(JSON.stringify({
+    message: 'Hello from Cloudflare Pages!',
+    authenticated: !!apiKey
+  }), {
+    headers: { 'Content-Type': 'application/json' }
+  });
+}
+```
+
+### Build-Time vs Runtime Variables
+
+**Build-time** (set during `npm run build`):
+```bash
+# .env file
+VITE_API_URL=https://api.example.com
+NEXT_PUBLIC_GA_ID=UA-XXXXXXX
+```
+
+**Runtime** (set via Wrangler):
+```bash
+# Secrets accessible in Pages Functions
+wrangler pages secret put STRIPE_SECRET_KEY --project-name=my-website
+```
+
+## Troubleshooting
+
+### Issue: "Command not found: wrangler"
+
+**Cause:** Wrangler CLI not installed or not in PATH
+
+**Solution:**
+```bash
+# Install globally
+npm install -g wrangler
+
+# Or use with npx
+npx wrangler pages deploy ./dist --project-name=my-website
+
+# Verify installation
+which wrangler
+wrangler --version
+```
+
+### Issue: "You are not authenticated"
+
+**Cause:** Not logged in to Cloudflare
+
+**Solution:**
+```bash
+# Login via OAuth
+wrangler login
+
+# Or set API token
+export CLOUDFLARE_API_TOKEN=your-token-here
+
+# Verify authentication
+wrangler whoami
+```
+
+### Issue: "Build directory not found"
+
+**Cause:** Build hasn't run or wrong directory specified
+
+**Solution:**
+```bash
+# Check if build directory exists
+ls -la dist/  # or build/ or out/
+
+# Run build command
+npm run build
+
+# Verify build output
+ls -lah dist/
+
+# Check common locations
+for dir in dist build out public .next/out; do
+  [ -d "$dir" ] && echo "Found: $dir"
+done
+```
+
+### Issue: "Project not found"
+
+**Cause:** Project doesn't exist in Cloudflare account
+
+**Solution:**
+```bash
+# List existing projects
+wrangler pages project list
+
+# Create new project (happens automatically on first deploy)
+wrangler pages deploy ./dist --project-name=my-new-project
+
+# Or create via dashboard:
+# https://dash.cloudflare.com/pages
+```
+
+### Issue: "Rate limit exceeded"
+
+**Cause:** Too many API requests in short time
+
+**Solution:**
+```bash
+# Wait indicated time (usually 60 seconds)
+sleep 60
+
+# Retry deployment
+wrangler pages deploy ./dist --project-name=my-website
+
+# Check for concurrent deployments
+ps aux | grep wrangler
+
+# Verify API token isn't being used elsewhere
+```
+
+### Issue: "File too large"
+
+**Cause:** Individual file exceeds 25MB limit
+
+**Solution:**
+```bash
+# Find large files
+find dist/ -type f -size +25M
+
+# Optimize images
+# - Use modern formats (WebP, AVIF)
+# - Compress with tools like imagemin
+# - Use responsive images
+
+# Split large bundles
+# - Code splitting in webpack/vite
+# - Dynamic imports
+# - Lazy loading
+
+# Use external hosting for large files
+# - Cloudflare R2
+# - AWS S3
+# - CDN for media files
+```
+
+### Issue: "Deployment successful but site not updating"
+
+**Cause:** Browser cache or CDN cache
+
+**Solution:**
+```bash
+# Hard refresh browser
+# Chrome/Firefox: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
+
+# Check deployment was successful
+wrangler pages deployment list --project-name=my-website
+
+# Verify latest deployment is active
+curl -I https://my-website.pages.dev
+
+# Purge Cloudflare cache (if using custom domain)
+# Via dashboard: Cache → Purge Everything
+```
+
+### Issue: "404 errors after deployment"
+
+**Cause:** SPA routing not configured
+
+**Solution:**
+```bash
+# Create _redirects file
+cat > dist/_redirects <<EOF
+/* /index.html 200
+EOF
+
+# Or create _routes.json for more control
+cat > dist/_routes.json <<EOF
+{
+  "version": 1,
+  "include": ["/*"],
+  "exclude": ["/api/*"]
+}
+EOF
+
+# Redeploy
+wrangler pages deploy ./dist --project-name=my-website
+```
+
+## Performance Optimization
+
+### Enable Compression
+
+Cloudflare automatically compresses responses, but you can pre-compress:
+
+```bash
+# Pre-compress files with gzip
+find dist/ -type f \( -name "*.js" -o -name "*.css" -o -name "*.html" \) -exec gzip -k {} \;
+
+# Pre-compress with brotli
+find dist/ -type f \( -name "*.js" -o -name "*.css" -o -name "*.html" \) -exec brotli -k {} \;
+```
+
+### Optimize Assets
+
+```bash
+# Minify JavaScript and CSS (usually done by build tool)
+npm run build  # with production mode
+
+# Optimize images
+npx @squoosh/cli --output-dir dist/images optimized/ *.{jpg,png}
+
+# Remove source maps in production
+# (configure in webpack/vite config)
+```
+
+### Cache Control Headers
+
+```
+# _headers file
+/static/*
+  Cache-Control: public, max-age=31536000, immutable
+
+/*.html
+  Cache-Control: public, max-age=0, must-revalidate
+
+/api/*
+  Cache-Control: private, no-cache
+```
+
+## Deployment Verification
+
+### Automated Checks
+
+```bash
+#!/bin/bash
+# deploy-verify.sh
+
+PROJECT_NAME="my-website"
+DEPLOY_URL="https://$PROJECT_NAME.pages.dev"
+
+# Deploy
+wrangler pages deploy ./dist --project-name=$PROJECT_NAME
+
+# Wait for deployment to propagate
+sleep 10
+
+# Check HTTP status
+STATUS=$(curl -o /dev/null -s -w "%{http_code}" $DEPLOY_URL)
+if [ "$STATUS" -eq 200 ]; then
+  echo "✅ Deployment successful: $DEPLOY_URL"
+else
+  echo "❌ Deployment failed: HTTP $STATUS"
+  exit 1
+fi
+
+# Check critical pages
+for page in "/about" "/contact" "/blog"; do
+  STATUS=$(curl -o /dev/null -s -w "%{http_code}" "$DEPLOY_URL$page")
+  if [ "$STATUS" -eq 200 ]; then
+    echo "✅ $page is accessible"
+  else
+    echo "⚠️  $page returned HTTP $STATUS"
+  fi
+done
+```
+
+### Manual Verification Checklist
+
+- [ ] Deployment URL accessible
+- [ ] Homepage loads correctly
+- [ ] All pages render properly
+- [ ] Images load
+- [ ] Forms work
+- [ ] API endpoints respond
+- [ ] Mobile layout correct
+- [ ] HTTPS enabled
+- [ ] Performance acceptable (Lighthouse check)
+- [ ] No console errors
+
+## Best Practices
+
+### 1. Version Control Integration
+
+```bash
+# Tag releases
+git tag -a v1.0.0 -m "Production release v1.0.0"
+git push --tags
+
+# Deploy with version info
+wrangler pages deploy ./dist \
+  --project-name=my-website \
+  --commit-hash=$(git rev-parse HEAD)
+```
+
+### 2. Environment-Specific Builds
+
+```bash
+# Development build
+NODE_ENV=development npm run build
+wrangler pages deploy ./dist --project-name=my-website --branch=dev
+
+# Production build
+NODE_ENV=production npm run build
+wrangler pages deploy ./dist --project-name=my-website --branch=main
+```
+
+### 3. Security Headers
+
+```
+# _headers file
+/*
+  X-Frame-Options: DENY
+  X-Content-Type-Options: nosniff
+  X-XSS-Protection: 1; mode=block
+  Referrer-Policy: strict-origin-when-cross-origin
+  Permissions-Policy: accelerometer=(), camera=(), geolocation=(), microphone=()
+  Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
+```
+
+### 4. Clean Build Before Deploy
+
+```bash
+# Remove old build artifacts
+rm -rf dist/
+
+# Fresh build
+npm run build
+
+# Verify build output
+ls -lah dist/
+
+# Deploy
+wrangler pages deploy ./dist --project-name=my-website
+```
+
+### 5. Rollback Strategy
+
+```bash
+# List recent deployments
+wrangler pages deployment list --project-name=my-website
+
+# Save deployment IDs
+# Production: abc123def456
+# Previous: xyz789ghi012
+
+# Rollback if needed
+wrangler pages deployment promote xyz789ghi012 --project-name=my-website
+```
+
+## Resources
+
+- **Wrangler CLI Docs**: https://developers.cloudflare.com/workers/wrangler/
+- **Pages Platform Docs**: https://developers.cloudflare.com/pages/
+- **Direct Upload Guide**: https://developers.cloudflare.com/pages/get-started/direct-upload/
+- **Framework Guides**: https://developers.cloudflare.com/pages/framework-guides/
+- **Cloudflare Community**: https://community.cloudflare.com/
+- **Status Page**: https://www.cloudflarestatus.com/