Deploying to Production

Original source / Raw SKILL.md

---
name: Deploying to Production
description: Automates GitHub repository creation and Vercel deployment for Next.js websites. Use when deploying new websites, pushing to production, setting up CI/CD pipelines, or when the user mentions deployment, GitHub, Vercel, or going live.
---

# Deploying to Production

Automated deployment workflow for Next.js websites using GitHub and Vercel.

## When to use this Skill

- Creating a new website and need to deploy it
- Setting up GitHub repository for version control
- Deploying to Vercel production environment
- User mentions: "deploy", "GitHub", "Vercel", "go live", "publish"

## Deployment Workflow

Copy this checklist and track your progress:

```
Deployment Progress:
- [ ] Step 1: Pre-deployment validation (build + E-E-A-T check)
- [ ] Step 2: Create GitHub repository
- [ ] Step 3: Push code to GitHub
- [ ] Step 4: Deploy to Vercel
- [ ] Step 5: Post-deployment verification
```

### Step 1: Pre-deployment validation

**Run build and verify no errors**:
```bash
cd "$PROJECT_DIR"
npm run build
```

**CRITICAL: Only proceed if build succeeds with no errors.**

**Pre-deployment checklist** - See [CHECKLIST.md](CHECKLIST.md) for complete list:
- [ ] `npm run build` completes successfully
- [ ] All environment variables configured
- [ ] E-E-A-T elements present (About page, author info)
- [ ] Core Web Vitals acceptable
- [ ] SEO meta tags complete

### Step 2: Create GitHub repository

Run the script to create a private GitHub repository:

```bash
bash scripts/create-github-repo.sh <project-name>
```

**What this script does**:
- Creates a private GitHub repository
- Initializes Git (if needed)
- Commits all changes
- Pushes to GitHub

**If the script fails**, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).

### Step 3: Verify GitHub push

Check the repository URL:
```bash
gh repo view --web
```

Verify all files are pushed correctly.

### Step 4: Deploy to Vercel

Run the deployment script:

```bash
bash scripts/deploy-to-vercel.sh <project-name>
```

**What this script does**:
- Links the project to Vercel
- Deploys to production environment
- Returns deployment URL

**If deployment fails**, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).

### Step 5: Post-deployment verification

**Verify deployment**:
1. Visit the deployment URL
2. Test core functionality:
   - Homepage loads correctly
   - Navigation works
   - Core features functional
3. Check Core Web Vitals (use PageSpeed Insights)
4. Verify SEO meta tags (use browser inspector)

**If issues found**:
- Review Vercel build logs: `vercel logs`
- Check environment variables in Vercel dashboard
- Verify DNS settings (if custom domain)
- Return to Step 1 and fix issues

**Only mark deployment complete when all verifications pass.**

## Script locations

All deployment scripts are in the `scripts/` directory:
- `create-github-repo.sh` - GitHub repository creation
- `deploy-to-vercel.sh` - Vercel deployment

## Important notes

**Prerequisites**:
- GitHub CLI (`gh`) installed and authenticated
- Vercel CLI installed and authenticated
- Project must be in `/Volumes/Time/go to wild/websites/` directory

**Project naming convention**:
- Format: `keyword-site-lang` (e.g., `pdf-converter-jp`)
- Use lowercase and hyphens only

**Environment variables**:
- Configure in Vercel dashboard after first deployment
- Required variables depend on project features (database, auth, etc.)

## Next steps after deployment

1. **Set up monitoring**:
   - Add Google Analytics or Plausible
   - Configure Google Search Console
   - Set up Vercel Analytics

2. **Configure custom domain** (if needed):
   - Add domain in Vercel dashboard
   - Update DNS records
   - Wait for SSL certificate

3. **Enable automatic deployments**:
   - Push to `main` branch auto-deploys to production
   - Push to other branches creates preview deployments

For detailed troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### CHECKLIST.md

