🗄️ Deploy an Express Application to Vercel

web

Vercel is a developer cloud to build and deploy web applications. It's very easy to deploy static files or projects using Next.js framework, but for Express applications, its documents are very simple and not easy to follow.

Setup your Express.js app

For simple apps, you can follow these instructions in the official doc:

  1. Create an /api directory (do NOT change the name) in your project root.
  2. Inside /api, create an index.js or index.ts file—this is your main server entry point.

Note: On Vercel, backend files are deployed as serverless functions. Each file in /api is an entry point. On the free plan, you are limited to 14 serverless functions. To keep things organized, put your actual routes and logic outside api folder and import them in index.js, or put them all in the main file.

Example /api/index.js:

const express = require('express')
const app = express()
 
// Import your routes
const userRoutes = require('./routes/user')
app.use('/user', userRoutes)
 
// Export as Vercel handler
module.exports = app

Configure your project for Vercel

Create a file named vercel.json in your project root. This file tells Vercel how to route requests.

vercel.json
{
  "version": 2,
  "routes": [
    {
      "src": "/api/(.*)",
      "dest": "api/index.js"
    },
    {
      "src": "/assets/(.*)",
      "dest": "/assets/$1"
    },
    {
      "src": "/favicon.ico",
      "dest": "/favicon.ico"
    },
    {
      "src": "/(.+)",
      "dest": "/"
    }
  ]
}
  • API calls (/api/*) are sent to your Express server.
  • Static files under /assets are served directly by Vercel.
  • Favicon and other static files are handled explicitly.
  • SPA fallback: Any other route falls back to /index.html (for single-page apps).

Tip: If you use TypeScript, make sure your build outputs JavaScript files to the /api directory, or adjust your build process accordingly.

Environment Variables

Set environment variables in the Vercel dashboard under Project Settings > Environment Variables.
You can access them in your Express app using process.env.MY_VARIABLE.

Custom Domain

If you have a custom domain (e.g., from Dynadot), configure DNS as follows:

Record TypeIP Address/DestinationSubdomain
Domain RecordA76.223.126.88N/A
Subdomain RecordsCNAMEname-china.vercel-dns.comwww
  1. Add your domain and www.<your-domain> in the Vercel dashboard.
  2. Set up a redirect rule in Vercel to forward www.<your-domain> to <your-domain> for canonical URLs.

Use Vercel CLI (optional)

  1. Install Vercel CLI:

    npm i -g vercel

  2. Deploy your project:

    vercel

    Follow the prompts to link your project and deploy.

  3. Automatic Deployments:
    If your project is connected to GitHub/GitLab/Bitbucket, every push to the main branch will trigger a deployment.

Limitations and Best Practices

  • Cold starts: Serverless functions may have a short delay on the first request after inactivity.
  • No persistent filesystem: Use external storage (e.g., S3, databases) for file uploads or persistent data.
  • Timeouts: Serverless functions have execution time limits (10s for Hobby, 60s for Pro/Enterprise).
  • Keep dependencies minimal: Only include what you need in /api to reduce cold start times.

Debugging

  • Logs: View logs in the Vercel dashboard under your project’s "Functions" tab.
  • Local testing: You can run your Express app locally with node api/index.js or use vercel dev for local emulation.

References