Skip to main content

Next.js

还没翻译译自英文（developers.cloudflare.com）本页 32 段都还没译

Use vinext to create or migrate a Next.js application and deploy it to Cloudflare Workers.

Cloudflare recommends vinext as the default way to run Next.js applications on Cloudflare Workers. vinext gives you two starting points: scaffold a new Workers-ready app with create-vinext-app, or add vinext to an existing Next.js 16 app with a single non-destructive vinext init (your existing next dev keeps working). You do not need a Cloudflare-specific template either way.

Already on OpenNext? See other Next.js deployment paths.

What is Next.js?

Next.js is a React framework for building full-stack applications.

Next.js supports server-side rendering, client-side rendering, static generation, React Server Components, Server Actions, route handlers, and middleware.

What is vinext?

vinext is a Vite plugin that reimplements the Next.js API surface. You can keep your existing app/, pages/, next.config.js, and public/ directories while using the Vite toolchain.

vinext is in beta. Before adopting it for an existing production application, run the compatibility check from your project directory and review the vinext compatibility dashboard.

npx vinext check
yarn dlx vinext check
pnpx vinext check

Supported features

vinext supports most commonly used Next.js features on Cloudflare Workers:

Featurevinext supportNotes
App RouterSupportedIncludes layouts, route handlers, metadata, loading, error, and not-found routes.
Pages RouterSupportedIncludes getStaticProps, getStaticPaths, and getServerSideProps.
React Server ComponentsSupportedUses Vite's React Server Components support.
Server ActionsSupportedWorks with forms and server mutations.
Server-side renderingSupportedIncludes streaming rendering.
Static generation and static exportSupportedUse output: "export" for static exports.
Incremental Static Regeneration (ISR)SupportedUses a stale-while-revalidate caching model so Workers can serve cached content while refreshing it in the background. Refer to asynchronous revalidation.
Middleware and proxy routesSupportedIncludes middleware.ts and proxy.ts.
next/* importsMostly supportedReview the compatibility dashboard for module-level details.
Cloudflare bindingsSupportedUse cloudflare:workers in server components, route handlers, and server actions.
Image optimizationPartially supportedCloudflare image optimization is available at request time.

For detailed compatibility results, refer to vinext compatibility.

Choose a setup path

Most Next.js projects can start from the same workflow: open a Next.js app, check compatibility, add vinext, then deploy to Workers.

Add vinext with an agent

Use the vinext Agent Skill when you want a coding agent to inspect your Next.js project, run compatibility checks, update configuration, and start the vinext development server.

  1. Open your Next.js project.

    Use an existing project, or create a project with your preferred Next.js setup flow.

  2. Install the vinext Agent Skill.

    npx skills add cloudflare/vinext
    yarn dlx skills add cloudflare/vinext
    pnpx skills add cloudflare/vinext

  3. Prompt your agent.

    In your coding agent, run the following prompt:

    migrate this project to vinext

    The skill runs vinext compatibility checks, applies the migration, and flags issues that need manual attention.

  4. Develop with vinext.

    Start the vinext development server.

    npm run dev:vinext
    yarn run dev:vinext
    pnpm run dev:vinext

  5. Build with vinext.

    Build the production output with vinext.

    npm run build:vinext
    yarn run build:vinext
    pnpm run build:vinext

  6. Deploy to Workers.

    Deploy with the vinext Cloudflare deploy command.

    npx @vinext/cloudflare deploy
    yarn dlx @vinext/cloudflare deploy
    pnpx @vinext/cloudflare deploy

Add vinext with the CLI

Use vinext init when you want a direct command-line setup. The migration is non-destructive: your existing Next.js setup continues to work alongside vinext while you test the Cloudflare Workers deployment.

  1. Open your Next.js project.

    Use an existing project, or create a project with your preferred Next.js setup flow.

  2. Check compatibility.

    Run the vinext compatibility check from your Next.js project directory.

    npx vinext check
    yarn dlx vinext check
    pnpx vinext check

    Review any reported compatibility issues before continuing.

  3. Initialize vinext.

    Run the vinext initializer and choose Cloudflare Workers as the deployment target when prompted.

    npx vinext init
    yarn dlx vinext init
    pnpx vinext init

    vinext init installs vinext and Vite dependencies, adds vinext scripts, generates the Vite configuration, and creates the Cloudflare Workers configuration.

  4. Develop with vinext.

    Start the vinext development server.

    npm run dev:vinext
    yarn run dev:vinext
    pnpm run dev:vinext

  5. Build with vinext.

    Build the production output with vinext.

    npm run build:vinext
    yarn run build:vinext
    pnpm run build:vinext

  6. Deploy to Workers.

    Deploy with the vinext Cloudflare deploy command.

    npx @vinext/cloudflare deploy
    yarn dlx @vinext/cloudflare deploy
    pnpx @vinext/cloudflare deploy

Create a Cloudflare-ready project

Use the create-cloudflare CLI (C3) when you want to scaffold a new Next.js project already configured for Cloudflare Workers.

  1. Create a new project with C3.

    npm create cloudflare@latest -- my-next-app --framework=next
    yarn create cloudflare my-next-app --framework=next
    pnpm create cloudflare@latest my-next-app --framework=next

  2. Develop with vinext.

    Change to your project directory and start the local development server.

    npm run dev
    yarn run dev
    pnpm run dev

  3. Build your application.

    Run the generated build script before deploying or testing a production build.

    npm run build
    yarn run build
    pnpm run build

  4. Deploy your project.

    Deploy your project to a *.workers.dev subdomain or a custom domain.

    npm run deploy
    yarn run deploy
    pnpm run deploy

Access Cloudflare bindings

In vinext applications deployed to Workers, use cloudflare:workers to access bindings from server components, route handlers, and server actions. Define bindings in your Wrangler configuration, then generate types with wrangler types.

For example, you can import env from cloudflare:workers in server-side application code to access D1, R2, KV, Durable Objects, Workers AI, Queues, Vectorize, and other bindings.

Use another Next.js deployment path

vinext is the recommended path for Next.js applications on Cloudflare Workers, but other deployment paths remain documented:

PathUse when
OpenNext adapterYou maintain an existing OpenNext application that cannot yet migrate to vinext because of a compatibility gap.
Static Next.js on PagesYour application is a static export and you specifically want to deploy it to Cloudflare Pages.
Edit on GitHub
AI 翻译查看英文原文