Deploy to Cloudflare Workers

The native Cloudflare integration is the most complete deployment target. It runs App Router server code in workerd and supports Workers bindings directly in your application.

#1. Configure the project

pnpm dlx vinext init --platform=cloudflare

The initializer creates or updates vite.config.ts and creates cloudflare.config.ts, then lets you choose caching and image optimization. It installs cf and Cloudflare Vite plugin v2 and generates scripts for vite dev, vite build, vite preview, and vinext-cloudflare deploy. Commit the source config files; the generated Cloudflare Build Output stays gitignored.

Response Store service-binding mode declares its second Worker in the typed config and builds both Workers together. KV namespaces and missing Response Store R2 buckets are automatically provisioned on deployment. See Caching on Cloudflare for each adapter's config.

For TypeScript projects, add .cloudflare/types to the include list in tsconfig.json. The plugin generates binding and runtime declarations there during development and builds; these files stay gitignored. Run cf workers types to generate them before a standalone type-check without building the app.

#2. Authenticate

pnpm exec cf auth login

Set accountId at the top level of defineConfig in cloudflare.config.ts (outside worker), or set CLOUDFLARE_ACCOUNT_ID. In CI, use a CLOUDFLARE_API_TOKEN instead of browser login.

#3. Deploy

pnpm dlx @vinext/cloudflare deploy
pnpm dlx @vinext/cloudflare deploy --env staging

The deploy command validates the initialized setup, builds all Vite environments, and deploys the application Worker's Build Output using cf. --env staging selects the staging Vite mode; --preview selects the preview mode.

For Response Store service-binding mode, build and deploy the cache Worker explicitly before the first application deployment:

pnpm run build:vinext
pnpm run deploy:response-store
pnpm run deploy:vinext

create-vinext-app uses build and deploy instead of build:vinext and deploy:vinext. Redeploy the Response Store when its package or config changes; normal application deployments do not redeploy it.

To prefill configured caches before promoting a new Worker version, see Cache warming.

#Use Workers bindings

Import env from cloudflare:workers in Server Components, Route Handlers, and Server Actions. Configure each binding in the Worker's env object in cloudflare.config.ts.

import { env } from "cloudflare:workers";

export default async function Page() {
  const posts = await env.DB.prepare("SELECT * FROM posts").all();
  return <pre>{JSON.stringify(posts.results)}</pre>;
}

See Cloudflare's bindings documentation for product-specific configuration, and the Workers Vite plugin documentation for the underlying development environment.

#Middleware and static files

In Next.js, middleware runs for every path its matcher matches, including files in public/. Workers Static Assets can serve a file before the Worker runs, and then middleware does not run for it. The config that vinext init generates routes every request except the build output through the Worker:

assets: {
  htmlHandling: "none",
  notFoundHandling: "none",
  runWorkerFirst: ["/*", "!/_next/static/*", "!/*/_next/static/*"],
},

Middleware runs before public/ files, and vinext then serves the file through the ASSETS binding. The hashed scripts and stylesheets under /_next/static still skip the Worker; they make up most static requests, so this avoids an invocation for each. The second exclusion covers that output under a basePath or a path assetPrefix. Unlike in Next.js, middleware does not run for the build output, which the recommended Next.js matchers exclude anyway, or for public files inside a nested _next/static/ directory, such as public/docs/_next/static/guide.pdf, which also match that exclusion. htmlHandling: "none" serves a public .html file only at its exact path, as Next.js does; the default auto-trailing-slash handling would redirect /page.html to /page, which is not a public file.

Patterns use * for deep matching, and a ! exclusion takes precedence over every other pattern; see Cloudflare's run_worker_first reference. Keep both exclusions. vinext serves the build output only from Workers Static Assets, so runWorkerFirst: true, or a pattern list without these exclusions, makes the app's scripts and stylesheets return 404.

Next.js runs no middleware for a static export, so for an app whose next.config sets output: "export", vinext init leaves these settings out and Workers Static Assets serves the exported files before the Worker, as it does by default.

Configs created before this default, or written by hand, serve public/ files without running middleware unless runWorkerFirst covers them. Add the patterns above, or list only the paths that need middleware, such as ["/downloads/*"]; other public files then skip the Worker and middleware.

As the Next.js authentication guide advises, middleware should not be the only check protecting content. Serve files that need authentication from a Route Handler or page that verifies access.

With the Static Assets response cache, /* also routes its private /_vinext/static-cache/* directory through the Worker. A list of specific paths must include /_vinext/static-cache/*. vinext init rejects other exclusion patterns on a config that uses this cache.