Vercel Deployment

Relevant source files

• README.md
• README_EN.md
• docker-compose.yml
• docs/user/mcp-server.md
• docs/user/mcp-server_en.md
• env.local.example
• mkdocs/docs/zh/user/mcp-server.md
• package.json
• packages/core/package.json
• packages/core/src/services/model/defaults.ts
• packages/core/tests/unit/model/defaults.test.ts
• packages/desktop/package.json
• packages/extension/package.json
• packages/extension/public/manifest.json
• packages/mcp-server/package.json
• packages/mcp-server/src/config/models.ts
• packages/ui/package.json
• packages/web/package.json
• pnpm-lock.yaml
• vercel.json

Purpose and Scope

This document covers the Vercel deployment configuration for the Prompt Optimizer web application. It explains how the web package (@prompt-optimizer/web) is built and deployed to Vercel as a static single-page application (SPA), including build configuration, environment variable management, and routing setup.

For Docker deployment, see Docker Deployment. For desktop distribution, see Desktop Distribution. For general environment configuration, see Environment Configuration and API Keys.

Deployment Architecture

The Vercel deployment represents one of five deployment targets supported by the Prompt Optimizer monorepo. Unlike the Desktop or Docker deployments which can bypass CORS restrictions, Vercel deployment runs as a pure client-side application where all API calls originate directly from the user's browser to AI service providers.

Sources: README.md82-94 README_EN.md82-94 vercel.json1-32 Diagram 4 from context

Build Configuration

The Vercel build is configured through vercel.json, which handles the monorepo structure by executing custom build and install commands.

vercel.json Structure

Configuration Key	Value	Purpose
buildCommand	Complex conditional script	Handles both direct and extension-subfolder builds
installCommand	Conditional pnpm install	Installs dependencies with Vercel analytics
outputDirectory	packages/web/dist	Location of built static files
rewrites	SPA routing rules	Ensures client-side routing works
env	VITE_VERCEL_DEPLOYMENT: "true"	Build-time environment flag

Sources: vercel.json1-32

Build Command Logic

The build command in vercel.json2 handles two scenarios:

1. Normal build (when in root directory):

2. Extension subdirectory build (when Vercel detects packages/extension as root):

This complexity addresses Vercel's automatic subdirectory detection when deploying from GitHub, ensuring the full monorepo is built regardless of which directory Vercel considers the root.

Sources: vercel.json2 package.json12-17

Deployment Methods

Method 1: One-Click Deployment

The simplest deployment method uses Vercel's clone button, which creates a new repository copy and deploys it immediately:

Limitations:

• Cannot track upstream updates from the original repository
• No automatic updates when new features are released
• Suitable for quick testing or one-time deployments

Sources: README.md82-83 README_EN.md82-83

Method 2: Fork and Import (Recommended)

This method provides better long-term maintainability:

1. Fork the repository to your GitHub account
2. Import to Vercel through the Vercel dashboard:
   • Visit vercel.com/new
   • Select "Import Git Repository"
   • Choose your forked repository
3. Configure build settings (auto-detected from vercel.json)
4. Set environment variables (see below)
5. Deploy

Advantages:

• Can sync with upstream repository for updates
• Better version control and history
• Can configure custom domains easily
• Full control over build and deployment settings

Sources: README.md85-94 README_EN.md85-94

Environment Variables

Vercel environment variables are configured through the Project Settings → Environment Variables section in the Vercel dashboard. All variables must use the VITE_ prefix to be embedded in the browser bundle during the build process.

Setting environment variables in Vercel:

1. Navigate to your project in the Vercel dashboard
2. Go to Settings → Environment Variables
3. Add each variable with its value
4. Select environment scope: Production, Preview, or Development
5. Click Save and redeploy for changes to take effect

API Key Configuration

All API keys must use the VITE_ prefix to be accessible in the browser bundle:

Environment Variable	Purpose	Required
VITE_OPENAI_API_KEY	OpenAI API access	No
VITE_GEMINI_API_KEY	Google Gemini API access	No
VITE_DEEPSEEK_API_KEY	DeepSeek API access	No
VITE_ZHIPU_API_KEY	Zhipu AI API access	No
VITE_SILICONFLOW_API_KEY	SiliconFlow API access	No
VITE_CUSTOM_API_KEY_*	Custom model APIs (see below)	No
VITE_CUSTOM_API_BASE_URL_*	Custom model base URLs	No
VITE_CUSTOM_API_MODEL_*	Custom model names	No

Multi-Custom Model Pattern:

The system supports unlimited custom models using a suffix-based naming convention:

The suffix (e.g., ollama, myapi) becomes the identifier for that custom model configuration.

Sources: README.md89-91 README.md272-288 README_EN.md89-92 README_EN.md275-288

Access Control (Not Supported)

Password protection via ACCESS_PASSWORD is not supported in Vercel deployments:

