npm run build succeeds with no errors
All images moved to /public and paths updated
Environment variables documented (if any)
Links are valid (GitHub, LinkedIn, project URLs)
No placeholder content ("Lorem ipsum", "TODO", etc.)
Responsive design works on mobile
Favicon and meta tags set

Deployment Options

1. Vercel (Recommended)

Why: Zero-config for Next.js, free tier, automatic HTTPS, preview deployments.

Steps:

# Install Vercel CLI
npm i -g vercel

# Deploy (first time - will prompt for setup)
vercel

# Deploy to production
vercel --prod

Or via GitHub:

Push to GitHub
Go to vercel.com
Import repository
Vercel auto-detects Next.js settings
Click Deploy

Custom Domain:

# Add domain in Vercel dashboard, then:
vercel domains add yourdomain.com

2. Netlify

Steps:

# Install Netlify CLI
npm i -g netlify-cli

# Build first
npm run build

# Deploy
netlify deploy --prod --dir=.next

Or via GitHub:

Push to GitHub
Go to netlify.com
"New site from Git"
Build command: npm run build
Publish directory: .next

3. Cloudflare Pages

Steps:

Push to GitHub
Go to Cloudflare Pages dashboard
Connect repository
Build settings:
- Framework: Next.js
- Build command: npm run build
- Output: .next

4. GitHub Pages (Static Export)

Note: Requires static export, no server features.

CRITICAL PRE-FLIGHT:

Check Remote: Run git remote -v. If it points to JacbK/persona (the template), REMOVE IT.
Clean API: Static export fails if /api routes exist. Run rm -rf src/app/api src/app/config.

Steps:

Prepare Repo:

# 1. Remove template remote (if exists)
git remote remove origin

# 2. Create NEW repository (replace 'my-portfolio' with your name)
gh repo create my-portfolio --public --source=. --push

Configure next.config.ts:

const nextConfig = {
  output: 'export',
  images: { unoptimized: true },
  // REQUIRED: match your repo name if not a user site
  basePath: '/my-portfolio', 
};

Build & Push:

# Clean incompatible files
rm -rf src/app/api src/app/config

# Build locally to verify
npm run build

# Push
git add .
git commit -m "chore: prepare for static deployment"
git push -u origin main

Enable Pages:
- Settings → Pages → Source: GitHub Actions

5. Self-Hosted (Docker)

Dockerfile:

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

Run:

docker build -t portfolio .
docker run -p 3000:3000 portfolio

Environment Variables

If using environment variables:

Local: Create .env.local
Vercel: Add in Project Settings → Environment Variables
Netlify: Add in Site Settings → Environment
Docker: Pass with -e or use .env file

Custom Domain Setup

General Steps

Add domain in hosting provider
Update DNS records:
- A record: Points to hosting IP
- CNAME: Points to hosting subdomain
Wait for DNS propagation (up to 48h, usually minutes)
SSL certificate auto-provisions

Common Providers

Vercel: Automatic SSL, add domain in dashboard
Netlify: Automatic SSL, add domain in dashboard
Cloudflare: Automatic SSL + CDN

Post-Deployment

After deploying:

Test the live site
- Check all pages load
- Test on mobile
- Verify images load
- Click all links
Set up analytics (optional)
- Vercel Analytics (built-in)
- Plausible (privacy-focused)
- Google Analytics
Submit to search engines (optional)
- Google Search Console
- Bing Webmaster Tools

Troubleshooting

Build Fails

Check npm run build locally first
Review error messages for missing dependencies
Ensure all imports are valid

Images Not Loading

Move to /public folder
Use absolute paths: /images/photo.jpg
Check case sensitivity (Linux is case-sensitive)

404 on Routes

For static export: ensure generateStaticParams for dynamic routes
Check next.config.ts for trailingSlash setting

Slow Performance

Run Lighthouse audit
Optimize images (use next/image)
Check for large bundle sizes

CI/CD with GitHub Actions

Pre-configured workflows in .github/workflows/:

Vercel (deploy-vercel.yml)

Auto-deploy on push to main. Setup:

Import repo at vercel.com
Run vercel link locally to get IDs
Add GitHub secrets:
- VERCEL_TOKEN (from vercel.com/account/tokens)
- VERCEL_ORG_ID
- VERCEL_PROJECT_ID

GitHub Pages (deploy-pages.yml)

Static export to GitHub Pages. Setup:

Enable in repo Settings → Pages → Source: GitHub Actions
Ensure next.config.ts has output: 'export'

MCP Integration

MCP (Model Context Protocol) enables AI-driven deployment. Supported by Claude Code, Codex, and Gemini CLI.

Setup: Run ./bin/setup.sh and select "Yes" when asked about deployment integration.

Manual Setup by CLI

Claude Code

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN="your-token" -- npx -y @modelcontextprotocol/server-github
claude mcp add vercel -e VERCEL_API_TOKEN="your-token" -- npx -y vercel-mcp-server

Codex

codex mcp add github -- npx -y @modelcontextprotocol/server-github
codex mcp add vercel -- npx -y vercel-mcp-server

Then set environment variables: GITHUB_PERSONAL_ACCESS_TOKEN, VERCEL_API_TOKEN

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token" }
    },
    "vercel": {
      "command": "npx",
      "args": ["-y", "vercel-mcp-server"],
      "env": { "VERCEL_API_TOKEN": "your-token" }
    }
  }
}

Get Tokens

GitHub: https://github.com/settings/tokens (scopes: repo, read:user)
Vercel: https://vercel.com/account/tokens

Usage

Once configured, just ask your AI assistant:

"Deploy my portfolio to Vercel"
"Create a GitHub repo and deploy to GitHub Pages"

Shell Commands (All CLIs)

Any AI assistant can deploy using standard CLI tools (no MCP required).

GitHub Pages via `gh` CLI

First, ensure you have your own repo (not the template):

# Check current remote
git remote -v

# If it points to the template repo, remove it and create your own:
git remote remove origin
gh repo create my-portfolio --public --source=. --push

Then enable GitHub Pages:

# Enable GitHub Pages with Actions
gh api repos/{owner}/{repo}/pages -X POST -f build_type=workflow

Requires:

gh CLI installed and authenticated (gh auth login)
Your own GitHub repository (not the template)

Static export in next.config.ts:

output: 'export',
images: { unoptimized: true }

Vercel via CLI

npm i -g vercel
vercel --prod

Netlify via CLI

npm i -g netlify-cli
netlify deploy --prod

Deployment Options

1. Vercel (Recommended)

2. Netlify

3. Cloudflare Pages

4. GitHub Pages (Static Export)

5. Self-Hosted (Docker)

Environment Variables

Custom Domain Setup

General Steps

Common Providers

Post-Deployment

Troubleshooting

Build Fails

Images Not Loading

404 on Routes

Slow Performance

CI/CD with GitHub Actions

Vercel (deploy-vercel.yml)

GitHub Pages (deploy-pages.yml)

MCP Integration

Manual Setup by CLI

Claude Code

Codex

Gemini CLI

Get Tokens

Usage

Shell Commands (All CLIs)

GitHub Pages via gh CLI

Vercel via CLI

Netlify via CLI

GitHub Pages via `gh` CLI

deploy

Skill: Deployment

Quick Deploy

Pre-Deployment Checklist

More from jacbk/persona

fonts

colors

content

research

design

seo