# cloudflare/vinext architecture

> Architecture diagram of the GitHub repository cloudflare/vinext, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudflare/vinext
- Repository: https://github.com/cloudflare/vinext

## Overview

#### Purpose and principal workflow

vinext reimplements much of the Next.js API surface on Vite, with Cloudflare Workers as its primary deployment target. The main workflow begins when an application developer runs Vite or the vinext CLI against a Next.js-style project: vinext configures the build and runtime, discovers and serves App Router or Pages Router routes, and returns rendered responses in development or production. Cloudflare deployment is an additional path. The repository also contains the vinext.dev website and its compatibility-results data flow.

#### Components

##### Framework setup and build

- **Vite plugin entry** — `packages/vinext/src/index.ts`: exposes vinext’s Vite integration, which the README documents as the way to run a project using `vinext()`.
- **CLI and project initialization** — `packages/vinext/src/cli.ts`: provides the documented `vinext` command-line entry; migration and configuration generation are implemented separately.
- **Next.js configuration handling** — `packages/vinext/src/config/next-config.ts`: substantial configuration module listed among the core files; the README says vinext loads existing `next.config.js` configuration.
- **Project migration** — `packages/vinext/src/init.ts`: implements `vinext init`, the documented migration workflow.
- **New-project scaffolding** — `packages/create-vinext-app/src/index.ts`: implements the `create-vinext-app` setup flow; its source references vinext initialization and platform setup.
- **Next.js type compatibility** — `packages/types/next/index.d.ts`: repository path for the compatibility type package; the README documents support for commonly used `next/*` modules, though this file’s precise role is not shown in the excerpts.

##### Routing and request execution

- **Route matching and validation** — `packages/vinext/src/routing/route-validation.ts`: part of the routing subsystem; the Pages request pipeline references route validation and routing utilities.
- **Shared request security and normalization** — `packages/vinext/src/server/request-pipeline.ts`: handles shared request checks, including base-path handling, middleware headers, and open-redirect protection.
- **Pages Router request pipeline** — `packages/vinext/src/server/pages-request-pipeline.ts`: owns the documented-in-code nine-step Pages Router request order; callers inject callbacks.
- **App Router page execution** — `packages/vinext/src/server/app-page-execution.ts`: implements a substantial App Router execution stage; its exact call chain is not established by the supplied excerpts.
- **Next.js server API shims** — `packages/vinext/src/shims/server.ts`: provides `NextRequest`, `NextResponse`, and related APIs using standard Web request/response types.
- **Request/render context state** — `packages/vinext/src/shims/internal/work-unit-async-storage.ts`: tracks request, prerender, and cache work-unit contexts with async-local storage.
- **Browser App Router navigation** — `packages/vinext/src/server/app-browser-navigation-controller.ts`: coordinates pending navigation commits and visible state updates; imports the browser-state and visible-commit helpers.

##### Cloudflare runtime and response caching

- **Cloudflare deployment CLI** — `packages/cloudflare/src/cli.ts`: repository entry for the Cloudflare command package; the README documents `@vinext/cloudflare deploy`.
- **Cloudflare CDN cache adapter** — `packages/cloudflare/src/cache/cdn-adapter.worker.ts`: Worker-side CDN response caching, including cache identity construction and shared-cache policy checks.
- **Cloudflare response-store adapter** — `packages/cloudflare/src/cache/response-store-adapter.worker.ts`: adapts response-store operations for Workers and handles replayable invocations and paired App Router document/RSC parts.
- **Workers response-store binding** — `packages/workers-response-store/src/binding.ts`: exposes the response-store binding implementation; the Cloudflare adapter imports its public types.
- **Durable Object metadata and storage coordination** — `packages/workers-response-store/src/metadata-do.ts`: maintains response metadata in Durable Object SQL and coordinates R2 updates and cleanup.

##### Website and compatibility data

- **Website routes and landing page** — `apps/web/app/page.tsx`: implements the homepage; the repository is documented as vinext’s website.
- **Compatibility dashboard** — `apps/web/app/compatibility/page.tsx`: substantial dashboard route; supporting suite and router classification logic is implemented in `apps/web/app/compatibility/suite-support.ts` and `apps/web/app/compatibility/router-buckets.ts`.
- **Compatibility ingestion endpoints** — `apps/web/app/api/compatibility/route.ts`: authenticates and upserts compatibility run counts and file results; `apps/web/app/api/compatibility/classify/route.ts` separately upserts router classification metadata.
- **Compatibility database schema and client** — `apps/web/app/lib/db/schema.ts`: defines compatibility data tables; `apps/web/app/lib/db/client.ts` creates a database client using that schema.
- **Blog content and feed** — `apps/web/app/blog/_source.ts`: supplies blog source data; `apps/web/app/blog/feed.xml/route.ts` uses it to produce the feed.

