fix: use <a> tag for external rewrites instead of relying on Next's Link component (#2707)

Co-authored-by: gabriel miranda <gabrielmfern@outlook.com>

Author: CarolinaMoraes

apps/web/src/components/menu.tsx

@@ -1,10 +1,10 @@
 'use client';
 
 import classnames from 'classnames';
-import Link from 'next/link';
 import { usePathname } from 'next/navigation';
 import * as React from 'react';
 import { Drawer } from 'vaul';
+import { SmartLink } from './smart-link';
 
 interface MenuItemProps {
   className?: string;
@@ -31,7 +31,7 @@ function MenuItem({ className, children, href, onClick }: MenuItemProps) {
 
   return (
     <li className="inline-flex w-full items-center justify-center md:w-fit">
-      <Link
+      <SmartLink
         className={classnames(
           'inline-flex h-8 scroll-m-2 items-center rounded-md text-slate-11 text-sm transition-colors hover:bg-slate-6 hover:text-slate-12 focus:bg-slate-6 focus:outline-none focus:ring focus:ring-slate-3 md:justify-center',
           'data-[active=true]:bg-slate-6 data-[active=true]:text-slate-12',
@@ -43,7 +43,7 @@ function MenuItem({ className, children, href, onClick }: MenuItemProps) {
         data-active={activeItem === href.replace('/', '')}
       >
         {children}
-      </Link>
+      </SmartLink>
     </li>
   );
 }

apps/web/src/components/smart-link.tsx

@@ -0,0 +1,28 @@
+import Link from 'next/link';
+import type { ComponentProps } from 'react';
+
+const EXTERNAL_REWRITE_PATHS = ['/docs'];
+
+type SmartLinkProps = ComponentProps<typeof Link>;
+
+/**
+ * We'll temporarily use <a> to redirect to external domains -- apparently Next.js 16 has a router regression
+ * where <Link> components try to do client-side navigation for rewritten paths (e.g., /docs -> mintlify.com)
+ * The router doesn't detect these are external rewrites and attempts to fetch RSC payloads by adding
+ * ?_rsc= query params (since the external domain doesn't serve RSC payloads, navigation fails)
+ *
+ * Context:
+ * https://resend.slack.com/archives/C05R55V6GBF/p1763739968845719?thread_ts=1763732012.356639&cid=C05R55V6GBF
+ * https://github.com/vercel/next.js/issues/86385
+ */
+export function SmartLink({ href, ...props }: SmartLinkProps) {
+  const isExternalRewrite =
+    typeof href === 'string' &&
+    EXTERNAL_REWRITE_PATHS.some((path) => href.startsWith(path));
+
+  if (isExternalRewrite) {
+    return <a href={href} {...(props as ComponentProps<'a'>)} />;
+  }
+
+  return <Link href={href} {...props} />;
+}