From eceec6f641b7497cc047dc7c756fb12811a77fce Mon Sep 17 00:00:00 2001
From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com>
Date: Thu, 5 Mar 2026 19:06:06 +0100
Subject: [PATCH] Move ~scalar/proxy route to site route group (#4083)

---
 .changeset/spicy-humans-deny.md                            | 6 ++++++
 .../[mode]/[siteURL]/[siteData]}/~scalar/proxy/route.ts    | 0
 .../src/components/DocumentView/OpenAPI/context.tsx        | 3 +++
 packages/gitbook/src/middleware.ts                         | 3 ++-
 packages/react-openapi/src/ScalarApiButton.tsx             | 7 +++++--
 packages/react-openapi/src/context.ts                      | 6 ++++++
 6 files changed, 22 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/spicy-humans-deny.md
 rename packages/gitbook/src/app/{ => sites/dynamic/[mode]/[siteURL]/[siteData]}/~scalar/proxy/route.ts (100%)

diff --git a/.changeset/spicy-humans-deny.md b/.changeset/spicy-humans-deny.md
new file mode 100644
index 000000000..5cfa75977
--- /dev/null
+++ b/.changeset/spicy-humans-deny.md
@@ -0,0 +1,6 @@
+---
+"@gitbook/react-openapi": patch
+"gitbook": patch
+---
+
+Move ~scalar/proxy route to site route group
diff --git a/packages/gitbook/src/app/~scalar/proxy/route.ts b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~scalar/proxy/route.ts
similarity index 100%
rename from packages/gitbook/src/app/~scalar/proxy/route.ts
rename to packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~scalar/proxy/route.ts
diff --git a/packages/gitbook/src/components/DocumentView/OpenAPI/context.tsx b/packages/gitbook/src/components/DocumentView/OpenAPI/context.tsx
index 06257171b..6e888d9c2 100644
--- a/packages/gitbook/src/components/DocumentView/OpenAPI/context.tsx
+++ b/packages/gitbook/src/components/DocumentView/OpenAPI/context.tsx
@@ -32,8 +32,11 @@ export function getOpenAPIContext(args: {
     const customizationLocale = context ? getSpaceLocale(context) : DEFAULT_LOCALE;
     const locale = checkIsValidLocale(customizationLocale) ? customizationLocale : DEFAULT_LOCALE;
 
+    const proxyUrl = context ? context.linker.toPathInSite('~scalar/proxy') : undefined;
+
     return {
         specUrl,
+        proxyUrl,
         icons: {
             chevronDown: <Icon icon="chevron-down" />,
             chevronRight: <Icon icon="chevron-right" />,
diff --git a/packages/gitbook/src/middleware.ts b/packages/gitbook/src/middleware.ts
index b390a7719..acfb1c0ca 100644
--- a/packages/gitbook/src/middleware.ts
+++ b/packages/gitbook/src/middleware.ts
@@ -36,7 +36,7 @@ import { getPreviewRequestIdentifier } from './lib/preview';
 import { serveProxyAnalyticsEvent } from './lib/tracking';
 export const config = {
     matcher: [
-        '/((?!_next/static|_next/image|~gitbook/static|~gitbook/revalidate|~gitbook/monitoring|~scalar/proxy).*)',
+        '/((?!_next/static|_next/image|~gitbook/static|~gitbook/revalidate|~gitbook/monitoring).*)',
     ],
 };
 
@@ -663,6 +663,7 @@ function encodePathInSiteContent(
             return { pathname, routeType: 'static' };
         case '~gitbook/pdf':
         case '~gitbook/search':
+        case '~scalar/proxy':
             // PDF and search routes are always dynamic as they depend on the request.
             return { pathname, routeType: 'dynamic' };
         default: {
diff --git a/packages/react-openapi/src/ScalarApiButton.tsx b/packages/react-openapi/src/ScalarApiButton.tsx
index 1b7250d19..dba10df58 100644
--- a/packages/react-openapi/src/ScalarApiButton.tsx
+++ b/packages/react-openapi/src/ScalarApiButton.tsx
@@ -53,6 +53,7 @@ export function ScalarApiButton(props: {
                         <ScalarModal
                             controllerRef={controllerRef}
                             withProxy={withProxy}
+                            proxyUrl={context.proxyUrl}
                             method={method}
                             path={path}
                             securities={securities}
@@ -73,9 +74,11 @@ function ScalarModal(props: {
     servers: OpenAPIOperationData['servers'];
     specUrl: string;
     withProxy: boolean;
+    proxyUrl?: string;
     controllerRef: React.Ref<ScalarModalControllerRef>;
 }) {
-    const { method, path, securities, servers, specUrl, withProxy, controllerRef } = props;
+    const { method, path, securities, servers, specUrl, withProxy, proxyUrl, controllerRef } =
+        props;
 
     const getPrefillInputContextData = useOpenAPIPrefillContext();
     const prefillInputContext = getPrefillInputContextData();
@@ -90,7 +93,7 @@ function ScalarModal(props: {
             configuration={{
                 url: specUrl,
                 ...prefillConfig,
-                proxyUrl: withProxy ? '/~scalar/proxy' : undefined,
+                proxyUrl: withProxy ? proxyUrl : undefined,
             }}
             initialRequest={{ method: toScalarHttpMethod(method), path }}
         >
diff --git a/packages/react-openapi/src/context.ts b/packages/react-openapi/src/context.ts
index 9283489fc..03d712356 100644
--- a/packages/react-openapi/src/context.ts
+++ b/packages/react-openapi/src/context.ts
@@ -34,6 +34,11 @@ export interface OpenAPIClientContext {
      */
     id?: string;
 
+    /**
+     * The URL for the Scalar proxy endpoint.
+     */
+    proxyUrl?: string;
+
     /**
      * Mark the context as a client context.
      */
@@ -97,6 +102,7 @@ export function getOpenAPIClientContext(context: OpenAPIUniversalContext): OpenA
         defaultInteractiveOpened: context.defaultInteractiveOpened,
         blockKey: context.blockKey,
         id: context.id,
+        proxyUrl: context.proxyUrl,
         $$isClientContext$$: true,
     };
 }