```markdown
# Pre-Deployment Checklist

Comprehensive checklist for deploying websites to production. This ensures code quality, SEO compliance, and E-E-A-T standards.

## Code Quality

### Build and Compilation
- [ ] `npm run build` completes successfully with no errors
- [ ] No TypeScript errors
- [ ] No ESLint warnings (or only acceptable warnings)
- [ ] All imports resolve correctly

### Functionality
- [ ] All core features tested and working
- [ ] Forms submit correctly
- [ ] Navigation works on all pages
- [ ] Links are not broken
- [ ] Images load properly

### Responsive Design
- [ ] Tested on mobile devices (or responsive mode)
- [ ] Tested on tablet devices
- [ ] Tested on desktop
- [ ] All breakpoints work correctly

## SEO Elements

### Meta Tags
- [ ] All pages have unique `<title>` tags (50-60 characters)
- [ ] All pages have unique `<meta description>` (150-160 characters)
- [ ] Open Graph tags configured (`og:title`, `og:description`, `og:image`)
- [ ] Twitter Card tags configured
- [ ] Canonical URLs set correctly

### Structured Data
- [ ] JSON-LD structured data added (WebSite, Organization, etc.)
- [ ] Schema.org markup valid (test with Google Rich Results Test)

### Sitemap and Robots
- [ ] `sitemap.xml` exists and includes all pages
- [ ] `robots.txt` configured correctly
- [ ] All language versions included in sitemap (for i18n sites)

### Internationalization (if applicable)
- [ ] `hreflang` tags configured for all language versions
- [ ] Language switcher works correctly
- [ ] URLs follow correct structure (`/en/`, `/ja/`, etc.)

## E-E-A-T Standards

### Experience & Expertise
- [ ] Content based on real experience (not AI-generated without review)
- [ ] First-hand usage examples included
- [ ] Real data and screenshots (not fabricated)

### Authoritativeness
- [ ] About page exists and shows professional background
- [ ] Author bio links to personal website or portfolio
- [ ] Content aligns with author's professional expertise

### Trustworthiness
- [ ] Contact information provided
- [ ] Privacy policy page exists (if collecting data)
- [ ] Terms of service page exists (if needed)
- [ ] AI usage disclosed transparently
- [ ] All claims are verifiable

## Performance

### Core Web Vitals
- [ ] LCP (Largest Contentful Paint) < 2.5s
- [ ] FCP (First Contentful Paint) < 1.8s
- [ ] TBT (Total Blocking Time) < 200ms
- [ ] CLS (Cumulative Layout Shift) < 0.1

### Optimization
- [ ] Images optimized (WebP format, proper sizing)
- [ ] JavaScript bundles minimized
- [ ] CSS optimized (unused styles removed)
- [ ] Fonts optimized (subset, preload)

### Caching
- [ ] Static assets have cache headers
- [ ] API responses cached appropriately

## Security

### HTTPS
- [ ] SSL certificate configured (Vercel provides automatically)
- [ ] All resources loaded over HTTPS

### Headers
- [ ] Security headers configured (CSP, X-Frame-Options, etc.)
- [ ] CORS configured correctly (if needed)

## Configuration

### Environment Variables
- [ ] All required environment variables documented
- [ ] Production environment variables configured in Vercel
- [ ] No secrets committed to repository

### Dependencies
- [ ] All dependencies up to date (or intentionally pinned)
- [ ] No known security vulnerabilities (`npm audit`)

## Analytics and Monitoring

### Analytics Setup
- [ ] Google Analytics or Plausible configured
- [ ] Analytics tracking code added to all pages
- [ ] Consent banner implemented (if needed for GDPR)

### Search Console
- [ ] Google Search Console property created (can be done after deployment)
- [ ] Sitemap submitted to Search Console (post-deployment)

## Project-Specific Checks

### Database (if applicable)
- [ ] Database migrations run successfully
- [ ] Connection strings configured in Vercel
- [ ] Database backups configured

### Authentication (if applicable)
- [ ] Auth providers configured (Google, GitHub, etc.)
- [ ] Callback URLs set correctly
- [ ] Session management working

### Payment (if applicable)
- [ ] Payment gateway configured (Stripe, etc.)
- [ ] Webhook endpoints configured
- [ ] Test mode disabled, production keys active

## Final Verification

### Manual Testing
- [ ] Homepage loads in under 3 seconds
- [ ] All CTAs (Call to Actions) work correctly
- [ ] Error pages (404, 500) render correctly
- [ ] Favicon displays correctly

### Pre-Launch Review
- [ ] All TODO comments removed or documented
- [ ] Console logs removed (or debug mode off)
- [ ] No placeholder content ("Lorem ipsum", etc.)
- [ ] Version number updated (if versioning)

## Post-Deployment Tasks

These can be done after deployment:
- [ ] Submit sitemap to Google Search Console
- [ ] Submit to Bing Webmaster Tools
- [ ] Monitor initial crawl activity
- [ ] Check indexing status after 24-48 hours
- [ ] Set up uptime monitoring (UptimeRobot, etc.)

---

**Remember**: If any critical item fails, fix it before deploying. It's easier to fix issues before launch than after.

Use this checklist as a guide, but always apply judgment based on the specific project needs.

```

