astro-webflow-to-vercel

Migrate Astro from Webflow Cloud to Vercel

What this skill does

Moving an Astro app from Webflow Cloud to Vercel mostly means swapping the adapter, not rewriting the app. On Webflow Cloud the app runs as a Cloudflare Worker through the @astrojs/cloudflare adapter, served from a mount path inside a Webflow site. On Vercel the same app runs on Vercel Functions with Fluid compute on by default, in a full Node.js runtime, served from the root, so it scales with traffic on its own and supports Astro's full on-demand rendering feature set.

The app code (pages, components, Server Endpoints) mostly stays the same. The work sits in a few places: the Astro adapter and config, the Webflow Cloud and Wrangler config files that get deleted, the base path the app mounted under, the Edge runtime directive on API routes, and any server code that read storage bindings through locals.runtime.env.

The Vercel Plugin

The user will have installed the Vercel Plugin already, which among other things includes a number of helpful skills that can assist you and the user with this migration. Prefer those skills for current, detailed product guidance, and let this skill drive the order of work. The ones that line up with these steps:

• vercel-storage and marketplace: step 5 (Blob, Edge Config, Neon, Upstash, and Marketplace provisioning).
• env-vars: steps 5 and 6 (vercel env, .env files, OIDC tokens).
• vercel-cli and deployments-cicd: steps 6 and 7 (env vars and deploy).
• vercel-functions: step 5 (Server Endpoints on Vercel Functions) and the Best practices section (maxDuration, regions, ISR).

There are other skills included that may assist with the migration.

Steps the user completes manually

You handle most of the migration directly by editing files and running commands. A few actions need the Vercel dashboard, a Vercel account, or secret values, so the user has to do those:

• Creating the Vercel account (see Before you start).
• Creating and connecting the backing stores in step 5.
• Adding environment variables in step 6.
• Deploying in step 7.

Guide the user through each of these. Give clear, specific instructions, then wait for them to confirm before moving on. Do not report any of them as done while the user still has to do it.

If you are unsure about a dashboard flow or whether a detail is still current, use an applicable Vercel skill when one is available (see "The Vercel Plugin" above), and check the latest with a web search scoped to the vercel.com domain (for example, site:vercel.com vercel blob oidc token).

Service mapping (quick reference)

Before you start

Check the repo for these, and ask the user to confirm anything the repo cannot show:

• A working Astro app deployed on Webflow Cloud. Look for astro in package.json and the @astrojs/cloudflare adapter in astro.config.mjs to confirm the framework and platform before changing anything.
• Node.js 20 or later.
• A Vercel account (the user confirms this; you cannot create one).
• The Vercel CLI, for the env and deploy steps: npm i -g vercel.

Do not use this skill for a different framework, a brand-new app (set it up for Vercel directly instead), or a move in the other direction (Vercel to Webflow Cloud).

Steps

Work through these in order. Step 0 tells you which of steps 3 and 5 apply, so you can skip what the app does not use.

Step 0: Audit the current Webflow Cloud setup

Run the audit script from the project root:

bash scripts/audit.sh /path/to/project

It reports the Webflow Cloud and Wrangler config files, the @astrojs/cloudflare adapter and its platformProxy option, the react-dom/server.edge Vite alias, the base path (base and build.assetsPrefix) and its manual prefixing, any runtime: 'edge' directives on routes, every locals.runtime.env / Astro.locals.runtime.env access, and which storage bindings are declared in wrangler.json (Object Storage, Key Value Store, SQLite). Use the output to pick which later steps apply, then show the user a short checklist. Skipping this leads to missed bindings and runtime errors.

Step 1: Replace the Cloudflare adapter with the Vercel adapter

Astro needs an adapter to server-render on each platform, so the core setup change is swapping one adapter for the other. Uninstall the Cloudflare adapter and Wrangler, then install the Vercel adapter:

npm uninstall @astrojs/cloudflare wrangler
npm install @astrojs/vercel

