Migrate Next.js to Vite with Vinext

Migrate a Next.js app to Vite and deploy it on Cloudflare Workers.

Introduction

30 Second Summary

Changing the machinery behind a working app can feel risky. Every page and request still needs to behave the same after the move.

In this project, you will move a small Next.js app onto Vite with Vinext. You will deploy the migrated app to Cloudflare Workers on the free plan.

What You'll Build

You'll share a live workers.dev URL for an app whose page and API route both run through Vite.

By the end of this project, you'll have:

A working Next.js app with a page you can open in your browser. You can call its API route separately.
A compatibility report showing what Vinext supports in your project. You can inspect anything it flags before migrating.
A Vite-powered app available through a public workers.dev URL. You can watch its requests appear in the Cloudflare dashboard.
Secret Mission: An optional challenge to push your migration skills further.

Are there any prerequisites?

You need Node with npm. You also need a free Cloudflare account plus basic experience editing a small Next.js project.

Before We Start

The migration commands in this project run on your computer. Your machine needs a browser plus a local JavaScript toolchain before you can move the app.

The final deployment also needs a Cloudflare account. This step prepares every prerequisite before you start building.

In this step, get ready to:

Prepare your coding workspace.
Install Node.js with npm.
Create or access your Cloudflare account.

Prepare your coding workspace

Visual Studio Code gives you a code editor with an integrated terminal. Keeping both tools in one window makes the later migration commands easier to follow.

Open the Visual Studio Code download page in your browser.

You should see download options for Visual Studio Code. That page confirms your browser is ready for the project.

Download the Visual Studio Code installer for your operating system.
Run the downloaded installer.
Approve your operating system's permission prompt if it appears.
Accept the default options on each installer screen.
Press Cmd+Space on macOS or the Windows key on Windows.
Type Visual Studio Code into the search bar.
Press Enter to start the editor.

You'll see the Visual Studio Code window. Your editor is now available for the project.

Select View from the top menu.
Select Terminal from the menu.

You'll see a terminal panel at the bottom of the editor. This panel is where you run every local command in the project.

Can't open the editor or terminal?

Confirm the Visual Studio Code installer finished before searching for the app. Restart your computer if the app still does not appear in search.

If the editor opens without a terminal panel, select View from the top menu. Select Terminal again.

Help me prepare Visual Studio Code and its integrated terminal.

Install and verify Node.js

Node.js runs the JavaScript tools that create the app and perform the migration. Its installer also includes npm for downloading the packages those tools need.

Check both tools from the Visual Studio Code terminal by running:

node --version
npm --version

What do these commands check?

The node --version command confirms that Node.js can run from your terminal.
The npm --version command confirms that npm was installed with Node.js.

✔️ I see two version numbers

Your local toolchain is ready. The first line reports Node.js while the second line reports npm.

ⓧ A command is not found

The terminal cannot find Node.js yet. The official installer adds Node.js plus npm to your computer.

The installer can take a minute to finish, so a short pause is normal.

Open the official Node.js download page in your browser.
Download the LTS installer for your operating system.
Run the downloaded installer.
Accept the default options on each installer screen.
Close the current terminal with the trash can icon in the terminal panel.
Select Terminal from the top menu.
Select New Terminal from the menu.
Check the new installation by running:

node --version
npm --version

Why use a fresh terminal?

A new terminal session loads the programs added by the installer. The version commands then confirm that both tools are available.

You'll now see one version number for Node.js plus another for npm.

Still missing a version number?

Close Visual Studio Code completely after the installation finishes. Start it again through your operating system's search bar.

Check that you downloaded the LTS installer for your operating system. Run the installer again if it stopped before completion.

Help me fix a missing Node.js or npm command.

Good progress. Those two version numbers confirm that your local JavaScript toolchain is ready.

Create or access your Cloudflare account

A Cloudflare account gives the deployment command a destination for your live app. You use the same account later to inspect the deployed Worker.

This project targets the Cloudflare Workers free plan. You do not need to choose a paid plan here.

Your password stays inside Cloudflare's account forms. It never goes into your project files.

Choose the tab that matches your current Cloudflare account status.

✔️ I already have an account

Your existing account can receive the deployment later in the project.

Open the Cloudflare dashboard in your browser.
Sign in using your usual method.

