vinext 0.0.30 → 0.0.31

package/README.md

@@ -25,7 +25,13 @@ The skill handles compatibility checking, dependency installation, config genera
 ### Or do it manually
 
 ```bash
-npm install vinext
+npm install -D vinext vite @vitejs/plugin-react
+```
+
+If you're using the App Router, also install:
+
+```bash
+npm install -D @vitejs/plugin-rsc react-server-dom-webpack
 ```
 
 Replace `next` with `vinext` in your scripts:
@@ -85,7 +91,7 @@ npx vinext init
 This will:
 
 1. Run `vinext check` to scan for compatibility issues
-2. Install `vite` (and `@vitejs/plugin-rsc` for App Router projects) as devDependencies
+2. Install `vite`, `@vitejs/plugin-react`, and App Router-only deps (`@vitejs/plugin-rsc`, `react-server-dom-webpack`) as devDependencies
 3. Rename CJS config files (e.g. `postcss.config.js` -> `.cjs`) to avoid ESM conflicts
 4. Add `"type": "module"` to `package.json`
 5. Add `dev:vinext` and `build:vinext` scripts to `package.json`
@@ -650,8 +656,8 @@ examples/                 # Deployed demo apps (see Live Examples above)
 ```bash
 pnpm test             # Vitest unit + integration tests
 pnpm run test:e2e     # Playwright E2E tests (5 projects)
-pnpm run typecheck    # TypeScript checking (tsgo)
-pnpm run lint         # Linting (oxlint)
+pnpm run check        # Format, lint, and type checks
+pnpm run lint         # Lint only (type-aware oxlint)
 pnpm run fmt          # Formatting (oxfmt)
 pnpm run fmt:check    # Check formatting without writing
 ```
