Getting started
Express.js is one of the most popular framework choices for building a backend using Node.js. If you are starting a new Express project and want to deploy it to Vercel, we recommend you to follow the Using Express.js with Vercel guide.
Common patterns
If you are coming from an existing project, we’ve put together this example repository to showcase the common development patterns for Express apps.
We recommend hosting your frontend application on a separate Vercel project to ensure that your frontend benefits from Vercel’s optimized CDN, reduced cost, and minimized complexity. However, if you wish to host it via Express, you can do it with minimal changes in your code.
Express with Vite (React)
The best way to use Express with your Vite project is to create a api/index.js file in your Vite project and add the server code to it. After this, you only need to ensure that your Vercel project is using the Vite preset.
After a successful deployment, you can also confirm from the deployment details page that the Vite app is served as static assets and the Express app as a serverless function:
Express with static content
You may want to serve some static content behind a route handler in the Express application. To do so, you can create a route handler and return the HTML response as you would do in any Express application, as follows:
// send the about.html file
app.get("/about", function (req, res) {
// run custom logic to authenticate request or log data
res.sendFile(path.join(__dirname, "..", "static", "about.html"));
});
However, you must note that serving static content through Express is an anti-pattern because it doesn’t utilizes the Vercel CDN and also adds to the cost of Vercel serverless function invocation for each request.
CORS with Express
To enable CORS on your Express application, you can use the cors middleware, as follows:
const app = express();
app.use(
cors({
origin: ["http://localhost:3000", "https://YOUR_FRONTEND_DOMAIN"],
})
);
Troubleshooting common issues
This guide is to help you troubleshoot common issues when migrating your Express project to a serverless platform.
Running the Node app
If you are coming from a server platform, you may have your start script setup to node index.js or something similar. However, this will not work on Vercel because it’s a serverless platform. Therefore, your application needs to be encapsulated in a serverless function that gets executed on request. We recommend following the Using Express.js with Vercel guide to get started.
Using incorrect project structure
In your project, you may have the main server file located at the root of the project or nested somewhere else. But, when using Express with Vercel, you must expose the main server from the /api folder. This way Vercel knows where to look for the serverless functions and deploy it correctly.
Missing rewrites configuration
By default, your Express application will be served from the /api/YOUR_SERVER_FILE_NAME endpoint. To ensure that all requests on your deployment reach your Express server, you must add the rewrites configuration to your project’s vercel.json, as follows:
"rewrites": [{ "source": "/(.*)", "destination": "/api" }],
Missing files
If you are getting missing files or file not found errors in your deployed application, you can use the includeFiles option in the functions configuration. This ensures the Vercel includes these files in the deployment output and your code can access them.
For example, if your app has some predefined HTML templates that you want to use, you can keep the templates folder at the project root and then update the vercel.json file with the functions > includeFiles configuration.
"functions": {
"api/index.js": {
"includeFiles": "templates/**/*"
}
}
Using legacy vercel.json configuration
You may be using legacy configuration options such as routes and builds in your vercel.json file. While these options may not cause issues directly, it’s better to use the updated options to make use of the latest features and avoid issues. To get started, follow the Upgrading legacy route guide.