ⓧ I need an account

A free Cloudflare account is enough for this project. Cloudflare verifies your email before the account is ready.

Open the official Cloudflare sign-up page in your browser.
Enter your email address in the Email field.
Create a unique password in the Password field.
Select Create Account.
Open the email provider for the address you entered.
Follow the verification link in Cloudflare's email.
Sign in to the Cloudflare dashboard.

Before you check, do you expect the dashboard to show your account home or return you to the sign-up page?

Return to the browser tab containing the Cloudflare dashboard.
Refresh the dashboard page.

You'll see Account home for your signed-in profile. Your Cloudflare account is ready for the later deployment.

Your browser, editor, terminal, local toolchain, and deployment account are ready. Next, you'll create the small Next.js app that moves through the migration.

Create and Run a Next.js App

A migration only proves itself when the app behaves the same before and after the build tool changes.

In this step, you will create a small Next.js project with the App Router. You will run a page route plus an API route on the normal Next.js development server.

In this step, get ready to:

Create the local Next.js App Router project.
Replace the starter page with a migration baseline.
Add an API route and test both routes in your browser.

Create the App Router project

The original Next.js project gives you a working baseline for the migration. Its existing configuration stays in the repository when Vinext adds the Vite setup later.

Move to your Desktop by running this command:

cd ~/Desktop

What does this command do?

This command moves your terminal into the Desktop directory. The scaffold creates the project there so you can find it easily.

The scaffold creates the project structure plus its package scripts. It also downloads the dependencies needed by the development server.

The first scaffold can pause while npm downloads those dependencies. A quiet terminal during that wait is expected.

Create the next-vinext-app project by running this command:

npx create-next-app@latest next-vinext-app --ts --app --no-tailwind --no-src-dir --use-npm --yes

What does this command create?

The create-next-app tool creates the project files and installs the required packages.
The --ts option configures the project for TypeScript.
The --app option selects the App Router.
The --no-tailwind option keeps the page styling minimal.
The --no-src-dir option places the app directory directly inside next-vinext-app.
The --use-npm option creates package scripts for npm.
The --yes option accepts the remaining defaults without opening an interactive wizard.

When the scaffold finishes, the terminal returns to a prompt. The new next-vinext-app folder is now on your Desktop.

Did the scaffold stop early?

Check the terminal for a message about your Node.js version or network connection. Resolve the named issue before running the scaffold command again.

Delete any incomplete next-vinext-app folder before retrying. The scaffold needs an empty destination.

Help me troubleshoot the failed Next.js scaffold.

Confirm the project folder exists by running this command:

ls

What does this check do?

The ls command lists the files and folders on your Desktop. It gives you a direct check that the scaffold created its destination.

You should see next-vinext-app in the output.

Enter the project folder and start the normal Next.js development server by running these commands:

cd next-vinext-app
npm run dev

What do these commands do?

The first command moves the terminal into next-vinext-app.
The second command runs the normal Next.js development script from package.json.
The development server keeps this terminal busy so it can respond to browser requests.

Before you open the local URL, what kind of page do you expect the new project to serve?

Visit http://localhost:3000 in your browser.

You should see the starter page from the new Next.js project. That page confirms the original development server is responding.

Can’t load the starter page?

Keep the terminal running while you use the browser. Stopping the command also stops the local site.

Check the terminal for the local URL if your computer assigned a different available port.

Help me fix my local Next.js development server.

Establish the browser baseline

The home page gives you a visible result to compare after the migration. A short heading plus one status line makes that comparison clear.

Press Cmd+Space on macOS or the Windows key on Windows to open your search bar.
Type your code editor’s name and press Enter.
Select the next-vinext-app folder from your Desktop using the editor’s folder-opening control.
Select app/page.tsx in the editor’s file sidebar.
Replace the contents of app/page.tsx with the baseline page by pasting this code:

export default function Page() {
  // Render a visible baseline for the later Vinext migration.
  return (
    <main>
      <h1>Hello, Next.js!</h1>
      <p>This page is running on the original Next.js dev server.</p>
    </main>
  )
}

What does this code do?

The Page() function is the React component for the root page.
The JSX inside <main> defines the content that your browser renders.
The heading identifies the framework baseline.
The paragraph identifies the development server currently serving the page.

