The Vercel Adapter enables Astro applications to be deployed seamlessly to the Vercel platform. It transforms Astro's build artifacts into Vercel's Build Output API v3 compatible format, supporting:
@astrojs/vercel/cache providerThis page provides a comprehensive technical overview of the Vercel adapter implementation detailing how these features are realized, the involved data flows, and the core code entities.
The Vercel adapter integrates with the Astro build lifecycle through its integration hooks. It converts Astro's output into Vercel's expected directory and configuration structure and bundles serverless functions with exact dependencies using NFT.
The adapter supports two middleware modes: classic Node.js serverless functions and the new edge middleware mode, deployable as Vercel Edge Functions.
Vercel Build Output Generation:
index.ts, exporting the adapter definition, managing bundling and config output packages/integrations/vercel/src/index.ts100-144copyDependenciesToFunction() in lib/nft.ts bundles server function dependencies using @vercel/nft packages/integrations/vercel/src/lib/nft.ts8-85generateEdgeMiddleware() in serverless/middleware.ts packages/integrations/vercel/src/serverless/middleware.ts27-92getRedirects() from lib/redirects.ts packages/integrations/vercel/src/lib/redirects.ts1-134serverless/entrypoint.ts) handles incoming requests on Vercel packages/integrations/vercel/src/serverless/entrypoint.ts1-72.vercel/output/ directory with static, functions, and config subfolders.Sources:
The adapter exposes a flexible configuration interface via the VercelServerlessConfig type for customizing deployment behavior and platform features:
| Option | Type | Description |
|---|---|---|
webAnalytics | VercelWebAnalyticsConfig | Configuration for Vercel Web Analytics |
includeFiles | string[] | Extra files to forcibly include in function bundling |
excludeFiles | string[] | Files to exclude from function bundling |
imageService | boolean | Enable Vercel Image Optimization API usage |
imagesConfig | VercelImageConfig | Settings for image optimization such as allowed sizes and domains |
devImageService | DevImageService | Choose image service in development when imageService is enabled |
middlewareMode | `'classic' | 'edge'` |
maxDuration | number | Serverless function max timeout duration in seconds |
isr | `boolean | VercelISRConfig` |
skewProtection | boolean | Enable deployment skew protection to avoid stale content issues |
staticHeaders | boolean | Save static headers metadata for CSP and other headers in output API |
Sources:
ISR allows caching and regeneration of dynamic pages on-demand, improving freshness without full rebuilds.
Vercel expects ISR routes to be rewritten to a special query pattern:
/_isr?x_astro_path=$0
$0 captures the original incoming path.ISR_PATH internally with ASTRO_PATH_PARAM set to 'x_astro_path' packages/integrations/vercel/src/index.ts44-63config.json, routes are mapped with this rewritten path to handle ISR requests.ISR Logic Flow:
Astro routes configured for ISR are normalized and transformed via Vercel's routing utilities to match expected path-to-regexp syntax, enabling proper ISR dispatching.
Sources:
Serverless functions require bundling of all code dependencies to ensure runtime completeness. The adapter uses NFT to perform this.
copyDependenciesToFunction() takes an entry file and output directory packages/integrations/vercel/src/lib/nft.ts8-85nodeFileTrace to collect all imported files.sharp, internal Astro packages) are logged but ignored.Sources:
The adapter supports Vercel Edge Middleware with middlewareMode: 'edge'.
esbuild targeting Edge runtime constraints.middlewareSecret header for authentication between middleware and serverless function.ctx), and forwards the request internally to the serverless function at path /_render.Sources:
The serverless function entrypoint (serverless/entrypoint.ts) exports a fetch handler to:
x-astro-middleware-secret) packages/integrations/vercel/src/serverless/entrypoint.ts16-72x-astro-path header if valid.x-vercel-isr is set.x-deployment-id if configured.app.render() to generate an Astro response.Sources:
The adapter integrates with Vercel's image optimization for <Image> components.
build-service.ts)/_vercel/image packages/integrations/vercel/src/image/build-service.ts6-64sizes from Vercel image config packages/integrations/vercel/src/image/shared.ts100-171srcset attributes for img tags.dev-service.ts)astro dev runs packages/integrations/vercel/src/image/dev-service.ts1-32Sources:
Astro route caching is supported via cacheVercel().
cacheVercel() from @astrojs/vercel/cache and set it in astro.config.mjs packages/integrations/vercel/CHANGELOG.md41-54Vercel-CDN-Cache-Control and Vercel-Cache-Tag headers packages/integrations/vercel/CHANGELOG.md58-67cache.invalidate() packages/integrations/vercel/CHANGELOG.md80-95Sources:
Skew protection protects against serving stale content from superseded deployments during rolling deploys.
x-deployment-id with the current Vercel deployment ID packages/integrations/vercel/src/index.ts128-143Sources:
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.