Add some comments to the multi-app example

Author: mjackson

examples/multi-app/README.md

@@ -1,4 +1,6 @@
-# Multi Page Example
+# Multi App Example
+
+This example demonstrates how to build a site with multiple React Router apps by mounting each at a URL pathname prefix using the `<Router basename>` prop. This essentially decouples the apps from each other and allows them to be portable and even deployed separately.
 
 ## Preview
 

examples/multi-app/home/App.jsx

@@ -34,6 +34,10 @@ function Layout() {
             <Link to="/about">About</Link>
           </li>
           <li>
+            {/* Use a normal <a> when linking to the "Inbox" app so the browser
+                does a full document reload, which is what we want when exiting
+                this app and entering another so we execute its entry point in
+                inbox/main.jsx. */}
             <a href="/inbox">Inbox</a>
           </li>
         </ul>

examples/multi-app/home/main.jsx

@@ -6,6 +6,7 @@ import HomeApp from "./App";
 
 ReactDOM.render(
   <React.StrictMode>
+    {/* No basename for this router. This app renders at the root / URL. */}
     <BrowserRouter>
       <HomeApp />
     </BrowserRouter>

examples/multi-app/inbox/App.jsx

@@ -6,6 +6,10 @@ import { NoMatch } from "./no-match";
 export default function InboxApp() {
   return (
     <Routes>
+      {/* Routes in this app don't need to worry about which URL prefix they are
+          mounted at. They can just assume they are mounted at /. Then, if they
+          are moved under a different basename later on, all routes and links will
+          continue to work. */}
       <Route path="/" element={<Layout />}>
         <Route index element={<Inbox />} />
         <Route path=":id" element={<Message />} />
@@ -22,6 +26,10 @@ function Layout() {
       <nav>
         <ul>
           <li>
+            {/* Using a normal link here will cause the browser to reload the
+                document when following this link, which is exactly what we want
+                when transitioning to the "Home" app so we execute its entry
+                point (see home/main.jsx). */}
             <a href="/">Home</a>
           </li>
           <li>

examples/multi-app/inbox/main.jsx

@@ -6,6 +6,8 @@ import InboxApp from "./App";
 
 ReactDOM.render(
   <React.StrictMode>
+    {/* "Mount" this app under the /inbox URL pathname. All routes and links
+        are relative to this name. */}
     <BrowserRouter basename="inbox">
       <InboxApp />
     </BrowserRouter>

examples/multi-app/server.js

@@ -26,6 +26,7 @@ async function createServer() {
   app.use("*", async (req, res) => {
     let url = req.originalUrl;
 
+    // Use a separate HTML file for the "Inbox" app.
     let appDirectory = url.startsWith("/inbox") ? "inbox" : "";
     let htmlFileToLoad;
 

examples/multi-app/vite.config.js

@@ -17,6 +17,7 @@ export default defineConfig({
   ],
   build: {
     rollupOptions: {
+      // Build two separate bundles, one for each app.
       input: {
         main: path.resolve(__dirname, "index.html"),
         inbox: path.resolve(__dirname, "inbox/index.html")