feat: support multiple staticDir entries

bartlomieju · claude · bartlomieju · commit 38d87eb8c6ec · 2026-04-08T19:35:56.000+02:00
Allow `staticDir` to accept an array of directories. When multiple directories are specified, they are searched in order and the first match wins. This is useful for separating generated assets from hand-authored static files. Closes #3105 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
diff --git a/packages/fresh/src/dev/builder.ts b/packages/fresh/src/dev/builder.ts
@@ -57,13 +57,15 @@ export interface BuildOptions {
    */
   outDir?: string;
   /**
-   * The directory to serve static files from.
+   * The directory (or directories) to serve static files from.
    *
-   * This can be an absolute path, a file URL or a relative path.
+   * Each entry can be an absolute path, a file URL or a relative path.
    * Relative paths are resolved against the `root` option.
+   * When multiple directories are specified, they are searched in order
+   * and the first match wins.
    * @default "static"
    */
-  staticDir?: string;
+  staticDir?: string | string[];
   /**
    * The directory which contains islands.
    *
@@ -103,11 +105,15 @@ export interface BuildOptions {
 /**
  * The final resolved Builder configuration.
  */
-export type ResolvedBuildConfig = Required<Omit<BuildOptions, "sourceMap">> & {
-  mode: "development" | "production";
-  buildId: string;
-  sourceMap?: FreshBundleOptions["sourceMap"];
-};
+export type ResolvedBuildConfig =
+  & Required<Omit<BuildOptions, "sourceMap" | "staticDir">>
+  & {
+    /** Always normalized to an array of absolute paths. */
+    staticDir: string[];
+    mode: "development" | "production";
+    buildId: string;
+    sourceMap?: FreshBundleOptions["sourceMap"];
+  };
 
 // deno-lint-ignore no-explicit-any
 export class Builder<State = any> {
@@ -122,7 +128,9 @@ export class Builder<State = any> {
     const root = parseDirPath(options?.root ?? ".", Deno.cwd());
     const serverEntry = parseDirPath(options?.serverEntry ?? "main.ts", root);
     const outDir = parseDirPath(options?.outDir ?? "_fresh", root);
-    const staticDir = parseDirPath(options?.staticDir ?? "static", root);
+    const rawStaticDir = options?.staticDir ?? "static";
+    const staticDir = (Array.isArray(rawStaticDir) ? rawStaticDir : [rawStaticDir])
+      .map((d) => parseDirPath(d, root));
     const islandDir = parseDirPath(options?.islandDir ?? "islands", root);
     const routeDir = parseDirPath(options?.routeDir ?? "routes", root);
 
diff --git a/packages/fresh/src/dev/builder_test.ts b/packages/fresh/src/dev/builder_test.ts
@@ -492,6 +492,106 @@ export const app = new App()
   },
 );
 
+integrationTest("Builder - multiple staticDir in dev", async () => {
+  const root = path.join(import.meta.dirname!, "..", "..");
+  await using _tmp = await withTmpDir({ dir: root, prefix: "tmp_builder_" });
+  const tmp = _tmp.dir;
+
+  const app = new App()
+    .use(staticFiles())
+    .get("/", () => new Response("no"));
+
+  await writeFiles(tmp, {
+    "static_a/a.txt": "from a",
+    "static_a/shared.txt": "from a",
+    "static_b/b.txt": "from b",
+    "static_b/shared.txt": "from b",
+  });
+
+  const builder = new Builder({
+    root: tmp,
+    staticDir: ["static_a", "static_b"],
+  });
+
+  const controller = new AbortController();
+  const waiter = Promise.withResolvers<void>();
+  await builder.listen(() => Promise.resolve<App<unknown>>(app), {
+    signal: controller.signal,
+    async onListen(addr) {
+      try {
+        const base = `http://localhost:${addr.port}`;
+
+        // File only in first dir
+        let res = await fetch(`${base}/a.txt`);
+        expect(await res.text()).toEqual("from a");
+
+        // File only in second dir
+        res = await fetch(`${base}/b.txt`);
+        expect(await res.text()).toEqual("from b");
+
+        // File in both dirs — first dir wins
+        res = await fetch(`${base}/shared.txt`);
+        expect(await res.text()).toEqual("from a");
+
+        // File in neither dir
+        res = await fetch(`${base}/missing.txt`);
+        expect(res.status).toEqual(404);
+
+        controller.abort();
+        waiter.resolve();
+      } catch (err) {
+        waiter.reject(err);
+      }
+    },
+  });
+
+  await waiter.promise;
+});
+
+integrationTest(
+  "Builder - multiple staticDir in prod",
+  async () => {
+    const root = path.join(import.meta.dirname!, "..", "..");
+    await using _tmp = await withTmpDir({
+      dir: root,
+      prefix: "tmp_builder_",
+    });
+    const tmp = _tmp.dir;
+
+    await writeFiles(tmp, {
+      "main.ts": `import { App, staticFiles } from "fresh";
+export const app = new App()
+  .use(staticFiles());`,
+      "static_a/a.txt": "from a",
+      "static_a/shared.txt": "from a",
+      "static_b/b.txt": "from b",
+      "static_b/shared.txt": "from b",
+    });
+
+    await new Builder({
+      root: tmp,
+      staticDir: ["static_a", "static_b"],
+    }).build();
+
+    await withChildProcessServer(
+      { cwd: tmp, args: ["serve", "-A", "--port=0", "_fresh/server.js"] },
+      async (address) => {
+        // File only in first dir
+        let res = await fetch(`${address}/a.txt`);
+        expect(await res.text()).toEqual("from a");
+
+        // File only in second dir
+        res = await fetch(`${address}/b.txt`);
+        expect(await res.text()).toEqual("from b");
+
+        // File in both dirs — first dir wins
+        res = await fetch(`${address}/shared.txt`);
+        expect(await res.text()).toEqual("from a");
+      },
+    );
+  },
+);
+
 integrationTest("Builder - custom server entry", async () => {
   const root = path.join(import.meta.dirname!, "..", "..");
   await using _tmp = await withTmpDir({ dir: root, prefix: "tmp_builder_" });
diff --git a/packages/fresh/src/dev/dev_build_cache.ts b/packages/fresh/src/dev/dev_build_cache.ts
@@ -130,50 +130,53 @@ export class MemoryBuildCache<State> implements DevBuildCache<State> {
       }
     }
 
-    let entry = pathname.startsWith("/") ? pathname.slice(1) : pathname;
-    entry = path.join(this.#config.staticDir, entry);
-    const relative = path.relative(this.#config.staticDir, entry);
-    if (relative.startsWith("..")) {
-      throw new Error(
-        `Processed file resolved outside of static dir ${entry}`,
+    const stripped = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+
+    for (const staticDir of this.#config.staticDir) {
+      const entry = path.join(staticDir, stripped);
+      const relative = path.relative(staticDir, entry);
+      if (relative.startsWith("..")) {
+        throw new Error(
+          `Processed file resolved outside of static dir ${entry}`,
+        );
+      }
+
+      // Might be a file that we still need to process
+      const transformed = await this.#transformer.process(
+        entry,
+        "development",
+        this.#config.target,
       );
-    }
 
-    // Might be a file that we still need to process
-    const transformed = await this.#transformer.process(
-      entry,
-      "development",
-      this.#config.target,
-    );
+      if (transformed !== null) {
+        for (let i = 0; i < transformed.length; i++) {
+          const file = transformed[i];
+          const rel = path.relative(staticDir, file.path);
+          if (rel.startsWith("..")) {
+            throw new Error(
+              `Processed file resolved outside of static dir ${file.path}`,
+            );
+          }
+          const filePn = new URL(rel, "http://localhost").pathname;
 
-    if (transformed !== null) {
-      for (let i = 0; i < transformed.length; i++) {
-        const file = transformed[i];
-        const relative = path.relative(this.#config.staticDir, file.path);
-        if (relative.startsWith("..")) {
-          throw new Error(
-            `Processed file resolved outside of static dir ${file.path}`,
-          );
+          this.addProcessedFile(filePn, file.content, null);
         }
-        const pathname = new URL(relative, "http://localhost").pathname;
-
-        this.addProcessedFile(pathname, file.content, null);
-      }
-      if (this.#processedFiles.has(pathname)) {
-        return this.readFile(pathname);
-      }
-    } else {
-      try {
-        const filePath = path.join(this.#config.staticDir, pathname);
-        const relative = path.relative(this.#config.staticDir, filePath);
-        if (!relative.startsWith("..") && (await Deno.stat(filePath)).isFile) {
-          const pathname = new URL(relative, "http://localhost").pathname;
-          this.addUnprocessedFile(pathname, this.#config.staticDir);
+        if (this.#processedFiles.has(pathname)) {
           return this.readFile(pathname);
         }
-      } catch (err) {
-        if (!(err instanceof Deno.errors.NotFound)) {
-          throw err;
+      } else {
+        try {
+          const filePath = path.join(staticDir, pathname);
+          const rel = path.relative(staticDir, filePath);
+          if (!rel.startsWith("..") && (await Deno.stat(filePath)).isFile) {
+            const filePn = new URL(rel, "http://localhost").pathname;
+            this.addUnprocessedFile(filePn, staticDir);
+            return this.readFile(filePn);
+          }
+        } catch (err) {
+          if (!(err instanceof Deno.errors.NotFound)) {
+            throw err;
+          }
         }
       }
     }
@@ -303,9 +306,13 @@ export class DiskBuildCache<State> implements DevBuildCache<State> {
   }
 
   async flush(): Promise<void> {
-    const { staticDir, outDir, target, root } = this.#config;
+    const { staticDir: staticDirs, outDir, target, root } = this.#config;
+
+    const seen = new Set<string>();
+
+    for (const staticDir of staticDirs) {
+      if (!(await fsAdapter.isDirectory(staticDir))) continue;
 
-    if (await fsAdapter.isDirectory(staticDir)) {
       const entries = fsAdapter.walk(staticDir, {
         includeDirs: false,
         includeFiles: true,
@@ -332,12 +339,18 @@ export class DiskBuildCache<State> implements DevBuildCache<State> {
             const file = result[i];
             assertInDir(file.path, staticDir);
             const pathname = `/${path.relative(staticDir, file.path)}`;
-            await this.addProcessedFile(pathname, file.content, null);
+            if (!seen.has(pathname)) {
+              seen.add(pathname);
+              await this.addProcessedFile(pathname, file.content, null);
+            }
           }
         } else {
           const relative = path.relative(staticDir, entry.path);
           const pathname = `/${relative}`;
-          this.addUnprocessedFile(pathname, staticDir);
+          if (!seen.has(pathname)) {
+            seen.add(pathname);
+            this.addUnprocessedFile(pathname, staticDir);
+          }
         }
       }
     }
diff --git a/packages/fresh/src/dev/dev_build_cache_test.ts b/packages/fresh/src/dev/dev_build_cache_test.ts
@@ -22,7 +22,7 @@ Deno.test({
       islandDir: "",
       outDir: "",
       routeDir: "",
-      staticDir: "",
+      staticDir: [""],
       target: "latest",
     };
     const fileTransformer = new FileTransformer(createFakeFs({}), tmp);
diff --git a/packages/plugin-tailwindcss-v3/src/mod.ts b/packages/plugin-tailwindcss-v3/src/mod.ts
@@ -106,7 +106,7 @@ async function initTailwind(
   config: ResolvedBuildConfig,
   options: TailwindPluginOptions,
 ): Promise<postcss.Processor> {
-  const root = path.dirname(config.staticDir);
+  const root = config.root;
 
   const configPath = await findTailwindConfigFile(root);
   const url = path.toFileUrl(configPath).href;
