@farm.js/plugin 0.1.0-beta.0

package/dist/rsc/types.d.ts

@@ -0,0 +1,123 @@
+import type { FarmServerActionsConfig, ResolvedFarmServerActionsConfig } from "@farm.js/core/server-action-security";
+/**
+ * Configuration options for the Farm.js RSC plugin.
+ */
+export interface FarmRscPluginOptions {
+    /** Security policy applied to server action requests. */
+    serverActions?: FarmServerActionsConfig;
+    /** Build identifier used to reject requests from stale browser deployments. */
+    deploymentId?: string;
+    /**
+     * Override the auto-generated virtual entries with custom files.
+     * If not provided, virtual entries are generated automatically based on
+     * the user's project structure.
+     */
+    entries?: {
+        /** Custom RSC environment entry file */
+        rsc?: string;
+        /** Custom SSR environment entry file */
+        ssr?: string;
+        /** Custom client environment entry file */
+        client?: string;
+    };
+    /**
+     * Enable encryption for server action bound arguments.
+     * This prevents exposing sensitive closure data in the client bundle.
+     * @default true
+     */
+    encryptActions?: boolean;
+    /**
+     * Subdirectory within srcDir containing route files.
+     * If empty, routes are discovered directly in srcDir.
+     * @default 'app'
+     */
+    routesDir?: string;
+    /**
+     * Custom CSS injection function.
+     * If not provided, uses import.meta.viteRsc.loadCss().
+     */
+    cssLoader?: string;
+    /**
+     * Enable verbose logging for debugging.
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Internal context passed to entry generators.
+ * Contains resolved configuration values needed to generate entry files.
+ */
+export interface EntryContext {
+    /** User's source directory, e.g. 'src' */
+    srcDir: string;
+    /** Build output directory, e.g. 'dist' */
+    outDir: string;
+    /** Base URL path, e.g. '/' */
+    basePath: string;
+    /** Route files subdirectory within srcDir */
+    routesDir?: string;
+    /** Root-relative Vite URL for an existing global stylesheet. */
+    globalCssPath?: string;
+    /** Ordered route roots. Modules from later roots override matching earlier modules. */
+    routeRoots?: Array<{
+        name: string;
+        base: string;
+        glob: string;
+    }>;
+    /** Whether server actions are enabled */
+    actionsEnabled: boolean;
+    /** Normalized server action request security policy. */
+    serverActions: ResolvedFarmServerActionsConfig;
+    /** Resolved build identifier embedded into the server and browser entries. */
+    deploymentId: string;
+    /** Whether debug mode is enabled */
+    debug: boolean;
+}
+/**
+ * Matched route information from the file-based router.
+ */
+export interface MatchedRoute {
+    /** The page component's default export */
+    Page: React.ComponentType<any>;
+    /** The file pattern that matched, e.g. '/src/about/page.tsx' */
+    pattern: string;
+    /** Dynamic route parameters, e.g. { slug: 'my-post' } */
+    params: Record<string, string>;
+}
+/**
+ * RSC payload structure sent from server to client.
+ */
+export interface RscPayload {
+    /** The root React element tree (full document for SSR) */
+    root: React.ReactElement;
+    /** Content for div#root only (for client hydration to avoid double/repeated content) */
+    rootContent?: React.ReactElement;
+    /** Serializable document metadata used during client-side navigation. */
+    metadata?: {
+        title?: string;
+        description?: string;
+    };
+    /** Server action return value (if action was executed) */
+    returnValue?: {
+        ok: boolean;
+        data: unknown;
+    };
+    /** Form state for progressive enhancement */
+    formState?: unknown;
+}
+/**
+ * Vite RSC module augmentation for import.meta.
+ */
+declare global {
+    interface ImportMeta {
+        readonly viteRsc: {
+            /** Load CSS for server components */
+            loadCss(): React.ReactElement[];
+            /** Load a module from another environment */
+            loadModule<T = unknown>(env: string, entry: string): Promise<T>;
+            /** Load bootstrap script content for hydration */
+            loadBootstrapScriptContent(entry: string): Promise<string>;
+        };
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rsc/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/rsc/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,+BAA+B,EAChC,MAAM,sCAAsC,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,aAAa,CAAC,EAAE,uBAAuB,CAAC;IAExC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,OAAO,CAAC,EAAE;QACR,wCAAwC;QACxC,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,wCAAwC;QACxC,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,2CAA2C;QAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IAEF;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IAEf,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IAEf,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IAEjB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,uFAAuF;IACvF,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IAEH,yCAAyC;IACzC,cAAc,EAAE,OAAO,CAAC;IAExB,wDAAwD;IACxD,aAAa,EAAE,+BAA+B,CAAC;IAE/C,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IAErB,oCAAoC;IACpC,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,IAAI,EAAE,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAE/B,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAEhB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,0DAA0D;IAC1D,IAAI,EAAE,KAAK,CAAC,YAAY,CAAC;IAEzB,wFAAwF;IACxF,WAAW,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC;IAEjC,yEAAyE;IACzE,QAAQ,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IAEF,0DAA0D;IAC1D,WAAW,CAAC,EAAE;QACZ,EAAE,EAAE,OAAO,CAAC;QACZ,IAAI,EAAE,OAAO,CAAC;KACf,CAAC;IAEF,6CAA6C;IAC7C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,UAAU;QAClB,QAAQ,CAAC,OAAO,EAAE;YAChB,qCAAqC;YACrC,OAAO,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;YAEhC,6CAA6C;YAC7C,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YAEhE,kDAAkD;YAClD,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;SAC5D,CAAC;KACH;CACF"}

package/dist/rsc/types.js

@@ -0,0 +1 @@
+export {};

package/dist/rsc/vite-plugin-nitro.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Vite plugin to run Nitro after RSC build (single "vite build", no post script).
+ * Implements the Nitro RSC deployment pipeline:
+ * - Step 1: Force per-environment output dirs to .nitro/vite/dist/${name} so Nitro can locate artifacts.
+ * - Step 2: Capture the server (RSC) Rollup bundle in writeBundle.
+ * - Step 3: Find the SSR entry chunk from the bundle.
+ * - Step 4: Compute renderer path and pass to Nitro with client publicDir.
+ *
+ * @example
+ * ```ts
+ * import nitro from '@farm.js/plugin/rsc/vite-plugin-nitro'
+ * export default defineConfig({
+ *   plugins: [rsc(), react(), nitro({ server: { environmentName: 'rsc' }, config: { preset: 'vercel' } })],
+ * })
+ * ```
+ */
+import type { Plugin } from "vite";
+export interface NitroPluginOptions {
+    server?: {
+        environmentName?: string;
+        /** Entry name in rollupOptions.input (default: 'index'). */
+        entryName?: string;
+    };
+    config?: {
+        preset?: string;
+    };
+    /** Base output dir when not using .nitro/vite/dist (fallback). */
+    outDir?: string;
+}
+export default function nitro(options?: NitroPluginOptions): Plugin;
+/** Called by RSC plugin buildApp (post) to run Nitro with the captured bundle. */
+export declare function runNitroFromBuildApp(): Promise<void>;
+//# sourceMappingURL=vite-plugin-nitro.d.ts.map

package/dist/rsc/vite-plugin-nitro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin-nitro.d.ts","sourceRoot":"","sources":["../../src/rsc/vite-plugin-nitro.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAenC,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE;QACP,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,4DAA4D;QAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,MAAM,CAAC,EAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAWD,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,OAAO,GAAE,kBAAuB,GAAG,MAAM,CAoHtE;AAED,kFAAkF;AAClF,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CA+C1D"}

package/dist/rsc/vite-plugin-nitro.js

@@ -0,0 +1,163 @@
+/**
+ * Vite plugin to run Nitro after RSC build (single "vite build", no post script).
+ * Implements the Nitro RSC deployment pipeline:
+ * - Step 1: Force per-environment output dirs to .nitro/vite/dist/${name} so Nitro can locate artifacts.
+ * - Step 2: Capture the server (RSC) Rollup bundle in writeBundle.
+ * - Step 3: Find the SSR entry chunk from the bundle.
+ * - Step 4: Compute renderer path and pass to Nitro with client publicDir.
+ *
+ * @example
+ * ```ts
+ * import nitro from '@farm.js/plugin/rsc/vite-plugin-nitro'
+ * export default defineConfig({
+ *   plugins: [rsc(), react(), nitro({ server: { environmentName: 'rsc' }, config: { preset: 'vercel' } })],
+ * })
+ * ```
+ */
+import path from "path";
+import { buildRscNitro } from "./nitro-build.js";
+import { waitForRscOutputs } from "./nitro-build.js";
+import { resolveRscBuildOutputPath } from "./build-paths.js";
+let nitroRunScheduled = false;
+/** Stored RSC (server) bundle from writeBundle so we can find the entry chunk. */
+let serverBundle = null;
+const NITRO_VITE_DIST = ".nitro/vite/dist";
+export default function nitro(options = {}) {
+    const serverEnvName = options.server?.environmentName ?? "rsc";
+    const serverEntryName = options.server?.entryName ?? "index";
+    let resolvedRoot = process.cwd();
+    let rscOutDir = path.join(NITRO_VITE_DIST, "rsc");
+    let ssrOutDir = path.join(NITRO_VITE_DIST, "ssr");
+    let clientOutDir = path.join(NITRO_VITE_DIST, "client");
+    let baseOutDir = NITRO_VITE_DIST;
+    return {
+        name: "vite-plugin-nitro",
+        apply: "build",
+        // Step 1: Force per-environment output dirs so Nitro can locate artifacts.
+        config() {
+            return {
+                environments: {
+                    rsc: { build: { outDir: path.join(NITRO_VITE_DIST, "rsc") } },
+                    ssr: { build: { outDir: path.join(NITRO_VITE_DIST, "ssr") } },
+                    client: { build: { outDir: path.join(NITRO_VITE_DIST, "client") } },
+                },
+            };
+        },
+        configResolved(config) {
+            resolvedRoot = path.resolve(config.root ?? process.cwd());
+            const envs = config.environments;
+            if (envs?.rsc?.build?.outDir && envs?.ssr?.build?.outDir && envs?.client?.build?.outDir) {
+                rscOutDir = envs.rsc.build.outDir;
+                ssrOutDir = envs.ssr.build.outDir;
+                clientOutDir = envs.client.build.outDir;
+                const dir = path.dirname(rscOutDir);
+                baseOutDir = path.isAbsolute(dir) ? path.relative(resolvedRoot, dir) || "." : dir;
+            }
+            else {
+                baseOutDir = options.outDir ?? "dist";
+                rscOutDir = path.join(baseOutDir, "rsc");
+                ssrOutDir = path.join(baseOutDir, "ssr");
+                clientOutDir = path.join(baseOutDir, "client");
+            }
+        },
+        // Step 2: Capture the server (RSC) Rollup bundle when that environment writes.
+        writeBundle(_options, bundle) {
+            if (this.environment?.name === serverEnvName) {
+                serverBundle = bundle;
+                globalThis.__FARM_NITRO_SERVER_BUNDLE = bundle;
+                globalThis.__FARM_NITRO_PATHS = {
+                    root: resolvedRoot,
+                    rscOutDir,
+                    ssrOutDir,
+                    clientOutDir,
+                    serverEntryName,
+                    preset: options.config?.preset ?? process.env.NITRO_PRESET ?? "vercel",
+                };
+            }
+        },
+        // Run Nitro once all env outputs exist (after step 5). buildEnd runs after each env; only run when all exist.
+        async buildEnd() {
+            if (nitroRunScheduled)
+                return;
+            const root = path.resolve(resolvedRoot);
+            const { existsSync } = await import("fs");
+            await new Promise((r) => setTimeout(r, 800));
+            const baseOutDir = rscOutDir.includes(".nitro/vite/dist")
+                ? NITRO_VITE_DIST
+                : path.isAbsolute(path.dirname(rscOutDir))
+                    ? path.relative(root, path.dirname(rscOutDir)) || "."
+                    : path.dirname(rscOutDir);
+            const rscOk = existsSync(resolveRscBuildOutputPath(root, baseOutDir, "rsc", "index.js"));
+            const ssrOk = existsSync(resolveRscBuildOutputPath(root, baseOutDir, "ssr", "index.js"));
+            const clientOk = existsSync(resolveRscBuildOutputPath(root, baseOutDir, "client", "assets"));
+            if (!rscOk || !ssrOk || !clientOk)
+                return;
+            nitroRunScheduled = true;
+            const preset = options.config?.preset ?? process.env.NITRO_PRESET ?? "vercel";
+            const run = async () => {
+                await waitForRscOutputs(root, baseOutDir, { timeoutMs: 20_000 }).catch(() => {
+                    // Outputs already verified; proceed (nitro-build stubs manifest if missing)
+                });
+                let rendererPath = resolveRscBuildOutputPath(root, rscOutDir, "index.js");
+                if (serverBundle) {
+                    const serverEntryChunks = [];
+                    for (const chunk of Object.values(serverBundle)) {
+                        if (chunk.type === "chunk" && chunk.isEntry && chunk.fileName) {
+                            serverEntryChunks.push(chunk);
+                        }
+                    }
+                    const selected = serverEntryName
+                        ? serverEntryChunks.find((c) => (c.name ?? c.fileName) === serverEntryName)
+                        : serverEntryChunks[0];
+                    if (selected?.fileName) {
+                        rendererPath = resolveRscBuildOutputPath(root, rscOutDir, selected.fileName);
+                    }
+                }
+                await buildRscNitro({
+                    root,
+                    rendererPath,
+                    publicDir: resolveRscBuildOutputPath(root, clientOutDir),
+                    ssrPath: resolveRscBuildOutputPath(root, ssrOutDir, "index.js"),
+                    assetsDir: undefined,
+                    preset,
+                });
+                globalThis.__FARM_NITRO_PLUGIN_RAN = true;
+            };
+            await run();
+        },
+    };
+}
+/** Called by RSC plugin buildApp (post) to run Nitro with the captured bundle. */
+export async function runNitroFromBuildApp() {
+    const paths = globalThis.__FARM_NITRO_PATHS;
+    const bundle = globalThis.__FARM_NITRO_SERVER_BUNDLE;
+    if (!paths)
+        return;
+    const root = paths.root;
+    const preset = paths.preset;
+    const baseOutDir = path.dirname(paths.rscOutDir);
+    await waitForRscOutputs(root, baseOutDir, { timeoutMs: 25_000 });
+    let rendererPath = resolveRscBuildOutputPath(root, paths.rscOutDir, "index.js");
+    if (bundle) {
+        const serverEntryChunks = [];
+        for (const chunk of Object.values(bundle)) {
+            if (chunk.type === "chunk" && chunk.isEntry && chunk.fileName) {
+                serverEntryChunks.push(chunk);
+            }
+        }
+        const selected = paths.serverEntryName
+            ? serverEntryChunks.find((c) => (c.name ?? c.fileName) === paths.serverEntryName)
+            : serverEntryChunks[0];
+        if (selected?.fileName) {
+            rendererPath = resolveRscBuildOutputPath(root, paths.rscOutDir, selected.fileName);
+        }
+    }
+    await buildRscNitro({
+        root,
+        rendererPath,
+        publicDir: resolveRscBuildOutputPath(root, paths.clientOutDir),
+        ssrPath: resolveRscBuildOutputPath(root, paths.ssrOutDir, "index.js"),
+        assetsDir: undefined,
+        preset,
+    });
+}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@farm.js/plugin",
+  "version": "0.1.0-beta.0",
+  "description": "Official plugins for Farm.js framework",
+  "license": "MIT",
+  "author": "Farm.js Team",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farmjs-plugin"
+  },
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./rsc": {
+      "types": "./dist/rsc/index.d.ts",
+      "import": "./dist/rsc/index.js"
+    },
+    "./rsc/optimized-boundary": {
+      "types": "./dist/rsc/optimized-boundary.d.ts",
+      "import": "./dist/rsc/optimized-boundary.js"
+    },
+    "./rsc/vite-plugin-nitro": {
+      "types": "./dist/rsc/vite-plugin-nitro.d.ts",
+      "import": "./dist/rsc/vite-plugin-nitro.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "import": "./dist/middleware/index.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/api/index.js"
+    },
+    "./observability": {
+      "types": "./dist/observability/index.d.ts",
+      "import": "./dist/observability/index.js"
+    },
+    "./context": {
+      "types": "./dist/context/index.d.ts",
+      "import": "./dist/context/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@farming-labs/strata": "0.1.2",
+    "better-call": "^1.0.19",
+    "es-module-lexer": "2.0.0",
+    "nitro": "3.0.1-alpha.0",
+    "picocolors": "^1.0.0",
+    "rsc-html-stream": "^0.0.4",
+    "@farm.js/core": "0.1.0-beta.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.21",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-rsc": "^0.5.18",
+    "tsdown": "^0.15.7",
+    "typescript": "^5.5.3",
+    "vite": "^6.0.0",
+    "vitest": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@vitejs/plugin-rsc": ">=0.5.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0",
+    "vite": ">=6.0.0",
+    "@farm.js/core": "0.1.0-beta.0"
+  },
+  "peerDependenciesMeta": {
+    "@vitejs/plugin-rsc": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "node scripts/clean.js && tsc && node scripts/build.js",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/scripts/build.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The TypeScript compiler emits ESM with .js extensions.
+
+console.log("Post-processing build output...");
+
+// Nothing to do for now - TypeScript handles ESM output
+console.log("Build complete!");

package/scripts/clean.js

@@ -0,0 +1,6 @@
+import { rmSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const distDirectory = fileURLToPath(new URL("../dist", import.meta.url));
+
+rmSync(distDirectory, { recursive: true, force: true });

package/scripts/run-nitro.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Run Nitro after Vite build. Use in package.json: "build": "vite build && node node_modules/@farm.js/plugin/scripts/run-nitro.mjs"
+ * Resolves from project root (cwd) so dist/ and .output are in the right place.
+ */
+import path from "node:path";
+import { buildRscNitro } from "../dist/rsc/nitro-build.js";
+
+const root = process.cwd();
+const outDir = process.env.RSC_OUT_DIR || "dist";
+
+await buildRscNitro({
+  root,
+  rendererPath: path.join(root, outDir, "rsc", "index.js"),
+  publicDir: path.join(root, outDir, "client"),
+  ssrPath: path.join(root, outDir, "ssr", "index.js"),
+  preset: process.env.NITRO_PRESET || "vercel",
+});