Migrate a TanStack Start app from Netlify to Vercel

Moving a TanStack Start app from Netlify to Vercel mostly means swapping the deployment layer. On Vercel, TanStack Start runs on Vercel Functions with Fluid compute enabled by default, so your app automatically scales up and down with traffic.

This guide walks you through the full migration. You'll swap @netlify/vite-plugin-tanstack-start for the Nitro Vite plugin, delete your netlify.toml, and move Netlify storage to its Vercel equivalents (e.g., Netlify Blobs to Vercel Blob). It also covers recreating environment variables, mapping Scheduled Functions and background work to Vercel Cron Jobs and Vercel Queues, and deploying with Git or the vercel CLI.

Copy link to headingPrerequisites

Before you begin, make sure you have:

• A working TanStack Start app
• A Vercel account
• Vercel CLI installed (npm i -g vercel)
• Node.js 20 or later

Copy link to headingMigrate with an agent

If you use an AI coding agent like Claude Code or Cursor, you can have it handle most of the migration for you and provide expert guidance. Install the Vercel Plugin to provide your agent with Vercel-specific context, then add the companion skill for this guide.

Install the Vercel Plugin:

npx plugins add vercel/vercel-plugin

Add the TanStack Start migration skill:

npx skills add vercel-labs/vercel-kb-skills --skill tanstack-start-netlify-to-vercel

With both in place, ask your agent to migrate your TanStack Start app from Netlify to Vercel. Your agent will follow the migration steps and apply Vercel's recommended patterns for Vercel Functions, storage solutions, environment variables, and more.

Copy link to headingWhat changes when you move your project

On Netlify, TanStack Start deploys to Netlify Functions, and your server code uses Netlify platform primitives such as Blobs and Scheduled Functions.

On Vercel, the same application runs on Vercel Functions using the Nitro Vite plugin, retrieves configuration from environment variables, and connects to storage providers in the Vercel Marketplace via native integrations.

The table below maps each Netlify component to its Vercel counterpart.

Copy link to headingSteps

Copy link to heading1. Replace the Netlify Vite plugin with Nitro

Vercel deploys TanStack Start using Nitro, which compiles your app into Vercel Functions. Install Nitro in your project root:

npm i nitro

Then update vite.config.ts to replace the Netlify plugin with the Nitro plugin:

import { defineConfig } from 'vite';
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { nitro } from 'nitro/vite';
import viteReact from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [tanstackStart(), nitro(), viteReact()],
});

Remove the netlify() plugin and its import from @netlify/vite-plugin-tanstack-start. Nitro detects Vercel during a Vercel build and applies the vercel preset without any extra configuration.

If you're on an older TanStack Start version, remove its Netlify target as well. Versions 1.121.0 to 1.131.x set tanstackStart({ target: 'netlify' }) in vite.config.ts, and versions before 1.121.0 set preset: 'netlify' in app.config.ts. Delete either setting so Nitro can apply the vercel preset instead.

Copy link to heading2. Remove the Netlify configuration

Delete the Netlify-specific files and dependencies that no longer apply on Vercel:

• Remove netlify.toml, including its publish = "dist/client" setting. Vercel auto-detects the TanStack Start output through Nitro.
• Uninstall the Netlify packages: npm uninstall @netlify/vite-plugin-tanstack-start. Also, remove any @netlify/functions, @netlify/blobs, or @netlify/edge-functions packages after you've migrated your code.
• If netlify.toml contained redirects, rewrites, or custom headers, recreate them as Nitro route rules or in vercel.json.

If you used a netlify/functions or netlify/edge-functions directory for standalone functions, or relied on Background Functions and Scheduled Functions, see step six and the mapping table for the Vercel approach to those features.

Copy link to heading3. Update your build scripts

Replace any Netlify-specific scripts in package.json with the standard Vite commands. Vercel runs the build for you, so you no longer need a script that calls netlify deploy:

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build"
  }
}

Vercel auto-detects TanStack Start during import and sets the build command and output directory, so the remaining scripts mainly support local development.

Copy link to heading4. Replace Netlify Blobs with Vercel storage

This is the core code change. On Netlify, you import getStore from @netlify/blobs and call methods such as store.set() and store.get(). On Vercel, you read connection details from process.env and talk to each store through its SDK. Remove every import { getStore } from "@netlify/blobs" statement and replace the blob calls.

For example, a file upload with Netlify Blobs looks like this:

// Before (Netlify Blobs)
import { createServerFn } from '@tanstack/react-start';
import { getStore } from '@netlify/blobs';

const uploadFile = createServerFn({ method: 'POST' })
  .validator((data: { key: string; content: string }) => data)
  .handler(async ({ data }) => {
    const store = getStore('uploads');
    await store.set(data.key, data.content);
    return { success: true };
  });

On Vercel, the same upload uses Vercel Blob:

// After (Vercel Blob)
import { createServerFn } from '@tanstack/react-start';
import { put } from '@vercel/blob';

const uploadFile = createServerFn({ method: 'POST' })
  .validator((data: { key: string; content: string }) => data)
  .handler(async ({ data }) => {
    const blob = await put(data.key, data.content, { access: 'public' });
    return { url: blob.url };
  });

Install the Blob SDK with npm i @vercel/blob, then create a Blob store from the Storage page in your Vercel dashboard. For authentication, connect the store to your project from its Projects tab. Vercel then adds a BLOB_STORE_ID and a short-lived VERCEL_OIDC_TOKEN that it rotates automatically. The SDK pairs the two automatically, so the put() call above needs no token in your code. This OIDC approach is recommended over the long-lived BLOB_READ_WRITE_TOKEN, which you'd use only for code that runs outside Vercel.

