@rangojs/router 0.14.0 → 0.15.0

package/README.md

@@ -207,7 +207,6 @@ stock lives in the database:
 import { createLoader } from "@rangojs/router";
 
 export const StockLoader = createLoader(async (ctx) => {
-  "use server";
   return db.stockFor(ctx.params.slug);
 });
 ```

package/dist/types/types/loader-types.d.ts

@@ -19,14 +19,12 @@ import type { RequestScope } from "./request-scope.js";
  * @example
  * ```typescript
  * const CartLoader = createLoader(async (ctx) => {
- *   "use server";
  *   const user = ctx.get("user");  // From auth middleware
  *   return await db.cart.get(user.id);
  * });
  *
  * // With typed params:
  * const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   "use server";
  *   const { slug } = ctx.params;  // slug is typed as string
  *   return await db.products.findBySlug(slug);
  * });
@@ -69,7 +67,6 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
      * @example
      * ```typescript
      * export const ProductLoader = createLoader(async (ctx) => {
-     *   "use server";
      *   const product = await getProduct(ctx.params.slug);
      *   ctx.use(Meta)({ title: product.name });
      *   ctx.use(Breadcrumbs)({ label: product.name });
@@ -95,7 +92,6 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
      * @example
      * ```typescript
      * const PricesLoader = createLoader(async (ctx) => {
-     *   "use server";
      *   await ctx.rendered();
      *   const products = ctx.get(Products); // reads handle data
      *   return pricing.getLive(products.map(p => p.id));
@@ -204,7 +200,8 @@ export type LoadOptions = {
  * Loader definition object
  *
  * Created via createLoader(). Contains the loader name and function.
- * On client builds, the fn is stripped by the bundler (via "use server" directive).
+ * On client builds, the fn is stripped by the router's loader transform; the
+ * definition must not carry a "use server" directive (the Vite plugin rejects it).
  *
  * @template T - The return type of the loader
  * @template TParams - Route params type (for type-safe params access)
@@ -213,13 +210,11 @@ export type LoadOptions = {
  * ```typescript
  * // Definition (same file works on server and client)
  * export const CartLoader = createLoader(async (ctx) => {
- *   "use server";
  *   return await db.cart.get(ctx.get("user").id);
  * });
  *
  * // With typed params:
  * export const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   "use server";
  *   const { slug } = ctx.params;  // slug is typed as string
  *   return await db.products.findBySlug(slug);
  * });

package/dist/types/vite/plugins/expose-ids/loader-transform.d.ts

@@ -6,3 +6,17 @@ export declare function generateClientLoaderStubs(bindings: CreateExportBinding[
     map?: undefined;
 } | null;
 export declare function transformLoaders(bindings: CreateExportBinding[], s: MagicString, filePath: string, isBuild: boolean): boolean;
+export interface LoaderServerDirective {
+    line: number;
+}
+/**
+ * Locate an inline `"use server"` directive at the top of a createLoader()
+ * callback body. Only top-level `const X = createLoader(...)` bindings (bare
+ * or exported) are checked — the same shapes the loader transform registers.
+ * Loaders are never client-callable, and the directive makes plugin-rsc
+ * hoist the body and `registerServerReference` it, so the loader body
+ * becomes a public action reachable with caller-supplied arguments (verified
+ * against a production build: a POST to `?_rsc_action=<id>` ran a loader body
+ * with a forged ctx). The guard plugin throws on the first hit.
+ */
+export declare function findLoaderServerDirective(code: string, fnNames: readonly string[], program: any): LoaderServerDirective | null;

package/dist/types/vite/plugins/expose-internal-ids.d.ts

@@ -11,6 +11,13 @@ export type { ExposeInternalIdsApi } from "./expose-ids/types.js";
  * validation rather than being hidden behind an opaque scan stub.
  */
 export declare function createLoaderScanStubPlugin(): Plugin;
+/**
+ * Refuse an inline `"use server"` directive inside a createLoader() callback.
+ * Runs `pre` so it sees the raw source before plugin-rsc's directive transform
+ * hoists the body into a registered server reference. See
+ * findLoaderServerDirective for why that registration is a problem.
+ */
+export declare function createLoaderDirectiveGuardPlugin(): Plugin;
 export declare function exposeInternalIds(options?: {
     forceBuild?: boolean;
 }): Plugin;

package/dist/vite/index.js

@@ -2242,6 +2242,7 @@ function buildUnsupportedShapeWarning(filePath, fnName, sites = []) {
 }
 
 // src/vite/plugins/expose-ids/loader-transform.ts
+import { hasDirective } from "@vitejs/plugin-rsc/transforms";
 function hasCreateLoaderImport(code) {
   return /import\s*\{[^}]*\bcreateLoader\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/.test(
     code
@@ -2276,6 +2277,27 @@ ${binding.localName}.$$id = "${loaderId}";`;
   }
   return hasChanges;
 }
+function loaderCallback(node, names) {
+  if (node?.type !== "CallExpression" || node.callee?.type !== "Identifier" || !names.has(node.callee.name)) {
+    return void 0;
+  }
+  const fn = node.arguments?.[0];
+  return (fn?.type === "ArrowFunctionExpression" || fn?.type === "FunctionExpression") && fn.body?.type === "BlockStatement" ? fn : void 0;
+}
+function findLoaderServerDirective(code, fnNames, program) {
+  const names = new Set(fnNames);
+  for (const statement of program.body ?? []) {
+    const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+    if (declaration?.type !== "VariableDeclaration") continue;
+    for (const declarator of declaration.declarations) {
+      const fn = loaderCallback(declarator.init, names);
+      if (fn && hasDirective(fn.body.body, "use server")) {
+        return { line: offsetToLineColumn(code, fn.body.body[0].start).line };
+      }
+    }
+  }
+  return null;
+}
 
 // src/vite/plugins/expose-ids/handler-transform.ts
 function transformHandles(bindings, s, filePath, isBuild) {
@@ -2499,6 +2521,33 @@ function createLoaderScanStubPlugin() {
     }
   };
 }
+function createLoaderDirectiveGuardPlugin() {
+  return {
+    name: "@rangojs/router:loader-directive-guard",
+    enforce: "pre",
+    transform(code, id) {
+      if (id.includes("/node_modules/") || !code.includes("use server") || !code.includes("createLoader") || !hasCreateLoaderImport(code)) {
+        return;
+      }
+      const cleanId = id.split("?", 1)[0];
+      let program;
+      try {
+        program = parseAst2(code, { lang: "tsx" });
+      } catch {
+        return;
+      }
+      const hit = findLoaderServerDirective(
+        code,
+        getImportedFnNames(code, "createLoader"),
+        program
+      );
+      if (!hit) return;
+      throw new Error(
+        `[rango] createLoader() body at ${cleanId}:${hit.line} carries a "use server" directive. Loader bodies already run only on the server; the directive would register the body as a client-callable server reference (reachable through the action endpoint with caller-supplied arguments). Remove the directive.`
+      );
+    }
+  };
+}
 function exposeInternalIds(options) {
   let config;
   let isBuild = false;
@@ -3037,7 +3086,7 @@ function useCacheTransform() {
           }
         }
         const {
-          hasDirective,
+          hasDirective: hasDirective2,
           transformWrapExport,
           transformHoistInlineDirective
         } = rscTransforms;
@@ -3051,7 +3100,7 @@ function useCacheTransform() {
         stripNullDirectiveFields(ast);
         const filePath = normalizePath(path5.relative(projectRoot, id));
         const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
-        if (hasDirective(ast.body, "use cache")) {
+        if (hasDirective2(ast.body, "use cache")) {
           return transformFileLevelUseCache(
             code,
             ast,
@@ -3060,7 +3109,7 @@ function useCacheTransform() {
             isBuild,
             isLayoutOrTemplate,
             transformWrapExport,
-            hasDirective
+            hasDirective2
           );
         }
         const functionResult = transformFunctionLevelUseCache(
@@ -3079,7 +3128,7 @@ function useCacheTransform() {
     }
   };
 }
-function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport, hasDirective) {
+function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport, hasDirective2) {
   const unconfirmedExports = [];
   const { exportNames, output } = transformWrapExport(code, ast, {
     runtime: (value, name) => {
@@ -3091,7 +3140,7 @@ function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLa
       if (name === "default" && isLayoutOrTemplate) return false;
       if (name.startsWith("$$hoist_")) return false;
       if (isHoistedServerReferenceRebind(meta.valueNode)) return false;
-      if (functionHasUseServerDirective(meta.valueNode, hasDirective)) {
+      if (functionHasUseServerDirective(meta.valueNode, hasDirective2)) {
         return false;
       }
       if (meta.isFunction !== true) {
@@ -3184,13 +3233,13 @@ function isHoistedServerReferenceRebind(valueNode) {
   const first = valueNode.arguments[0];
   return first !== void 0 && first.type === "Identifier" && first.name.startsWith("$$hoist_");
 }
-function functionHasUseServerDirective(valueNode, hasDirective) {
+function functionHasUseServerDirective(valueNode, hasDirective2) {
   if (!valueNode || !("body" in valueNode)) return false;
   const { body } = valueNode;
   if (!body || Array.isArray(body) || body.type !== "BlockStatement") {
     return false;
   }
-  return hasDirective(
+  return hasDirective2(
     body.body,
     "use server"
   );
@@ -3746,7 +3795,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.14.0",
+  version: "0.15.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -12304,6 +12353,7 @@ If this is a multi-app host router, export a createHostRouter() instance and set
       }
     }
   });
+  plugins.push(createLoaderDirectiveGuardPlugin());
   plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
   plugins.push(useCacheTransform());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/breadcrumbs/SKILL.md

@@ -67,7 +67,6 @@ consumption, `clientUrls()` groups) still build trails:
 
 ```typescript
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
   const product = await getProduct(ctx.params.slug);
 
   const pushCrumb = ctx.use(Breadcrumbs);

package/skills/client-urls/SKILL.md

@@ -54,9 +54,10 @@ Consequences you will hit:
   `path("/x", <HomePage />)` and not an inline arrow — the projection stores a
   component reference, and an anonymous value throws
   (`clientUrls() path() expects a named client component value`).
-- **Loaders must be `createLoader()` definitions** whose bodies are
-  `"use server"` — they execute on the server, addressed by id; the client
-  module only imports the definition object.
+- **Loaders must be `createLoader()` definitions.** They execute on the
+  server, addressed by id; the client module only imports the definition
+  object. Do NOT put a `"use server"` directive in the body — it is not
+  needed, and the build rejects it (see `/loader` → "Creating a Loader").
 - **Everything in the definition must be JSON-projectable.** That is why the
   unsupported helpers below are rejected rather than silently dropped.
 
@@ -230,7 +231,6 @@ is server code either way.
 
 ```ts
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
   const moved = LEGACY_SLUGS[ctx.params.slug];
   if (moved) throw redirect(`/shop/product/${moved}`);
   if (!(await exists(ctx.params.slug))) notFound(`No "${ctx.params.slug}"`);

package/skills/hooks/data.md

@@ -270,8 +270,6 @@ Server-side loader for the upload:
 import { createLoader } from "@rangojs/router";
 
 export const FileUploadLoader = createLoader(async (ctx) => {
-  "use server";
-
   const file = ctx.formData?.get("file") as File | null;
   if (file && file.size > 0) {
     // Process file (save to R2, D1, etc.)

package/skills/loader/SKILL.md

@@ -24,8 +24,6 @@ flow is _action mutates → loader re-reads → UI updates_.
 import { createLoader } from "@rangojs/router";
 
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
-
   const product = await ctx.env.DB.prepare(
     "SELECT * FROM products WHERE slug = ?",
   )
@@ -36,6 +34,15 @@ export const ProductLoader = createLoader(async (ctx) => {
 });
 ```
 
+Loader bodies already run only on the server — never add a `"use server"`
+directive inside the callback. `"use server"` means "expose this function to
+the client as a callable server reference", not "server only": the directive
+would hoist the body into a registered server reference that anyone can invoke
+through the action endpoint with caller-supplied arguments. The Vite plugin
+rejects it at transform time (`createLoader() body at <file>:<line> carries a
+"use server" directive`). For a build-time guarantee that a module never
+reaches the client graph, use `import "server-only"` instead.
+
 ### Supported export patterns
 
 All of the following are equivalent and fully supported by the Vite transform:
@@ -194,8 +201,6 @@ Loaders receive the same context shape as route handlers.
 
 ```typescript
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
-
   // URL params (may include client-provided overrides for fetchable loaders)
   const { slug } = ctx.params;
 
@@ -242,8 +247,6 @@ or resource scoping:
 
 ```typescript
 export const OrderLoader = createLoader(async (ctx) => {
-  "use server";
-
   // Use routeParams for auth checks — client cannot spoof the URL-matched ID
   const { orderId } = ctx.routeParams;
   const user = ctx.get("user");
@@ -674,7 +677,6 @@ signal instead of re-checking existence at each read site:
 import { createLoader, notFound, redirect } from "@rangojs/router";
 
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
   const moved = LEGACY_SLUGS[ctx.params.slug];
   if (moved) throw redirect(`/shop/product/${moved}`);
 
@@ -708,7 +710,6 @@ where the data lives:
 import { Meta, Breadcrumbs } from "./handles";
 
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
   const product = await getProduct(ctx.params.slug);
 
   ctx.use(Meta)({ title: `${product.name} — Shop` });
@@ -799,8 +800,6 @@ via `useFetchLoader()` and `load()`:
 import { createLoader } from "@rangojs/router";
 
 export const SearchLoader = createLoader(async (ctx) => {
-  "use server";
-
   const query = ctx.params.query ?? "";
   const results = await ctx.env.DB.prepare(
     "SELECT * FROM products WHERE name LIKE ?",
@@ -812,6 +811,13 @@ export const SearchLoader = createLoader(async (ctx) => {
 }, true); // true = fetchable
 ```
 
+`true` attaches an EMPTY middleware list, and the fetch lane never runs route
+`middleware()` (see `/middleware` → "Request flow"). A fetchable loader that
+reads a var set by route middleware (`ctx.get(CurrentUser)`) therefore sees
+`undefined` on `useFetchLoader()` / `load()` / `useRefreshLoaders()` unless it
+passes that middleware itself: `createLoader(fn, { middleware: [loadSession,
+requireAuth] })` (next section).
+
 > **No registration needed — and no worker-entry import.** A fetchable loader
 > does not have to be registered with `loader()` in the route DSL, and it does
 > not have to be imported by any server module. Importing it into the client
@@ -835,8 +841,6 @@ import { rateLimitMiddleware } from "../middleware/rate-limit";
 
 export const ProtectedLoader = createLoader(
   async (ctx) => {
-    "use server";
-
     const user = ctx.get("user");
     return { orders: await db.orders.list(user.id) };
   },
@@ -847,6 +851,12 @@ export const ProtectedLoader = createLoader(
 The middleware uses the same `MiddlewareFn` signature as route/app middleware,
 so you can reuse existing middleware functions directly.
 
+A `redirect()` thrown by per-loader middleware becomes a real 3xx on the fetch
+lane, so the browser's `fetch` follows it and `useFetchLoader()` receives the
+login page's HTML instead of loader data. Reserve redirects for document and
+navigation requests; on the fetch lane return a 401 (or a structured error
+payload) and let the caller decide.
+
 Fetchable loaders support both GET and POST (PUT, PATCH, DELETE) from the client.
 The `load()` function auto-detects the body type:
 
@@ -860,8 +870,6 @@ includes additional fields depending on the body type:
 
 ```typescript
 export const MutationLoader = createLoader(async (ctx) => {
-  "use server";
-
   // JSON body — available as ctx.body (parsed object)
   const data = ctx.body as { name: string; email: string };
 
@@ -883,8 +891,6 @@ export const MutationLoader = createLoader(async (ctx) => {
 import { createLoader } from "@rangojs/router";
 
 export const FileUploadLoader = createLoader(async (ctx) => {
-  "use server";
-
   const file = ctx.formData?.get("file") as File | null;
   if (file && file.size > 0) {
     // Save to R2, D1, etc.
@@ -911,8 +917,6 @@ Client usage — see `/hooks useFetchLoader` for the full client-side pattern.
 import { createLoader } from "@rangojs/router";
 
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
-
   const product = await ctx.env.DB
     .prepare("SELECT * FROM products WHERE slug = ?")
     .bind(ctx.params.slug)
@@ -926,8 +930,6 @@ export const ProductLoader = createLoader(async (ctx) => {
 });
 
 export const CartLoader = createLoader(async (ctx) => {
-  "use server";
-
   const user = ctx.get("user");
   if (!user) return { cart: null };
 

package/skills/middleware/SKILL.md

@@ -38,6 +38,9 @@ Request flow (with action):
 Request flow (no action):
   global mw -> route mw -> render pass
 
+Fetchable loader request (_rsc_loader: useFetchLoader / load / useRefreshLoaders):
+  global mw -> per-loader { middleware } list -> loader   (route mw does NOT run)
+
 Progressive enhancement (no-JS form POST):
   global mw -> action executes -> route mw -> full page re-render
 ```

package/skills/migrate-nextjs/SKILL.md

@@ -737,7 +737,6 @@ maps to a Meta push from the LOADER that owns the data, plus
 // Rango: push from the loader; the flag makes the document render await it,
 // so the title is in the SSR'd <head> like generateMetadata guarantees.
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
   const product = await getProduct(ctx.params.slug);
   ctx.use(Meta)({ title: product.name });
   return product;

package/skills/router-setup/SKILL.md

@@ -356,7 +356,6 @@ path("/product/:slug", async (ctx) => {
 
 // In a loader — data-dependent authority lives with the data
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
   if (!(await exists(ctx.params.slug))) notFound("Product not found");
   return getProduct(ctx.params.slug);
 });

package/skills/shell-manifest/SKILL.md

@@ -92,7 +92,6 @@ import { createLoader } from "@rangojs/router";
 import { RenderedProducts } from "../handles/rendered-products";
 
 export const PriceLoader = createLoader(async (ctx) => {
-  "use server";
   await ctx.rendered();
   const ids = ctx.get(RenderedProducts);
   return db.pricesFor(ids); // Map<string, number> keyed by product id

package/src/types/loader-types.ts

@@ -24,14 +24,12 @@ import type { RequestScope } from "./request-scope.js";
  * @example
  * ```typescript
  * const CartLoader = createLoader(async (ctx) => {
- *   "use server";
  *   const user = ctx.get("user");  // From auth middleware
  *   return await db.cart.get(user.id);
  * });
  *
  * // With typed params:
  * const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   "use server";
  *   const { slug } = ctx.params;  // slug is typed as string
  *   return await db.products.findBySlug(slug);
  * });
@@ -81,7 +79,6 @@ export type LoaderContext<
    * @example
    * ```typescript
    * export const ProductLoader = createLoader(async (ctx) => {
-   *   "use server";
    *   const product = await getProduct(ctx.params.slug);
    *   ctx.use(Meta)({ title: product.name });
    *   ctx.use(Breadcrumbs)({ label: product.name });
@@ -111,7 +108,6 @@ export type LoaderContext<
    * @example
    * ```typescript
    * const PricesLoader = createLoader(async (ctx) => {
-   *   "use server";
    *   await ctx.rendered();
    *   const products = ctx.get(Products); // reads handle data
    *   return pricing.getLive(products.map(p => p.id));
@@ -234,7 +230,8 @@ export type LoadOptions =
  * Loader definition object
  *
  * Created via createLoader(). Contains the loader name and function.
- * On client builds, the fn is stripped by the bundler (via "use server" directive).
+ * On client builds, the fn is stripped by the router's loader transform; the
+ * definition must not carry a "use server" directive (the Vite plugin rejects it).
  *
  * @template T - The return type of the loader
  * @template TParams - Route params type (for type-safe params access)
@@ -243,13 +240,11 @@ export type LoadOptions =
  * ```typescript
  * // Definition (same file works on server and client)
  * export const CartLoader = createLoader(async (ctx) => {
- *   "use server";
  *   return await db.cart.get(ctx.get("user").id);
  * });
  *
  * // With typed params:
  * export const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   "use server";
  *   const { slug } = ctx.params;  // slug is typed as string
  *   return await db.products.findBySlug(slug);
  * });

package/src/vite/plugins/expose-ids/loader-transform.ts

@@ -1,7 +1,8 @@
 import type MagicString from "magic-string";
 import { makeStubId } from "../expose-id-utils.js";
 import type { CreateExportBinding } from "./types.js";
-import { isExportOnlyFile } from "./export-analysis.js";
+import { hasDirective } from "@vitejs/plugin-rsc/transforms";
+import { isExportOnlyFile, offsetToLineColumn } from "./export-analysis.js";
 
 export function hasCreateLoaderImport(code: string): boolean {
   return /import\s*\{[^}]*\bcreateLoader\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/.test(
@@ -62,3 +63,55 @@ export function transformLoaders(
 
   return hasChanges;
 }
+
+export interface LoaderServerDirective {
+  line: number;
+}
+
+function loaderCallback(node: any, names: Set<string>): any {
+  if (
+    node?.type !== "CallExpression" ||
+    node.callee?.type !== "Identifier" ||
+    !names.has(node.callee.name)
+  ) {
+    return undefined;
+  }
+  const fn = node.arguments?.[0];
+  return (fn?.type === "ArrowFunctionExpression" ||
+    fn?.type === "FunctionExpression") &&
+    fn.body?.type === "BlockStatement"
+    ? fn
+    : undefined;
+}
+
+/**
+ * Locate an inline `"use server"` directive at the top of a createLoader()
+ * callback body. Only top-level `const X = createLoader(...)` bindings (bare
+ * or exported) are checked — the same shapes the loader transform registers.
+ * Loaders are never client-callable, and the directive makes plugin-rsc
+ * hoist the body and `registerServerReference` it, so the loader body
+ * becomes a public action reachable with caller-supplied arguments (verified
+ * against a production build: a POST to `?_rsc_action=<id>` ran a loader body
+ * with a forged ctx). The guard plugin throws on the first hit.
+ */
+export function findLoaderServerDirective(
+  code: string,
+  fnNames: readonly string[],
+  program: any,
+): LoaderServerDirective | null {
+  const names = new Set(fnNames);
+  for (const statement of program.body ?? []) {
+    const declaration =
+      statement.type === "ExportNamedDeclaration"
+        ? statement.declaration
+        : statement;
+    if (declaration?.type !== "VariableDeclaration") continue;
+    for (const declarator of declaration.declarations) {
+      const fn = loaderCallback(declarator.init, names);
+      if (fn && hasDirective(fn.body.body, "use server")) {
+        return { line: offsetToLineColumn(code, fn.body.body[0].start).line };
+      }
+    }
+  }
+  return null;
+}

package/src/vite/plugins/expose-internal-ids.ts

@@ -35,6 +35,7 @@ import {
   hasCreateLoaderImport,
   generateClientLoaderStubs,
   transformLoaders,
+  findLoaderServerDirective,
 } from "./expose-ids/loader-transform.js";
 import {
   transformHandles,
@@ -114,6 +115,51 @@ export function createLoaderScanStubPlugin(): Plugin {
   };
 }
 
+/**
+ * Refuse an inline `"use server"` directive inside a createLoader() callback.
+ * Runs `pre` so it sees the raw source before plugin-rsc's directive transform
+ * hoists the body into a registered server reference. See
+ * findLoaderServerDirective for why that registration is a problem.
+ */
+export function createLoaderDirectiveGuardPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:loader-directive-guard",
+    enforce: "pre",
+    transform(code, id) {
+      if (
+        id.includes("/node_modules/") ||
+        !code.includes("use server") ||
+        !code.includes("createLoader") ||
+        !hasCreateLoaderImport(code)
+      ) {
+        return;
+      }
+
+      const cleanId = id.split("?", 1)[0];
+      let program: any;
+      try {
+        program = parseAst(code, { lang: "tsx" });
+      } catch {
+        return;
+      }
+
+      const hit = findLoaderServerDirective(
+        code,
+        getImportedFnNames(code, "createLoader"),
+        program,
+      );
+      if (!hit) return;
+
+      throw new Error(
+        `[rango] createLoader() body at ${cleanId}:${hit.line} carries a "use server" directive. ` +
+          `Loader bodies already run only on the server; the directive would register the body as a ` +
+          `client-callable server reference (reachable through the action endpoint with caller-supplied ` +
+          `arguments). Remove the directive.`,
+      );
+    },
+  };
+}
+
 export function exposeInternalIds(options?: { forceBuild?: boolean }): Plugin {
   let config: ResolvedConfig;
   let isBuild = false;

package/src/vite/rango.ts

@@ -4,6 +4,7 @@ import { resolve } from "node:path";
 import { exposeActionId } from "./plugins/expose-action-id.js";
 import { defineEncryptionKeyExpr } from "./encryption-key.js";
 import {
+  createLoaderDirectiveGuardPlugin,
   createLoaderScanStubPlugin,
   exposeInternalIds,
   exposeRouterId,
@@ -561,6 +562,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     },
   });
 
+  plugins.push(createLoaderDirectiveGuardPlugin());
   plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
   plugins.push(useCacheTransform());