### TROUBLESHOOTING.md

```markdown
# Deployment Troubleshooting

Common issues and solutions for GitHub and Vercel deployment.

## GitHub Repository Creation Issues

### Error: "GitHub CLI (gh) not installed"

**Cause**: GitHub CLI is not installed on the system.

**Solution**:
```bash
# Install GitHub CLI
brew install gh

# Authenticate
gh auth login
```

Follow the prompts to authenticate with your GitHub account.

### Error: "GitHub CLI not logged in"

**Cause**: GitHub CLI is installed but not authenticated.

**Solution**:
```bash
gh auth login
```

Select "GitHub.com", choose authentication method (browser or token), and complete the login flow.

### Error: "Repository already exists"

**Cause**: A repository with the same name already exists in your GitHub account.

**Solution**:

Option 1 - Use existing repository:
```bash
# Add remote manually
git remote add origin https://github.com/YOUR_USERNAME/REPO_NAME.git
git push -u origin main
```

Option 2 - Rename the project:
```bash
# Rename project directory
mv old-name new-name

# Run script with new name
bash scripts/create-github-repo.sh new-name
```

Option 3 - Delete existing repository:
```bash
# Delete via CLI (careful!)
gh repo delete REPO_NAME --yes

# Then run script again
bash scripts/create-github-repo.sh REPO_NAME
```

### Error: "Project directory does not exist"

**Cause**: The project is not in the expected location.

**Expected location**: `/Volumes/Time/go to wild/websites/<project-name>`

**Solution**:
```bash
# Check current location
pwd

# Move project to correct location
mv /path/to/project "/Volumes/Time/go to wild/websites/project-name"

# Run script
bash scripts/create-github-repo.sh project-name
```

### Error: "failed to push some refs"

**Cause**: Local branch is behind remote, or push was rejected.

**Solution**:
```bash
# Pull changes first
git pull origin main --rebase

# Then push
git push -u origin main
```

## Vercel Deployment Issues

### Error: "Vercel CLI not installed"

**Cause**: Vercel CLI is not installed.

**Solution**:
```bash
# Install Vercel CLI globally
npm install -g vercel

# Verify installation
vercel --version
```

### Error: "Not authenticated with Vercel"

**Cause**: Vercel CLI is not logged in.

**Solution**:
```bash
# Login to Vercel
vercel login
```

Enter your email address and click the verification link sent to your email.

### Error: "Build failed" during deployment

**Cause**: Code doesn't compile or build script failed.

**Solution**:

1. **Check build logs**:
```bash
vercel logs
```

2. **Common build errors**:

**TypeScript errors**:
```bash
# Fix TypeScript errors locally
npm run build

# Check specific errors
npx tsc --noEmit
```

**Missing dependencies**:
```bash
# Install all dependencies
npm install

