next-forge-convex-migration

@danmarauda/next-forge-convex-migration

0 forks

Updated 3/31/2026

Automate full migration from single Next.js/Convex app to Next Forge Turborepo monorepo with programmatic Vercel deployment, API key setup via marketplace, and browser-based testing

Installation

$npx agent-skills-cli install @danmarauda/next-forge-convex-migration

Claude Code

Cursor

Copilot

Codex

Antigravity

Details

Repositorydanmarauda/pro

Pathnext-prisma-authjs/.claude/skills/next-forge-convex-migration/SKILL.md

Branchmonorepo

Scoped Name@danmarauda/next-forge-convex-migration

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

npx agent-skills-cli list

Skill Instructions

name: next-forge-convex-migration description: Automate full migration from single Next.js/Convex app to Next Forge Turborepo monorepo with programmatic Vercel deployment, API key setup via marketplace, and browser-based testing

Next Forge Convex Migration Skill

Purpose

Fully automated migration from a single Next.js application with Convex backend to a Next Forge Turborepo monorepo, including:

Programmatic Next Forge setup and configuration
Complete Prisma/PostgreSQL removal
Convex backend integration (schema + functions)
Vercel marketplace integration for API keys
Automated Doppler secret management
End-to-end Vercel deployment
Browser-based testing and validation

When to Use This Skill

Use this skill when:

Migrating from single Next.js app to Next Forge monorepo
Current project uses Convex backend
Need to remove Prisma/PostgreSQL dependencies
Want programmatic Vercel deployment setup
Need automated API key configuration via Vercel marketplace
Require browser-based testing validation

DO NOT use this skill when:

Project doesn't use Convex (uses Prisma/PostgreSQL)
Not migrating to Next Forge
Manual deployment preferred

Prerequisites

Required Tools:

- node >= 18
- pnpm >= 10
- bun >= 1.1.0
- git
- vercel CLI
- doppler CLI
- playwright

Environment Setup:

# Verify tools
node --version    # >= 18
pnpm --version    # >= 10
bun --version     # >= 1.1.0
vercel --version  # latest
doppler --version # latest

# Login to services
vercel login
doppler login

Required Access:

Vercel account with deployment permissions
Doppler project with secret access
GitHub repository access
Convex project access
Clerk authentication keys

Migration Workflow

Phase 0: Knowledge Base & Foundation

Step 0.1: Create and Copy Knowledge Base

IMPORTANT: This must be done FIRST before all other phases.

# Verify knowledge base exists in current project
ls docs/FREO_KNOWLEDGE_BASE.md
# Should exist with 20,000+ words

# Copy to new project
cp docs/FREO_KNOWLEDGE_BASE.md [NEW_PROJECT_PATH]/docs/

# Verify copy
cat [NEW_PROJECT_PATH]/docs/FREO_KNOWLEDGE_BASE.md | wc -w
# Should show 20,000+ words

What the knowledge base contains:

Company overview and brand identity
Brand colors (Primary Blue, Safety Orange, Success Green, etc.)
User personas (5 detailed personas)
Common workflows (4 critical workflows)
Compliance standards (AS1418, AS2550)
Email template specifications
Storybook category structure
AI SDK 6 integration points (24 tools across 5 categories)
Vercel AI Gateway configuration details

Why this is first: The knowledge base provides context for all subsequent phases - email templates use brand colors, Storybook follows brand guidelines, AI tools implement workflows, documentation reflects personas.

Phase 1: Project Analysis

Step 1.1: Analyze Current Project

# Navigate to current project
cd [CURRENT_PROJECT_PATH]

# Verify Convex backend
ls convex/schema.ts convex/_generated/
# Should show schema and generated API

# Count Convex function files
find convex -type f -name "*.ts" | wc -l
# Expected: 100+ files

# Check environment variables
doppler secrets --config prd

Step 1.2: Verify Prerequisites

Create TodoWrite checklist:

TodoWrite({
  todos: [
    { content: "Verify Convex backend exists (schema.ts + functions)", status: "pending", activeForm: "Verifying Convex backend" },
    { content: "Check Doppler configuration and secrets", status: "pending", activeForm: "Checking Doppler" },
    { content: "Verify Vercel CLI authentication", status: "pending", activeForm: "Verifying Vercel CLI" },
    { content: "Confirm GitHub repository access", status: "pending", activeForm: "Confirming GitHub access" },
    { content: "Validate current deployment URL", status: "pending", activeForm: "Validating deployment" }
  ]
});

