Deploying Astro Apps vs Custom Node.js Servers on Vercel
@astrojs/vercel is the official integration adapter that allows Astro projects to deploy seamlessly to Vercel, enabling features like Server-Side Rendering (SSR), Image Optimization, and Edge Functions tailored for Astro's architecture. @vercel/node is a lower-level builder and runtime package that enables standard Node.js applications (such as Express or Koa servers) to run within Vercel's serverless infrastructure. While the former is a framework-specific bridge, the latter is a general-purpose tool for running custom Node.js code on the platform.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Astro Integration vs Raw Node Runtime on Vercel
When deploying to Vercel, developers often encounter two distinct packages: @astrojs/vercel and @vercel/node. While both enable JavaScript execution on Vercel's infrastructure, they operate at different layers. One is a framework adapter designed for content-driven sites, while the other is a runtime builder for custom server logic. Understanding the distinction is critical for architectural stability.
⚙️ Configuration Setup: Framework Adapter vs Manual Builder
@astrojs/vercel integrates directly into your Astro configuration.
- You define it as a plugin in
astro.config.mjs. - It automatically generates the necessary
vercel.jsonand serverless functions during build.
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';
export default defineConfig({
output: 'server',
adapter: vercel()
});
@vercel/node typically requires explicit configuration in vercel.json or relies on zero-config detection for API routes.
- You specify it as a builder if running a custom entry point.
- Useful for wrapping an existing Express app in a serverless function.
// vercel.json
{
"builds": [
{ "src": "server.js", "use": "@vercel/node" }
],
"routes": [
{ "src": "/(.*)", "dest": "server.js" }
]
}
📥 Request Handling: Astro Pages vs Custom Server Logic
@astrojs/vercel handles requests through Astro's routing system.
- Files in
src/pagesbecome routes automatically. - You write standard Astro components with frontmatter scripts.
// src/pages/api/users.astro
---
export async function GET() {
const users = await db.findAll();
return new Response(JSON.stringify(users));
}
---
<h1>Users</h1>
@vercel/node exposes a standard Node.js HTTP server interface.
- You manage routing manually or via a library like Express.
- The entry point must export a request handler compatible with Vercel's runtime.
// server.js
import server from 'express';
const app = server();
app.get('/api/users', async (req, res) => {
const users = await db.findAll();
res.json(users);
});
export default app;
🖼️ Asset Optimization: Built-In vs Manual Implementation
@astrojs/vercel includes automatic image optimization via Vercel's Image Optimization API.
- Astro's
<Image />component works out of the box. - No extra code is needed to resize or format images.
// src/pages/index.astro
import { Image } from 'astro:assets';
import hero from '../images/hero.jpg';
<Image src={hero} alt="Hero" width={800} />
@vercel/node does not provide automatic image optimization.
- You must implement resizing logic yourself or call external APIs.
- Requires additional dependencies like
sharpfor processing.
// server.js (Manual optimization)
import sharp from 'sharp';
app.get('/image', async (req, res) => {
const resized = await sharp('input.jpg').resize(800).toBuffer();
res.type('image/jpeg').send(resized);
});
🚀 Rendering Modes: Hybrid vs Single Runtime
@astrojs/vercel supports hybrid rendering strategies.
- You can mark some pages as static and others as server-rendered.
- The adapter manages the split between CDN caching and function execution.
// src/pages/blog/[slug].astro
---
export const prerender = false; // Forces SSR
---
<html>...</html>
@vercel/node runs as a consistent Node.js serverless function.
- Every request hits the function unless you implement caching headers.
- You are responsible for defining cache control policies manually.
// server.js
app.get('/data', (req, res) => {
res.set('Cache-Control', 'public, max-age=60');
res.json({ data: 'fresh' });
});
🛠️ When to Use Each Package
These tools solve different problems. @astrojs/vercel is purpose-built for the Astro framework, handling the complexity of translating Astro's output into Vercel's infrastructure. It manages routing, middleware, and assets automatically. In contrast, @vercel/node is a utility for running raw Node.js code. It is best reserved for scenarios where you are not using a framework adapter or need to migrate an existing Express application without rewriting it.
Shared Capabilities
Despite their differences, both packages leverage Vercel's underlying serverless infrastructure.
-
⚡ Serverless Execution
Both run code in isolated, scalable functions.// Both execute in Vercel's serverless environment // No server management required -
🌍 Environment Variables
Both access secrets viaprocess.env.const apiKey = process.env.API_KEY; // Works in both -
🔒 HTTPS Enforcement
Both benefit from Vercel's automatic SSL.// No manual HTTPS setup needed for either
📊 Summary: Key Differences
| Feature | @astrojs/vercel | @vercel/node |
|---|---|---|
| Primary Use | Astro Framework Deployment | Custom Node.js Server |
| Config Location | astro.config.mjs | vercel.json or Zero-Config |
| Routing | File-based (src/pages) | Manual (Express/Router) |
| Image Opt | Built-in (astro:assets) | Manual (e.g., sharp) |
| Rendering | Hybrid (Static + SSR) | Dynamic (Function per request) |
💡 The Big Picture
@astrojs/vercel is the standard choice for modern content sites built with Astro. It removes infrastructure overhead and lets you focus on components. Use this for blogs, marketing sites, and dashboards powered by Astro.
@vercel/node is a specialized tool for backend-heavy workloads or legacy migrations. It gives you full control over the server lifecycle but requires more maintenance. Use this for API gateways, microservices, or when Astro does not fit your architecture.
Final Thought: Do not mix these unnecessarily. If you are using Astro, the adapter handles everything. If you are running a standalone Node server, the builder ensures compatibility. Choosing the right tool prevents configuration drift and keeps deployments predictable.
How to Choose: @astrojs/vercel vs @vercel/node
- @astrojs/vercel:
Choose
@astrojs/vercelif you are building an application with the Astro framework. It automatically configures the necessary serverless functions, handles asset optimization, and supports Astro-specific features like hybrid rendering (static + SSR) without manual infrastructure setup. This is the required path for any Astro project targeting Vercel. - @vercel/node:
Choose
@vercel/nodeif you are deploying a custom Node.js server (like Express or Fastify) that does not use a framework adapter, or if you need specific control over the build process viavercel.json. It is suitable for legacy migrations or specialized backend services where zero-config serverless functions are insufficient.
Popular Comparisons
README for @astrojs/vercel
@astrojs/vercel
This adapter allows Astro to deploy your SSR site to Vercel.
Documentation
Read the @astrojs/vercel docs
Support
-
Get help in the Astro Discord. Post questions in our
#supportforum, or visit our dedicated#devchannel to discuss current development and more! -
Check our Astro Integration Documentation for more on integrations.
-
Submit bug reports and feature requests as GitHub issues.
Contributing
This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started:
License
MIT
Copyright (c) 2023–present Astro