Netlify Blobs serves two roles, so map your usage based on how you used it:

• Blobs used as a key/value store for app data becomes a Redis integration (e.g., Upstash Redis) from the Vercel Marketplace, or Global Config for small, read-heavy configuration.
• Netlify Database becomes a Postgres database (e.g., Neon) from the Vercel Marketplace.

When you provision storage from the Marketplace, Vercel adds the connection string and credentials as environment variables, which your code reads from process.env.

Copy link to heading5. Move your environment variables and secrets

Recreate your Netlify environment variables as Vercel environment variables. On Netlify, variables live in two separate places: the store you manage through the dashboard, CLI, or API, and any declared directly in netlify.toml.

Vercel instead stores them per environment (production, preview, and development) in project settings. The dashboard and netlify env:list only surface the store-based variables, not anything in netlify.toml, so check both the dashboard and the file to capture the full set before you move them. Note too that netlify.toml variables are build-time only and were never available to Netlify Functions, so any value your functions actually rely on should already be in the dashboard.

Add each variable to your project's environment variables, or from the CLI:

vercel env add DATABASE_URL production

To run your app locally with the same values, link the project and pull the variables into a local .env file:

vercel link
vercel env pull

vercel env pull writes a .env file with your development environment variables. Vercel supports up to 64 KB of environment variables per deployment across all variables combined.

Copy link to heading6. Migrate scheduled functions and background work

If your Netlify site used Scheduled Functions, Background Functions, or Async Workloads, Nitro maps the scheduled side to Vercel Cron Jobs at build time, and you use Vercel Queues for background message processing. Skip this step if your app doesn't use them.

On Netlify, you set a schedule by exporting a config object with a schedule cron expression from a function, or by declaring it in netlify.toml. On Vercel, define Nitro scheduled tasks in nitro.config.ts. Nitro converts them into Vercel Cron Jobs during the build, so you don't write any vercel.json cron configuration by hand:

import { defineConfig } from 'nitro';

export default defineConfig({
  experimental: {
    tasks: true,
  },
  scheduledTasks: {
    // Run the cms:update task every hour
    '0 * * * *': ['cms:update'],
  },
});

To secure the generated cron endpoint, set a CRON_SECRET environment variable in your Vercel project. When CRON_SECRET is set, Nitro validates the Authorization header on every cron invocation.

For message processing, replace Netlify Background Functions and Async Workloads with Vercel Queues. Define your topics under the vercel.queues key in nitro.config.ts:

import { defineConfig } from 'nitro';

export default defineConfig({
  vercel: {
    queues: {
      triggers: [{ topic: 'orders' }],
    },
  },
});

Handle incoming messages with the vercel:queue hook in a Nitro plugin under server/plugins/:

export default defineNitroPlugin((nitro) => {
  nitro.hooks.hook('vercel:queue', ({ message, metadata }) => {
    console.log(`[${metadata.topicName}] Message ${metadata.messageId}:`, message);
  });
});

To produce messages, install @vercel/queue (npm i @vercel/queue) and call its send() from any server function, for example const { messageId } = await send('orders', order).

For long-running, multi-step processes that Netlify background work handled, consider Vercel Workflows, which run durable steps on Vercel Functions and Vercel Queues.

Copy link to heading7. Deploy to Vercel

You have two deployment options. Both build your app with Nitro's Vercel preset and run it on Vercel Functions.

Deploy with Git (recommended):

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

If the framework preset or build settings aren't detected correctly, fix them from the Vercel CLI (requires v54.21.1+):

 vercel project update <project-name> --framework tanstack-start

Use --build-command or --output-directory if those also need adjusting.

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

Deploy with the CLI:

vercel

Run vercel from your project root to create a preview deployment, or vercel --prod to deploy to production.

Once deployed, your app runs on Vercel Functions with Fluid compute, with preview deployments, observability, and the Vercel Firewall available.

Copy link to headingTroubleshooting

Copy link to headingNetlify platform calls fail at runtime

Server code still calls Netlify-only APIs such as Netlify Blobs, the Netlify Functions Context object, or Netlify edge-runtime imports. Search your project for @netlify/ and replace each call with its Vercel equivalent from the mapping table. These packages depend on Netlify's runtime and won't connect when your app runs on Vercel.

Copy link to headingEnvironment variables are undefined at runtime

Confirm each variable exists in the correct environment under your project's environment variables, then redeploy. Variables added to production aren't available in preview or development unless you add them there too. For local runs, re-run vercel env pull after changing variables.

Copy link to headingVercel Blob authentication fails during local development

Run vercel env pull to download a short-lived VERCEL_OIDC_TOKEN and BLOB_STORE_ID into your local .env, then keep Blob access inside server functions. With Vite, only variables prefixed with VITE_ reach client code, so reading blob credentials from the client won't work.

Copy link to headingAPI routes return a 404

Nitro's /api directory convention isn't compatible with Vercel. Move standalone API handlers to routes/api/ so Nitro generates the correct Vercel Functions.

Copy link to headingBest practices

• Recreate Netlify redirects, rewrites, and headers. If you relied on netlify.toml or redirects_ and _headers files, move that logic into Nitro route rules or vercel.json so requests resolve the same way on Vercel.
• Tune function resources per route. If specific routes need more memory or a longer timeout than the default, set vercel.functionRules in nitro.config.ts to override maxDuration, memory, or regions for matching route patterns.
• Place functions near your data. Set regions in functionRules or your project settings close to your database region to reduce latency.

Copy link to headingRelated resources

• TanStack Start on Vercel
• Vercel Functions and Fluid Compute
• Storage on the Vercel Marketplace and Vercel Blob
• Managing environment variables
• Deploy Nitro to Vercel