##### External actors

- **Application developer** — (null repository path): runs Vite or a vinext CLI command in a consuming project.
- **Consuming Next.js-style application** — (null repository path): supplies the project routes, configuration, and application code vinext builds and serves.
- **Browser or HTTP client** — (null repository path): requests application pages and APIs and receives responses.
- **Cloudflare Workers platform** — (null repository path): runs deployed Workers and provides the platform bindings used by the response store.
- **Compatibility-suite CI caller** — (null repository path): submits compatibility run results and classifications to the website’s ingestion endpoints.

#### Relationships

- **Application developer -> Vite plugin entry**: invokes Vite with vinext; evidence: `README.md`.
- **Application developer -> CLI and project initialization**: runs documented migration or CLI commands; evidence: `README.md`.
- **Vite plugin entry -> Next.js configuration handling**: plugin loads the project’s Next configuration, as documented; evidence: `README.md`.
- **Vite plugin entry -> Route matching and validation**: plugin provides the framework route integration; evidence: none (inferred from documented Vite integration and routing subsystem).
- **Browser or HTTP client -> Shared request security and normalization**: sends a request that is checked and normalized; evidence: `packages/vinext/src/server/request-pipeline.ts`.
- **Pages Router request pipeline -> Shared request security and normalization**: imports and uses the shared request pipeline; evidence: `packages/vinext/src/server/pages-request-pipeline.ts`.
- **Pages Router request pipeline -> Route matching and validation**: imports route-validation and routing utilities; evidence: `packages/vinext/src/server/pages-request-pipeline.ts`.
- **Route matching and validation -> Consuming Next.js-style application**: routes requests to application-defined pages; evidence: none (inferred; exact runtime dispatch is not shown).
- **Browser App Router navigation -> Browser or HTTP client**: updates browser-visible navigation state; evidence: `packages/vinext/src/server/app-browser-navigation-controller.ts`.
- **Cloudflare deployment CLI -> Cloudflare Workers platform**: deploys the application to Workers; evidence: `README.md`.
- **Cloudflare CDN cache adapter -> Workers response-store binding**: no direct call is established in the supplied excerpts; evidence: none (inferred only as part of the documented Cloudflare cache integration).
- **Cloudflare response-store adapter -> Workers response-store binding**: imports response-store types; evidence: `packages/cloudflare/src/cache/response-store-adapter.worker.ts`.
- **Workers response-store binding -> Durable Object metadata and storage coordination**: binding references the metadata Durable Object; evidence: `packages/workers-response-store/src/binding.ts`.
- **Compatibility-suite CI caller -> Compatibility ingestion endpoints**: submits run counts and file results; evidence: `apps/web/app/api/compatibility/route.ts`.
- **Compatibility-suite CI caller -> Compatibility ingestion endpoints**: submits classification metadata; evidence: `apps/web/app/api/compatibility/classify/route.ts`.
- **Compatibility ingestion endpoints -> Compatibility database schema and client**: run ingestion writes run/file rows, and classification ingestion uses the database client to write classifications; evidence: `apps/web/app/api/compatibility/route.ts` and `apps/web/app/api/compatibility/classify/route.ts`.
- **Compatibility database schema and client -> Compatibility dashboard**: the dashboard presents compatibility results; evidence: none (inferred; dashboard query wiring is not sampled).

#### Coverage limits

The README and tree establish broad supported features, but the excerpts do not show the full Vite plugin registration, production server dispatch, App Router rendering chain, Cloudflare deploy sequence, or dashboard reads. Those relationships are left out or marked inferred rather than asserted as concrete calls.

