Add jsdocs for SSR/Framework components (#14013)

brophdawg11 · web-flow · commit 617f052a1252 · 2025-07-16T14:12:09.000-04:00
diff --git a/.eslintrc b/.eslintrc
@@ -24,7 +24,10 @@
       "files": [
         "packages/react-router/lib/components.tsx",
         "packages/react-router/lib/hooks.tsx",
-        "packages/react-router/lib/dom/lib.tsx"
+        "packages/react-router/lib/dom/lib.tsx",
+        "packages/react-router/lib/dom/ssr/components.tsx",
+        "packages/react-router/lib/dom/ssr/server.tsx",
+        "packages/react-router/lib/dom-export/hydrated-router.tsx"
       ],
       "plugins": ["jsdoc"],
       "rules": {
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -51,6 +51,9 @@ jobs:
           pnpm run docs:jsdoc --path packages/react-router/lib/components.tsx --write
           pnpm run docs:jsdoc --path packages/react-router/lib/hooks.tsx --write
           pnpm run docs:jsdoc --path packages/react-router/lib/dom/lib.tsx --write
+          pnpm run docs:jsdoc --path packages/react-router/lib/dom/ssr/components.tsx --write
+          pnpm run docs:jsdoc --path packages/react-router/lib/dom/ssr/server.tsx --write
+          pnpm run docs:jsdoc --path packages/react-router/lib/dom-export/hydrated-router.tsx --write
 
       - name: 💪 Commit
         run: |
diff --git a/docs/api/components/ServerRouter.md b/docs/api/components/ServerRouter.md
diff --git a/docs/api/data-routers/HydratedRouter.md b/docs/api/data-routers/HydratedRouter.md
diff --git a/docs/api/data-routers/index.md b/docs/api/data-routers/index.md
@@ -1,4 +1,4 @@
 ---
 title: Data Routers
+order: 5
 ---
-
diff --git a/docs/api/declarative-routers/index.md b/docs/api/declarative-routers/index.md
@@ -1,4 +1,4 @@
 ---
 title: Declarative Routers
+order: 6
 ---
-
diff --git a/docs/api/framework-routers/index.md b/docs/api/framework-routers/index.md
@@ -0,0 +1,4 @@
+---
+title: Framework Routers
+order: 4
+---
diff --git a/docs/api/rsc/index.md b/docs/api/rsc/index.md
@@ -1,3 +1,4 @@
 ---
 title: RSC (Unstable)
+order: 7
 ---
diff --git a/packages/react-router/lib/dom-export/hydrated-router.tsx b/packages/react-router/lib/dom-export/hydrated-router.tsx
@@ -217,10 +217,17 @@ interface HydratedRouterProps {
 }
 
 /**
- * Framework-mode router component to be used in `entry.client.tsx` to hydrate a
- * router from a `ServerRouter`
+ * Framework-mode router component to be used to to hydrate a router from a
+ * `ServerRouter`. See [`entry.client.tsx`](../api/framework-conventions/entry.client.tsx).
  *
- * @category Component Routers
+ * @public
+ * @category Framework Routers
+ * @mode framework
+ * @param props Props
+ * @param props.unstable_getContext Context object to passed through to
+ * {@link createBrowserRouter} and made available to `clientLoader`/`clientAction`
+ * functions
+ * @returns A React element that represents the hydrated application.
  */
 export function HydratedRouter(props: HydratedRouterProps) {
   if (!router) {
diff --git a/packages/react-router/lib/dom/ssr/components.tsx b/packages/react-router/lib/dom/ssr/components.tsx
@@ -213,26 +213,30 @@ function getActiveMatches(
 }
 
 /**
-  Renders all of the `<link>` tags created by route module {@link LinksFunction} export. You should render it inside the `<head>` of your document.
-
-  ```tsx
-  import { Links } from "react-router";
-
-  export default function Root() {
-    return (
-      <html>
-        <head>
-          <Links />
-        </head>
-        <body></body>
-      </html>
-    );
-  }
-  ```
-
-  @category Components
+ * Renders all of the `<link>` tags created by the route module
+ * [`links`](../../start/framework/route-module#links) export. You should render
+ * it inside the `<head>` of your document.
+ *
+ * @example
+ * import { Links } from "react-router";
+ *
+ * export default function Root() {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <Links />
+ *       </head>
+ *       <body></body>
+ *     </html>
+ *   );
+ * }
+ *
+ * @public
+ * @category Components
+ * @mode framework
+ * @returns A collection of React elements for `<link>` tags
  */
-export function Links() {
+export function Links(): React.JSX.Element {
   let { isSpaMode, manifest, routeModules, criticalCss } =
     useFrameworkContext();
   let { errors, matches: routerMatches } = useDataRouterStateContext();
@@ -264,17 +268,28 @@ export function Links() {
 }
 
 /**
-  Renders `<link rel=prefetch|modulepreload>` tags for modules and data of another page to enable an instant navigation to that page. {@link LinkProps.prefetch | `<Link prefetch>`} uses this internally, but you can render it to prefetch a page for any other reason.
-
-  ```tsx
-  import { PrefetchPageLinks } from "react-router"
-
-  <PrefetchPageLinks page="/absolute/path" />
-  ```
-
-  For example, you may render one of this as the user types into a search field to prefetch search results before they click through to their selection.
-
-  @category Components
+ * Renders `<link rel=prefetch|modulepreload>` tags for modules and data of
+ * another page to enable an instant navigation to that page.
+ * [`<Link prefetch>`](../../components/Link#prefetch) uses this internally, but
+ * you can render it to prefetch a page for any other reason.
+ *
+ * For example, you may render one of this as the user types into a search field
+ * to prefetch search results before they click through to their selection.
+ *
+ * @example
+ * import { PrefetchPageLinks } from "react-router";
+ *
+ * <PrefetchPageLinks page="/absolute/path" />
+ *
+ * @public
+ * @category Components
+ * @mode framework
+ * @param props Props
+ * @param props.page The absolute path of the page to prefetch, e.g. `/absolute/path`.
+ * @param props.dataLinkProps Additional props to pass to the
+ * [`<link>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/link)
+ * tag, such as `crossOrigin`, `integrity`, `rel`, etc.
+ * @returns A collection of React elements for `<link>` tags
  */
 export function PrefetchPageLinks({
   page,
@@ -446,25 +461,29 @@ function PrefetchPageLinksImpl({
 }
 
 /**
-  Renders all the `<meta>` tags created by route module {@link MetaFunction} exports. You should render it inside the `<head>` of your HTML.
-
-  ```tsx
-  import { Meta } from "react-router";
-
-  export default function Root() {
-    return (
-      <html>
-        <head>
-          <Meta />
-        </head>
-      </html>
-    );
-  }
-  ```
-
-  @category Components
+ * Renders all the `<meta>` tags created by the route module
+ * [`meta`](../../start/framework/route-module#meta) exports. You should render
+ * it inside the `<head>` of your HTML.
+ *
+ * @example
+ * import { Meta } from "react-router";
+ *
+ * export default function Root() {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <Meta />
+ *       </head>
+ *     </html>
+ *   );
+ * }
+ *
+ * @public
+ * @category Components
+ * @mode framework
+ * @returns A collection of React elements for `<meta>` tags
  */
-export function Meta() {
+export function Meta(): React.JSX.Element {
   let { isSpaMode, routeModules } = useFrameworkContext();
   let {
     errors,
@@ -604,14 +623,14 @@ function isValidMetaTag(tagName: unknown): tagName is "meta" | "link" {
 let isHydrated = false;
 
 /**
-  A couple common attributes:
-
-  - `<Scripts crossOrigin>` for hosting your static assets on a different server than your app.
-  - `<Scripts nonce>` to support a [content security policy for scripts](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src) with [nonce-sources](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#sources) for your `<script>` tags.
-
-  You cannot pass through attributes such as `async`, `defer`, `src`, `type`, `noModule` because they are managed by React Router internally.
-
-  @category Types
+ * A couple common attributes:
+ *
+ * - `<Scripts crossOrigin>` for hosting your static assets on a different server than your app.
+ * - `<Scripts nonce>` to support a [content security policy for scripts](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src) with [nonce-sources](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#sources) for your `<script>` tags.
+ *
+ * You cannot pass through attributes such as `async`, `defer`, `src`, `type`, `noModule` because they are managed by React Router internally.
+ *
+ * @category Types
  */
 export type ScriptsProps = Omit<
   React.HTMLProps<HTMLScriptElement>,
@@ -632,28 +651,36 @@ export type ScriptsProps = Omit<
 };
 
 /**
-  Renders the client runtime of your app. It should be rendered inside the `<body>` of the document.
-
-  ```tsx
-  import { Scripts } from "react-router";
-
-  export default function Root() {
-    return (
-      <html>
-        <head />
-        <body>
-          <Scripts />
-        </body>
-      </html>
-    );
-  }
-  ```
-
-  If server rendering, you can omit `<Scripts/>` and the app will work as a traditional web app without JavaScript, relying solely on HTML and browser behaviors.
-
-  @category Components
+ * Renders the client runtime of your app. It should be rendered inside the
+ * `<body>` of the document.
+ *
+ * If server rendering, you can omit `<Scripts/>` and the app will work as a
+ * traditional web app without JavaScript, relying solely on HTML and browser
+ * behaviors.
+ *
+ * @example
+ * import { Scripts } from "react-router";
+ *
+ * export default function Root() {
+ *   return (
+ *     <html>
+ *       <head />
+ *       <body>
+ *         <Scripts />
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ *
+ * @public
+ * @category Components
+ * @mode framework
+ * @param props Props for the
+ * [`<script>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script)
+ * tag, such as `crossOrigin`, `nonce`, etc.
+ * @returns A collection of React elements for `<script>` tags
  */
-export function Scripts(props: ScriptsProps) {
+export function Scripts(props: ScriptsProps): React.JSX.Element | null {
   let {
     manifest,
     serverHandoffString,
diff --git a/packages/react-router/lib/dom/ssr/server.tsx b/packages/react-router/lib/dom/ssr/server.tsx
@@ -15,11 +15,20 @@ export interface ServerRouterProps {
 }
 
 /**
- * The entry point for a Remix app when it is rendered on the server (in
- * `app/entry.server.js`). This component is used to generate the HTML in the
- * response from the server.
+ * The server entry point for a React Router app in Framework Mode. This component
+ * is used to generate the HTML in the response from the server.
+ * See [`entry.server.tsx`](../api/framework-conventions/entry.server.tsx).
  *
- * @category Components
+ * @public
+ * @category Framework Routers
+ * @mode framework
+ * @param props Props
+ * @param props.context The entry context containing the manifest, route modules,
+ * and other data needed for rendering.
+ * @param props.url The URL of the request being handled.
+ * @param props.nonce An optional nonce for Content Security Policy (CSP) compliance,
+ * used to allow inline scripts to run safely.
+ * @returns A React element that represents the server-rendered application.
  */
 export function ServerRouter({
   context,
diff --git a/scripts/docs.ts b/scripts/docs.ts
@@ -77,16 +77,16 @@ const MODES = ["framework", "data", "declarative"] as const;
 const CATEGORIES = [
   "Components",
   "Hooks",
+  "Framework Routers",
   "Data Routers",
   "Declarative Routers",
   "Utils",
 ] as const;
 const isComponentApi = (c: SimplifiedComment) =>
   c.category === "Components" ||
+  c.category === "Framework Routers" ||
   c.category === "Declarative Routers" ||
-  c.name === "HydratedRouter" ||
-  c.name === "RouterProvider" ||
-  c.name === "StaticRouterProvider";
+  (c.category === "Data Routers" && !c.name.startsWith("create"));
 
 // Read a filename from standard input using the node parseArgs utility
 
@@ -565,12 +565,9 @@ function simplifyComment(
 
   let reference = typedocLookup.get(name)?.href;
   if (!reference) {
-    if (args.write) {
-      throw new Error(`Could not find API in typedoc reference docs: ${name}`);
-    } else {
-      console.warn(`Could not find API in typedoc reference docs: ${name}`);
-      reference = "!!! UNKNOWN !!!";
-    }
+    console.warn(
+      `Warning: Could not find API in typedoc reference docs, skipping reference link: ${name}`
+    );
   }
 
   let signature = getSignature(comment.code);

-Original file line number
+Diff line change
@@ @@ -1,4 +1,4 @@ @@
 ---
 title: Data Routers
 +order: 5
 ---
+-