Save app/page.tsx.
Refresh the browser tab at http://localhost:3000.

You should now see Hello, Next.js! above the sentence about the original Next.js development server.

Still seeing the starter page?

Confirm that you edited app/page.tsx inside the next-vinext-app folder. A similarly named file outside that folder does not affect the running app.

Check that the terminal still shows the development server running. Restart it from next-vinext-app if the process stopped.

Help me find why my edited Next.js page is not appearing.

✔️ Awesome, I've got everything!

Your saved page now provides the visual baseline for the migration.

ⓧ I'd like to double check the full code

export default function Page() {
  // Render a visible baseline for the later Vinext migration.
  return (
    <main>
      <h1>Hello, Next.js!</h1>
      <p>This page is running on the original Next.js dev server.</p>
    </main>
  )
}

Create the hello API route

A page checks the visual side of the app. A JSON response checks that server-side request handling survives the migration too.

Create a new file at app/api/hello/route.ts from your editor’s file sidebar.
Add the GET handler to app/api/hello/route.ts by pasting this code:

export async function GET() {
  // Return a stable JSON payload for the later Vinext comparison.
  return Response.json({ message: 'Hello World' })
}

What does this code do?

The exported GET() function handles browser requests to the route.
The file location maps the handler to /api/hello.
The Response.json() call sends a JSON object back to the browser.
The fixed message gives you a stable API response to compare after the migration.

Save app/api/hello/route.ts.

Before you load the endpoint, do you expect the browser to show a rendered page or raw JSON?

Open a new browser tab.
Visit http://localhost:3000/api/hello.

You should see {"message":"Hello World"} in the browser. This proves the App Router handled the API request.

Seeing a missing route page?

Check that the full file path is app/api/hello/route.ts. Each folder name contributes to the endpoint path.

Confirm that the exported function is named GET with uppercase letters. The method name determines which request the handler accepts.

Help me fix my App Router API route.

✔️ Awesome, I've got everything!

Your API route now returns the stable response needed for the migration comparison.

ⓧ I'd like to double check the full code

export async function GET() {
  // Return a stable JSON payload for the later Vinext comparison.
  return Response.json({ message: 'Hello World' })
}

Before the final check, do you expect both routes to respond from the same development server?

Refresh the browser tab at http://localhost:3000.
Refresh the browser tab at http://localhost:3000/api/hello.

The root route should show your heading plus its server message. The API route should show the JSON response.

That is your first working baseline: one development server now handles both the visible page and the API request.

Your original Next.js baseline is live. Next, you will use Vinext to check how well this project fits the new build tool.

Check Vinext Compatibility

Your Next.js page already loads through the normal development server. Your API route responds in the browser too.

Now Vinext needs to inspect those features before moving the app onto Vite.

Its compatibility report shows which project features are supported. It also surfaces items that need attention.

In this step, get ready to:

Keep the existing Next.js development server running.
Run the Vinext compatibility check from the project folder.
Review every result in the compatibility report.

Prepare a separate terminal

The running Next.js server is your working baseline. A separate terminal lets you check the same project without interrupting that baseline.

Leave the terminal running the normal Next.js development server untouched.
Create a second terminal session for next-vinext-app in the code editor from earlier.

You should now have one terminal serving the app. Your second terminal should point to the next-vinext-app folder.

Check Vinext compatibility

The compatibility check reads your project structure to build a report. Your existing page route and API route stay in place during this scan.

Allow the Vinext package download if npx asks during the first run.

Before you run the check, do you expect every feature in this small App Router project to be supported?

Generate the compatibility report by running this command:

npx vinext check

What does this check do?

The check command inspects the current project against Vinext's supported feature set.
The report gives you a migration checkpoint before the project configuration changes.
Compatibility flags identify features that deserve closer attention before deployment.

You'll see a compatibility report listing Vinext-supported project features. Any compatibility flags appear with the relevant results.

Read the supported feature results from top to bottom.
Inspect every compatibility flag shown in the report.

Compatibility report missing?

Confirm the second terminal is working inside next-vinext-app. Running the check from another folder prevents it from inspecting this project.

A failed package download usually points to network access. Restore the connection before you rerun the check.

Ask for help with a Vinext compatibility check that does not produce a report.

