@jk2908/solas 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.5.0 - 2026-06-06
+
+- Added runtime selection via `runtime: 'auto' | 'node' | 'bun'`, with `auto` choosing Bun when available and falling back to Node otherwise.
+- Removed the default Bun runtime requirement from the documented workflow. Standard `vite dev`, `vite build`, and `vite preview` commands now work on the default Node path, while Bun-backed Vite commands remain available when you want to run Solas in Bun.
+- Added a dedicated `@jk2908/solas/$` runtime-safe export for generated/runtime code so preview and production server bundles no longer need to pull through the package root plugin entry.
+- Fixed prerender static param resolution to stop depending on host support for `Promise.try`, so build-time route processing now works correctly under Node-based Vite runs.
+
+## 0.4.5 - 2026-05-29
+
+- Documented concrete `href` and `router.go(...)` usage in the README, including how explicit `query` values merge with an existing query string and take precedence for duplicate keys.
+- Clarified in the README that `router.go(...)` and `router.refresh()` are awaitable, and that `router.refresh()` always refreshes the current browser location at call time.
+- Fixed browser-router typing so `refresh` is exposed as a promise-returning method, matching the runtime implementation.
+
+## 0.4.4 - 2026-05-29
+
+- Added `router.refresh()` to the browser router, and made it clear that it clears the current route cache before fetching a fresh RSC payload.
+- Reworked browser-router response caching so prefetched RSC responses can be reused by later navigations without a second fetch.
+- Documented client routing and generated route typing in the README, including `useRouter()`, `router.go()`, `router.prefetch()`, `router.refresh()`, `Link` prefetch behaviour, and typed `Route.Metadata`/`Route.StaticParams` usage.
+- Added a refresh demo route to the basic example app for manual regression testing.
+
 ## 0.4.3 - 2026-05-27
 
 - Updated README docs to show that `dynamic()` must be awaited in request-time deferred `ppr` usage examples.

package/README.md

@@ -4,8 +4,6 @@ Solas is a minimal React meta-framework powered by Vite, created for experimenti
 
 Solas is experimental and currently has no automated test suite, so expect rough edges.
 
