uhyo · uhyo · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026
diff --git a/packages/docs/src/pages/api/FunstackStatic.mdx b/packages/docs/src/pages/api/FunstackStatic.mdx
@@ -226,6 +226,23 @@ Sentry.init({
 
 **Note:** Errors in the client init module will propagate normally and prevent the app from rendering.
 
+### rscPayloadDir (optional)
+
+**Type:** `string`
+**Default:** `"fun:rsc-payload"`
+
+Directory name used for RSC payload files in the build output. The final file paths follow the pattern `/funstack__/{rscPayloadDir}/{hash}.txt`.
+
+Change this if your hosting platform has issues with the default directory name. For example, Cloudflare Workers redirects URLs containing colons to percent-encoded equivalents, adding an extra round trip.
+
+```typescript
+funstackStatic({
+  root: "./src/root.tsx",
+  app: "./src/App.tsx",
+  rscPayloadDir: "fun-rsc-payload", // Avoid colons for Cloudflare Workers
+});
+```
+
 ## Full Example
 
 ### Single-Entry

diff --git a/packages/docs/src/pages/learn/HowItWorks.mdx b/packages/docs/src/pages/learn/HowItWorks.mdx
@@ -50,7 +50,7 @@ dist/public
 └── index.html
 ```
 
-The RSC payload files under `funstack__` are loaded by the client-side code to bootstrap the application with server-rendered content.
+The RSC payload files under `funstack__` are loaded by the client-side code to bootstrap the application with server-rendered content. The `fun:rsc-payload` directory name is [configurable](/api/funstack-static#rscpayloaddir-optional) via the `rscPayloadDir` option.
 
 This can been seen as an **optimized version of traditional client-only SPAs**, where the entire application is bundled into JavaScript files. By using RSC, some of the rendering work is offloaded to the build time, resulting in smaller JavaScript bundles combined with RSC payloads that require less client-side processing (parsing is easier, no JavaScript execution needed).
 

diff --git a/packages/static/e2e/tests/build.spec.ts b/packages/static/e2e/tests/build.spec.ts
@@ -20,7 +20,7 @@ test.describe("Build output verification", () => {
     expect(html).toContain("__FUNSTACK_APP_ENTRY__");
     // Verify the RSC payload is preloaded
     expect(html).toContain('rel="preload"');
-    expect(html).toContain("funstack__/fun:rsc-payload/");
+    expect(html).toContain("funstack__/");
   });
 
   test("generates RSC payload files at /funstack__/*.txt", async ({
@@ -31,9 +31,7 @@ test.describe("Build output verification", () => {
     const html = await indexResponse.text();
 
     // Look for the RSC payload in preload link or FUNSTACK config
-    const rscPayloadMatch = html.match(
-      /funstack__\/fun:rsc-payload\/[^"'\s]+\.txt/,
-    );
+    const rscPayloadMatch = html.match(/funstack__\/[^"'\s]+\.txt/);
     expect(rscPayloadMatch).not.toBeNull();
 
     const rscPayloadPath = "/" + rscPayloadMatch![0];

diff --git a/packages/static/e2e/tests/hydration.spec.ts b/packages/static/e2e/tests/hydration.spec.ts
@@ -62,7 +62,7 @@ test.describe("Client-side hydration", () => {
 
     page.on("request", (request) => {
       const url = request.url();
-      if (url.includes("funstack__/fun:rsc-payload/") && url.endsWith(".txt")) {
+      if (url.includes("funstack__/") && url.endsWith(".txt")) {
         rscRequests.push(url);
       }
     });

diff --git a/packages/static/e2e/tests/multi-entry.spec.ts b/packages/static/e2e/tests/multi-entry.spec.ts
@@ -11,7 +11,7 @@ test.describe("Multi-entry build output", () => {
     expect(html).toContain("<!DOCTYPE html>");
     expect(html).toContain("<html");
     expect(html).toContain("__FUNSTACK_APP_ENTRY__");
-    expect(html).toContain("funstack__/fun:rsc-payload/");
+    expect(html).toContain("funstack__/");
   });
 
   test("generates about.html with expected HTML structure", async ({
@@ -24,7 +24,7 @@ test.describe("Multi-entry build output", () => {
     expect(html).toContain("<!DOCTYPE html>");
     expect(html).toContain("<html");
     expect(html).toContain("__FUNSTACK_APP_ENTRY__");
-    expect(html).toContain("funstack__/fun:rsc-payload/");
+    expect(html).toContain("funstack__/");
   });
 
   test("each page has its own RSC payload", async ({ request }) => {
@@ -35,12 +35,8 @@ test.describe("Multi-entry build output", () => {
     const aboutHtml = await aboutResponse.text();
 
     // Both pages should reference RSC payloads
-    const homePayloadMatch = homeHtml.match(
-      /funstack__\/fun:rsc-payload\/[^"'\s]+\.txt/,
-    );
-    const aboutPayloadMatch = aboutHtml.match(
-      /funstack__\/fun:rsc-payload\/[^"'\s]+\.txt/,
-    );
+    const homePayloadMatch = homeHtml.match(/funstack__\/[^"'\s]+\.txt/);
+    const aboutPayloadMatch = aboutHtml.match(/funstack__\/[^"'\s]+\.txt/);
 
     expect(homePayloadMatch).not.toBeNull();
     expect(aboutPayloadMatch).not.toBeNull();

diff --git a/packages/static/src/build/buildApp.ts b/packages/static/src/build/buildApp.ts
@@ -13,6 +13,7 @@ import type { EntryBuildResult } from "../rsc/entry";
 export async function buildApp(
   builder: ViteBuilder,
   context: MinimalPluginContextWithoutEnvironment,
+  options: { rscPayloadDir: string },
 ) {
   const { config } = builder;
   // import server entry
@@ -50,12 +51,20 @@ export async function buildApp(
   const { components, idMapping } = await processRscComponents(
     deferRegistry.loadAll(),
     dummyStream,
+    options.rscPayloadDir,
     context,
   );
 
   // Write each entry's HTML and RSC payload
   for (const result of entries) {
-    await buildSingleEntry(result, idMapping, baseDir, base, context);
+    await buildSingleEntry(
+      result,
+      idMapping,
+      baseDir,
+      base,
+      options.rscPayloadDir,
+      context,
+    );
   }
 
   // Write all deferred component payloads
@@ -94,6 +103,7 @@ async function buildSingleEntry(
   idMapping: Map<string, string>,
   baseDir: string,
   base: string,
+  rscPayloadDir: string,
   context: MinimalPluginContextWithoutEnvironment,
 ) {
   const { path: entryPath, html, appRsc } = result;
@@ -109,8 +119,8 @@ async function buildSingleEntry(
   const mainPayloadHash = await computeContentHash(appRscContent);
   const mainPayloadPath =
     base === ""
-      ? getRscPayloadPath(mainPayloadHash)
-      : base + getRscPayloadPath(mainPayloadHash);
+      ? getRscPayloadPath(mainPayloadHash, rscPayloadDir)
+      : base + getRscPayloadPath(mainPayloadHash, rscPayloadDir);
 
   // Replace placeholder with final hashed path
   const finalHtmlContent = htmlContent.replaceAll(
@@ -127,7 +137,10 @@ async function buildSingleEntry(
 
   // Write RSC payload with hashed filename
   await writeFileNormal(
-    path.join(baseDir, getRscPayloadPath(mainPayloadHash).replace(/^\//, "")),
+    path.join(
+      baseDir,
+      getRscPayloadPath(mainPayloadHash, rscPayloadDir).replace(/^\//, ""),
+    ),
     appRscContent,
     context,
   );

diff --git a/packages/static/src/build/rscPath.ts b/packages/static/src/build/rscPath.ts
@@ -8,6 +8,9 @@ export const rscPayloadPlaceholder = "__FUNSTACK_RSC_PAYLOAD_PATH__";
 /**
  * Generate final path from content hash (reuses same folder as deferred payloads)
  */
-export function getRscPayloadPath(contentHash: string): string {
-  return getModulePathFor(getPayloadIDFor(contentHash));
+export function getRscPayloadPath(
+  contentHash: string,
+  rscPayloadDir: string,
+): string {
+  return getModulePathFor(getPayloadIDFor(contentHash, rscPayloadDir));
 }
diff --git a/packages/static/src/build/rscProcessor.ts b/packages/static/src/build/rscProcessor.ts
@@ -31,6 +31,7 @@ interface RawComponent {
 export async function processRscComponents(
   deferRegistryIterator: AsyncIterable<RawComponent>,
   appRscStream: ReadableStream,
+  rscPayloadDir: string,
   context?: { warn: (message: string) => void },
 ): Promise<ProcessResult> {
   // Step 1: Collect all components from deferRegistry
@@ -95,7 +96,7 @@ export async function processRscComponents(
 
     // Compute content hash for this component
     const contentHash = await computeContentHash(content);
-    const finalId = getPayloadIDFor(contentHash);
+    const finalId = getPayloadIDFor(contentHash, rscPayloadDir);
 
     // Create mapping
     idMapping.set(tempId, finalId);

diff --git a/packages/static/src/plugin/index.ts b/packages/static/src/plugin/index.ts
@@ -3,6 +3,7 @@ import type { Plugin } from "vite";
 import rsc from "@vitejs/plugin-rsc";
 import { buildApp } from "../build/buildApp";
 import { serverPlugin } from "./server";
+import { defaultRscPayloadDir } from "../rsc/rscModule";
 
 interface FunstackStaticBaseOptions {
   /**
@@ -25,6 +26,16 @@ interface FunstackStaticBaseOptions {
    * The module is imported for its side effects only (no exports needed).
    */
   clientInit?: string;
+  /**
+   * Directory name used for RSC payload files in the build output.
+   * The final path will be `/funstack__/{rscPayloadDir}/{hash}.txt`.
+   *
+   * Change this if your hosting platform has issues with the default
+   * directory name (e.g. Cloudflare Workers redirects URLs containing colons).
+   *
+   * @default "fun:rsc-payload"
+   */
+  rscPayloadDir?: string;
 }
 
 interface SingleEntryOptions {
@@ -58,7 +69,12 @@ export type FunstackStaticOptions = FunstackStaticBaseOptions &
 export default function funstackStatic(
   options: FunstackStaticOptions,
 ): (Plugin | Plugin[])[] {
-  const { publicOutDir = "dist/public", ssr = false, clientInit } = options;
+  const {
+    publicOutDir = "dist/public",
+    ssr = false,
+    clientInit,
+    rscPayloadDir = defaultRscPayloadDir,
+  } = options;
 
   let resolvedEntriesModule: string = "__uninitialized__";
   let resolvedClientInitEntry: string | undefined;
@@ -166,7 +182,10 @@ export default function funstackStatic(
           ].join("\n");
         }
         if (id === "\0virtual:funstack/config") {
-          return `export const ssr = ${JSON.stringify(ssr)};`;
+          return [
+            `export const ssr = ${JSON.stringify(ssr)};`,
+            `export const rscPayloadDir = ${JSON.stringify(rscPayloadDir)};`,
+          ].join("\n");
         }
         if (id === "\0virtual:funstack/client-init") {
           if (resolvedClientInitEntry) {
@@ -179,7 +198,7 @@ export default function funstackStatic(
     {
       name: "@funstack/static:build",
       async buildApp(builder) {
-        await buildApp(builder, this);
+        await buildApp(builder, this, { rscPayloadDir });
       },
     },
   ];

diff --git a/packages/static/src/rsc/defer.tsx b/packages/static/src/rsc/defer.tsx
@@ -3,6 +3,7 @@ import { renderToReadableStream } from "@vitejs/plugin-rsc/react/rsc";
 import { DeferredComponent } from "#rsc-client";
 import { drainStream } from "../util/drainStream";
 import { getPayloadIDFor } from "./rscModule";
+import { rscPayloadDir } from "virtual:funstack/config";
 
 export interface DeferEntry {
   state: DeferEntryState;
@@ -184,7 +185,7 @@ export function defer(
   const rawId = sanitizedName
     ? `${sanitizedName}-${crypto.randomUUID()}`
     : crypto.randomUUID();
-  const id = getPayloadIDFor(rawId);
+  const id = getPayloadIDFor(rawId, rscPayloadDir);
   deferRegistry.register(element, id, name);
 
   return <DeferredComponent moduleID={id} />;

diff --git a/packages/static/src/rsc/rscModule.ts b/packages/static/src/rsc/rscModule.ts
@@ -1,14 +1,17 @@
 /**
- * ID is prefixed with this string to form module path.
+ * Default directory name for RSC payload files.
  */
-const rscPayloadIDPrefix = "fun:rsc-payload/";
+export const defaultRscPayloadDir = "fun:rsc-payload";
 
 /**
  * Add prefix to raw ID to form payload ID so that the ID is
  * distinguishable from other possible IDs.
  */
-export function getPayloadIDFor(rawId: string): string {
-  return `${rscPayloadIDPrefix}${rawId}`;
+export function getPayloadIDFor(
+  rawId: string,
+  rscPayloadDir: string = defaultRscPayloadDir,
+): string {
+  return `${rscPayloadDir}/${rawId}`;
 }
 
 const rscModulePathPrefix = "/funstack__/";

diff --git a/packages/static/src/virtual.d.ts b/packages/static/src/virtual.d.ts
@@ -5,5 +5,6 @@ declare module "virtual:funstack/entries" {
 }
 declare module "virtual:funstack/config" {
   export const ssr: boolean;
+  export const rscPayloadDir: string;
 }
 declare module "virtual:funstack/client-init" {}