Phase 2: Clone and Setup Next Forge

Step 2.1: Clone Next Forge

# Clone to sibling directory
cd [PARENT_DIRECTORY]
git clone https://github.com/vercel/next-forge.git [NEW_PROJECT_NAME]
cd [NEW_PROJECT_NAME]

# Install dependencies
pnpm install

Step 2.2: Remove Unused Apps

# Remove unnecessary apps (keep only app, web, api)
rm -rf apps/docs
rm -rf apps/email
rm -rf apps/storybook
rm -rf apps/studio

# Verify removal
ls apps/
# Should show: api, app, web

Step 2.3: Update Root Configuration

Update package.json:

{
  "name": "[NEW_PROJECT_NAME]",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ],
  "scripts": {
    "dev": "turbo dev --parallel",
    "dev:convex": "bunx convex dev",
    "build": "turbo build",
    "deploy:convex": "bunx convex deploy",
    "test:e2e": "bunx playwright test"
  }
}

Update turbo.json:

{
  "pipeline": {
    "build": {
      "outputs": [".next/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "app#dev": {
      "dependsOn": ["^build"]
    },
    "web#dev": {
      "dependsOn": ["^build"]
    },
    "api#dev": {
      "dependsOn": ["^build"]
    }
  }
}

Phase 3: Remove Prisma/PostgreSQL

Step 3.1: Delete Database Package

# Remove database package entirely
rm -rf packages/database

# Verify deletion
ls packages/ | grep database
# Should return empty

Step 3.2: Remove Database Dependencies

Update apps/app/package.json:

# Remove @repo/database dependency
sed -i '' '/"@repo\/database":/d' apps/app/package.json

Update apps/api/package.json:

# Remove @repo/database dependency
sed -i '' '/"@repo\/database":/d' apps/api/package.json

Step 3.3: Remove Database Imports

# Find all @repo/database imports
grep -r "@repo/database" apps/ --include="*.ts" --include="*.tsx"

# Remove imports automatically
find apps/ -type f \( -name "*.ts" -o -name "*.tsx" \) \
  -exec sed -i '' '/import.*@repo\/database/d' {} +

# Clean up empty lines
find apps/ -type f \( -name "*.ts" -o -name "*.tsx" \) \
  -exec sed -i '' '/^$/N;/^\n$/d' {} +

Step 3.4: Rebuild Dependencies

# Clean node_modules
pnpm clean

# Reinstall without database package
pnpm install

Phase 4: Integrate Convex Backend

Step 4.1: Install Convex Dependencies

# Root project
pnpm add convex

# Apps
cd apps/app && pnpm add convex convex-helpers
cd ../api && pnpm add convex
cd ../..

Step 4.2: Copy Convex Backend

# Copy entire Convex directory
cp -r [CURRENT_PROJECT_PATH]/convex ./

# Verify copy
ls convex/
# Should show schema.ts and all function directories

Step 4.3: Create Convex Configuration

Create convex.json:

{
  "node": "22.11.0",
  "generateCommonJSApi": false,
  "functions": "convex/"
}

Update root tsconfig.json:

{
  "include": ["convex/**/*"],
  "compilerOptions": {
    "paths": {
      "convex/*": ["./convex/*"]
    }
  }
}

Step 4.4: Create Convex Provider

Create apps/app/lib/convex-provider.tsx:

"use client";

import { ConvexProvider, ConvexReactClient } from "convex/react";
import { type ReactNode } from "react";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export function ConvexClientProvider({ children }: { children: ReactNode }) {
  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
}

Update apps/app/app/layout.tsx:

import { ConvexClientProvider } from "@/lib/convex-provider";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html>
      <body>
        <ConvexClientProvider>
          {children}
        </ConvexClientProvider>
      </body>
    </html>
  );
}

Phase 4.5: React Email Templates

Step 4.5.1: Install React Email

cd packages/email
pnpm add @react-email/components react-email

Step 4.5.2: Copy Email Templates

# Copy welcome email template
cp [CURRENT_PROJECT_PATH]/packages/email/templates/welcome.tsx packages/email/templates/

# Copy document expiry alert template
cp [CURRENT_PROJECT_PATH]/packages/email/templates/document-expiry-alert.tsx packages/email/templates/

# Verify templates
ls packages/email/templates/
# Should show: welcome.tsx, document-expiry-alert.tsx

Step 4.5.3: Configure React Email

