Improve TypeDoc output for dev package (#11981)

Author: markdalgleish

packages/react-router-dev/config/routes.ts

@@ -8,6 +8,10 @@ export function setAppDirectory(directory: string) {
   appDirectory = directory;
 }
 
+/**
+ * Provides the absolute path to the app directory, for use within `routes.ts`.
+ * This is designed to support resolving file system routes.
+ */
 export function getAppDirectory() {
   invariant(appDirectory);
   return appDirectory;
@@ -52,10 +56,15 @@ export interface RouteManifest {
   [routeId: string]: RouteManifestEntry;
 }
 
+/**
+ * Route config to be exported via the `routes` export within `routes.ts`.
+ */
 export type RouteConfig = RouteConfigEntry[] | Promise<RouteConfigEntry[]>;
 
 /**
- * A route exported from the routes config file
+ * Configuration for an individual route, for use within `routes.ts`. As a
+ * convenience, route config entries can be created with the {@link route},
+ * {@link index} and {@link layout} helper functions.
  */
 export interface RouteConfigEntry {
   /**
@@ -90,8 +99,6 @@ export interface RouteConfigEntry {
   children?: RouteConfigEntry[];
 }
 
-type CreateRoutePath = string | null | undefined;
-
 const createConfigRouteOptionKeys = [
   "id",
   "index",
@@ -101,19 +108,23 @@ type CreateRouteOptions = Pick<
   RouteConfigEntry,
   (typeof createConfigRouteOptionKeys)[number]
 >;
+/**
+ * Helper function for creating a route config entry, for use within
+ * `routes.ts`.
+ */
 function createRoute(
-  path: CreateRoutePath,
+  path: string | null | undefined,
   file: string,
   children?: RouteConfigEntry[]
 ): RouteConfigEntry;
 function createRoute(
-  path: CreateRoutePath,
+  path: string | null | undefined,
   file: string,
   options: CreateRouteOptions,
   children?: RouteConfigEntry[]
 ): RouteConfigEntry;
 function createRoute(
-  path: CreateRoutePath,
+  path: string | null | undefined,
   file: string,
   optionsOrChildren: CreateRouteOptions | RouteConfigEntry[] | undefined,
   children?: RouteConfigEntry[]
@@ -141,6 +152,10 @@ type CreateIndexOptions = Pick<
   RouteConfigEntry,
   (typeof createIndexOptionKeys)[number]
 >;
+/**
+ * Helper function for creating a route config entry for an index route, for use
+ * within `routes.ts`.
+ */
 function createIndex(
   file: string,
   options?: CreateIndexOptions
@@ -159,6 +174,10 @@ type CreateLayoutOptions = Pick<
   RouteConfigEntry,
   (typeof createLayoutOptionKeys)[number]
 >;
+/**
+ * Helper function for creating a route config entry for a layout route, for use
+ * within `routes.ts`.
+ */
 function createLayout(
   file: string,
   children?: RouteConfigEntry[]
@@ -191,19 +210,41 @@ function createLayout(
 export const route = createRoute;
 export const index = createIndex;
 export const layout = createLayout;
-type RouteHelpers = {
+/**
+ * Creates a set of route config helpers that resolve file paths relative to the
+ * given directory, for use within `routes.ts`. This is designed to support
+ * splitting route config into multiple files within different directories.
+ */
+export function relative(directory: string): {
   route: typeof route;
   index: typeof index;
   layout: typeof layout;
-};
-export function relative(directory: string): RouteHelpers {
+} {
   return {
+    /**
+     * Helper function for creating a route config entry, for use within
+     * `routes.ts`. Note that this helper has been scoped, meaning that file
+     * path will be resolved relative to the directory provided to the
+     * `relative` call that created this helper.
+     */
     route: (path, file, ...rest) => {
       return route(path, resolve(directory, file), ...(rest as any));
     },
+    /**
+     * Helper function for creating a route config entry for an index route, for
+     * use within `routes.ts`. Note that this helper has been scoped, meaning
+     * that file path will be resolved relative to the directory provided to the
+     * `relative` call that created this helper.
+     */
     index: (file, ...rest) => {
       return index(resolve(directory, file), ...(rest as any));
     },
+    /**
+     * Helper function for creating a route config entry for a layout route, for
+     * use within `routes.ts`. Note that this helper has been scoped, meaning
+     * that file path will be resolved relative to the directory provided to the
+     * `relative` call that created this helper.
+     */
     layout: (file, ...rest) => {
       return layout(resolve(directory, file), ...(rest as any));
     },

packages/react-router-dev/package.json

@@ -28,8 +28,8 @@
       "default": "./dist/vite.js"
     },
     "./vite/cloudflare": {
-      "types": "./dist/vite-cloudflare.d.ts",
-      "default": "./dist/vite-cloudflare.js"
+      "types": "./dist/vite/cloudflare.d.ts",
+      "default": "./dist/vite/cloudflare.js"
     },
     "./package.json": "./package.json"
   },

packages/react-router-dev/rollup.config.js

@@ -30,7 +30,7 @@ module.exports = function rollup() {
         `${SOURCE_DIR}/index.ts`,
         `${SOURCE_DIR}/routes.ts`,
         `${SOURCE_DIR}/vite.ts`,
-        `${SOURCE_DIR}/vite-cloudflare.ts`,
+        `${SOURCE_DIR}/vite/cloudflare.ts`,
       ],
       output: {
         banner: createBanner("@react-router/dev", version),

packages/react-router-dev/typedoc.json

@@ -1,3 +1,8 @@
 {
-  "entryPoints": ["./index.ts"]
+  "entryPoints": [
+    "./index.ts",
+    "./routes.ts",
+    "./vite.ts",
+    "./vite/cloudflare.ts"
+  ]
 }

packages/react-router-dev/vite/cloudflare-dev-proxy.ts

@@ -28,12 +28,19 @@ function importWrangler() {
 
 const PLUGIN_NAME = "react-router-cloudflare-vite-dev-proxy";
 
-export const cloudflareDevProxyVitePlugin = <Env, Cf extends CfProperties>({
-  getLoadContext,
-  ...options
-}: {
-  getLoadContext?: GetLoadContext<Env, Cf>;
-} & GetPlatformProxyOptions = {}): Plugin => {
+/**
+ * Vite plugin that provides [Node proxies to local workerd
+ * bindings](https://developers.cloudflare.com/workers/wrangler/api/#getplatformproxy)
+ * to `context.cloudflare` in your server loaders and server actions during
+ * development.
+ */
+export const cloudflareDevProxyVitePlugin = <Env, Cf extends CfProperties>(
+  options: {
+    getLoadContext?: GetLoadContext<Env, Cf>;
+  } & GetPlatformProxyOptions = {}
+): Plugin => {
+  let { getLoadContext, ...restOptions } = options;
+
   return {
     name: PLUGIN_NAME,
     config: () => ({
@@ -59,7 +66,9 @@ export const cloudflareDevProxyVitePlugin = <Env, Cf extends CfProperties>({
     configureServer: async (viteDevServer) => {
       let { getPlatformProxy } = await importWrangler();
       // Do not include `dispose` in Cloudflare context
-      let { dispose, ...cloudflare } = await getPlatformProxy<Env, Cf>(options);
+      let { dispose, ...cloudflare } = await getPlatformProxy<Env, Cf>(
+        restOptions
+      );
       let context = { cloudflare };
       return () => {
         if (!viteDevServer.config.server.middlewareMode) {

packages/react-router-dev/vite-cloudflare.ts renamed to packages/react-router-dev/vite/cloudflare.ts

@@ -1 +1 @@
-export { cloudflareDevProxyVitePlugin as cloudflareDevProxy } from "./vite/cloudflare-dev-proxy";
+export { cloudflareDevProxyVitePlugin as cloudflareDevProxy } from "./cloudflare-dev-proxy";

packages/react-router-dev/vite/plugin.ts

@@ -415,6 +415,9 @@ let deepFreeze = (o: any) => {
 };
 
 type ReactRouterVitePlugin = (config?: ReactRouterConfig) => Vite.Plugin[];
+/**
+ * React Router [Vite plugin.](https://vitejs.dev/guide/using-plugins.html)
+ */
 export const reactRouterVitePlugin: ReactRouterVitePlugin = (_config) => {
   let reactRouterUserConfig = _config ?? {};
 

packages/react-router-fs-routes/index.ts

@@ -9,18 +9,29 @@ import { routeManifestToRouteConfig } from "./manifest";
 import { flatRoutes as flatRoutesImpl } from "./flatRoutes";
 import { normalizeSlashes } from "./normalizeSlashes";
 
-export async function flatRoutes({
-  ignoredRouteFiles,
-  rootDirectory: userRootDirectory = "./routes",
-}: {
-  ignoredRouteFiles?: string[];
+/**
+ * Creates route config from the file system using a convention that matches
+ * [Remix v2's route file
+ * naming](https://remix.run/docs/en/v2/file-conventions/routes-files), for use
+ * within `routes.ts`.
+ */
+export async function flatRoutes(
+  options: {
+    /**
+     * An array of [minimatch](https://www.npmjs.com/package/minimatch) globs that match files to ignore.
+     * Defaults to `[]`.
+     */
+    ignoredRouteFiles?: string[];
 
-  /**
-   * The directory containing file system routes, relative to the app directory.
-   * Defaults to `./routes`.
-   */
-  rootDirectory?: string;
-} = {}): Promise<RouteConfigEntry[]> {
+    /**
+     * The directory containing file system routes, relative to the app directory.
+     * Defaults to `"./routes"`.
+     */
+    rootDirectory?: string;
+  } = {}
+): Promise<RouteConfigEntry[]> {
+  let { ignoredRouteFiles = [], rootDirectory: userRootDirectory = "routes" } =
+    options;
   let appDirectory = getAppDirectory();
   let rootDirectory = path.resolve(appDirectory, userRootDirectory);
   let relativeRootDirectory = path.relative(appDirectory, rootDirectory);

packages/react-router-remix-config-routes-adapter/defineRoutes.ts

@@ -1,7 +1,9 @@
 import type { RouteManifest, RouteManifestEntry } from "./manifest";
 import { normalizeSlashes } from "./normalizeSlashes";
 
-export type DefineRoutesFunction = typeof defineRoutes;
+export type DefineRoutesFunction = (
+  callback: (defineRoute: DefineRouteFunction) => void
+) => RouteManifest;
 
 interface DefineRouteOptions {
   /**
@@ -55,9 +57,7 @@ interface DefineRouteFunction {
  * A function for defining routes programmatically, instead of using the
  * filesystem convention.
  */
-export function defineRoutes(
-  callback: (defineRoute: DefineRouteFunction) => void
-): RouteManifest {
+export const defineRoutes: DefineRoutesFunction = (callback) => {
   let routes: RouteManifest = Object.create(null);
   let parentRoutes: RouteManifestEntry[] = [];
   let alreadyReturned = false;
@@ -119,7 +119,7 @@ export function defineRoutes(
   alreadyReturned = true;
 
   return routes;
-}
+};
 
 function createRouteId(file: string) {
   return normalizeSlashes(stripFileExtension(file));

packages/react-router-remix-config-routes-adapter/index.ts

@@ -5,13 +5,18 @@ import { defineRoutes, type DefineRoutesFunction } from "./defineRoutes";
 
 export type { DefineRoutesFunction };
 
+/**
+ * Adapts routes defined using [Remix's `routes` config
+ * option](https://remix.run/docs/en/v2/file-conventions/vite-config#routes) to
+ * React Router's config format, for use within `routes.ts`.
+ */
 export async function remixConfigRoutes(
-  customRoutes: (
+  routes: (
     defineRoutes: DefineRoutesFunction
   ) =>
     | ReturnType<DefineRoutesFunction>
     | Promise<ReturnType<DefineRoutesFunction>>
 ): Promise<RouteConfigEntry[]> {
-  let routeManifest = await customRoutes(defineRoutes);
+  let routeManifest = await routes(defineRoutes);
   return routeManifestToRouteConfig(routeManifest);
 }