Good work capturing the migration baseline. Next, you will generate the Vite setup for the same page and API route.

Initialize Vinext and Vite

Your Vinext compatibility report showed how the existing project maps to Vinext. The app still runs only through Next.js.

This step adds a Vite path beside that setup. You will prove that the existing page route plus API route behave the same way through the new server.

In this step, get ready to:

Initialize Vinext beside the original Next.js setup.
Confirm the generated Vite configuration.
Run the existing routes through the Vite development server.

Initialize Vinext alongside Next.js

Vinext automates the migration work needed for Vite. Your existing routes stay in place.

Dependency installation can take about a minute. The terminal may stay quiet briefly while the packages download.

Return to the terminal where you ran the compatibility check.
Confirm the terminal prompt is inside the next-vinext-app folder.
Initialize Vinext by running this command:

npx vinext init

What does initialization change?

The initializer adds the dependencies needed to run the project through Vite.
It generates vite.config.ts as the Vite configuration entry point.
It adds separate Vinext scripts to package.json.
It preserves the original Next.js setup for side-by-side use.

Review the initialization summary in the terminal.

You should see a completion summary that names vite.config.ts plus the new Vinext scripts.

That is the migration layer in place: your project now has a Vite path without losing its original Next.js path.

Initialization did not finish?

Return to the next-vinext-app folder before running the command again.
Review the earlier compatibility report for a flagged feature that blocks initialization.
Check your network connection if the dependency download stops.

Ask for help with the full terminal output: help me diagnose why npx vinext init failed in my Next.js App Router project.

Inspect the side-by-side setup

A safe migration keeps the original build path available for comparison. The generated files give Vite its own route into the same application.

Use your code editor's folder picker to open next-vinext-app.
Select vite.config.ts in the file sidebar.

You should see a generated Vite configuration for the existing application.

Why keep both setups?

The original Next.js development script remains your baseline. The separate Vinext script lets you test Vite against the same routes.

This makes each comparison concrete because the application code stays constant.

Select package.json in the file sidebar.
Confirm the scripts include dev:vinext.
Confirm the scripts include build:vinext.
Confirm the original dev script remains present.
Find vinext in the dependency sections.
Find vite in the dependency sections.
Confirm app/page.tsx remains in the file sidebar.
Confirm app/api/hello/route.ts remains in the file sidebar.

You now have the original routes plus an additional Vite configuration. The generated scripts control which development server runs them.

Missing a generated file or script?

Check that the terminal ran the initializer from inside next-vinext-app.
Check the initialization summary for a dependency installation failure.
Refresh the code editor's file sidebar if vite.config.ts is still missing.

Get help comparing the generated project state: help me check why my Vinext scripts or Vite configuration are missing.

Run the app through Vite

The generated dev:vinext script starts the Vite development server on a separate port. The original Next.js server can remain available for comparison.

Before you start the new server, do you expect it to reuse the original Next.js port or use a separate one?

Return to the terminal where initialization finished.
Start the generated Vite development script by running this command:

npm run dev:vinext

What does this command do?

The npm command reads dev:vinext from package.json.
That script starts the Vite development server through Vinext.
The generated script uses port 3001 so the original development server can keep its port.

Keep this terminal session open after the server starts.

You should see a local development URL using port 3001.

Vite server did not start?

Confirm dev:vinext exists in the scripts section of package.json.
Check the initialization output for an incomplete dependency installation.
Confirm another process is not already using port 3001.

Share the startup output for targeted help: help me diagnose why the Vinext Vite development server will not start.

Before you load the routes, do you expect their content to change just because the build tool changed?

Switch back to the browser from earlier.
Open http://localhost:3001 in a new browser tab.
Open http://localhost:3001/api/hello in another browser tab.

You should see the same visible page from earlier at the first URL. The second URL should show the same API response from your hello route.

You have proved the migration works: Vinext now serves both existing routes through Vite.

A route does not load through Vite?

Confirm the address uses port 3001.
Confirm the Vite terminal is still running.
Compare the failing path with app/page.tsx or app/api/hello/route.ts.

Get help tracing the route failure: help me diagnose why my existing page or API route does not load through Vinext and Vite.

Your application now runs through its original setup plus Vite. Next, you will deploy the Vite-powered version to Cloudflare Workers.

Deploy to Cloudflare Workers