Create packages/email/.react-email/config.js:

module.exports = {
  dir: './templates',
  port: 3002,
  open: false,
};

Update packages/email/package.json:

{
  "scripts": {
    "dev": "react-email dev",
    "build": "react-email build",
    "export": "react-email export"
  }
}

Phase 4.6: Storybook with Brand Guidelines

Step 4.6.1: Install Storybook

cd apps/app
pnpm add -D storybook @storybook/addon-essentials @storybook/addon-a11y @storybook/addon-themes @storybook/nextjs
bunx storybook@latest init --type nextjs --skip-install

Step 4.6.2: Copy Storybook Configuration

# Copy Storybook config and stories
cp -r [CURRENT_PROJECT_PATH]/apps/app/.storybook apps/app/
cp -r [CURRENT_PROJECT_PATH]/apps/app/stories apps/app/

# Verify copy
ls apps/app/.storybook/
ls apps/app/stories/Brand/
# Should show Colors.stories.tsx

Step 4.6.3: Verify Storybook Theme

Ensure .storybook/preview.ts contains FREO brand defaults:

Default theme: "dark"
Dark background: #0F172A (FREO primary)
Story sort order: Brand → Components

Phase 4.7: AI SDK 6 Integration

Step 4.7.1: Install AI SDK 6

# Root project
pnpm add ai @ai-sdk/anthropic @ai-sdk/openai @ai-sdk/google zod

# Apps
cd apps/app
pnpm add ai @ai-sdk/anthropic @ai-sdk/openai @ai-sdk/google zod

cd ../api
pnpm add ai @ai-sdk/anthropic @ai-sdk/openai @ai-sdk/google zod

Step 4.7.2: Copy AI Tools and Gateway Config

# Copy AI tools directory (24 tools)
cp -r [CURRENT_PROJECT_PATH]/apps/app/lib/ai apps/app/lib/

# Verify 24 tools
cat apps/app/lib/ai/tools.ts | grep "export const" | wc -l
# Should show 24

# Verify gateway config
grep "aiModels" apps/app/lib/ai/gateway-config.ts
# Should show model configurations

Step 4.7.3: AI Tool Categories

Verify all 5 categories are present:

Document Processing (4 tools)
Compliance Assistant (4 tools)
Fleet Intelligence (4 tools)
Knowledge Assistant (4 tools)
Report Generation (4 tools)

Phase 4.8: Documentation Generation

Step 4.8.1: Copy User Documentation

# Copy getting started guide
cp [CURRENT_PROJECT_PATH]/docs/getting-started.md docs/

# Copy API reference
cp [CURRENT_PROJECT_PATH]/docs/api-reference.md docs/

# Verify documentation
ls docs/
# Should show: FREO_KNOWLEDGE_BASE.md, getting-started.md, api-reference.md

Step 4.8.2: Verify Documentation Contents

# Check getting started has all sections
grep -E "^##" docs/getting-started.md
# Should show: Quick Start, Core Concepts, Key Features, etc.

# Check API reference has all endpoints
grep -E "^###" docs/api-reference.md
# Should show: Documents, Cranes, Jobs, Compliance, AI Assistant, Webhooks

Phase 5: Migrate Application Code

Step 5.1: Copy Core Application Files

