From a2ab8775d9b4b2c0f9c5d41738ab0f2bdcb824a6 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 21 Dec 2025 11:52:43 +0000
Subject: [PATCH] chore: add Vercel deploy preview configuration

- Add vercel.json with Vite framework settings
- Configure SPA routing with rewrites
- Set up asset caching headers
- Add .vercelignore to exclude unnecessary files
- Add VERCEL_SETUP.md with step-by-step setup instructions

This enables automatic deploy previews for every PR once the repo is connected to Vercel.
---
 .vercelignore   |  27 ++++++++++++
 VERCEL_SETUP.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++
 vercel.json     |  33 ++++++++++++++
 3 files changed, 172 insertions(+)
 create mode 100644 .vercelignore
 create mode 100644 VERCEL_SETUP.md
 create mode 100644 vercel.json

diff --git a/.vercelignore b/.vercelignore
new file mode 100644
index 0000000..10c84b8
--- /dev/null
+++ b/.vercelignore
@@ -0,0 +1,27 @@
+# Dependencies
+node_modules
+
+# Testing
+coverage
+*.test.ts
+*.test.tsx
+**/__tests__
+
+# Development
+.env.local
+.env.development
+
+# IDE
+.vscode
+.idea
+
+# Git
+.git
+.github
+
+# Documentation (not needed for deployment)
+CLAUDE.md
+README.md
+
+# Test configuration
+vitest.config.ts
diff --git a/VERCEL_SETUP.md b/VERCEL_SETUP.md
new file mode 100644
index 0000000..3e10e6e
--- /dev/null
+++ b/VERCEL_SETUP.md
@@ -0,0 +1,112 @@
+# Vercel Deploy Preview Setup
+
+This guide walks you through setting up automatic deploy previews on Vercel for every pull request.
+
+## Prerequisites
+
+- GitHub repository with push access
+- Vercel account (free tier works fine)
+
+## Setup Steps
+
+### 1. Connect Repository to Vercel
+
+1. Go to [vercel.com](https://vercel.com) and sign in with your GitHub account
+2. Click "Add New..." → "Project"
+3. Import your `purrgrammer/grimoire` repository
+4. Vercel will auto-detect the Vite framework settings (already configured in `vercel.json`)
+
+### 2. Configure Project Settings
+
+Vercel should automatically detect:
+- **Framework Preset**: Vite
+- **Build Command**: `npm run build`
+- **Output Directory**: `dist`
+- **Install Command**: `npm ci`
+
+If not auto-detected, these are already specified in `vercel.json`.
+
+### 3. Deploy
+
+1. Click "Deploy" to create your first production deployment
+2. Vercel will build and deploy your main branch
+
+### 4. Enable PR Previews (Auto-Enabled)
+
+By default, Vercel automatically:
+- Creates a preview deployment for every PR
+- Updates the preview on every commit to the PR
+- Posts deployment status and preview URL as a comment on the PR
+- Runs builds in parallel with GitHub Actions
+
+### 5. Configure GitHub Integration (Optional)
+
+In your Vercel project settings → Git:
+- ✅ **Production Branch**: Set to `main` (or your default branch)
+- ✅ **Preview Deployments**: Enabled for all branches
+- ✅ **Auto-assign Custom Domains**: Enabled
+- ✅ **Comments on Pull Requests**: Enabled
+- ✅ **Deployment Protection**: Configure as needed
+
+## How It Works
+
+Once configured, for every PR:
+
+1. Developer opens a PR → Vercel automatically builds and deploys
+2. Vercel posts a comment with the preview URL
+3. New commits to the PR → Vercel rebuilds and updates the preview
+4. PR merged → Vercel deploys to production
+
+## Preview URL Format
+
+- **Production**: `grimoire.vercel.app` (or your custom domain)
+- **PR Previews**: `grimoire-git-<branch-name>-<team>.vercel.app`
+- **Unique deployment**: `grimoire-<hash>.vercel.app`
+
+## Environment Variables
+
+If your app needs environment variables:
+
+1. Go to Project Settings → Environment Variables
+2. Add variables for:
+   - **Production** (main branch)
+   - **Preview** (PR branches)
+   - **Development** (local dev)
+
+## Configuration Files
+
+- **`vercel.json`**: Build settings, rewrites, headers, caching
+- **`.vercelignore`**: Files to exclude from deployment
+
+## Troubleshooting
+
+### Build Fails on Vercel
+
+Check the build logs in Vercel dashboard. Common issues:
+- Missing environment variables
+- TypeScript errors (ensure `npm run build` works locally)
+- Node version mismatch (Vercel uses Node 20 by default)
+
+### Preview Not Created
+
+Ensure:
+- GitHub integration is connected
+- Repository has proper permissions in Vercel
+- PR is targeting the correct base branch
+
+### Changes Not Reflected
+
+- Clear Vercel cache: Project Settings → Clear Cache
+- Redeploy from the Deployments tab
+
+## Security Notes
+
+- Preview deployments are **publicly accessible** by default
+- Use Vercel's Deployment Protection for sensitive projects
+- Never commit secrets to the repository
+
+## Additional Resources
+
+- [Vercel Documentation](https://vercel.com/docs)
+- [Vercel Git Integration](https://vercel.com/docs/concepts/git)
+- [Preview Deployments](https://vercel.com/docs/concepts/deployments/preview-deployments)
diff --git a/vercel.json b/vercel.json
new file mode 100644
index 0000000..dec5707
--- /dev/null
+++ b/vercel.json
@@ -0,0 +1,33 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "buildCommand": "npm run build",
+  "devCommand": "npm run dev",
+  "installCommand": "npm ci",
+  "framework": "vite",
+  "outputDirectory": "dist",
+  "cleanUrls": true,
+  "trailingSlash": false,
+  "rewrites": [
+    {
+      "source": "/(.*)",
+      "destination": "/index.html"
+    }
+  ],
+  "headers": [
+    {
+      "source": "/assets/(.*)",
+      "headers": [
+        {
+          "key": "Cache-Control",
+          "value": "public, max-age=31536000, immutable"
+        }
+      ]
+    }
+  ],
+  "github": {
+    "enabled": true,
+    "autoAlias": true,
+    "silent": false,
+    "autoJobCancelation": true
+  }
+}