The same Next.js app now runs through Vite on your machine. Vinext carries your existing routes through the new build tool.

A local server still stops at your laptop. This step publishes the migrated app to Cloudflare Workers on the free plan.

In this step, get ready to:

Publish the Vinext build to Cloudflare Workers with warm-cache deployment.
Authenticate your Cloudflare account when requested.
Capture the live deployment URL from the terminal output.

Prepare the Cloudflare deployment

The deployment command packages the Vinext build. It creates a Worker under your Cloudflare account.

Creating a public Worker can feel like a billing step. This project uses the free plan throughout.

The deployment can pause for Cloudflare authentication. The terminal shows when your account needs to be connected.

Before you run the command, predict which proof of success the terminal should return.

Switch back to the terminal from the previous step.
Stop the Vite process by pressing Ctrl+C if it is still running.
Deploy the app by running this command:

npx @vinext/cloudflare deploy --warm-cache

What does this command do?

The npx command runs the deployment package without adding another global tool to your machine.
The @vinext/cloudflare deploy portion sends the Vinext-built project to Cloudflare Workers.
The --warm-cache flag selects the warm-cache deployment required for this project.

Sign in to Cloudflare when the deployment flow asks.
Return to the terminal from earlier after authentication finishes.
Wait for the deployment process to finish.

You will see the command continue through the build and deployment process. The terminal returns control when that process is complete.

Deployment stopped before publishing?

Confirm that the terminal prompt points to the next-vinext-app folder.
Complete any Cloudflare authentication request still waiting in the deployment flow.
Run the deployment command above again after authentication finishes.

Ask for help with the Cloudflare deployment. You can also search the Cloudflare Community.

Capture the live URL

The final terminal output acts as your deployment receipt. Its workers.dev address is the value you will test in the next step.

Before you inspect the final lines, predict which detail will show that the Worker received a public address.

Inspect the final lines of the deployment output in the terminal from earlier.

You should see the warm-cache deployment finish with a live workers.dev URL. This confirms that Cloudflare created the Worker.

Record the live URL here: your workers.dev URL.

You have crossed the biggest boundary in the migration. Next, you will test the live page and API route at the public Cloudflare Workers address.

Verify Your Live Worker

Your Vinext build is now deployed as a Cloudflare Worker at the public address from the previous step.

A successful deployment message proves that Cloudflare accepted the build. Live checks prove that real browser requests can reach your app.

In this step, get ready to:

Verify the deployed page at its public address.
Call the deployed API route from your browser.
Confirm request activity for the deployed Worker in dashboard analytics.

Test the live page

The workers.dev URL is the public entry point for your deployed Worker. This check sends a real request outside your local Vite server.

Before you load it, do you think the public page will match the version you tested under Vite? The next check reveals the answer.

Switch back to the terminal panel from the previous step.
Find the workers.dev URL in the deployment output.
Record the full address here: your workers.dev URL.
Return to your browser from earlier.
Select the browser address bar.
Paste your workers.dev URL into the address bar.
Press Enter.

You will see the same visible page that loaded during your local Vite test. That first public check is complete.

Live page not loading?

Copy the full address again from the deployment output.
Paste the corrected address into the browser address bar.
Reload the browser tab.

Help me troubleshoot why my deployed workers.dev page is not loading.

Test the live API route

The visible page confirms that the frontend route works. A separate request to /api/hello checks the server-side route inside the same deployment.

Before you call the route, do you expect its response to match your local test? The browser request tests your prediction.

Open a new browser tab.
Replace the current address with your workers.dev URL followed by /api/hello.
Press Enter.

You will see the same response content that appeared during your local Vite test. Your server-side route now works through the deployed Worker.

API route not responding?

Confirm that the address ends with /api/hello.
Return to your workers.dev URL.
Confirm that the visible page still loads.
Reload the API route after correcting its path.

Help me troubleshoot why my deployed API route is not responding.

Confirm request activity

Cloudflare Workers metrics aggregate request data for an individual Worker. The browser checks you just completed give the dashboard activity to display.

Before you inspect the metrics, do you expect the request graph to remain empty? The dashboard provides the final proof.

Open a new browser tab.
Return to your signed-in Cloudflare dashboard in the new tab.
Select Workers & Pages.
In Overview, select the Worker whose address matches your workers.dev URL.
Select Metrics.
Review the Summary graph for request activity.

