Skip to content

Latest commit

 

History

History
392 lines (265 loc) · 21.2 KB

AGENTS.md

File metadata and controls

392 lines (265 loc) · 21.2 KB

Agent Guidelines

Instructions for AI agents working on this codebase.

Project Overview

vinext is a Vite plugin that reimplements the Next.js API surface, with Cloudflare Workers as the primary deployment target. The goal: take any Next.js app and deploy it to Workers with one command.

vinext reimplements the Next.js API surface using Vite, with Cloudflare Workers as the primary deployment target. The goal is to let developers keep their existing Next.js code and deploy it to Workers.

Quick Reference

Commands

pnpm test                                        # Vitest — full suite (~2 min, serial)
pnpm test tests/routing.test.ts                  # Run a single test file (~seconds)
pnpm test tests/shims.test.ts tests/link.test.ts # Run specific files
pnpm run test:e2e                                # Playwright E2E tests (all projects, use PLAYWRIGHT_PROJECT=<name> to target one)
pnpm run typecheck                               # TypeScript via tsgo (fast)
pnpm run lint                                    # oxlint
pnpm run fmt                                     # oxfmt (format)
pnpm run fmt:check                               # oxfmt (check only, no writes)
pnpm run build                                   # Build the vinext package

Project Structure

packages/vinext/src/
  index.ts              # Main Vite plugin
  cli.ts                # vinext CLI
  shims/                # One file per next/* module
  routing/              # File-system route scanners
  server/               # SSR handlers, ISR, middleware
  cloudflare/           # KV cache handler

tests/
  *.test.ts             # Vitest tests
  fixtures/             # Test apps (pages-basic, app-basic, etc.)
  e2e/                  # Playwright tests

examples/               # User-facing demo apps

Key Files

