Merge branch 'main' into v2.3.0

Author: bartlomieju

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
 
   test:
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 10
+    timeout-minutes: 15
 
     strategy:
       fail-fast: false
@@ -39,7 +39,7 @@ jobs:
 
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Deno
         uses: denoland/setup-deno@v2

.github/workflows/post_publish.yml

@@ -11,18 +11,18 @@ jobs:
     if: github.repository == 'denoland/fresh'
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Authenticate with Google Cloud
-        uses: google-github-actions/auth@v2
+        uses: google-github-actions/auth@v3
         with:
           project_id: denoland
           credentials_json: ${{ secrets.GCP_SA_KEY }}
           export_environment_variables: true
           create_credentials_file: true
 
       - name: Setup gcloud
-        uses: google-github-actions/setup-gcloud@v2
+        uses: google-github-actions/setup-gcloud@v3
         with:
           project_id: denoland
 

.github/workflows/publish.yml

@@ -16,7 +16,7 @@ jobs:
     if: github.repository_owner == 'denoland'
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install Deno
         uses: denoland/setup-deno@v2

docs/latest/advanced/builder.md

@@ -40,8 +40,10 @@ const builder = new Builder({
   // Where to write generated files when doing a production build.
   // (default: `<root>/_fresh/`)
   outDir?: string;
-  // Path to static file directory. (Default: `<root>/static/`)
-  staticDir?: string;
+  // Path to static file directory, or an array of directories.
+  // When multiple directories are specified they are searched in order
+  // and the first match wins. (Default: `<root>/static/`)
+  staticDir?: string | string[];
   // Path to island directory. (Default: `<root>/islands`)
   islandDir?: string;
   // Path to routes directory. (Default: `<root>/routes`)
@@ -93,8 +95,23 @@ builder.onTransformStaticFile({
 });
 ```
 
-> [info]: Only static files in `static/` or the value you set `staticDir` to
-> will be processed. The builder won't process anything else.
+> [info]: Only static files in `static/` or the directories you set `staticDir`
+> to will be processed. The builder won't process anything else.
+
+### Multiple static directories
+
+You can pass an array to `staticDir` to serve files from multiple directories.
+When the same filename exists in more than one directory, the first directory in
+the array takes precedence.
+
+```ts dev.ts
+const builder = new Builder({
+  staticDir: ["static", "generated"],
+});
+```
+
+This is useful when you have a build step that generates assets into a separate
+directory and you want to keep them apart from hand-authored static files.
 
 ## Testing
 

docs/latest/advanced/partials.md

@@ -208,6 +208,66 @@ Partial updates can be animated using the browser's
 alongside `f-client-nav` to enable smooth animated transitions between pages
 with zero JavaScript animation code.
 
+## Loading indicators
+
+When a partial request is in flight, you may want to show a loading spinner or
+disable a button. Fresh supports this through the `_freshIndicator` property.
+
+Attach an object with a `value` property to any element that triggers a partial
+navigation. Fresh will set `value` to `true` when the request starts and back to
+`false` when it completes (or fails).
+
+```tsx
+import { useSignal } from "@preact/signals";
+
+function NavLink() {
+  const loading = useSignal(false);
+
+  return (
+    <a
+      href="/next-page"
+      f-partial="/partials/next-page"
+      ref={(el) => {
+        if (el) el._freshIndicator = loading;
+      }}
+    >
+      {loading.value ? "Loading..." : "Go"}
+    </a>
+  );
+}
+```
+
+This works for links, forms, and submit buttons. For form submissions, Fresh
+checks the submitter element (e.g. the clicked button) first, then falls back to
+the form element itself. This lets you show per-button indicators when a form
+has multiple submit buttons.
+
+```tsx
+import { useSignal } from "@preact/signals";
+
+function MyForm() {
+  const saving = useSignal(false);
+
+  return (
+    <form action="/save" f-partial="/partials/save">
+      {/* indicator is on the button, not the form */}
+      <button
+        type="submit"
+        ref={(el) => {
+          if (el) el._freshIndicator = saving;
+        }}
+      >
+        {saving.value ? "Saving..." : "Save"}
+      </button>
+    </form>
+  );
+}
+```
+
+> [info]: Any object with a mutable `value` property works — Preact signals are
+> the most convenient choice because they automatically re-render the component
+> when the value changes.
+
 ## Bypassing or disabling Partials
 
 If you want to exempt a particular element from triggering a partial request

docs/latest/advanced/vite.md

@@ -27,6 +27,10 @@ export default defineConfig({
       islandsDir: "./islands",
       // Path to routes directory. Default: ./routes
       routeDir: "./routes",
+      // Static file directory or directories. Default: "static"
+      // When multiple directories are given, they are searched in
+      // order and the first match wins.
+      staticDir: ["static", "generated"],
       // Optional regex to ignore folders when crawling the routes and
       // island directory.
       ignore: [/[\\/]+some-folder[\\/]+/],

docs/latest/concepts/app.md

@@ -37,6 +37,23 @@ With `basePath: "/my-app"`, a route registered at `/about` will respond to
 mounted alongside other apps. The base path is available in handlers via
 `ctx.config.basePath`.
 
+### Reverse proxy support
+
+When running behind a reverse proxy (nginx, Caddy, etc.), set `trustProxy` to
+make `ctx.url` reflect the client-facing URL instead of the internal one:
+
+```ts
+const app = new App({ trustProxy: true });
+```
+
+With this enabled, Fresh reads `X-Forwarded-Proto` and `X-Forwarded-Host`
+headers and rewrites `ctx.url` accordingly. For example, if your proxy
+terminates TLS and forwards `X-Forwarded-Proto: https`, `ctx.url.protocol` will
+be `https:` instead of `http:`.
+
+> [warn]: Only enable `trustProxy` when your app is actually behind a trusted
+> reverse proxy. Untrusted clients could otherwise spoof these headers.
+
 All items are applied from top to bottom. This means that when you defined a
 middleware _after_ a `.get()` handler, it won't be included.
 

docs/latest/concepts/architecture.md

@@ -9,91 +9,7 @@ browser. This page explains how a request flows through the framework.
 
 ## Request lifecycle
 
-<div style="max-width:620px;font-family:system-ui,-apple-system,sans-serif;font-size:14px;color:#1a1a1a;">
-  <style>
-    .flow-step{display:flex;align-items:flex-start;gap:16px}
-    .flow-box{flex-shrink:0;width:200px;padding:10px 14px;border:1.5px solid #333;border-radius:6px;background:#f8f9fa;text-align:center}
-    .flow-box strong{display:block;font-size:14px}
-    .flow-box small{font-size:11px;color:#777}
-    .flow-box.accent{background:#eef6ff}
-    .flow-box.green{background:#f0faf0}
-    .flow-desc{padding-top:10px;font-size:12.5px;color:#555;line-height:1.5}
-    .flow-arrow{text-align:center;width:200px;color:#666;font-size:18px;line-height:1;padding:4px 0}
-    .flow-arrow-label{text-align:center;width:200px;padding:2px 0}
-    .flow-arrow-label em{font-size:11px;color:#777}
-    .flow-divider{margin:12px 0 8px;padding-top:8px;border-top:1px dashed #e0e0e0;font-size:11px;color:#999;font-weight:600;letter-spacing:0.5px;text-transform:uppercase}
-  </style>
-  <!-- Browser Request -->
-  <div class="flow-step">
-    <div class="flow-box accent"><strong>Browser Request</strong></div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Static Files -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Static Files</strong></div>
-    <div class="flow-desc">Serve file directly if path matches a static asset</div>
-  </div>
-  <div class="flow-arrow-label"><em>no match</em></div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Global Middleware -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Global Middleware</strong><small>runs in registration order</small></div>
-    <div class="flow-desc">Can modify request/response, set state, or short&#8209;circuit with a Response</div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Router -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Router</strong></div>
-    <div class="flow-desc">Match URL pattern + HTTP method. Static routes checked first, then dynamic.</div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Scoped Middleware -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Scoped Middleware</strong></div>
-    <div class="flow-desc">Middleware that only runs for matching path prefixes (e.g. /admin/*). Used for auth, logging, or other route&#8209;specific logic.</div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Handler -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Handler</strong></div>
-    <div class="flow-desc">API route? Return Response directly (JSON, redirect, etc.)</div>
-  </div>
-  <div class="flow-arrow-label"><em>has component</em></div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Rendering section -->
-  <div class="flow-divider">Rendering</div>
-  <!-- App Wrapper -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>App Wrapper</strong></div>
-    <div class="flow-desc">Outer &lt;html&gt;/&lt;head&gt;/&lt;body&gt; structure</div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Layouts -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Layouts</strong></div>
-    <div class="flow-desc">Nested layout components (inherited from parent directories)</div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Page Component -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Page Component</strong></div>
-    <div class="flow-desc">Route component receives props.data from handler</div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- HTML Response -->
-  <div class="flow-step">
-    <div class="flow-box accent"><strong>HTML + JS Response</strong><small>sent to browser</small></div>
-    <div class="flow-desc">Server&#8209;rendered HTML with island props <a href="/docs/advanced/serialization">serialized</a> inline</div>
-  </div>
-  <!-- Client section -->
-  <div class="flow-divider">Client (Browser)</div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Hydration -->
-  <div class="flow-step">
-    <div class="flow-box green"><strong>Island Hydration</strong><small>only islands receive JS</small></div>
-    <div class="flow-desc">Rest of the page stays static HTML. No JavaScript for non&#8209;island components.</div>
-  </div>
-</div>
+![Request lifecycle flow diagram](/docs/architecture-flow-v2.svg)
 
 ## Key concepts
 

docs/latest/concepts/static-files.md

@@ -47,6 +47,31 @@ pipeline, optimizes it, and adds a content hash to the filename for cache
 busting. Keeping these files outside `static/` ensures they're only included
 once in your build output.
 
+## Multiple static directories
+
+You can serve files from more than one directory by passing an array to the
+`staticDir` option. When the same filename exists in multiple directories, the
+first directory in the array takes precedence.
+
+```ts vite.config.ts
+import { defineConfig } from "vite";
+import { fresh } from "@fresh/plugin-vite";
+
+export default defineConfig({
+  plugins: [
+    fresh({
+      staticDir: ["static", "generated"],
+    }),
+  ],
+});
+```
+
+This is useful when you have a build step that generates assets into a separate
+directory and you want to keep them apart from hand-authored static files.
+
+> [info]: If you're using the [Builder](/docs/advanced/builder) API instead of
+> Vite, the same `staticDir` option accepts a string or an array of strings.
+
 ## Caching headers
 
 By default, Fresh adds caching headers for the `src` and `srcset` attributes on

docs/latest/examples/active-links.md

@@ -10,10 +10,27 @@ current page within a set of pages.
 
 - `aria-current="page"` - Added to links with an exact path match, enhancing
   accessibility by indicating the current page to assistive technologies.
+- `aria-current="true"` - Added to ancestor links (e.g. `/docs` when the current
+  page is `/docs/intro`).
 
 As we aim to improve accessibility, we encourage the use of aria-current for
 styling current links where applicable.
 
+### Query parameters
+
+When a link's `href` includes query parameters, Fresh considers them during
+matching. A link to `/products?sort=name` will only receive
+`aria-current="page"` when the current URL also has `?sort=name`. If the query
+parameters differ, the link is treated as an ancestor instead. Links without
+query parameters in their `href` match regardless of the current URL's query
+string.
+
+### Preserving custom `aria-current`
+
+If you set `aria-current` on an `<a>` element yourself, Fresh will leave it
+untouched. This is useful when integrating with component libraries (e.g.
+daisyUI tabs) that manage their own active state.
+
 ## Styling with CSS
 
 The aria-current attribute is easily styled with CSS using attribute selectors,