Encore + Vercel Deployment Skill

Automates the deployment of full-stack applications with Encore.ts backend and Next.js frontend.

When to Use This Skill

Use this skill when:

• Deploying backend to Encore Cloud and frontend to Vercel
• Setting up a fresh Encore app after git/deployment issues
• Configuring environment variables and secrets
• Connecting frontend to deployed backend
• Troubleshooting deployment failures

Prerequisites

Before deployment, verify:

• Encore CLI installed and authenticated (encore auth whoami)
• Vercel CLI installed and authenticated (vercel whoami)
• Git repository with proper structure (no broken submodules)
• OpenAI API key available for agent services

Deployment Process

Step 1: Verify Git Structure

Ensure backend is NOT a git submodule:

# Check if backend is tracked properly
cd /path/to/project
git ls-tree HEAD backend

If output shows mode 160000 → Backend is a broken submodule. Fix it:

# Remove submodule reference
git rm --cached backend

# Add backend files properly
git add backend

# Commit
git commit -m "fix: properly add backend to git"

Step 2: Create or Link Encore App

Option A: Create New App (if starting fresh)

cd /path/to/project
encore app create your-app-name

# Update backend/encore.app with new app ID
# Copy the app ID from output (e.g., your-app-name-xyz123)

Update backend/encore.app:

{
  "id": "your-app-name-xyz123",
  "lang": "typescript",
  "global_cors": {
    "allow_origins_without_credentials": [
      "http://localhost:3000",
      "https://your-app.vercel.app",
      "https://your-app-*.vercel.app"
    ]
  }
}

Option B: Link Existing App

cd backend
encore app init  # Interactive linking

Step 3: Configure Git Remote for Encore

# Remove old remote if exists
git remote remove encore 2>/dev/null

# Add Encore remote (use encore:// protocol)
git remote add encore encore://your-app-id

# Verify
git remote -v

Step 4: Set Required Secrets

All agent services require OpenAIApiKey:

cd backend
encore secret set --type prod,dev OpenAIApiKey
# Paste your OpenAI API key when prompted

For additional secrets, repeat the command with different names.

Step 5: Deploy Backend to Encore

# From project root
git add -A
git commit -m "feat: deploy to encore"
git push encore main:main

Expected output:

remote: main: triggered deploy https://app.encore.cloud/your-app-id/deploys/staging/...

Deployment will be at:

• Staging: https://staging-your-app-id.encr.app
• Dashboard: https://app.encore.cloud/your-app-id

Step 6: Deploy Frontend to Vercel

Set environment variable:

cd frontend

# Add API URL (updates existing or creates new)
echo "https://staging-your-app-id.encr.app" | vercel env add NEXT_PUBLIC_API_URL production

# Or if variable exists, update via dashboard:
# https://vercel.com/your-team/your-project/settings/environment-variables

Deploy:

# Remove old project link if redeploying
rm -rf .vercel

# Deploy
vercel --prod --yes

Alternative: Push to GitHub if Vercel GitHub integration is configured.

Step 7: Verify Deployment

Backend health check:

curl https://staging-your-app-id.encr.app/hello/World
# Should return: {"message":"Hello World!"}

Frontend check:

curl -I https://your-app.vercel.app
# Should return: 200 OK

Test integration:

• Open frontend URL
• Try sending a chat message
• Verify backend responds via SSE stream

Common Issues & Solutions

Issue: "repository not found" when pushing to Encore

Cause: Wrong git remote format or app not created

Fix:

# Verify app exists
encore auth whoami

# Recreate remote with encore:// protocol
git remote remove encore
git remote add encore encore://your-app-id

Issue: "secret key(s) not defined: OpenAIApiKey"

Cause: Secrets not set before deployment

Fix:

cd backend
encore secret set --type prod,dev OpenAIApiKey
# Trigger redeploy
git commit --allow-empty -m "chore: redeploy after secrets"
git push encore main:main

Issue: Backend showing old services (auth/portfolio instead of chat-gateway)

Cause: Backend was never properly pushed to git/Encore

Fix:

# Verify backend files are in git
git ls-files backend | head -20

# If empty or showing "backend" only → fix submodule issue
git rm --cached backend
git add backend
git commit -m "fix: add backend files"
git push origin main
git push encore main:main

Issue: CORS errors between frontend and backend

Cause: Frontend domain not in backend/encore.app CORS config

Fix:

Update backend/encore.app:

{
  "global_cors": {
    "allow_origins_without_credentials": [
      "http://localhost:3000",
      "https://your-actual-domain.vercel.app",
      "https://your-actual-domain-*.vercel.app"
    ]
  }
}

Then redeploy backend:

git add backend/encore.app
git commit -m "fix: update CORS for frontend"
git push encore main:main

Issue: Vercel project named "frontend" instead of app name

Fix:

1. Go to Vercel project settings
2. Rename project to match desired domain
3. New URL will be https://your-project-name.vercel.app

Quick Reference

Encore Commands

# Check auth status
encore auth whoami

# Create new app
encore app create app-name

# List secrets
encore secret list

# View logs
encore logs --env=staging

# Get API URL
echo "https://staging-$(cat backend/encore.app | grep '"id"' | cut -d'"' -f4).encr.app"

Vercel Commands

# Check auth
vercel whoami

# List projects
vercel list

# Set env var
vercel env add VAR_NAME production

# Deploy
vercel --prod

# Rollback
vercel rollback

Git Commands

# Check for submodules
git ls-tree HEAD | grep 160000

# View remotes
git remote -v

# Push to multiple remotes
git push origin main
git push encore main:main

Environment URLs

After successful deployment:

Security Notes

• Never commit .env.local or .env.production files
• Rotate OpenAI API keys regularly
• Use Encore's secret management for all sensitive values
• Enable Vercel password protection for preview deployments if needed

Success Checklist

• Backend git structure verified (no broken submodules)
• Encore app created/linked with correct ID
• Git remote configured: encore://app-id
• OpenAI secret set in Encore
• Backend deployed successfully to Encore
• Frontend NEXTPUBLICAPI_URL points to Encore staging
• Frontend deployed to Vercel
• CORS configured correctly in backend/encore.app
• Health check endpoints responding
• Frontend can communicate with backend

Related Documentation

• Encore Deployment: https://encore.dev/docs/deploy/deploying
• Encore Secrets: https://encore.dev/docs/primitives/secrets
• Vercel CLI: https://vercel.com/docs/cli
• Vercel Environment Variables: https://vercel.com/docs/projects/environment-variables