File Purpose
index.ts Vite plugin — resolves next/* imports, generates virtual modules
shims/*.ts Reimplementations of next/link, next/navigation, etc.
server/dev-server.ts Pages Router SSR handler
entries/app-rsc-entry.ts App Router RSC entry generator
routing/pages-router.ts Scans pages/ directory
routing/app-router.ts Scans app/ directory

Development Workflow

Adding a New Feature

  1. Check if Next.js has it — look at Next.js source to understand expected behavior
  2. Search the Next.js test suite — before writing code, search test/e2e/ and test/unit/ in the Next.js repo for related test files (see below)
  3. Add tests first — put test cases in the appropriate tests/*.test.ts file
  4. Implement in shims or server — most features are either a shim (next/* module) or server-side logic
  5. Add fixture pages if needed — tests/fixtures/ has test apps for integration testing
  6. Run the relevant test file(s) to verify your changes (see Running Tests below)

Searching the Next.js Test Suite

This is a required step for all feature work and bug fixes. Before writing code, search the Next.js repo's test/e2e/ and test/unit/ directories for tests related to whatever you're working on. Search broadly, not just for exact feature names.

For example, when working on middleware:

  • Search for middleware and proxy in test directory names
  • Search for error messages like "must export" to find validation tests
  • Check for edge cases like missing exports, misspelled names, invalid configs

Why this matters: vinext aims to match Next.js behavior exactly. If Next.js has a test for it, we should have an equivalent test. Missing this step has caused silent behavioral differences, like middleware failing open on invalid exports instead of throwing an error (which Next.js tests explicitly).

When you find relevant Next.js tests, port the test cases to our test suite and include a comment linking back to the original Next.js test file:

// Ported from Next.js: test/e2e/app-dir/proxy-missing-export/proxy-missing-export.test.ts
// https://github.com/vercel/next.js/blob/canary/test/e2e/app-dir/proxy-missing-export/proxy-missing-export.test.ts

Use gh search code for efficient searching:

gh search code "middleware" --repo vercel/next.js --filename "*.test.*" --limit 20
gh search code "must export" --repo vercel/next.js --filename "*.test.*" --limit 10

Running Tests

Always run targeted tests, not the full suite. The full Vitest suite takes ~2 minutes because test files run serially (to avoid Vite deps optimizer cache races). Running the full suite during development wastes time, especially when multiple agents are working on the repo simultaneously.

During development, run only the test file(s) relevant to your change:

# Run a single test file (fast — seconds, not minutes)
pnpm test tests/routing.test.ts

# Run a few related files
pnpm test tests/shims.test.ts tests/link.test.ts

# Run all nextjs-compat tests
pnpm test tests/nextjs-compat/

# Run tests matching a name pattern
pnpm test -t "middleware"

Which test files to run depends on what you changed:

If you changed... Run these tests
A shim (shims/*.ts) tests/shims.test.ts + the specific shim test (e.g., tests/link.test.ts)
Routing (routing/*.ts) tests/routing.test.ts, tests/route-sorting.test.ts
App Router server (entries/app-rsc-entry.ts) tests/app-router.test.ts, tests/features.test.ts
Pages Router server (server/dev-server.ts) tests/pages-router.test.ts
Caching/ISR tests/isr-cache.test.ts, tests/fetch-cache.test.ts, tests/kv-cache-handler.test.ts
Build/deploy tests/deploy.test.ts, tests/build-optimization.test.ts
Next.js compat features tests/nextjs-compat/ (the relevant file)

Let CI run the full suite. The full pnpm test and all 5 Playwright E2E projects run in CI on every PR. You do not need to run the full suite locally before pushing. CI will catch any cross-cutting regressions.

When to run the full suite locally: Only if you're making a broad change that touches shared infrastructure (e.g., the Vite plugin's resolveId hook, virtual module generation, or the test helpers themselves). Even then, consider pushing and letting CI do it.

Fixing Bugs

Always check dev and prod server parity. Request handling logic exists in multiple places that must stay in sync:

  • entries/app-rsc-entry.ts — App Router dev (generates the RSC entry)
  • server/dev-server.ts — Pages Router dev
  • server/prod-server.ts — Pages Router production (handles middleware, routing, SSR directly)
  • cloudflare/worker-entry.ts — Cloudflare Workers entry

The App Router production server delegates to the built RSC entry, so it inherits fixes from entries/app-rsc-entry.ts. But the Pages Router production server has its own middleware/routing/SSR logic that must be updated separately.

When fixing a bug in any of these files, check whether the same bug exists in the others. Do not leave known bugs as "follow-ups" — fix them in the same PR.

Debugging

  • Dev server logs: Run npx vite dev in a fixture directory
  • RSC streaming issues: Context is often cleared before stream consumption — check AsyncLocalStorage usage
  • Module resolution: Vite has separate module instances for RSC/SSR/client environments

Test Fixtures

  • tests/fixtures/pages-basic/ — Pages Router test app
  • tests/fixtures/app-basic/ — App Router test app
  • examples/app-router-cloudflare/ — App Router on Workers
  • examples/pages-router-cloudflare/ — Pages Router on Workers

Add new test pages to fixtures, not to examples. Examples are for user-facing demos.

Examples (Ecosystem Ports)

The examples/ directory contains real-world Next.js apps ported to run on vinext. These are deployed to Cloudflare Workers on every push to main (see .github/workflows/deploy-examples.yml).

Example Type URL
app-router-cloudflare App Router basics app-router-cloudflare.vinext.workers.dev
pages-router-cloudflare Pages Router basics pages-router-cloudflare.vinext.workers.dev
app-router-playground Next.js playground (MDX, Tailwind) app-router-playground.vinext.workers.dev
realworld-api-rest RealWorld spec (Pages Router) realworld-api-rest.vinext.workers.dev
nextra-docs-template Nextra docs site (MDX, App Router) nextra-docs-template.vinext.workers.dev
benchmarks Performance benchmarks benchmarks.vinext.workers.dev
hackernews HN clone (App Router, RSC) hackernews.vinext.workers.dev

Adding a New Example

  1. Create a directory under examples/ with a package.json (use "vinext": "workspace:*")
  2. Add a vite.config.ts with vinext() and cloudflare() plugins
  3. Add a wrangler.jsonc — for simple apps use "main": "vinext/server/app-router-entry" (no custom worker entry needed)
  4. Add the example to the deploy matrix in .github/workflows/deploy-examples.yml:
    • Add to matrix.example array (with name, project, wrangler_config)
    • Add to the examples array in the PR comment step
  5. Add a smoke test entry in scripts/smoke-test.sh — add a line to the CHECKS array: 
    "your-example-name  /  expected-text-in-body"
  6. Run ./scripts/smoke-test.sh locally to verify after deploying

Smoke Tests

scripts/smoke-test.sh is a lightweight post-deploy check that curls every deployed example and verifies HTTP 200 + expected content. It runs automatically in CI after the deploy job completes.

./scripts/smoke-test.sh                    # check production URLs
./scripts/smoke-test.sh --preview pr-42    # check PR preview URLs

When adding a new example, always add a corresponding smoke test entry. The format is:

"worker-name  /path  expected-text"

where expected-text is a case-insensitive string that must appear in the response body.

Porting Strategy

The examples in .github/repos.json are the ecosystem of Next.js apps we want to support. When porting one:

  1. Use App Router unless the original app specifically requires Pages Router
  2. Keep the same content — the goal is to prove the app works on vinext, not to rewrite it
  3. Use @mdx-js/rollup for MDX support (vinext auto-detects and injects it, or you can register it manually in vite.config.ts)
  4. File issues for anything that requires workarounds — missing shims, unsupported config options, etc.
  5. Don't depend on the original framework's build plugins — e.g., Nextra's webpack plugin won't work; port the content and build a lightweight equivalent

Research Tools

Context7 MCP

Context7 provides fast access to up-to-date documentation and source code for libraries. Use it liberally when researching how to implement something or debugging behavior.

Key library IDs for this project:

  • /vercel/next.js — Next.js source code and docs
  • /llmstxt/nextjs_llms_txt — Extended Next.js documentation
  • /vitejs/vite-plugin-react — Vite RSC plugin docs

Example queries:

  • How Next.js implements headers() and cookies() internally
  • AsyncLocalStorage patterns for request-scoped context
  • RSC streaming and rendering lifecycle
  • Route matching and middleware patterns

EXA Search

Use EXA for web search when you need to find recent discussions, blog posts, GitHub issues, or documentation that isn't in Context7. Particularly useful for:

  • Finding workarounds for edge cases
  • Understanding how other frameworks solved similar problems
  • Locating relevant GitHub issues and discussions

Looking at Next.js Source

When in doubt, look at how Next.js does it. Vinext aims to replicate Next.js behavior, so their implementation is the authoritative reference.

If you're trying to understand how something works under the hood — route matching, RSC streaming, caching behavior, API semantics — the best approach is to go look at the Next.js source code and understand what they're doing, then apply it to how we do things in this project.

Code Style & Dependencies

Prefer Node.js Built-in APIs

Always use Node.js built-in modules and APIs before reaching for third-party packages or hand-rolling your own implementation. Node ships a lot of useful utilities that people forget about or don't know exist. Examples:

  • node:util parseEnv for parsing .env file contents (not dotenv)
  • node:crypto randomUUID() for UUIDs (not uuid)
  • node:fs/promises for async file operations
  • node:test patterns when they apply
  • URL and URLSearchParams for URL manipulation (not string splitting)
  • structuredClone for deep cloning (not lodash.cloneDeep)

If a Node built-in does the job, use it. Only reach for a dependency when the built-in is genuinely insufficient.

Git Workflow

  • NEVER push directly to main. Always create a feature branch and open a PR, even for small fixes. This ensures CI runs before changes are merged and provides a review checkpoint.

  • Branch protection is enabled on main. Required checks: Format, Lint, Typecheck, Vitest, Playwright E2E. Pushing directly to main bypasses these protections and can introduce regressions.

  • NEVER use gh pr merge --admin. The --admin flag bypasses branch protection checks entirely. If merge is blocked, investigate why — don't force it through. A blocked merge usually means a required check failed or is still running.

  • PR workflow:

    1. Create a branch: git checkout -b fix/descriptive-name
    2. Make changes and commit
    3. Push branch: git push -u origin fix/descriptive-name
    4. Open PR via gh pr create
    5. Wait for CI to pass — all required checks (Format, Lint, Typecheck, Vitest, Playwright E2E) must be green
    6. Merge via gh pr merge --squash --delete-branch
    7. If merge is blocked, check which status check failed and fix it — do not bypass with --admin

CI for External Contributors

CI is split into safe checks (no secrets) and deploy previews (requires secrets). This lets external contributors get feedback on their PRs without exposing credentials.

Safe CI (ci.yml) runs for all PRs after first-time contributor approval:

  • Format, Lint, Typecheck, Vitest, Playwright E2E
  • Uses zero secrets and read-only permissions
  • First-time contributors need one manual approval, then subsequent PRs run automatically

Deploy previews (deploy-examples.yml) run automatically only for same-repo branches:

  • The entire workflow is skipped for fork PRs via a job-level if condition
  • Cloudflare employees should push branches to the main repo (not fork), so previews deploy automatically
  • For fork PRs, a maintainer can comment /deploy-preview to trigger the deploy (see deploy-preview-command.yml)

/deploy-preview slash command (deploy-preview-command.yml):

  • Triggered by commenting /deploy-preview on any PR
  • Restricted to org members, collaborators, and repo owners via author_association
  • Builds all examples, deploys previews, runs smoke tests, and posts preview URLs

When modifying CI workflows, keep these rules in mind:

  • ci.yml must never use secrets. It runs untrusted code from forks.
  • deploy-examples.yml must skip entirely for fork PRs. Don't remove the job-level if guard.
  • The /deploy-preview slash command gates secret usage behind the author_association check.

Architecture & Gotchas

Non-obvious patterns and pitfalls discovered during development. Read this before making significant changes.

RSC and SSR Are Separate Vite Environments

This is the single most important architectural detail. The RSC environment and the SSR environment are separate Vite module graphs with separate module instances. If you set state in a module in the RSC environment (e.g., setNavigationContext() in next/navigation), the SSR environment's copy of that module is unaffected.

Per-request state (pathname, searchParams, params, headers, cookies) must be explicitly passed from the RSC entry to the SSR entry via the handleSsr(rscStream, navContext) call. The SSR entry calls the setter before rendering and cleans up afterward.

Rule of thumb: Any per-request state that "use client" components need during SSR must be passed across the environment boundary. They don't share module state.

What @vitejs/plugin-rsc Does vs What vinext Does

The RSC plugin handles:

  • Bundler transforms for "use client" / "use server" directives
  • RSC stream serialization (wraps react-server-dom-webpack)
  • Multi-environment builds (RSC/SSR/Client)
  • CSS code-splitting and auto-injection
  • HMR for server components
  • Bootstrap script injection for client hydration

vinext handles everything else:

  • File-system routing (scanning app/ and pages/ directories)
  • Request lifecycle (middleware, headers, redirects, rewrites, then route handling)
  • Layout nesting and React tree construction
  • Client-side navigation and prefetching
  • Caching (ISR, "use cache", fetch cache)
  • All next/* module shims

The RSC entry's default export is the request handler. The plugin calls it for every request; vinext does route matching, builds the React tree, renders to RSC stream, and delegates to the SSR entry for HTML.

Production Builds Require createBuilder

You must use createBuilder() + builder.buildApp() for production builds, not build() directly. Calling build() from the Vite JS API doesn't trigger the RSC plugin's multi-environment build pipeline. buildApp() runs the 5-step RSC/SSR/client build sequence in the correct order.

Virtual Module Resolution Quirks

  • Build-time root prefix: Vite prefixes virtual module IDs with the project root path when resolving SSR build entries. The resolveId hook must handle both virtual:vinext-server-entry and <root>/virtual:vinext-server-entry.
  • \0 prefix in client environment: When the RSC plugin generates its browser entry, it imports virtual modules using the already-resolved \0-prefixed ID. Vite's import-analysis plugin can't resolve this. Fix: strip the \0 prefix before matching in resolveId.
  • Absolute paths required: Virtual modules have no real file location, so all imports within them must use absolute paths.

Next.js 15+ Thenable Params

Next.js 15 changed params and searchParams to Promises. For backward compatibility with pre-15 code, vinext creates "thenable objects":

Object.assign(Promise.resolve(params), params);

This works both as await params (new style) and params.id (old style). The same pattern applies to generateMetadata and generateViewport.

ISR Architecture

The ISR cache layer sits above CacheHandler, not inside it. CacheHandler (matching Next.js 16's interface) is a simple key-value store. ISR semantics live in a separate isr-cache.ts module:

  • Stale-while-revalidate: Returns stale entries (not null) while background regeneration runs
  • Dedup: A Map<string, Promise> keyed by cache key ensures only one regeneration per key at a time
  • Revalidate tracking: A side map stores revalidate durations by cache key (populated on MISS, read on HIT/STALE)
  • Tag invalidation: Tag-invalidated entries are hard-deleted (return null), unlike time-expired entries which return stale

The caching layer is pluggable via setCacheHandler(). KV is the default for Cloudflare Workers. The ISR logic works automatically with any backend.

Ecosystem Library Compatibility

When adding support for third-party Next.js libraries:

  • next/navigation.js (with .js extension): Libraries like nuqs import with the .js extension. Vite's resolve.alias does exact matching, so a resolveId hook strips .js from next/* imports and redirects through the shim map.
  • next-themes: Works out of the box. ThemeProvider, useTheme, SSR script injection all function correctly.
  • next-intl: Requires deep integration. It expects a plugin from next.config.ts (createNextIntlPlugin) that injects config at build time. Simply installing and importing doesn't work.
  • General pattern: Libraries that only import from next/* public APIs tend to work. Libraries that depend on Next.js build plugins or internal APIs need custom shimming.