-Solas currently requires Bun 1.2+ on your `PATH`. You can still manage dependencies with `npm`, `pnpm`, or `yarn`, but the Solas CLI and Vite plugin runtime use Bun APIs directly.
-
 ## Install
 
 ```sh
@@ -75,10 +73,202 @@ If a route has both `+page.tsx` and `+endpoint.ts`, Solas selects the GET handle
 
 Non-GET methods (`POST`, `PUT`, `PATCH`, `DELETE`) always run `+endpoint.ts`.
 
+## Client Routing
+
+Import client navigation helpers from `@jk2908/solas/router`.
+
+```tsx
+import { Link, useRouter } from '@jk2908/solas/router'
+```
+
+Solas generates route types for your app. `Link` and `router.go(...)` use those generated route types for autocomplete and type checking:
+
+```tsx
+<Link href="/posts" />
+<Link href="/p/:id" params={{ id: 'post-1' }} />
+
+await router.go('/posts')
+await router.go('/p/:id', { params: { id: 'post-1' } })
+```
+
+That gives you:
+
+- autocomplete for known route paths
+- required params for dynamic routes like `/p/:id`
+- rejected params for static routes that do not accept them
+- typed query and navigation options on `router.go(...)`
+
+If you already have a concrete path, you can pass that directly instead of using route params:
+
+```tsx
+;<Link href={`/p/${post.id}`} />
+
+await router.go(`/p/${post.id}`)
+```
+
+In that form the path is already resolved, so `params` are not used. Typed `Link` and `router.go(...)` only allow `params` when you pass a route pattern like `/p/:id`.
+
+If the target already contains a query string and you also pass `query`, Solas merges them. Existing query entries are kept unless you override the same key in `query`, and explicit `query` values win:
+
+```tsx
+<Link href={`/p/${post.id}?tab=summary`} query={{ draft: true, tab: 'full' }} />
+```
+
+That resolves to `/p/${post.id}?tab=full&draft=true`.
+
+Use `Link` for same-origin app navigation. Prefetching is opt-in:
+
+```tsx
+<Link href="/posts">Posts</Link>
+<Link href="/posts" prefetch="intent">Prefetch on focus or touch</Link>
+<Link href="/posts" prefetch="hover">Prefetch on hover</Link>
+<Link href="/p/:id" params={{ id: 'post-1' }}>Typed params</Link>
+```
+
+`prefetch="none"` is the default. Solas does not automatically prefetch routes unless you opt in with `Link` or call `router.prefetch(...)` yourself.
+
+Use `useRouter()` inside client components for programmatic navigation, prefetching, and refreshing the current route:
+
+```tsx
+'use client'
+
+import { useRouter } from '@jk2908/solas/router'
+
+export function Controls() {
+	const router = useRouter()
+
+	return (
+		<>
+			<button type="button" onClick={() => router.go('/posts')}>
+				Go to posts
+			</button>
+
+			<button type="button" onMouseEnter={() => router.prefetch('/posts')}>
+				Prefetch posts
+			</button>
+
+			<button type="button" onClick={() => router.refresh()}>
+				Refresh current route
+			</button>
+		</>
+	)
+}
+```
+
+`router.go(...)` and `router.refresh()` both return promises, so you can `await` either of them when you need to sequence work after navigation completes:
+
+```tsx
+const finalPath = await router.go('/posts')
+```
+
+```tsx
+await router.refresh()
+```
+
+`router.refresh()` always refreshes the current browser location at the moment you call it. If you call it after `await router.go('/posts')`, it refreshes `/posts` (or the final redirected path).
+
+`router.go(...)` accepts route params and query values using the same typed route rules as `Link`:
+
+```tsx
+await router.go('/p/:id', {
+	params: { id: 'post-2' },
+	query: { draft: true },
+})
+```
+
+Those same generated route types can also be reused outside navigation helpers when you want route params to stay typed in page exports:
+
+```tsx
+import type { Route, Solas } from '@jk2908/solas'
+
+export const metadata: Route.Metadata<Solas.Routes['/writing/:slug']> = ({ params }) => {
+	const post = allPosts?.find(p => p.__mdsrc.slug === params?.slug)
+
+	return {
+		title: post?.title ?? 'Post not found',
+	}
+}
+
+export const params: Route.StaticParams<Solas.Routes['/writing/:slug']> = () =>
+	allPosts?.map(p => ({ slug: p.__mdsrc.slug })) ?? []
+```
+
+That keeps your route params aligned across links, imperative navigation, metadata, and static params.
+
+`router.refresh()` clears the cached RSC response for the current path and fetches a fresh payload, so it is most useful for routes that render request-time data. `router.isNavigating` exposes pending client-side navigation state.
+
 ## Config
 
 All Solas options are passed to `solas()` inside `defineConfig`.
 
+## Runtime
+
+Solas uses a runtime for filesystem access, mime lookup, and hashing.
+
+This is not a deployment or packaging adapter. Platform adapters are not available yet.
+
+Use the `runtime` config key to select the runtime used by Solas server code.
+
+Supported values are `'auto'`, `'node'`, and `'bun'`.
+
+`solas()` defaults to `runtime: 'auto'`. In a Bun process, that selects Bun. Otherwise it falls back to Node.
+
+If you already run Vite through Bun, `runtime: 'auto'` is usually enough and Solas will detect Bun automatically.
+
+### Node runtime
+
+If you want to pin Node explicitly, set `runtime: 'node'`:
+
+```ts
+import { defineConfig } from 'vite'
+
+import solas from '@jk2908/solas'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+	plugins: [solas({ runtime: 'node' }), react()],
+})
+```
+
+Use the normal Vite commands with the Node runtime:
+
+```json
+{
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build",
+		"preview": "vite preview"
+	}
+}
+```
+
+### Bun runtime
+
+If you want Solas runtime code to execute in Bun, set `runtime: 'bun'`:
+
+```ts
+import { defineConfig } from 'vite'
+
+import solas from '@jk2908/solas'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+	plugins: [solas({ runtime: 'bun' }), react()],
+})
+```
+
+When you use the Bun runtime, run Vite through Bun so the server/runtime code executes in a Bun process:
+
+```json
+{
+	"scripts": {
+		"dev": "bunx --bun vite dev",
+		"build": "bunx --bun vite build",
+		"preview": "bunx --bun vite preview"
+	}
+}
+```
+
 ### `url`
 
 `url` is optional. If you set it, Solas treats it as the public origin for your app.
@@ -398,18 +588,20 @@ Add scripts to your app:
 ```json
 {
 	"scripts": {
-		"dev": "bunx --bun vite dev",
-		"build": "bunx --bun vite build",
-		"preview": "bunx --bun vite preview"
+		"dev": "vite dev",
+		"build": "vite build",
+		"preview": "vite preview"
 	}
 }
 ```
 
+These defaults assume either `runtime: 'node'` or `runtime: 'auto'` while running Vite under Node. If you set `runtime: 'bun'`, or let `runtime: 'auto'` resolve to Bun by running Vite through Bun, use the Bun-backed commands shown in the runtime section above.
+
 ## Commands
 
-- `bunx --bun vite dev` starts the development server.
-- `bunx --bun vite build` creates a production build. Solas finalizes that build by prerendering configured routes, writing the runtime manifest, generating `sitemap.xml` when enabled, and precompressing output when enabled.
-- `bunx --bun vite preview` serves the built app for local verification.
+- `vite dev` starts the development server.
+- `vite build` creates a production build. Solas finalizes that build by prerendering configured routes, writing the runtime manifest, generating `sitemap.xml` when enabled, and precompressing output when enabled.
+- `vite preview` serves the built app for local verification.
 
 ## Security
 

package/dist/adapters/bun.d.ts

@@ -0,0 +1,12 @@
+import { RuntimeBase } from '../internal/runtimes/runtime.js';
+export declare class RuntimeBun extends RuntimeBase {
+    readonly name: "bun";
+    readonly module: string;
+    exists(filePath: string): Promise<boolean>;
+    readText(filePath: string): Promise<string>;
+    readBuffer(filePath: string): Promise<ArrayBuffer>;
+    mimeType(filePath: string): string;
+    write(filePath: string, content: string | NodeJS.ArrayBufferView): Promise<void>;
+    hash(value: string): string;
+}
+export default function bunAdapter(): RuntimeBun;

package/dist/adapters/bun.js

@@ -0,0 +1,39 @@
+import { RuntimeBase } from '../internal/runtimes/runtime.js';
+import { Solas } from '../solas.js';
+export class RuntimeBun extends RuntimeBase {
+    name = 'bun';
+    module = `${Solas.Config.PKG_NAME}/adapters/bun`;
+    async exists(filePath) {
+        return Bun.file(filePath).exists();
+    }
+    readText(filePath) {
+        return Bun.file(filePath).text();
+    }
+    readBuffer(filePath) {
+        return Bun.file(filePath).arrayBuffer();
+    }
+    mimeType(filePath) {
+        return Bun.file(filePath).type || 'application/octet-stream';
+    }
+    async write(filePath, content) {
+        // normalise wider arraybuffer views into a shape Bun.write accepts directly
+        await Bun.write(filePath, typeof content === 'string'
+            ? content
+            : content instanceof Uint8Array
+                ? content
+                : new Uint8Array(content.buffer, content.byteOffset, content.byteLength));
+    }
+    hash(value) {
+        const hash = Bun.hash(value);
+        // Bun.hash returns an integer-like value, so keep it in BigInt space and avoid
+        // precision loss. Clamp it to an unsigned 64-bit value before hex
+        // formatting. Pad to 16 chars to match the Node adapter
+        // output shape
+        return BigInt.asUintN(64, typeof hash === 'bigint' ? hash : BigInt(hash))
+            .toString(16)
+            .padStart(16, '0');
+    }
+}
+export default function bunAdapter() {
+    return new RuntimeBun();
+}

package/dist/adapters/node.d.ts

@@ -0,0 +1,11 @@
+import { RuntimeBase } from '../internal/runtimes/runtime.js';
+export declare class RuntimeNode extends RuntimeBase {
+    readonly name: "node";
+    readonly module: string;
+    exists(filePath: string): Promise<boolean>;
+    readText(filePath: string): Promise<string>;
+    readBuffer(filePath: string): Promise<ArrayBuffer>;
+    mimeType(filePath: string): string;
+    write(filePath: string, content: string | NodeJS.ArrayBufferView): Promise<void>;
+    hash(value: string): string;
+}

package/dist/adapters/node.js

@@ -0,0 +1,34 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import { lookup } from 'mime-types';
+import { RuntimeBase } from '../internal/runtimes/runtime.js';
+import { Solas } from '../solas.js';
+export class RuntimeNode extends RuntimeBase {
+    name = 'node';
+    module = `${Solas.Config.PKG_NAME}/adapters/node`;
+    async exists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    readText(filePath) {
+        return fs.readFile(filePath, 'utf-8');
+    }
+    async readBuffer(filePath) {
+        const buffer = await fs.readFile(filePath);
+        return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+    }
+    mimeType(filePath) {
+        return lookup(filePath) || 'application/octet-stream';
+    }
+    async write(filePath, content) {
+        await fs.writeFile(filePath, content);
+    }
+    hash(value) {
+        return createHash('sha256').update(value).digest('hex').slice(0, 16);
+    }
+}

package/dist/index.js

@@ -14,19 +14,26 @@ import { writeMaps } from './internal/codegen/maps.js';
 import { writeTypes } from './internal/codegen/types.js';
 import { postbuild } from './internal/postbuild.js';
 import { collect as collectPublicFiles } from './internal/public-files.js';
+import { Runtime } from './internal/runtimes/runtime.js';
 import { Solas } from './solas.js';
 const DEFAULT_CONFIG = {
+    runtime: 'auto',
     precompress: false,
     prerender: false,
     trustedOrigins: [],
     trailingSlash: 'never',
 };
 function solas(c) {
-    const config = Solas.Config.validate({
-        ...DEFAULT_CONFIG,
+    const validatedConfig = Solas.Config.validate({
         ...c,
         url: c?.url ?? process.env.VITE_APP_URL?.toString(),
     });
+    const config = {
+        ...DEFAULT_CONFIG,
+        ...validatedConfig,
+        runtime: validatedConfig.runtime ?? DEFAULT_CONFIG.runtime,
+    };
+    Runtime.runtime = Solas.Runtime.create(config.runtime);
     if (config.logger?.level)
         Logger.defaultLevel = config.logger.level;
     const logger = new Logger();
@@ -43,11 +50,11 @@ function solas(c) {
             const cached = fileCache.get(filePath);
             if (cached === content) {
                 // if content is unchanged and file exists, skip write
-                if (await Bun.file(filePath).exists())
+                if (await Runtime.exists(filePath))
                     return null;
                 // else, file is missing but cached content is the same as
                 // last time we saw it, write it
-                await Bun.write(filePath, content);
+                await Runtime.write(filePath, content);
                 fileCache.set(filePath, content);
                 return path.relative(process.cwd(), filePath);
             }
@@ -57,7 +64,7 @@ function solas(c) {
             if (curr === content)
                 return null;
             try {
-                await Bun.write(filePath, content);
+                await Runtime.write(filePath, content);
                 fileCache.set(filePath, content);
                 return path.relative(process.cwd(), filePath);
             }
@@ -70,7 +77,7 @@ function solas(c) {
             // file doesn't exist, write it
             if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
                 try {
-                    await Bun.write(filePath, content);
+                    await Runtime.write(filePath, content);
                     fileCache.set(filePath, content);
                     return path.relative(process.cwd(), filePath);
                 }
@@ -100,7 +107,7 @@ function solas(c) {
             ['manifest.ts', writeManifest(manifest)],
             ['maps.ts', writeMaps(imports, modules)],
             [`${Solas.Config.SLUG}.d.ts`, writeTypes(manifest)],
-            [Solas.Config.ENTRY_RSC, writeRSCEntry()],
+            [Solas.Config.ENTRY_RSC, writeRSCEntry(config)],
             [Solas.Config.ENTRY_SSR, writeSSREntry()],
             [Solas.Config.ENTRY_BROWSER, writeBrowserEntry()],
         ];
@@ -299,7 +306,7 @@ function solas(c) {
             }
             // write build manifest
             const generatedDir = path.join(process.cwd(), Solas.Config.GENERATED_DIR);
-            await Bun.write(path.join(generatedDir, 'build.json'), JSON.stringify({
+            await Runtime.write(path.join(generatedDir, 'build.json'), JSON.stringify({
                 base: resolvedViteConfig?.base ?? '/',
                 publicFiles: await collectPublicFiles(resolvedViteConfig?.publicDir),
                 prerenderRoutes: Array.from(buildContext.prerenderRoutes),

package/dist/internal/browser-router/link.js

@@ -16,6 +16,8 @@ function guard(path, prefetcher) {
 export function Link({ children, href, params, prefetch = 'none', query, ...rest }) {
     const { go, prefetch: prefetcher } = useRouter();
     const timer = useRef(null);
+    // track whether the link is meant to be handled by the router, to avoid
+    // unnecessary prefetching and event handling for external links
     const handled = useRef(false);
     const target = BrowserRouter.toTarget(href, params, query);
     // clear any pending hover-prefetch timer on unmount

package/dist/internal/{prefetcher.d.ts → browser-router/response-cache.d.ts}

@@ -1,10 +1,17 @@
-export declare namespace Prefetcher {
+export declare namespace ResponseCache {
     type Entry = {
         promise: Promise<Response>;
         timeoutId: ReturnType<typeof setTimeout>;
     };
 }
-export declare class Prefetcher {
+/**
+ * A simple in-memory cache for RSC response promises used by the BrowserRouter.
+ * It lets a later navigation reuse a prefetched response for the same path,
+ * and helps avoid issuing a second fetch when navigation follows shortly
+ * after prefetch. Entries are stored by normalised path with TTL and
+ * max size eviction
+ */
+export declare class ResponseCache {
     #private;
     ttl: number;
     maxSize: number;
@@ -16,7 +23,7 @@ export declare class Prefetcher {
      * Converts a url path to a cache key by normalising it
      * against a base url
      */
-    static key(path: string, base: string): string | null;
+    static toCacheKey(path: string, base: string): string | null;
     /**
      * Evicts the oldest entry from the cache
      */
@@ -26,8 +33,8 @@ export declare class Prefetcher {
      */
     has(path: string): boolean;
     /**
-     * Retrieves a fresh response promise for the given path if it exists
-     * by cloning the cached response so each consumer gets an unread stream
+     * Retrieves a fresh response promise for the given path if it exists by
+     * cloning the cached response so each consumer gets an unread stream
      */
     get(path: string): Promise<Response> | undefined;
     /**

package/dist/internal/{prefetcher.js → browser-router/response-cache.js}

@@ -1,4 +1,11 @@
-export class Prefetcher {
+/**
+ * A simple in-memory cache for RSC response promises used by the BrowserRouter.
+ * It lets a later navigation reuse a prefetched response for the same path,
+ * and helps avoid issuing a second fetch when navigation follows shortly
+ * after prefetch. Entries are stored by normalised path with TTL and
+ * max size eviction
+ */
+export class ResponseCache {
     #cache = new Map();
     ttl = 60_000;
     maxSize = 32;
@@ -10,7 +17,7 @@ export class Prefetcher {
      * Converts a url path to a cache key by normalising it
      * against a base url
      */
-    static key(path, base) {
+    static toCacheKey(path, base) {
         try {
             const url = new URL(path, base);
             // hash is client-only and never sent to the server, so exclude it
@@ -40,8 +47,8 @@ export class Prefetcher {
         return this.#cache.has(path);
     }
     /**
-     * Retrieves a fresh response promise for the given path if it exists
-     * by cloning the cached response so each consumer gets an unread stream
+     * Retrieves a fresh response promise for the given path if it exists by
+     * cloning the cached response so each consumer gets an unread stream
      */
     get(path) {
         const promise = this.#cache.get(path)?.promise;

package/dist/internal/browser-router/router.d.ts

@@ -4,6 +4,7 @@ export { BrowserRouter } from './shared.js';
 export declare const BrowserRouterContext: import("react").Context<{
     go: BrowserRouter.Go;
     prefetch: (path: string) => void;
+    refresh: BrowserRouter.Refresh;
     isNavigating: boolean;
     url: {
         pathname?: string | undefined;

package/dist/internal/browser-router/router.js

@@ -4,12 +4,13 @@ import { createContext, useCallback, useEffect, useMemo, useRef } from 'react';
 import { createFromFetch } from '@vitejs/plugin-rsc/browser';
 import { Logger } from '../../utils/logger.js';
 import { Solas } from '../../solas.js';
-import { Prefetcher } from '../prefetcher.js';
+import { ResponseCache } from './response-cache.js';
 import { BrowserRouter } from './shared.js';
 export { BrowserRouter } from './shared.js';
 export const BrowserRouterContext = createContext({
     go: async () => '',
     prefetch: () => { },
+    refresh: async () => '',
     isNavigating: false,
     url: {},
 });
@@ -17,10 +18,18 @@ const DEFAULT_GO_CONFIG = {
     replace: false,
 };
 const logger = new Logger();
-const prefetcher = new Prefetcher();
+const responseCache = new ResponseCache();
 export function BrowserRouterProvider({ children, setPayload, isNavigating = false, url, }) {
     const id = useRef(0);
     const controller = useRef(null);
+    /**
+     * Navigates to a given path
+     *
+     * @param to - the target path to navigate to, which can be a route pattern with params or an external URL
+     * @param opts - options for navigation, including whether to replace the current history entry and pass query
+     * and route params
+     * @returns the final path navigated to after any redirects, or the original path if navigation failed
+     */
     const go = useCallback(async (to, opts = {}) => {
         id.current += 1;
         const navigationId = id.current;
@@ -36,7 +45,7 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
                 throw new Error('[router.go]: external URLs are not supported. Use <a> instead');
             }
             const url = new URL(target, window.location.origin);
-            const key = Prefetcher.key(url.toString(), window.location.origin);
+            const key = ResponseCache.toCacheKey(url.toString(), window.location.origin);
             if (!key)
                 throw new Error('Invalid navigation url');
             path = key;
@@ -48,7 +57,7 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
                     window.history.pushState(null, '', path);
                 }
             }
-            let promise = prefetcher.get(path);
+            let promise = responseCache.get(path);
             existing = promise !== undefined;
             if (!promise) {
                 const ctrl = new AbortController();
@@ -57,7 +66,7 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
                     headers: { accept: 'text/x-component' },
                     signal: ctrl.signal,
                 });
-                prefetcher.set(path, promise);
+                responseCache.set(path, promise);
             }
             if (navigationId !== id.current)
                 return path;
@@ -65,7 +74,7 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
                 promise,
                 createFromFetch(promise),
             ]);
-            const resolvedPath = Prefetcher.key(res.url, window.location.origin) ?? path;
+            const resolvedPath = ResponseCache.toCacheKey(res.url, window.location.origin) ?? path;
             if (navigationId !== id.current)
                 return resolvedPath;
             if (resolvedPath !== path) {
@@ -92,20 +101,42 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
         finally {
             if (navigationId === id.current)
                 controller.current = null;
-            if (!existing) {
-                prefetcher.remove(path);
-            }
+            if (!existing)
+                responseCache.remove(path);
         }
         return path;
     }, [setPayload]);
+    /**
+     * Prefetches the RSC response for a given path and caches it for later navigation.
+     * Does nothing if a cached response already exists for the path
+     *
+     * @param path - the target path to prefetch
+     * @returns void
+     */
     const prefetch = useCallback((path) => {
-        const key = Prefetcher.key(path, window.location.origin);
+        const key = ResponseCache.toCacheKey(path, window.location.origin);
         if (!key)
             return;
-        if (prefetcher.has(key))
+        if (responseCache.has(key))
             return;
-        prefetcher.set(key, fetch(key, { headers: { Accept: 'text/x-component' } }));
+        responseCache.set(key, fetch(key, { headers: { Accept: 'text/x-component' } }));
     }, []);
+    /**
+     * Refreshes the current page by re-fetching the RSC response for the current path and updating the
+     * payload. It also clears any cached response for the current path to ensure that the latest
+     * version is fetched
+     */
+    const refresh = useCallback(() => {
+        const currentPath = window.location.pathname + window.location.search;
+        const key = ResponseCache.toCacheKey(currentPath, window.location.origin);
+        if (!key)
+            return Promise.resolve(currentPath);
+        if (responseCache.has(key))
+            responseCache.remove(key);
+        return go(currentPath, {
+            replace: true,
+        });
+    }, [go]);
     useEffect(() => {
         const handler = () => go(BrowserRouter.toTarget(window.location.pathname + window.location.search), {
             replace: true,
@@ -120,11 +151,12 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
     const value = useMemo(() => ({
         go,
         prefetch,
+        refresh,
         isNavigating,
         url: {
             pathname: url?.pathname,
             search: url?.search,
         },
-    }), [go, prefetch, isNavigating, url]);
+    }), [go, prefetch, refresh, isNavigating, url]);
     return _jsx(BrowserRouterContext, { value: value, children: children });
 }

package/dist/internal/browser-router/shared.d.ts

@@ -156,6 +156,7 @@ export declare namespace BrowserRouter {
         <TTo extends Target>(to: TTo, opts?: TargetConfig & Replace): Promise<string>;
         <TTo extends string>(to: string extends TTo ? TTo : never, opts?: GoOptions): Promise<string>;
     };
+    export type Refresh = () => Promise<string>;
     /**
      * Convert a route pattern and params into a real path string. This is used internally
      * to implement <Link /> and router.go