How to Deploy Folia to Vercel: Complete Guide for React Vite Apps

Deploy Folia to Vercel by clicking the "Deploy" button in the repository README, configuring the required environment variables for the NetEase music API and AI provider, and pushing to main to trigger automatic builds.

Folia is a React-based music discovery application built with Vite that ships with production-ready Vercel configuration. The chthollyphile/folia-major repository includes pre-configured build settings and environment variable templates, allowing you to deploy Folia to Vercel in minutes without custom build scripts.

One-Click Deployment from GitHub

The fastest way to deploy Folia to Vercel uses the official deployment button embedded in README.md at line 22. This button initiates Vercel's import flow and automatically clones the repository into a new project under your account.

Clicking the Deploy button opens Vercel's "Import Project" interface with the repository URL pre-populated. After you select your GitHub account and confirm the project creation, Vercel automatically detects the Vite framework and configures the build command (npm run build) and output directory (dist/).

Required Environment Variables Configuration

Folia requires specific environment variables to connect to the NetEase Cloud Music API and your chosen AI provider. According to docs/technical.md (lines 101-113), you must configure these in the Vercel dashboard under Settings → Environment Variables before your first deployment.

Music API Configuration

The application requires the VITE_NETEASE_API_BASE variable to communicate with the NetEase Cloud Music API backend.

• Variable: VITE_NETEASE_API_BASE
• Description: Base URL of your NeteaseCloudMusicApiEnhanced service instance
• Required: Yes

AI Provider Configuration

Folia supports two AI backends: Google Gemini or any OpenAI-compatible API. Set VITE_AI_PROVIDER to "google" or "openai" to select your backend.

For Google Gemini:

• GEMINI_API_KEY: Your Gemini API key

For OpenAI-compatible providers:

• OPENAI_API_KEY: Your API key
• OPENAI_API_URL: Full endpoint URL (e.g., https://api.openai.com/v1/chat/completions)
• OPENAI_API_MODEL: Model identifier (e.g., gpt-4o, deepseek-v4-flash)

You can add these via the Vercel CLI instead of the dashboard:

vercel env add VITE_NETEASE_API_BASE production
vercel env add VITE_AI_PROVIDER production
vercel env add GEMINI_API_KEY production

To sync existing environment variables to your local machine, run:

vercel env pull .env.local

Local Development and Testing

Before deploying to production, verify your configuration locally using the Vercel CLI. The vercel dev command (documented in docs/technical.md lines 80-87) runs the same build pipeline locally, including the Vite dev-lyric-proxy plugin and PWA manifest generation.

First, install dependencies and prepare your environment file:

npm install
cp .env.example .env.local

Then start the local development server:

vercel dev

This serves the application on port 3000 by default, using the same configuration that Vercel applies in production builds.

Build Configuration and Deployment

Once environment variables are configured, Vercel automatically executes npm run build on every push to the main branch. The build process generates a static output in the dist/ directory, which Vercel serves through its edge network without requiring additional server configuration.

The Vite configuration in vite.config.ts (lines 40-46) detects the Vercel environment by checking process.env.VERCEL_GIT_COMMIT_SHA. When present, it injects commit metadata into the build for debugging and version display purposes.

Push changes to trigger a deployment:

git add .
git commit -m "Configure environment variables"
git push origin main

Vercel's CI pipeline detects the push, runs the build, and deploys the updated static assets automatically.

Summary

• One-click setup: Use the Deploy button in README.md line 22 to import chthollyphile/folia-major into a new Vercel project.
• Environment variables: Configure VITE_NETEASE_API_BASE and VITE_AI_PROVIDER (plus provider-specific keys) in the Vercel dashboard or via CLI.
• Local testing: Run vercel dev to validate the production build pipeline locally before pushing.
• Automatic deployment: Pushes to main trigger npm run build, outputting static files to dist/ for edge distribution.
• Vercel detection: The Vite build automatically detects Vercel via VERCEL_GIT_COMMIT_SHA and injects commit metadata.

Frequently Asked Questions

What environment variables are required to deploy Folia to Vercel?

You must set VITE_NETEASE_API_BASE for the music API and VITE_AI_PROVIDER to select your AI backend. If using Google Gemini, provide GEMINI_API_KEY. If using an OpenAI-compatible service, provide OPENAI_API_KEY, OPENAI_API_URL, and OPENAI_API_MODEL. These are documented in docs/technical.md lines 101-113.

Can I test Folia locally before deploying to Vercel?

Yes. Run vercel dev after installing dependencies and copying .env.example to .env.local. This command uses the same build configuration as Vercel production, including the Vite dev-lyric-proxy plugin, allowing you to verify API connections and environment variables before pushing to GitHub.

How does Folia detect that it is running on Vercel?

The vite.config.ts file checks for the VERCEL_GIT_COMMIT_SHA environment variable (lines 40-46). When this variable exists, the build process injects commit metadata into the application, enabling version tracking and debugging features specific to Vercel deployments.

Does Folia require additional build configuration for Vercel?

No. The repository includes a standard Vite configuration that Vercel automatically detects. The build command npm run build outputs static files to the dist/ directory, which Vercel serves by default. No custom vercel.json or additional build scripts are required.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}