# Copy application pages
cp -r [CURRENT_PROJECT_PATH]/app/* apps/app/app/

# Copy components
cp -r [CURRENT_PROJECT_PATH]/components/* packages/design-system/components/

# Copy lib utilities
cp -r [CURRENT_PROJECT_PATH]/lib/* apps/app/lib/

# Copy hooks
cp -r [CURRENT_PROJECT_PATH]/hooks/* apps/app/hooks/

Step 5.2: Update Import Paths

# Update Convex import paths (remove @/ prefix for monorepo)
find apps/app -type f \( -name "*.ts" -o -name "*.tsx" \) \
  -exec sed -i '' 's|@/convex/_generated/api|convex/_generated/api|g' {} +

# Update component imports for design-system
find apps/app -type f \( -name "*.ts" -o -name "*.tsx" \) \
  -exec sed -i '' 's|@/components/ui|@repo/design-system/components|g' {} +

Step 5.3: Verify Imports

# Check for broken imports
pnpm turbo typecheck

# Fix any remaining import errors manually
# Common patterns:
# - @/convex → convex
# - @/components → @repo/design-system/components
# - @/lib → ../lib or @/lib (depending on app structure)

Phase 6: Programmatic Vercel Setup

Step 6.1: Initialize Vercel Project

# Create Vercel project programmatically
vercel --yes --force

# Link to existing project (if needed)
vercel link

Step 6.2: Configure Vercel via API

Use Vercel API to configure project settings:

# Get Vercel token
VERCEL_TOKEN=$(vercel whoami --token)

# Get project ID
PROJECT_ID=$(vercel inspect --token "$VERCEL_TOKEN" | grep "Project ID" | awk '{print $3}')

# Configure build settings via API
curl -X PATCH "https://api.vercel.com/v9/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "buildCommand": "pnpm turbo build",
    "framework": "nextjs",
    "installCommand": "pnpm install"
  }'

Step 6.3: Vercel Marketplace Integration

Programmatically add integrations via Vercel API:

# Add Convex integration
curl -X POST "https://api.vercel.com/v1/integrations" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "convex",
    "projectId": "'"$PROJECT_ID"'"
  }'

# Add Sentry integration
curl -X POST "https://api.vercel.com/v1/integrations" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "sentry",
    "projectId": "'"$PROJECT_ID"'"
  }'

# Add Clerk integration
curl -X POST "https://api.vercel.com/v1/integrations" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "clerk",
    "projectId": "'"$PROJECT_ID"'"
  }'

Step 6.4: Set Environment Variables via Doppler

# Export secrets from current Doppler project
cd [CURRENT_PROJECT_PATH]
doppler secrets download --config prd --format env > /tmp/secrets.env

# Import to new Doppler project
cd [NEW_PROJECT_PATH]
doppler setup
doppler secrets upload /tmp/secrets.env --config prd

# Sync to Vercel automatically
doppler secrets download --config prd --format vercel | vercel env add production

# Cleanup
rm /tmp/secrets.env

Step 6.5: Configure Vercel Environment Variables

Set additional Vercel-specific variables:

# Set Convex URL
vercel env add NEXT_PUBLIC_CONVEX_URL production <<< "[CONVEX_URL]"

# Set Clerk keys
vercel env add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY production <<< "[CLERK_KEY]"
vercel env add CLERK_SECRET_KEY production <<< "[CLERK_SECRET]"

# Verify environment variables
vercel env ls

Phase 7: Automated Testing

Step 7.1: Copy E2E Tests

# Copy Playwright tests
cp -r [CURRENT_PROJECT_PATH]/e2e ./
cp [CURRENT_PROJECT_PATH]/playwright.config.ts ./

# Install Playwright
pnpm add -D @playwright/test
bunx playwright install

Step 7.2: Update Playwright Configuration

Update playwright.config.ts for monorepo:

import { defineConfig } from "@playwright/test";

export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  use: {
    baseURL: "http://localhost:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
  },
  webServer: {
    command: "pnpm dev",
    port: 3000,
    reuseExistingServer: !process.env.CI,
    timeout: 120000,
  },
  projects: [
    { name: "chromium", use: { browserName: "chromium" } },
  ],
});

Step 7.3: Run Local Tests

# Start development server
pnpm dev &
DEV_PID=$!

# Wait for server to be ready
sleep 30

# Run E2E tests
pnpm test:e2e

# Stop development server
kill $DEV_PID

Step 7.4: Deploy to Preview and Test

# Deploy to preview
PREVIEW_URL=$(vercel --yes | grep "https://" | tail -1)

# Run tests against preview
PLAYWRIGHT_TEST_BASE_URL="$PREVIEW_URL" pnpm test:e2e

Phase 8: Browser-Based Validation

Step 8.1: Use Browser Tools for Manual Verification

Use the mcp__plugin_superpowers-chrome_chrome__use_browser tool to verify deployment:

// Navigate to preview deployment
use_browser({
  action: "navigate",
  payload: "[PREVIEW_URL]"
});

// Take screenshot of homepage
use_browser({
  action: "screenshot",
  payload: "/tmp/homepage-preview.png"
});

// Verify authentication flow
use_browser({
  action: "click",
  selector: "//button[contains(text(), 'Sign In')]"
});

// Wait for Clerk sign-in modal
use_browser({
  action: "await_element",
  selector: "//div[@data-clerk-modal]",
  timeout: 5000
});

// Take screenshot of sign-in
use_browser({
  action: "screenshot",
  payload: "/tmp/signin-preview.png"
});

Step 8.2: Automated Browser Checks

Create browser check script:

// e2e/browser-validation.spec.ts
import { test, expect } from "@playwright/test";

test.describe("Browser Validation", () => {
  test("homepage loads successfully", async ({ page }) => {
    await page.goto("/");
    await expect(page).toHaveTitle(/FREO Cranes/i);
  });

  test("Clerk authentication loads", async ({ page }) => {
    await page.goto("/");
    const clerkLoaded = await page.evaluate(() => {
      return typeof (window as any).Clerk !== "undefined";
    });
    expect(clerkLoaded).toBe(true);
  });

  test("Convex connection works", async ({ page }) => {
    await page.goto("/");
    await page.waitForTimeout(2000);

    const errors: string[] = [];
    page.on("console", (msg) => {
      if (msg.type() === "error") errors.push(msg.text());
    });

    const convexErrors = errors.filter(e => e.includes("Convex"));
    expect(convexErrors).toHaveLength(0);
  });
});

Run browser validation:

pnpm test:e2e e2e/browser-validation.spec.ts

Phase 9: Production Deployment

Step 9.1: Deploy to Production

# Deploy using Doppler secrets
doppler run --config prd -- vercel --prod --yes

Step 9.2: Switch Domain

Use Vercel API to update domain:

# Get Vercel token and project IDs
VERCEL_TOKEN=$(vercel whoami --token)
OLD_PROJECT_ID="[OLD_PROJECT_ID]"
NEW_PROJECT_ID=$(vercel inspect --token "$VERCEL_TOKEN" | grep "Project ID" | awk '{print $3}')

# Remove domain from old project
curl -X DELETE "https://api.vercel.com/v9/projects/$OLD_PROJECT_ID/domains/freo.aliaslabs.ai" \
  -H "Authorization: Bearer $VERCEL_TOKEN"

# Add domain to new project
curl -X POST "https://api.vercel.com/v9/projects/$NEW_PROJECT_ID/domains" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "freo.aliaslabs.ai"
  }'

# Wait for DNS propagation
sleep 60

# Verify domain
curl -I https://freo.aliaslabs.ai

Step 9.3: Production Smoke Tests

Run E2E tests against production:

PLAYWRIGHT_TEST_BASE_URL="https://freo.aliaslabs.ai" pnpm test:e2e

Step 9.4: Browser-Based Production Verification

// Verify production deployment
use_browser({
  action: "navigate",
  payload: "https://freo.aliaslabs.ai"
});

// Take screenshot
use_browser({
  action: "screenshot",
  payload: "/tmp/production-homepage.png"
});

// Extract page text
const pageContent = use_browser({
  action: "extract",
  selector: "//body",
  payload: "text"
});

// Verify no errors
const hasErrors = pageContent.includes("Application error") ||
                  pageContent.includes("500") ||
                  pageContent.includes("404");

if (hasErrors) {
  throw new Error("Production deployment has errors!");
}

Phase 10: Post-Migration Validation

Step 10.1: Monitoring Setup

# Verify Sentry is receiving events
curl "https://sentry.io/api/0/projects/[ORG]/[PROJECT]/events/" \
  -H "Authorization: Bearer [SENTRY_TOKEN]"

# Check Vercel Analytics
vercel logs [DEPLOYMENT_URL]

# Monitor Convex Dashboard
open "https://dashboard.convex.dev"

Step 10.2: Final Checklist

Create final validation TodoWrite:

TodoWrite({
  todos: [
    { content: "Verify production homepage loads", status: "pending", activeForm: "Checking homepage" },
    { content: "Test user authentication flow", status: "pending", activeForm: "Testing authentication" },
    { content: "Verify document upload works", status: "pending", activeForm: "Testing document upload" },
    { content: "Check Convex real-time updates", status: "pending", activeForm: "Checking real-time" },
    { content: "Verify search functionality", status: "pending", activeForm: "Testing search" },
    { content: "Test mobile responsiveness", status: "pending", activeForm: "Testing mobile" },
    { content: "Check error tracking (Sentry)", status: "pending", activeForm: "Verifying Sentry" },
    { content: "Verify analytics (Vercel)", status: "pending", activeForm: "Checking analytics" },
    { content: "Monitor performance metrics", status: "pending", activeForm: "Monitoring performance" },
    { content: "Document migration completion", status: "pending", activeForm: "Creating documentation" }
  ]
});

Error Handling

Common Issues and Solutions

Issue 1: Convex Connection Failures

# Verify Convex deployment
bunx convex env

# Re-deploy if needed
bunx convex deploy --prod

# Update environment variables
vercel env add NEXT_PUBLIC_CONVEX_URL production

Issue 2: Clerk Authentication Not Working

# Verify Clerk keys
echo $NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
echo $CLERK_SECRET_KEY

# Check Clerk dashboard domain configuration
open "https://dashboard.clerk.com"

Issue 3: Build Failures

# Clear Turbo cache
pnpm turbo clean

# Rebuild
pnpm turbo build --force

# Check build logs
vercel logs

Issue 4: Missing Environment Variables

# Re-sync from Doppler
doppler secrets download --config prd --format vercel | vercel env add production

# Redeploy
vercel --prod --yes

Rollback Procedure

If critical issues occur:

Quick Rollback (< 5 minutes)

# 1. Revert domain via Vercel API
VERCEL_TOKEN=$(vercel whoami --token)
OLD_PROJECT_ID="[OLD_PROJECT_ID]"
NEW_PROJECT_ID="[NEW_PROJECT_ID]"

# Remove from new project
curl -X DELETE "https://api.vercel.com/v9/projects/$NEW_PROJECT_ID/domains/freo.aliaslabs.ai" \
  -H "Authorization: Bearer $VERCEL_TOKEN"

# Add back to old project
curl -X POST "https://api.vercel.com/v9/projects/$OLD_PROJECT_ID/domains" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "freo.aliaslabs.ai"
  }'

# 2. Verify rollback
curl -I https://freo.aliaslabs.ai

# 3. Investigate issues
vercel logs [NEW_DEPLOYMENT_URL]

Success Metrics

Technical Validation:

All 3 apps build without errors
Zero Prisma/PostgreSQL dependencies
Convex backend fully operational
All environment variables configured
E2E tests passing (45+ tests)
Production deployment successful

Functional Validation:

Performance Validation:

Homepage load time < 3 seconds
Convex query latency < 50ms
Lighthouse score > 90
Zero memory leaks

Notes

Prerequisites Verification: Always verify prerequisites before starting migration:

# Check current project has Convex
test -f convex/schema.ts || echo "ERROR: No Convex schema found"

# Verify Doppler access
doppler secrets --config prd | wc -l
# Should show 40+ secrets

# Verify Vercel CLI
vercel whoami
# Should show username

# Check GitHub access
git remote -v
# Should show repository URL

Automation Tips:

Use set -e in bash scripts to fail fast
Always verify operations before proceeding
Create backups before destructive operations
Use TodoWrite to track progress
Log all operations for debugging

Best Practices:

Test locally before deploying
Use preview deployments for validation
Monitor error tracking (Sentry)
Keep rollback procedure ready
Document any custom changes

Example Usage

# Full migration example
cd /Users/alias/Documents/GitHub

# Step 1: Clone Next Forge
git clone https://github.com/vercel/next-forge.git freo-cranes-staging
cd freo-cranes-staging

# Step 2: Run automated migration
# (Use this skill to guide the process)

# Step 3: Verify locally
pnpm dev

# Step 4: Deploy to Vercel
doppler run --config prd -- vercel --prod --yes

# Step 5: Browser validation
# (Use browser tools as shown above)

# Step 6: Switch domain
# (Use Vercel API as shown above)

Related Skills

vercel-auto-deploy: For standard Vercel deployments
superpowers-chrome:browsing: For browser-based testing
test-driven-development: For writing tests during migration

Version History

v1.0.0 (2025-11-20): Initial skill creation with full automation

More by danmarauda

View all

web-design-guidelines

Review UI code for compliance with web interface best practices. Audits code for 100+ rules covering accessibility, performance, and UX. Use when asked to review UI code, check accessibility, audit design, or check site against best practices.

react-native-guidelines

React Native best practices optimized for AI agents. Contains 16 rules across 7 sections covering performance, architecture, and platform-specific patterns. Use when building React Native or Expo apps, optimizing mobile performance, implementing animations or gestures, or working with native modules.

supabase-to-convex-migration

Migrate ANY Supabase project to Convex with exact feature/design/architecture parity. Complete database schema translation, function migration, authentication, real-time queries, RLS replacement, and storage migration. Use when converting Supabase backends to Convex or planning Supabase-to-Convex migrations.

vercel-ai-cortex-integrator

Analyzes codebase for structural, contextual, and semantic understanding, then fully integrates Vercel AI SDK 6 and Cortex Memory features using Nia for documentation research