You will see request activity in the Summary graph. This confirms that public requests reached the Worker runtime.

No request activity yet?

Return to the live page tab.
Reload the live page.
Return to the live API route tab.
Reload the API route.
Return to Metrics in the Cloudflare dashboard.
Review the Summary graph again.

Help me find request activity for my deployed Worker.

That is the full deployment path confirmed. Your page and API route now reach users through Cloudflare Workers.

Secret mission

Measure Live Worker Traffic

Create a controlled burst of live page requests plus API requests. Use Worker analytics to prove the traffic reached your deployment.

Clean Up Your Resources

Your deployed app uses the Cloudflare Workers free plan. Decide whether to keep the deployment live, pause your local work, or delete the resources entirely.

Resources you used:

A Cloudflare Worker that hosts your app at its workers.dev URL.
The local next-vinext-app folder with the original Next.js setup plus the Vinext configuration and Vite scripts.

Keep everything running

No action needed. Choose this if you want the app to remain available at its current URL.

Keep the Cloudflare Worker deployed at its current workers.dev URL.
Keep the next-vinext-app folder with both build setups intact.
Return to the dashboard analytics whenever you want to confirm that requests are still reaching the Worker.

Pause - I'll come back to this later

Pause your local development process to free up memory. Your deployed Worker stays live on the free plan.

Switch back to the terminal running your local development server if it is still active.
Stop the local development server by pressing Ctrl+C.
Keep the deployed Worker active for your next session.

You should see the terminal return to its command prompt. Your public app remains available through its workers.dev URL.

Your local process is now stopped. Both versions of the project remain ready for your return.

Delete - I don't want to use this again

Removing these resources is permanent. The steps are split so you can take the public deployment offline without losing your local code.

Return to the deployed Worker's details page in the Cloudflare dashboard from earlier.
Select Delete for that Worker.
Confirm the permanent deletion in the confirmation prompt.
Refresh the workers.dev URL you tested earlier.

Your live app should no longer load at that URL. That confirms the deployed Worker is gone.

Can't remove the Worker?

Check that you returned to the Worker associated with the workers.dev URL from your deployment output.

Ask for help if the deletion control is unavailable: Help me remove the Cloudflare Worker that hosts my Vinext deployment.

The local repo is separate from the deployed Worker. Delete the next-vinext-app folder only if you no longer need its source code or configuration.

Locate the folder that contains next-vinext-app on your computer.
Record that location here: path to the folder containing next-vinext-app.

macOS

Remove the local project folder by running these commands:

cd "[[PARENT_DIRECTORY="path to the folder containing next-vinext-app"]]"
rm -rf next-vinext-app

What do these commands do?

The cd command moves the terminal into the folder that contains your project.
The rm command permanently removes the project folder and everything inside it.

Return to that location in Finder.

You should no longer see the next-vinext-app folder.

Still see the project folder?

Check that the parent directory points to the folder immediately above next-vinext-app.

Ask for help checking the path before trying again: Help me safely remove my local next-vinext-app folder on macOS.

Windows

Remove the local project folder by running these commands:

cd "[[PARENT_DIRECTORY="path to the folder containing next-vinext-app"]]"
rmdir /s /q next-vinext-app

What do these commands do?

The cd command moves the terminal into the folder that contains your project.
The rmdir command permanently removes the project folder and everything inside it.

Return to that location in File Explorer.

You should no longer see the next-vinext-app folder.

Still see the project folder?

Check that the parent directory points to the folder immediately above next-vinext-app.

Ask for help checking the path before trying again: Help me safely remove my local next-vinext-app folder on Windows.

Nice Work!

That migration is live! Your Next.js App Router page and API route now run through Vite with Vinext on Cloudflare Workers.

You've learned how to:

Build an App Router project with a visible page. Add an API route that returns a response in your browser.
Assess migration compatibility with a compatibility report. Migrate the app while preserving its original Next.js setup.
Deploy the migrated app to a Cloudflare Worker. Confirm the live page at its workers.dev URL. Verify the API response. Track request activity in dashboard analytics.
Secret Mission: Complete an optional challenge that extends your migrated app and pushes your skills further.

Ready to quiz yourself?