Update astro.config.mjs to import and use the Vercel adapter. Keep output: "server" to render every route on demand as a Vercel function, which matches how the app ran on Webflow Cloud:

import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel";
import react from "@astrojs/react";

export default defineConfig({
  output: "server",
  adapter: vercel(),
  integrations: [react()],
});

The react() integration above is only an example; keep whatever integrations the app already declares and just swap the adapter.

If most pages are static and only a few are dynamic, set output: "static" instead and add export const prerender = false to the components that need server rendering.

Two Cloudflare-specific options can go at the same time. Remove the platformProxy setting, which only configured the Workers runtime for local development, and remove the react-dom/server.edge Vite alias, a Workers workaround the Node.js runtime doesn't need.

Step 2: Remove the Webflow Cloud configuration files

Delete the Cloudflare- and Webflow-specific files that no longer apply on Vercel:

• webflow.json, which told Webflow Cloud your framework. Vercel detects Astro automatically.
• wrangler.json, including its compatibility_date, nodejs_compat flag, assets binding, and storage bindings. Vercel Functions run on Node.js, so the compatibility flags have no equivalent.
• worker-configuration.d.ts, the generated binding types.

Your storage bindings live in wrangler.json. Before deleting the file, note which bindings the app uses (Object Storage, Key Value Store, or SQLite) so you can recreate them on Vercel in step 5.

Step 3: Remove the base path and Edge runtime settings

On Webflow Cloud the app is served from a mount path such as /app, so base and build.assetsPrefix are set in astro.config.mjs to match. On Vercel the app is served from the root, so remove both options unless you intend to keep serving the app under a subpath:

import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel";

export default defineConfig({
  // Remove base and build.assetsPrefix when serving from the root
  // base: "/app",
  // build: { assetsPrefix: "/app" },
  output: "server",
  adapter: vercel(),
});

Because the base path is gone, remove the manual prefixing Webflow Cloud required in client-side fetch calls and asset references. Change fetch(${import.meta.env.BASE_URL}/api/users) back to fetch("/api/users"), and drop import.meta.env.ASSETS_PREFIX from plain <img> tags and from the favicon link in your layout.

Webflow Cloud also runs API routes on the Edge runtime. Remove the export const config = { runtime: 'edge' } directive from your Server Endpoints so they run on the default Node.js runtime. Migrating from the Edge runtime to Node.js is recommended for performance and reliability, both runtimes run on Fluid compute with Active CPU pricing, and Node.js gives your routes the full Node.js API surface and access to npm packages that depend on Node.js built-ins.

Step 4: Update your build scripts

Replace the Webflow Cloud preview script in package.json with the standard Astro commands. Vercel runs the build for you, so you no longer need Wrangler to preview the Workers build:

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

Vercel auto-detects Astro on import and sets the build command and output directory, so these scripts mainly support local development.

Step 5: Replace Webflow Cloud bindings with Vercel storage

This is the main code change. On Webflow Cloud you read storage through bindings on the Cloudflare runtime, accessed in a Server Endpoint through the locals object (locals.runtime.env) and in components through Astro.locals.runtime.env. On Vercel you read connection details from process.env and talk to each store through its SDK. Remove every locals.runtime.env and Astro.locals.runtime.env access, and replace the binding operations. Read references/service-mapping.md for the before and after code for each binding, then install the SDK you need, for example:

npm i @vercel/blob

Have the user create and connect the backing stores. This is what adds the env vars the code reads, so it has to be done before the app will run:

• Object Storage to Blob: create a Blob store on the Storage page, then connect it to the project from the store's Projects tab. Vercel adds the store's environment variables, including a short-lived VERCEL_OIDC_TOKEN that it rotates, and the SDK uses them automatically, so put() needs no token in code. This OIDC approach is recommended over the long-lived BLOB_READ_WRITE_TOKEN, which is only for code that runs outside Vercel.
• Key Value Store to Redis: add a Redis integration such as Upstash Redis for caching and session data, or use Edge Config for small, read-heavy config.
• SQLite to Postgres: add a Postgres database such as Neon. If you used Drizzle ORM with SQLite, Drizzle supports Postgres too, so you keep your schema-first workflow.

