@ivogt/rsc-router 0.0.0-experimental.6 → 0.0.0-experimental.8

package/dist/expose-action-id.d.ts

@@ -0,0 +1,18 @@
+import type { Plugin } from "vite";
+/**
+ * Vite plugin that exposes action IDs on server reference functions.
+ *
+ * When React Server Components creates server references via createServerReference(),
+ * the action ID (format: "hash#actionName") is passed as the first argument but not
+ * exposed on the returned function. This plugin transforms the output to attach
+ * the $id property to each server reference function, enabling the router to
+ * identify which action was called during revalidation.
+ *
+ * Server bundles (RSC/SSR) get file paths in $id for filtering (e.g., "src/actions.ts#add").
+ * Client bundles keep hashed IDs for security (e.g., "ec387bc704d4#add").
+ *
+ * Works in:
+ * - Build mode: uses renderChunk to transform bundled chunks
+ * - Dev mode: uses transform with enforce:"post" to transform after RSC plugin
+ */
+export declare function exposeActionId(): Plugin;

package/dist/expose-handle-id.d.ts

@@ -0,0 +1,19 @@
+import type { Plugin } from "vite";
+/**
+ * Vite plugin that exposes $$id on createHandle calls.
+ *
+ * When users create handles with createHandle(), this plugin:
+ * 1. Injects a $$id as the last parameter (used as the handle name)
+ * 2. Sets $$id property on the exported constant for external access
+ *
+ * This allows handles to be created without explicit names:
+ * - Before: export const Breadcrumbs = createHandle<Item>("breadcrumbs")
+ * - After:  export const Breadcrumbs = createHandle<Item>()
+ *
+ * The name is auto-generated from file path + export name.
+ *
+ * Requirements:
+ * - Must use direct import: import { createHandle } from "rsc-router"
+ * - Must use named export: export const MyHandle = createHandle(...)
+ */
+export declare function exposeHandleId(): Plugin;

package/dist/expose-loader-id.d.ts

@@ -0,0 +1,16 @@
+import type { Plugin } from "vite";
+/**
+ * Vite plugin that exposes $$id on createLoader calls and generates a loader manifest.
+ *
+ * When users create loaders with createLoader(), this plugin:
+ * 1. Injects a $$id property containing the file path and export name
+ * 2. Tracks all loaders and generates a virtual manifest module
+ *
+ * The manifest can be imported by the RSC handler to get all loaders.
+ *
+ * Requirements:
+ * - Must use direct import: import { createLoader } from "rsc-router"
+ * - No aliasing support (import { createLoader as cl } won't work)
+ * - Must use named export: export const MyLoader = createLoader(...)
+ */
+export declare function exposeLoaderId(): Plugin;

package/dist/expose-location-state-id.d.ts

