Docs updates for lazy/Component/ErrorBoundary (#10178)

Author: brophdawg11

docs/route/lazy.md

@@ -59,4 +59,70 @@ export function ErrorBoundary() {
 ErrorBoundary.displayName = "SampleErrorBoundary";
 ```
 
+## Statically Defined Properties
+
+Any properties defined statically on the route cannot be overwritten by the `lazy` function, and you'll receive a console warning if you attempt to overwrite them.
+
+Additionally, as an optimization, if you statically define a `loader`/`action` then it will be called in parallel with the `lazy` function. This is useful if you have slim loaders that you don't mind on the critical bundle, and would like to kick off their data fetches in parallel with the component download. This is close to how Remix handles fetching because each route is it's own API route.
+
+```js
+let route = {
+  path: "projects",
+  loader: ({ request }) => fetchDataForUrl(request.url),
+  lazy: () => import("./projects"),
+};
+```
+
+This also allows you to do more granular code splitting. For example, you could split your `loader` and `Component` into different files for parallel downloading:
+
+```js
+let route = {
+  path: "projects",
+  async loader({ request, params }) {
+    let { loader } = await import("./projects-loader");
+    return loader({ request, params });
+  },
+  lazy: () => import("./projects-component"),
+};
+```
+
+## Multiple Routes in a single file
+
+While `lazy` may generally be used 1:1 with an async `import()` per route, you are free to implement a more advanced `lazy` function and just need to return the properties you want added to that route. This opens up some interesting possibilities.
+
+For example, if you want to avoid loading multiple chunks for nested routes, you could store them all in the same file and return them to the individual routes. Modern bundlers will latch onto the same Promise for the different `import()` invocations.
+
+```js
+// Assume pages/Dashboard.jsx has all of our loaders/components for multiple
+// dashboard routes
+let dashboardRoute = {
+  path: "dashboard",
+  async lazy() {
+    let { Layout } = await import("./pages/Dashboard");
+    return { Component: Layout };
+  },
+  children: [
+    {
+      index: true,
+      async lazy() {
+        let { Index } = await import("./pages/Dashboard");
+        return { Component: Index };
+      },
+    },
+    {
+      path: "messages",
+      async lazy() {
+        let { messagesLoader, Messages } = await import(
+          "./pages/Dashboard"
+        );
+        return {
+          loader: messagesLoader,
+          Component: Messages,
+        };
+      },
+    },
+  ],
+};
+```
+
 [pickingarouter]: ../routers/picking-a-router

docs/route/route.md

@@ -296,17 +296,27 @@ The route action is called when a submission is sent to the route from a [Form][
 
 Please see the [action][action] documentation for more details.
 
-## `element`
+## `element`/`Component`
 
-The element to render when the route matches the URL.
+The React Element/Component to render when the route matches the URL.
+
+If you want to create the React Element, use `element`:
 
 ```tsx
 <Route path="/for-sale" element={<Properties />} />
 ```
 
-## `errorElement`
+Otherwise use `Component` and React Router will create the React Element for you:
+
+```tsx
+<Route path="/for-sale" Component={Properties} />
+```
+
+## `errorElement`/`ErrorBoundary`
 
-When a route throws an exception while rendering, in a `loader` or in an `action`, this element will render instead of the normal `element`.
+When a route throws an exception while rendering, in a `loader` or in an `action`, this React Element/Component will render instead of the normal `element`/`Component`.
+
+If you want to create the React Element on your own, use `errorElement`:
 
 ```tsx
 <Route
@@ -324,6 +334,20 @@ When a route throws an exception while rendering, in a `loader` or in an `action
 />
 ```
 
+Otherwise use `ErrorBoundary` and React Router will create the React Element for you:
+
+```tsx
+<Route
+  path="/for-sale"
+  Component={Properties}
+  loader={() => loadProperties()}
+  action={async ({ request }) =>
+    createProperty(await request.formData())
+  }
+  ErrorBoundary={ErrorBoundary}
+/>
+```
+
 <docs-warning>If you are not using a data router like [`createBrowserRouter`][createbrowserrouter], this will do nothing</docs-warning>
 
 Please see the [errorElement][errorelement] documentation for more details.