@@ -671,7 +677,7 @@ pnpm install
 pnpm run build
 ```
 
-This compiles the vinext package to `packages/vinext/dist/`. For active development, use `pnpm --filter vinext run dev` to run `tsc --watch`.
+This builds the vinext package to `packages/vinext/dist/` via `vp pack`. For active development, use `pnpm --filter vinext run dev` to run `vp pack --watch`.
 
 To use it against an external Next.js app, link the built package:
 
@@ -698,7 +704,7 @@ This project is experimental and under active development. Issues and PRs are we
 
 ### CI
 
-When you open a PR, CI (lint, typecheck, Vitest, Playwright E2E) runs automatically. First-time contributors need one manual approval from a maintainer, then subsequent PRs run without intervention.
+When you open a PR, CI (check, Vitest, Playwright E2E) runs automatically. First-time contributors need one manual approval from a maintainer, then subsequent PRs run without intervention.
 
 Deploy previews (building and deploying examples to Cloudflare Workers) only run for branches pushed to the main repo. If you're a Cloudflare employee, push your branch to the main repo instead of forking, and previews deploy automatically. For fork PRs, a maintainer can comment `/deploy-preview` to trigger the deploy and post preview URLs.
 

package/dist/build/prerender.d.ts

@@ -0,0 +1,188 @@
+import { Route } from "../routing/pages-router.js";
+import { AppRoute } from "../routing/app-router.js";
+import { ResolvedNextConfig } from "../config/next-config.js";
+import { readPrerenderSecret } from "./server-manifest.js";
+import { Server } from "node:http";
+
+//#region src/build/prerender.d.ts
+interface PrerenderResult {
+  /** One entry per route (including skipped/error routes). */
+  routes: PrerenderRouteResult[];
+}
+type PrerenderRouteResult = {
+  /** The route's file-system pattern, e.g. `/blog/:slug`. */route: string;
+  status: "rendered";
+  outputFiles: string[];
+  revalidate: number | false;
+  /**
+   * The concrete prerendered URL path, e.g. `/blog/hello-world`.
+   * Only present when the route is dynamic and `path` differs from `route`.
+   * Omitted for non-dynamic routes where pattern === path.
+   */
+  path?: string;
+} | {
+  route: string;
+  status: "skipped";
+  reason: "ssr" | "dynamic" | "no-static-params" | "api" | "internal";
+} | {
+  route: string;
+  status: "error";
+  error: string;
+};
+/** Called after each route is resolved (rendered, skipped, or error). */
+type PrerenderProgressCallback = (update: {
+  /** Routes completed so far (rendered + skipped + error). */completed: number; /** Total routes queued for rendering. */
+  total: number; /** The route URL that just finished. */
+  route: string; /** Its final status. */
+  status: PrerenderRouteResult["status"];
+}) => void;
+interface PrerenderOptions {
+  /**
+   * 'default' — prerender static/ISR routes; skip SSR routes
+   * 'export'  — same as default but SSR routes are errors
+   */
+  mode: "default" | "export";
+  /** Output directory for generated HTML/RSC files. */
+  outDir: string;
+  /**
+   * Directory where `vinext-prerender.json` is written.
+   * Defaults to `outDir` when omitted.
+   * Set this when the manifest should land in a different location than the
+   * generated HTML/RSC files (e.g. `dist/server/` while HTML goes to `dist/server/prerendered-routes/`).
+   */
+  manifestDir?: string;
+  /** Resolved next.config.js. */
+  config: ResolvedNextConfig;
+  /**
+   * Maximum number of routes rendered in parallel.
+   * Defaults to `os.availableParallelism()` capped at 8.
+   */
+  concurrency?: number;
+  /**
+   * Called after each route finishes rendering.
+   * Use this to display a progress bar in the CLI.
+   */
+  onProgress?: PrerenderProgressCallback;
+  /**
+   * When true, skip writing `vinext-prerender.json` at the end of this phase.
+   * Use this when the caller (e.g. `runPrerender`) will merge results from
+   * multiple phases and write a single unified manifest itself.
+   */
+  skipManifest?: boolean;
+}
+interface PrerenderPagesOptions extends PrerenderOptions {
+  /** Discovered page routes (non-API). */
+  routes: Route[];
+  /** Discovered API routes. */
+  apiRoutes: Route[];
+  /** Pages directory path. */
+  pagesDir: string;
+  /**
+   * Absolute path to the pre-built Pages Router server bundle
+   * (e.g. `dist/server/entry.js`).
+   *
+   * Required when not passing `_prodServer`. For hybrid builds,
+   * `runPrerender` passes a shared `_prodServer` instead.
+   */
+  pagesBundlePath?: string;
+}
+interface PrerenderAppOptions extends PrerenderOptions {
+  /** Discovered app routes. */
+  routes: AppRoute[];
+  /**
+   * Absolute path to the pre-built RSC handler bundle (e.g. `dist/server/index.js`).
+   */
+  rscBundlePath: string;
+}
+type PrerenderPagesOptionsInternal = PrerenderPagesOptions & {
+  _prodServer?: {
+    server: Server;
+    port: number;
+  };
+  /**
+   * Prerender secret to use when `_prodServer` is provided and `pagesBundlePath`
+   * is absent (hybrid builds). Read from `vinext-server.json` by `runPrerender`
+   * and passed here so `prerenderPages` does not need to locate the manifest itself.
+   */
+  _prerenderSecret?: string;
+};
+type PrerenderAppOptionsInternal = PrerenderAppOptions & {
+  _prodServer?: {
+    server: Server;
+    port: number;
+  };
+};
+/**
+ * Build a URL path from a route pattern and params.
+ * "/posts/:id" + { id: "42" } → "/posts/42"
+ * "/docs/:slug+" + { slug: ["a", "b"] } → "/docs/a/b"
+ */
+declare function buildUrlFromParams(pattern: string, params: Record<string, string | string[]>): string;
+/**
+ * Determine the HTML output file path for a URL.
+ * Respects trailingSlash config.
+ */
+declare function getOutputPath(urlPath: string, trailingSlash: boolean): string;
+/**
+ * Run the prerender phase for Pages Router.
+ *
+ * Rendering is done via HTTP through a locally-spawned production server.
+ * Works for both plain Node and Cloudflare Workers builds.
+ * Route classification uses static file analysis (classifyPagesRoute);
+ * getStaticPaths is fetched via a dedicated
+ * `/__vinext/prerender/pages-static-paths?pattern=…` endpoint on the server.
+ *
+ * Returns structured results for every route (rendered, skipped, or error).
+ * Writes HTML files to `outDir`. If `manifestDir` is set, writes
+ * `vinext-prerender.json` there; otherwise writes it to `outDir`.
+ */
+declare function prerenderPages({
+  routes,
+  apiRoutes,
+  pagesDir,
+  outDir,
+  config,
+  mode,
+  ...options
+}: PrerenderPagesOptionsInternal): Promise<PrerenderResult>;
+/**
+ * Run the prerender phase for App Router.
+ *
+ * Starts a local production server and fetches every static/ISR route via HTTP.
+ * Works for both plain Node and Cloudflare Workers builds — the CF Workers bundle
+ * (`dist/server/index.js`) is a standard Node-compatible server entry, so no
+ * wrangler/miniflare is needed. Writes HTML files, `.rsc` files, and
+ * `vinext-prerender.json` to `outDir`.
+ *
+ * If the bundle does not exist, an error is thrown directing the user to run
+ * `vinext build` first.
+ *
+ * Speculative static rendering: routes classified as 'unknown' (no explicit
+ * config, non-dynamic URL) are attempted with an empty headers/cookies context.
+ * If they succeed, they are marked as rendered. If they throw a DynamicUsageError
+ * or fail, they are marked as skipped with reason 'dynamic'.
+ */
+declare function prerenderApp({
+  routes,
+  outDir,
+  config,
+  mode,
+  rscBundlePath,
+  ...options
+}: PrerenderAppOptionsInternal): Promise<PrerenderResult>;
+/**
+ * Determine the RSC output file path for a URL.
+ * "/blog/hello-world" → "blog/hello-world.rsc"
+ * "/"                 → "index.rsc"
+ */
+declare function getRscOutputPath(urlPath: string): string;
+/**
+ * Write `vinext-prerender.json` to `outDir`.
+ *
+ * This is a minimal flat list of route results used during testing and as a
+ * seed for future ISR cache population. Not consumed by the production server.
+ */
+declare function writePrerenderIndex(routes: PrerenderRouteResult[], outDir: string): void;
+//#endregion
+export { PrerenderAppOptions, PrerenderOptions, PrerenderPagesOptions, PrerenderProgressCallback, PrerenderResult, PrerenderRouteResult, buildUrlFromParams, getOutputPath, getRscOutputPath, prerenderApp, prerenderPages, readPrerenderSecret, writePrerenderIndex };
+//# sourceMappingURL=prerender.d.ts.map