Environment Variable	Supported in Vercel?	Notes
ACCESS_PASSWORD	❌ No	Requires NGINX or serverless function (not implemented)
ACCESS_USERNAME	❌ No	Docker-only feature

Why not supported:

• Vercel deploys static files directly to CDN
• No NGINX or server-side middleware to enforce authentication
• Implementing password protection would require custom Vercel Edge Functions or serverless API routes
• Current codebase is purely client-side with no server components

Alternatives:

• Use Docker deployment with NGINX basic authentication (see Docker Deployment)
• Implement Vercel Edge Middleware (requires custom development)
• Use Vercel's built-in Password Protection feature (Team/Enterprise plans only)

Sources: README.md90 docker-compose.yml40-41 docker/generate-auth.sh1-46

Build-Time Flag

The VITE_VERCEL_DEPLOYMENT environment variable is automatically set during Vercel builds:

This flag is defined in vercel.json24-30 and is embedded in the build. The application can use this to:

• Display CORS-related warnings
• Hide features requiring server-side processing
• Show Vercel-specific UI elements or documentation links

Example usage in code:

Sources: vercel.json24-30

Build Process Flow

The monorepo build follows a strict dependency order to ensure all packages are correctly built before the web application:

Build Artifacts Explained:

Package	Build Tool	Output Location	Key Files
@prompt-optimizer/core	tsup	packages/core/dist/	index.js (ESM), index.cjs (CommonJS), index.d.ts (types)
@prompt-optimizer/ui	Vite (library)	packages/ui/dist/	index.js, style.css, *.vue.d.ts
@prompt-optimizer/web	Vite (SPA)	packages/web/dist/	index.html, assets/index-[hash].js, assets/index-[hash].css

Build Scripts

The root package.json12-17 defines the build pipeline:

Build execution:

1. Sequential phase: Core → UI (must complete before next step)
2. Parallel phase: Web and Extension (can build simultaneously since both depend only on UI)
3. Output: Vercel serves packages/web/dist/ from CDN

Sources: package.json12-17 packages/core/package.json17 packages/ui/package.json26 packages/web/package.json8

Vite Configuration

The web package (packages/web/package.json8) uses Vite for bundling with SPA-optimized settings:

Configuration:

• Base path: ./ (relative paths for flexible hosting)
• Output directory: packages/web/dist/
• Build target: ES2020+ (modern browsers only)
• Code splitting: Automatic vendor chunk splitting
• Asset optimization: CSS/JS minification, tree-shaking, image optimization
• Source maps: Disabled in production builds

Build output structure:

packages/web/dist/
├── index.html                    # Entry point with script/style tags
├── assets/
│   ├── index-[hash].js          # Main application bundle (~200-300KB)
│   ├── index-[hash].css         # Compiled styles (~50-100KB)
│   ├── vendor-[hash].js         # Third-party libs (Vue, Naive UI, etc.)
│   └── [asset]-[hash].(woff2|png|svg)  # Static assets
├── favicon.ico
└── robots.txt

Hash-based caching: All assets use content hashes in filenames, enabling aggressive CDN caching with automatic cache busting on updates.

Sources: packages/web/package.json8

SPA Routing Configuration

Vercel's rewrites configuration ensures that Vue Router's client-side routing works correctly:

Routing Rules

Route Pattern	Destination	Purpose
/api/:path*	/api/:path*	Reserved for future API routes (currently unused)
/(.*)	/index.html	All other routes → SPA entry point

This configuration means:

• Direct access to any URL (e.g., https://yourdomain.com/pro/multi) serves index.html
• Vue Router handles the routing in the browser
• Hard refresh on any route still works correctly
• Deep linking is fully supported

Vue Router Routes

The application defines the following routes (handled client-side):

Route	Workspace Component	Mode
/basic/system	BasicSystemWorkspace	Basic system prompt optimization
/basic/user	BasicUserWorkspace	Basic user prompt optimization
/pro/multi	ContextSystemWorkspace	Multi-turn conversation testing
/pro/variable	ContextUserWorkspace	Variable extraction and management
/image/text2image	ImageText2ImageWorkspace	Text-to-image generation
/image/image2image	ImageImage2ImageWorkspace	Image-to-image transformation

Sources: vercel.json5-14 Diagram 3 from context

Storage and Persistence

Vercel deployments use browser-based storage since no server-side persistence is available:

Storage Implementation:

• DexieStorageProvider (IndexedDB): Used for structured data like models, templates, history, and favorites. Provides 50MB+ storage per origin.
• LocalStorageProvider (localStorage): Used for lightweight preferences and session state. Limited to ~5-10MB.

All data remains entirely client-side and is never transmitted to Vercel's servers or any intermediate servers.

Sources: Diagram 2 from context, packages/core/src/services

Limitations and Considerations

CORS Restrictions

As a pure client-side application deployed to Vercel's CDN, the web app is subject to browser CORS (Cross-Origin Resource Sharing) policies. This means API requests originate directly from the user's browser, not from a backend server.

Why CORS matters:

Browser security prevents JavaScript on https://your-vercel-domain.com from making requests to http://localhost:11434 (local Ollama) or enterprise APIs that don't allow arbitrary origins.

Problematic scenarios:

Scenario	Issue	Error
Local Ollama without CORS config	Request blocked	CORS policy: No 'Access-Control-Allow-Origin' header
Commercial API with origin whitelist	Origin not in whitelist	CORS policy: Origin not allowed
Mixed content (HTTPS → HTTP)	Browser security policy	Mixed Content: blocked loading insecure endpoint
Strict Content Security Policy	CSP blocks external requests	Refused to connect: violates CSP directive

Workarounds:

1. Desktop application (recommended): No CORS restrictions, runs as native app

   • Download: GitHub Releases
   • See Desktop Application

2. Configure CORS on local services:

3. Deploy API proxy service: Use OneAPI, NewAPI, or custom proxy with proper CORS headers

   • Proxy handles CORS and forwards to actual API
   • See Environment Configuration for custom API setup

4. Docker deployment (HTTP): Access via http://localhost:8081 avoids mixed content issues

   • See Docker Deployment

Technical explanation:

When you configure an API key in the Vercel-deployed app, the API call flow is:

User Browser (https://your-app.vercel.app)
    → API Provider (https://api.openai.com) ✓ CORS allowed
    → Local Service (http://localhost:11434) ✗ CORS + Mixed Content blocked

Sources: README.md356-380 README_EN.md356-382 packages/core/src/services/llm/adapters

No Server-Side Processing

Vercel deployment is purely static – all files are served from CDN without server-side execution:

What's NOT possible:

Feature	Why Not Available	Workaround
Server-side API key storage	No backend to store secrets	Users configure keys in browser
Request rate limiting	No server to track requests	Use provider's built-in limits
Centralized logging	No server to collect logs	Use browser DevTools console
Password protection (NGINX)	No NGINX or server middleware	Use Docker deployment (Docker Deployment)
API key validation	No backend to verify keys	Client attempts request and handles error

Security implications:

1. API keys in browser: Users configure keys via UI, stored in IndexedDB

   • Keys never leave the user's browser
   • Each user manages their own keys
   • No shared secrets or server-side key storage

2. No backend exposure: Since there's no backend, there's nothing to secure or exploit

   • All API calls go directly from browser to provider
   • No intermediate server to intercept or log requests

3. Client-side validation only: The app cannot enforce policies like:

   • API usage quotas across users
   • Request rate limiting
   • API key rotation requirements

For enterprise deployment with authentication and logging, use:

• Docker Deployment with NGINX basic auth
• Self-hosted backend with custom authentication layer
• Vercel Edge Functions (requires custom development)

Sources: docker/generate-auth.sh1-46 packages/core/src/storage/dexie-storage.ts

Build Time Limitations

Vercel free tier has build time limits:

• Build timeout: 45 seconds (free tier), 45 minutes (pro tier)
• Build cache: Speeds up subsequent builds
• Concurrent builds: 1 (free tier), multiple (pro tier)

The monorepo build typically completes in 2-4 minutes, well within free tier limits.

Sources: vercel.json1-32

Deployment Verification

After deployment completes, Vercel provides a deployment URL (e.g., https://prompt-optimizer-abc123.vercel.app). Verify the deployment using this checklist:

Detailed verification steps:

Step	Action	Expected Result	Troubleshooting
1	Open deployment URL	App loads, shows workspace selector	Check build logs if 404/500
2	Click navigation links	Smooth transitions, no page reload	Verify vercel.json5-14 rewrites
3	F12 → Application → Storage	IndexedDB: PromptOptimizerDB exists	Enable 3rd-party cookies if needed
4	Settings → Model Manager → Add Model	Can input API key and save	Check localStorage quota
5	Basic mode → Enter prompt → Optimize	Streaming response appears	Check CORS, API key validity

Common issues:

1. 404 on direct route access: Rewrites not applied → Check vercel.json is committed
2. Blank page on load: Build error → Check Vercel build logs
3. Storage quota exceeded: Clear browser data → Reduce history retention
4. CORS errors: Use Desktop app or add CORS headers to API endpoint

Sources: vercel.json5-14 packages/core/src/storage/dexie-storage.ts

Custom Domain Configuration

Vercel supports custom domains through the dashboard:

1. Add domain in project settings
2. Configure DNS (A record or CNAME)
3. Enable HTTPS (automatic via Let's Encrypt)
4. Set as primary (optional)

Custom domains work identically to .vercel.app domains with the same routing and environment variable configuration.

Sources: README.md82-94 README_EN.md82-94