@@ -0,0 +1,19 @@
+import type { Plugin } from "vite";
+/**
+ * Vite plugin that exposes location state keys on createLocationState calls.
+ *
+ * When users create location states with createLocationState(), this plugin:
+ * 1. Injects an auto-generated key as the first parameter
+ * 2. Sets __rsc_ls_key property for verification
+ *
+ * This allows location states to be created without explicit keys:
+ * - Before: export const ProductState = createLocationState<Product>("product")
+ * - After:  export const ProductState = createLocationState<Product>()
+ *
+ * The key is auto-generated from file path + export name.
+ *
+ * Requirements:
+ * - Must use direct import: import { createLocationState } from "rsc-router"
+ * - Must use named export: export const MyState = createLocationState(...)
+ */
+export declare function exposeLocationStateId(): Plugin;

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import type { PluginOption } from "vite";
+export { exposeActionId } from "./expose-action-id.ts";
+export { exposeLoaderId } from "./expose-loader-id.ts";
+export { exposeHandleId } from "./expose-handle-id.ts";
+export { exposeLocationStateId } from "./expose-location-state-id.ts";
+/**
+ * RSC plugin entry points configuration.
+ * All entries use virtual modules by default. Specify a path to use a custom entry file.
+ */
+export interface RscEntries {
+    /**
+     * Path to a custom browser/client entry file.
+     * If not specified, a default virtual entry is used.
+     */
+    client?: string;
+    /**
+     * Path to a custom SSR entry file.
+     * If not specified, a default virtual entry is used.
+     */
+    ssr?: string;
+    /**
+     * Path to a custom RSC entry file.
+     * If not specified, a default virtual entry is used that imports the router from the `entry` option.
+     */
+    rsc?: string;
+}
+/**
+ * Options for @vitejs/plugin-rsc integration
+ */
+export interface RscPluginOptions {
+    /**
+     * Entry points for client, ssr, and rsc environments.
+     * All entries use virtual modules by default.
+     * Specify paths only when you need custom entry files.
+     */
+    entries?: RscEntries;
+}
+/**
+ * Base options shared by all presets
+ */
+interface RscRouterBaseOptions {
+    /**
+     * Expose $$id property on server action functions.
+     * Required for action-based revalidation to work.
+     * @default true
+     */
+    exposeActionId?: boolean;
+}
+/**
+ * Options for Node.js deployment (default)
+ */
+export interface RscRouterNodeOptions extends RscRouterBaseOptions {
+    /**
+     * Deployment preset. Defaults to 'node' when not specified.
+     */
+    preset?: "node";
+    /**
+     * Path to your router configuration file that exports the route tree.
+     * This file must export a `router` object created with `createRouter()`.
+     *
+     * @example
+     * ```ts
+     * rscRouter({ router: './src/router.tsx' })
+     * ```
+     */
+    router: string;
+    /**
+     * RSC plugin configuration. By default, rsc-router includes @vitejs/plugin-rsc
+     * with sensible defaults.
+     *
+     * Entry files (browser, ssr, rsc) are optional - if they don't exist,
+     * virtual defaults are used.
+     *
+     * - Omit or pass `true`/`{}` to use defaults (recommended)
+     * - Pass `{ entries: {...} }` to customize entry paths
+     * - Pass `false` to disable (for manual @vitejs/plugin-rsc configuration)
+     *
+     * @default true
+     */
+    rsc?: boolean | RscPluginOptions;
+}
+/**
+ * Options for Cloudflare Workers deployment
+ */
+export interface RscRouterCloudflareOptions extends RscRouterBaseOptions {
+    /**
+     * Deployment preset for Cloudflare Workers.
+     * When using cloudflare preset:
+     * - @vitejs/plugin-rsc is NOT added (cloudflare plugin adds it)
+     * - Your worker entry (e.g., worker.rsc.tsx) imports the router directly
+     * - Browser and SSR use virtual entries
+     */
+    preset: "cloudflare";
+}
+/**
+ * Options for rscRouter plugin
+ */
+export type RscRouterOptions = RscRouterNodeOptions | RscRouterCloudflareOptions;
+/**
+ * Vite plugin for rsc-router.
+ *
+ * Includes @vitejs/plugin-rsc and all necessary transforms for the router
+ * to function correctly with React Server Components.
+ *
+ * @example Node.js (default)
+ * ```ts
+ * export default defineConfig({
+ *   plugins: [react(), rscRouter({ router: './src/router.tsx' })],
+ * });
+ * ```
+ *
+ * @example Cloudflare Workers
+ * ```ts
+ * export default defineConfig({
+ *   plugins: [
+ *     react(),
+ *     rscRouter({ preset: 'cloudflare' }),
+ *     cloudflare({ viteEnvironment: { name: 'rsc' } }),
+ *   ],
+ * });
+ * ```
+ */
+export declare function rscRouter(options: RscRouterOptions): Promise<PluginOption[]>;

package/dist/package-resolution.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Package Resolution Utilities
+ *
+ * Handles detection of workspace vs npm install context and generates
+ * appropriate aliases and exclude lists for Vite configuration.
+ */
+/**
+ * Get the published package name (e.g., "@ivogt/rsc-router")
+ */
+export declare function getPublishedPackageName(): string;
+/**
+ * Check if the package is installed from npm (scoped) vs workspace (unscoped)
+ *
+ * In workspace development:
+ * - Package is installed as "rsc-router" via pnpm workspace alias
+ * - The scoped name (@ivogt/rsc-router) doesn't exist in node_modules
+ *
+ * When installed from npm:
+ * - Package is installed as "@ivogt/rsc-router"
+ * - We need aliases to map "rsc-router/*" to "@ivogt/rsc-router/*"
+ */
+export declare function isInstalledFromNpm(): boolean;
+/**
+ * Check if we're in a monorepo/workspace development context
+ */
+export declare function isWorkspaceDevelopment(): boolean;
+/**
+ * Generate the list of modules to exclude from Vite's dependency optimization.
+ *
+ * We include both the published name and the virtual name because
+ * Vite's optimizer runs before alias resolution.
+ */
+export declare function getExcludeDeps(): string[];
+/**
+ * Generate aliases to map virtual package paths to the actual published package.
+ *
+ * Only needed when installed from npm, where the package is under @ivogt/rsc-router
+ * but virtual entries import from rsc-router/*.
+ *
+ * Returns empty object in workspace development where rsc-router resolves directly.
+ */
+export declare function getPackageAliases(): Record<string, string>;

package/dist/virtual-entries.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Default virtual entry file contents for rsc-router.
+ * These are used when users don't provide their own entry files.
+ */
+export declare const VIRTUAL_ENTRY_BROWSER: string;
+export declare const VIRTUAL_ENTRY_SSR: string;
+/**
+ * Generate the RSC entry content with the specified router path
+ */
+export declare function getVirtualEntryRSC(routerPath: string): string;
+/**
+ * Virtual module IDs
+ */
+export declare const VIRTUAL_IDS: {
+    readonly browser: "virtual:rsc-router/entry.browser.js";
+    readonly ssr: "virtual:rsc-router/entry.ssr.js";
+    readonly rsc: "virtual:rsc-router/entry.rsc.js";
+    readonly version: "rsc-router:version";
+};
+/**
+ * Virtual module content for version.
+ * Exports VERSION - a timestamp that changes on server restart (dev) or at build time (production).
+ */
+export declare function getVirtualVersionContent(version: string): string;