Main entry points: [`apps/web/app/api/compatibility/route.ts`](https://github.com/cloudflare/vinext/blob/main/apps/web/app/api/compatibility/route.ts) (Compatibility Ingestion), [`packages/vinext/src/index.ts`](https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/index.ts) (Vite Plugin), [`packages/vinext/src/routing/route-validation.ts`](https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/routing/route-validation.ts) (Route Matching), [`packages/workers-response-store/src/binding.ts`](https://github.com/cloudflare/vinext/blob/main/packages/workers-response-store/src/binding.ts) (Response-Store Binding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_framework["Framework Setup"]
  node_developer(("Application Developer<br/>External actor"))
  node_vite["Vite Plugin<br/>Framework integration"]
  node_cli["Vinext CLI<br/>[cli.ts]"]
  node_next_config["Next Config<br/>Configuration"]
end

subgraph group_requests["Request Execution"]
  node_app["Next.js-Style App<br/>External application"]
  node_browser(("Browser or HTTP Client<br/>External actor"))
  node_shared_request["Shared Request Pipeline<br/>Request normalization"]
  node_pages_pipeline["Pages Request Pipeline<br/>Request execution"]
  node_route_validation["Route Matching<br/>Routing"]
  node_browser_navigation["Browser Navigation<br/>Navigation controller"]
end

subgraph group_cloudflare["Cloudflare Runtime"]
  node_cf_cli["Cloudflare Deploy CLI<br/>Deployment CLI"]
  node_workers(("Cloudflare Workers<br/>External platform"))
  node_cdn_cache["CDN Cache Adapter"]
  node_response_adapter["Response-Store Adapter<br/>Storage adapter"]
  node_store_binding["Response-Store Binding<br/>Storage binding"]
  node_metadata_do[("Metadata Durable Object<br/>Metadata and storage coordination")]
end

subgraph group_website["Compatibility Website"]
  node_ci_caller(("Compatibility CI Caller<br/>External actor"))
  node_ingestion["Compatibility Ingestion<br/>API endpoints"]
  node_compat_db[("Compatibility Database<br/>Schema and client")]
  node_dashboard["Compatibility Dashboard<br/>Website route"]
end

node_developer -->|"runs with"| node_vite
node_developer -->|"runs commands"| node_cli
node_vite -->|"loads config"| node_next_config
node_vite -.->|"integrates routing"| node_route_validation
node_browser -->|"sends request"| node_shared_request
node_pages_pipeline -->|"uses pipeline"| node_shared_request
node_pages_pipeline -->|"uses routing"| node_route_validation
node_route_validation -.->|"routes requests"| node_app
node_browser_navigation -->|"updates navigation"| node_browser
node_cf_cli -->|"deploys to"| node_workers
node_cdn_cache -.->|"integrates with"| node_store_binding
node_response_adapter -->|"uses types"| node_store_binding
node_store_binding -->|"references"| node_metadata_do
node_ci_caller -->|"submits run results"| node_ingestion
node_ci_caller -->|"submits classifications"| node_ingestion
node_ingestion -->|"writes run results"| node_compat_db
node_ingestion -->|"writes classifications"| node_compat_db
node_compat_db -.->|"provides results"| node_dashboard

click node_vite "https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/index.ts"
click node_cli "https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/cli.ts"
click node_next_config "https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/config/next-config.ts"
click node_shared_request "https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/server/request-pipeline.ts"
click node_pages_pipeline "https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/server/pages-request-pipeline.ts"
click node_route_validation "https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/routing/route-validation.ts"
click node_browser_navigation "https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/server/app-browser-navigation-controller.ts"
click node_cf_cli "https://github.com/cloudflare/vinext/blob/main/packages/cloudflare/src/cli.ts"
click node_cdn_cache "https://github.com/cloudflare/vinext/blob/main/packages/cloudflare/src/cache/cdn-adapter.worker.ts"
click node_response_adapter "https://github.com/cloudflare/vinext/blob/main/packages/cloudflare/src/cache/response-store-adapter.worker.ts"
click node_store_binding "https://github.com/cloudflare/vinext/blob/main/packages/workers-response-store/src/binding.ts"
click node_metadata_do "https://github.com/cloudflare/vinext/blob/main/packages/workers-response-store/src/metadata-do.ts"
click node_ingestion "https://github.com/cloudflare/vinext/blob/main/apps/web/app/api/compatibility/route.ts"
click node_compat_db "https://github.com/cloudflare/vinext/blob/main/apps/web/app/lib/db/client.ts"
click node_dashboard "https://github.com/cloudflare/vinext/blob/main/apps/web/app/compatibility/page.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_developer,node_vite,node_cli,node_next_config toneBlue
class node_app,node_browser,node_shared_request,node_pages_pipeline,node_route_validation,node_browser_navigation toneAmber
class node_cf_cli,node_workers,node_cdn_cache,node_response_adapter,node_store_binding,node_metadata_do toneMint
class node_ci_caller,node_ingestion,node_compat_db,node_dashboard toneRose
```

## Components

### Framework Setup

Developer entry points and project configuration.

- **Application Developer**: External actor
- [Vite Plugin](https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/index.ts): Framework integration · `packages/vinext/src/index.ts`
- [Vinext CLI](https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/cli.ts): CLI · `packages/vinext/src/cli.ts`
- [Next Config](https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/config/next-config.ts): Configuration · `packages/vinext/src/config/next-config.ts`

### Request Execution

Routing and browser-facing request handling.

- **Next.js-Style App**: External application
- **Browser or HTTP Client**: External actor
- [Shared Request Pipeline](https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/server/request-pipeline.ts): Request normalization · `packages/vinext/src/server/request-pipeline.ts`
- [Pages Request Pipeline](https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/server/pages-request-pipeline.ts): Request execution · `packages/vinext/src/server/pages-request-pipeline.ts`
- [Route Matching](https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/routing/route-validation.ts): Routing · `packages/vinext/src/routing/route-validation.ts`
- [Browser Navigation](https://github.com/cloudflare/vinext/blob/main/packages/vinext/src/server/app-browser-navigation-controller.ts): Navigation controller · `packages/vinext/src/server/app-browser-navigation-controller.ts`

### Cloudflare Runtime

Deployment and response-store integration.

- [Cloudflare Deploy CLI](https://github.com/cloudflare/vinext/blob/main/packages/cloudflare/src/cli.ts): Deployment CLI · `packages/cloudflare/src/cli.ts`
- **Cloudflare Workers**: External platform
- [CDN Cache Adapter](https://github.com/cloudflare/vinext/blob/main/packages/cloudflare/src/cache/cdn-adapter.worker.ts): Cache adapter · `packages/cloudflare/src/cache/cdn-adapter.worker.ts`
- [Response-Store Adapter](https://github.com/cloudflare/vinext/blob/main/packages/cloudflare/src/cache/response-store-adapter.worker.ts): Storage adapter · `packages/cloudflare/src/cache/response-store-adapter.worker.ts`
- [Response-Store Binding](https://github.com/cloudflare/vinext/blob/main/packages/workers-response-store/src/binding.ts): Storage binding · `packages/workers-response-store/src/binding.ts`
- [Metadata Durable Object](https://github.com/cloudflare/vinext/blob/main/packages/workers-response-store/src/metadata-do.ts): Metadata and storage coordination · `packages/workers-response-store/src/metadata-do.ts`

### Compatibility Website

Compatibility ingestion and results display.

- **Compatibility CI Caller**: External actor
- [Compatibility Ingestion](https://github.com/cloudflare/vinext/blob/main/apps/web/app/api/compatibility/route.ts): API endpoints · `apps/web/app/api/compatibility/route.ts`
- [Compatibility Database](https://github.com/cloudflare/vinext/blob/main/apps/web/app/lib/db/client.ts): Schema and client · `apps/web/app/lib/db/client.ts`
- [Compatibility Dashboard](https://github.com/cloudflare/vinext/blob/main/apps/web/app/compatibility/page.tsx): Website route · `apps/web/app/compatibility/page.tsx`

## Connections

- Application Developer → Vite Plugin: runs with (evidence: `README.md`)
- Application Developer → Vinext CLI: runs commands (evidence: `README.md`)
- Vite Plugin → Next Config: loads config (evidence: `README.md`)
- Vite Plugin → Route Matching: integrates routing · Inferred; not shown in the code that was read.
- Browser or HTTP Client → Shared Request Pipeline: sends request (evidence: `packages/vinext/src/server/request-pipeline.ts`)
- Pages Request Pipeline → Shared Request Pipeline: uses pipeline (evidence: `packages/vinext/src/server/pages-request-pipeline.ts`)
- Pages Request Pipeline → Route Matching: uses routing (evidence: `packages/vinext/src/server/pages-request-pipeline.ts`)
- Route Matching → Next.js-Style App: routes requests · Inferred; not shown in the code that was read.
- Browser Navigation → Browser or HTTP Client: updates navigation (evidence: `packages/vinext/src/server/app-browser-navigation-controller.ts`)
- Cloudflare Deploy CLI → Cloudflare Workers: deploys to (evidence: `README.md`)
- CDN Cache Adapter → Response-Store Binding: integrates with · Inferred; not shown in the code that was read.
- Response-Store Adapter → Response-Store Binding: uses types (evidence: `packages/cloudflare/src/cache/response-store-adapter.worker.ts`)
- Response-Store Binding → Metadata Durable Object: references (evidence: `packages/workers-response-store/src/binding.ts`)
- Compatibility CI Caller → Compatibility Ingestion: submits run results (evidence: `apps/web/app/api/compatibility/route.ts`)
- Compatibility CI Caller → Compatibility Ingestion: submits classifications
- Compatibility Ingestion → Compatibility Database: writes run results (evidence: `apps/web/app/api/compatibility/route.ts`)
- Compatibility Ingestion → Compatibility Database: writes classifications
- Compatibility Database → Compatibility Dashboard: provides results · Inferred; not shown in the code that was read.