Provisioning a store from the Marketplace adds its connection string and credentials as env vars, which the code reads from process.env.

Step 6: Move environment variables and secrets

Recreate your Webflow Cloud environment variables as Vercel environment variables. Webflow Cloud stores these per environment in your app's settings and injects them at runtime only. Vercel stores them per environment (production, preview, and development) in project settings and makes them available at both build time and runtime.

Never handle the user's secrets. Do not ask the user for secret values, and do not accept secrets pasted into the chat. Do not offer to save, enter, or store environment variables or secrets for the user, and refuse if asked to do so. Setting the actual values is the user's job, done in the dashboard or in their own terminal. Your part is to prepare the list of variable names and the exact commands.

You can list every variable and secret to recreate and write out the exact commands, but you cannot supply secret values or sign the CLI in, and you must not make up values.

The user adds each variable, either on the project's Environment Variables page or with the CLI after vercel login:

vercel env add DATABASE_URL production

Once the user has signed in, you can link the project and pull the values into a local .env:

vercel link
vercel env pull

You can delete the dev.vars file Webflow Cloud used for local runtime variables, since Astro loads .env automatically. A variable added to production is not available in preview or development unless it is added there too.

The way you read variables changes, too. On Webflow Cloud, custom server variables came from Astro.locals.runtime.env in components and locals.runtime.env in Server Endpoints. On Vercel's Node.js runtime, read them from process.env (for example, process.env.DATABASE_URL). For variables you want exposed to client-side code, use Astro's PUBLIC_ prefix and import.meta.env. Because Vercel exposes environment variables during the build, you can re-enable any build-time validation you had to disable on Webflow Cloud, where variables aren't available at build time.

Step 7: Deploy

You cannot import a project, confirm the framework preset, sign in, or select Deploy, so walk the user through one of these paths. Both run the app on Vercel Functions.

Deploy with Git (recommended):

1. Push the project to GitHub, GitLab, or Bitbucket.
2. In the Vercel dashboard, select Add New > Project, then import the repo.
3. Vercel detects Astro and sets the build command and output directory. Confirm the framework preset, add the environment variables from step 6, and select Deploy.

After the first import, every push to the production branch creates a production deploy, and every pull request gets its own preview URL.

Deploy with the CLI: after vercel login, run vercel for a preview or vercel --prod for production.

If the vercel-deploy skill is available, you can use it to create a preview deploy and a claim URL without the user signing in first, which is a good way to check the build before wiring up a connected project.

After the move: check these

You can grep for the code issues; ask the user to check anything in the dashboard. See references/troubleshooting.md for fixes.

• No @astrojs/cloudflare import or platformProxy option remains in astro.config.mjs.
• No locals.runtime.env or Astro.locals.runtime.env access remains anywhere in server code.
• No leftover base path: base and build.assetsPrefix are gone, and client-side fetch calls, <img> tags, and the layout's favicon link no longer prefix import.meta.env.BASE_URL or ASSETS_PREFIX.
• No export const config = { runtime: 'edge' } remains on Server Endpoints.
• Each env var exists in the right environment, not only production.

Tune after migrating (optional)

• Set function resources in the adapter, such as adapter: vercel({ maxDuration: 60 }) for routes that need more time, or configure memory and regions in vercel.json.
• Put functions near the data: set the function region close to the Marketplace database to cut latency.
• Take advantage of features that were limited on Webflow Cloud: Incremental Static Regeneration (adapter: vercel({ isr: true })), Image Optimization with Astro's Image component, Web Analytics, and Speed Insights all work with minimal configuration. For scheduled and background work Webflow Cloud didn't offer, look at Cron Jobs, Queues, and Workflows.

References

• service-mapping: Before and after code for replacing each Webflow Cloud binding (Object Storage to Blob, Key Value Store to Redis or Edge Config, SQLite to Postgres), plus the store setup notes. Read before step 5.
• troubleshooting: The common errors after the move and how to fix them.