Astro preview with the Vercel adapter

First published

I have a site built with Astro and deployed to Vercel. The site has thousands of pages, so it’s using ISR (Incremental Static Regeneration) to generate the pages on demand. This is great for performance, as pages are rendered on first request and then cached indefinitely, so the whole site is basically static. There is a catch, however: the Vercel adapter does not support local preview.

pn build && pn preview
> astro preview 
[preview] The @astrojs/vercel adapter does not support the preview command. 
Location:
  /Users/yusif/Developer/projects/project/node_modules/.pnpm/astro@5.7.12_@types+node@22.14.1_jiti@2.4.2_lightningcss@1.29.2_rollup@4.40.0_typescript@5.7.2_yaml@2.6.1/node_modules/astro/dist/core/preview/index.js:44:11
Stack trace:
  at preview (file:///Users/yusif/Developer/projects/project/node_modules/.pnpm/astro@5.7.12_@types+node@22.14.1_jiti@2.4.2_lightningcss@1.29.2_rollup@4.40.0_typescript@5.7.2_yaml@2.6.1/node_modules/astro/dist/core/preview/index.js:44:11)
  at async runCommand (file:///Users/yusif/Developer/projects/project/node_modules/.pnpm/astro@5.7.12_@types+node@22.14.1_jiti@2.4.2_lightningcss@1.29.2_rollup@4.40.0_typescript@5.7.2_yaml@2.6.1/node_modules/astro/dist/cli/index.js:152:22)
 ELIFECYCLE  Command failed with exit code 1.


While I do have the whole CI/CD pipeline set up, I still like to preview the site locally before deploying, so this is a bit of a bummer. Worry not though, as there is a workaround - the @astrojs/node adapter. The logic is pretty simple: we build and preview the site locally using the node adapter, while in production the Vercel adapter is used.

So, here’s how to do it: first, install the node adapter:

pn add @astrojs/node


Add the node adapter to your astro.config.mjs file:


import { defineConfig } from "astro/config";

import vercel from "@astrojs/vercel";
import node from "@astrojs/node"; 

import sitemap from "@astrojs/sitemap";

import tailwindcss from "@tailwindcss/vite";

let adapter = vercel({ isr: true }); 

if (process.argv[3] === "--node" || process.argv[4] === "--node") { 
adapter = node({ mode: "standalone" }); 
}

// https://astro.build/config
export default defineConfig({
site: "https://example.com",
integrations: [sitemap()],
adapter: vercel({ isr: true }), 
adapter, 
output: "server",
vite: {
  plugins: [tailwindcss()],
},
});


Then, we update the package.json scripts section to include the node adapter:

"scripts": {
  "dev": "astro dev",
  "build": "astro build",
  "build:node": "astro build --node", 
  "preview": "astro preview", 
  "preview": "astro preview --node", 
}


Now, instead of running pn build && pn preview, we run pn build:node && pn preview to preview the site locally.

pn build:node && pn preview
> project@0.0.1 preview /Users/yusif/Developer/projects/project
> astro preview --node

11:05:13 [@astrojs/node] Enabling sessions with filesystem storage
11:05:13 [@astrojs/node] Server listening on http://localhost:4321


Voilà! You can now preview your site locally while still using the Vercel adapter that does not support local preview.