# Commit package-lock.json
git add package-lock.json
git commit -m "Update dependencies"
git push
```

**Environment variables missing**:
- Add required variables in Vercel dashboard
- Go to Project Settings > Environment Variables
- Add variables for Production environment

3. **Redeploy after fixes**:
```bash
vercel --prod
```

### Error: "No framework detected"

**Cause**: Vercel cannot detect the framework (Next.js).

**Solution**:

Check `package.json` has correct scripts:
```json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}
```

If using Next.js 15, verify `next` is in dependencies:
```bash
npm list next
```

### Error: "Deployment timeout"

**Cause**: Build process takes too long (> 10 minutes on free tier).

**Solution**:

1. **Optimize build**:
   - Remove unused dependencies
   - Reduce bundle size
   - Check for infinite loops in build scripts

2. **Upgrade Vercel plan** (if needed for longer builds)

### Error: "Module not found" in production

**Cause**: Dependency is in `devDependencies` but needed in production.

**Solution**:

Move dependency to `dependencies`:
```bash
npm install <package-name> --save

# Remove from devDependencies
npm uninstall <package-name> --save-dev

# Commit changes
git add package.json package-lock.json
git commit -m "Fix dependency location"
git push
```

### Error: "CORS errors" in production

**Cause**: API requests blocked by CORS policy.

**Solution**:

Add CORS headers in `next.config.mjs`:
```javascript
const nextConfig = {
  async headers() {
    return [
      {
        source: '/api/:path*',
        headers: [
          { key: 'Access-Control-Allow-Origin', value: '*' },
          { key: 'Access-Control-Allow-Methods', value: 'GET,POST,PUT,DELETE,OPTIONS' },
          { key: 'Access-Control-Allow-Headers', value: 'Content-Type, Authorization' },
        ],
      },
    ];
  },
};
```

## Environment Variables Issues

### Error: "Environment variable undefined"

**Cause**: Variable not configured in Vercel.

**Solution**:

1. Go to Vercel dashboard
2. Select your project
3. Settings > Environment Variables
4. Add the missing variable
5. **Important**: Redeploy after adding variables

```bash
vercel --prod --force
```

### Database connection fails in production

**Cause**: Database URL not configured or incorrect.

**Solution**:

1. **Check connection string format**:
```
postgres://user:password@host:port/database?sslmode=require
```

2. **Verify in Vercel**:
   - Environment Variables section
   - Variable name matches code (e.g., `DATABASE_URL`)
   - Variable set for "Production" environment

3. **Test connection**:
```bash
# Use Vercel CLI to check
vercel env ls
```

## Performance Issues

### Site loads slowly after deployment

**Cause**: Images not optimized, JavaScript bundles too large.

**Solution**:

1. **Optimize images**:
```bash
node scripts/optimize-images.js
```

2. **Analyze bundle size**:
```bash
npm run build

# Check .next/analyze (if configured)
```

3. **Enable Vercel Analytics**:
   - Free tier includes basic analytics
   - Enable in Project Settings

### High function execution time

**Cause**: Server-side functions take too long.

**Solution**:

1. **Use static generation** where possible (ISR, SSG)
2. **Implement caching** for API responses
3. **Optimize database queries**
4. **Consider edge functions** for faster response

## General Debugging

### Check deployment status

```bash
# List recent deployments
vercel ls

# View specific deployment logs
vercel logs [deployment-url]
```

### Access production environment

```bash
# View environment variables
vercel env ls

# Pull environment variables locally
vercel env pull
```

### Force redeploy

Sometimes a fresh deployment fixes issues:
```bash
vercel --prod --force
```

## Getting Help

If the issue persists:

1. **Check Vercel status**: https://www.vercel-status.com/
2. **Review build logs** carefully for specific errors
3. **Search Vercel documentation**: https://vercel.com/docs
4. **GitHub issues**: Check if others have similar problems
5. **Vercel community**: https://github.com/vercel/vercel/discussions

## Prevention Tips

**Before every deployment**:
- [ ] Test build locally: `npm run build`
- [ ] Check environment variables are documented
- [ ] Review recent code changes
- [ ] Test in development mode first
- [ ] Use preview deployments for testing (push to non-main branch)

**Best practices**:
- Keep dependencies up to date
- Use TypeScript for type safety
- Write tests for critical paths
- Monitor deployment notifications
- Set up Slack/Discord webhooks for deployment alerts

```

### scripts/create-github-repo.sh

```bash
#!/bin/bash

# GitHub 私有仓库自动创建脚本
# 使用方法: bash create-github-repo.sh <project-name>

set -e  # 遇到错误立即退出

PROJECT_NAME=$1

if [ -z "$PROJECT_NAME" ]; then
  echo "❌ 错误: 请提供项目名称"
  echo "使用方法: bash create-github-repo.sh <project-name>"
  exit 1
fi

REPO_NAME="${PROJECT_NAME}"
PROJECT_DIR="/Volumes/Time/go to wild/websites/${PROJECT_NAME}"

# 检查项目目录是否存在
if [ ! -d "$PROJECT_DIR" ]; then
  echo "❌ 错误: 项目目录不存在: $PROJECT_DIR"
  exit 1
fi

echo "📁 切换到项目目录: $PROJECT_DIR"
cd "$PROJECT_DIR"

# 检查是否已有Git仓库
if [ -d ".git" ]; then
  echo "✅ Git仓库已存在"
else
  echo "🔧 初始化Git仓库..."
  git init
  git add .
  git commit -m "Initial commit from Shipany template"
fi

# 检查是否安装了GitHub CLI
if ! command -v gh &> /dev/null; then
  echo "❌ 错误: GitHub CLI (gh) 未安装"
  echo "请先安装: brew install gh"
  echo "然后登录: gh auth login"
  exit 1
fi

# 检查GitHub CLI是否已登录
if ! gh auth status &> /dev/null; then
  echo "❌ 错误: GitHub CLI 未登录"
  echo "请先登录: gh auth login"
  exit 1
fi

echo "🚀 创建GitHub私有仓库: $REPO_NAME"

# 创建私有仓库
gh repo create "$REPO_NAME" \
  --private \
  --source=. \
  --remote=origin \
  --push

if [ $? -eq 0 ]; then
  echo ""
  echo "✅ GitHub仓库创建成功!"
  echo "📊 仓库URL: https://github.com/$(gh api user --jq .login)/${REPO_NAME}"
  echo ""
else
  echo "❌ 创建失败"
  exit 1
fi

```

### scripts/deploy-to-vercel.sh

```bash
#!/bin/bash

# Vercel 自动部署脚本
# 使用方法: bash deploy-to-vercel.sh <project-name>

set -e  # 遇到错误立即退出

PROJECT_NAME=$1

if [ -z "$PROJECT_NAME" ]; then
  echo "❌ 错误: 请提供项目名称"
  echo "使用方法: bash deploy-to-vercel.sh <project-name>"
  exit 1
fi

PROJECT_DIR="/Volumes/Time/go to wild/websites/${PROJECT_NAME}"

# 检查项目目录是否存在
if [ ! -d "$PROJECT_DIR" ]; then
  echo "❌ 错误: 项目目录不存在: $PROJECT_DIR"
  exit 1
fi

echo "📁 切换到项目目录: $PROJECT_DIR"
cd "$PROJECT_DIR"

# 检查是否安装了Vercel CLI
if ! command -v vercel &> /dev/null; then
  echo "❌ 错误: Vercel CLI 未安装"
  echo "请先安装: npm install -g vercel"
  exit 1
fi

echo "🔧 链接Vercel项目..."
vercel link --yes

echo "🚀 部署到Vercel (生产环境)..."
vercel --prod --yes

if [ $? -eq 0 ]; then
  echo ""
  echo "✅ Vercel部署成功!"
  echo "📱 查看部署: vercel ls ${PROJECT_NAME}"
  echo ""

  # 获取部署URL
  DEPLOY_URL=$(vercel ls ${PROJECT_NAME} --limit=1 | grep -o 'https://[^ ]*' | head -1)
  if [ ! -z "$DEPLOY_URL" ]; then
    echo "🌐 部署URL: $DEPLOY_URL"
  fi
else
  echo "❌ 部署失败"
  exit 1
fi

```