@funstack/router 0.0.8 → 0.0.9

package/dist/docs/LearnRscPage.tsx

@@ -27,8 +27,7 @@ export function LearnRscPage() {
           <code>"use client"</code> because it exports components and hooks that
           depend on browser APIs (the Navigation API, React context, etc.). This
           means importing from <code>@funstack/router</code> in a server module
-          would pull the entire router into the client bundle &mdash; defeating
-          the purpose of RSC.
+          would fail.
         </p>
         <p>
           To solve this, the package provides a separate entry point:{" "}
@@ -68,9 +67,8 @@ export default function App() {
           In this example, <code>App</code> is a server component. It builds the
           route array using <code>route()</code> from{" "}
           <code>@funstack/router/server</code> and renders the{" "}
-          <code>Router</code> component from <code>@funstack/router</code>.
-          Since <code>Router</code> is a client component, the RSC bundler
-          handles the client boundary automatically.
+          <code>Router</code> component from <code>@funstack/router</code> which
+          is a client component.
         </p>
         <h4>What the server entry point exports</h4>
         <ul>
@@ -90,45 +88,29 @@ export default function App() {
         </ul>
       </section>
 
-      <section>
-        <h3>The Client Boundary</h3>
-        <p>
-          The <code>Router</code> component subscribes to the Navigation API and
-          manages React state, so it is a client component. It serves as the
-          client boundary in your component tree &mdash; server components above
-          it construct the route definitions, while <code>Router</code> and its
-          runtime dependencies run in the browser.
-        </p>
-        <p>
-          Route definitions (paths, component references, children) are plain
-          serializable data, so they can be passed from a server component into{" "}
-          <code>Router</code> as props.
-        </p>
-      </section>
-
       <section>
         <h3>Defining Routes in the Server Context</h3>
         <p>
-          Because route definitions are plain data (paths, component references,
-          and children), they can be constructed entirely on the server. The{" "}
-          <code>route()</code> helper from <code>@funstack/router/server</code>{" "}
-          produces the same <code>RouteDefinition</code> objects as the one from
-          the main entry point &mdash; the only difference is that it does not
-          pull in client-side code.
+          Route definitions can be defined in server modules because they are{" "}
+          <strong>plain data structures</strong> except for page components and
+          loader functions. Fortunately, it is possible to import both of these
+          from client modules which results in client references that can be
+          passed from the server to the client through the <code>routes</code>{" "}
+          prop.
         </p>
         <CodeBlock language="tsx">{`// App.tsx — Server Component
 import { Router } from "@funstack/router";
 import { route } from "@funstack/router/server";
 import { lazy } from "react";
 
-// Lazy-load page components — these will be code-split
-const HomePage = lazy(() => import("./pages/HomePage.js"));
-const DashboardPage = lazy(() => import("./pages/DashboardPage.js"));
-const SettingsPage = lazy(() => import("./pages/SettingsPage.js"));
+// Import page components from client modules
+import HomePage from "./pages/HomePage.js";
+import DashboardPage from "./pages/DashboardPage.js";
+import SettingsPage from "./pages/SettingsPage.js";
 
 const routes = [
   route({
-    component: <Layout />,
+    component: Layout,
     children: [
       route({ path: "/", component: HomePage }),
       route({ path: "/dashboard", component: DashboardPage }),
@@ -140,13 +122,6 @@ const routes = [
 export default function App() {
   return <Router routes={routes} />;
 }`}</CodeBlock>
-        <p>
-          Note that page components referenced in route definitions can be
-          either server components or client components. When a page component
-          uses hooks or browser APIs, it should have the{" "}
-          <code>"use client"</code> directive. Otherwise, it can remain a server
-          component for optimal performance.
-        </p>
 
         <h4>Loaders in an RSC Context</h4>
         <p>
@@ -169,7 +144,7 @@ import { dashboardLoader } from "./loaders/dashboard.js";
 
 const routes = [
   route({
-    component: <Layout />,
+    component: Layout,
     children: [
       route({ path: "/", component: HomePage }),
       route({
@@ -193,80 +168,78 @@ export default function App() {
       </section>
 
       <section>
-        <h3>A Complete Example</h3>
+        <h3>Using Server Components as Route Components</h3>
         <p>
-          This documentation site itself uses this pattern. Here is a simplified
-          version of how it is structured:
+          All examples so far have used client components as route components,
+          but you can go even further and{" "}
+          <strong>use server components as route components</strong>. Actually,
+          this is the primary use case for the RSC support in FUNSTACK Router
+          &mdash; it allows pre-rendering each route on the server (or at build
+          time for static sites).
         </p>
-        <CodeBlock language="tsx">{`// vite.config.ts
-import funstackStatic from "@funstack/static";
-import react from "@vitejs/plugin-react";
-import { defineConfig } from "vite";
 
-export default defineConfig({
-  plugins: [
-    funstackStatic({
-      root: "./src/Root.tsx",  // Server Component — HTML shell
-      app: "./src/App.tsx",    // Server Component — route definitions
-      ssr: true,
-    }),
-    react(),
-  ],
-});`}</CodeBlock>
-        <CodeBlock language="tsx">{`// Root.tsx — Server Component (HTML shell)
-import type { ReactNode } from "react";
-
-export default function Root({ children }: { children: ReactNode }) {
-  return (
-    <html lang="en">
-      <head>
-        <meta charSet="UTF-8" />
-        <title>My App</title>
-      </head>
-      <body>{children}</body>
-    </html>
-  );
-}`}</CodeBlock>
-        <CodeBlock language="tsx">{`// App.tsx — Server Component (route definitions)
+        <h4>Use React Node as Route Components</h4>
+        <p>
+          When you use server components as route components, the route's{" "}
+          <code>component</code> must be a React node (i.e.{" "}
+          <code>&lt;MyComponent /&gt;</code>) instead of a component reference
+          (i.e. <code>MyComponent</code>) because a references to server
+          components cannot be passed to the client.
+        </p>
+        <CodeBlock language="tsx">{`// App.tsx — Server Component
 import { Router } from "@funstack/router";
 import { route } from "@funstack/router/server";
-import { Layout } from "./components/Layout.js";
-import { HomePage } from "./pages/HomePage.js";
-import { AboutPage } from "./pages/AboutPage.js";
+import HomePage from "./pages/HomePage.js";
+import AboutPage from "./pages/AboutPage.js";
 
 const routes = [
   route({
     component: <Layout />,
     children: [
-      route({ path: "/", component: HomePage }),
-      route({ path: "/about", component: AboutPage }),
+      route({ path: "/", component: <HomePage /> }),
+      route({ path: "/about", component: <AboutPage /> }),
     ],
   }),
 ];
 
 export default function App() {
-  return <Router routes={routes} fallback="static" />;
+  return <Router routes={routes} />;
 }`}</CodeBlock>
         <p>
-          In this setup, <code>Root</code> and <code>App</code> are server
-          components. The route definitions are constructed on the server and
-          passed into <code>Router</code>, which acts as the client boundary.
+          In this example, <code>HomePage</code> and <code>AboutPage</code> are
+          server components. They are rendered on the server and the resulting
+          HTML is sent to the client.
         </p>
         <p>
-          If the server knows the requested pathname, you can pass it via the{" "}
-          <code>ssrPathname</code> prop so that path-based routes render during
-          SSR (see the <a href="/learn/server-side-rendering">SSR guide</a> for
-          details):
+          Due to this nature, a route component defined as a server component{" "}
+          <em>cannot</em> receive route props (params, search params, navigation
+          state, etc). We are exploring ways to lift this limitation in the
+          future, but for now if you need to access route props you will need to
+          use client components as route components.
+        </p>
+        <p>
+          For some use cases it is enough to have a client component child as a
+          pathless route:
+        </p>
+        <CodeBlock language="tsx">{`const routes = [
+  route({
+    path: "/",
+    component: <HomePage />, // Server Component
+    children: [
+      route({
+        component: InteractivePartOfHomePage, // Client Component
+        loader: someLoaderForHomePage,
+      }),
+    ],
+  }),
+];`}</CodeBlock>
+        <p>
+          In this example, <code>HomePage</code> is a server component that
+          renders the static parts of the page while{" "}
+          <code>InteractivePartOfHomePage</code> is a client component that can
+          access route props (like loader data). <code>HomePage</code> can
+          render <code>&lt;Outlet /&gt;</code> to render its child routes.
         </p>
-        <CodeBlock language="tsx">{`export default function App({ pathname }: { pathname: string }) {
-  return (
-    <Router
-      routes={routes}
-      fallback="static"
-      ssrPathname={pathname}
-    />
-  );
-}`}</CodeBlock>
       </section>
 
       <section>
@@ -274,30 +247,27 @@ export default function App() {
         <ul>
           <li>
             Import <code>route</code> and <code>routeState</code> from{" "}
-            <code>@funstack/router/server</code> in server modules to avoid
-            pulling client code into the server module graph
+            <code>@funstack/router/server</code> to define routes in server
+            modules
           </li>
           <li>
             <code>Router</code> is a client component and serves as the client
             boundary &mdash; render it directly from your server component
           </li>
-          <li>
-            Route definitions are plain data and can be constructed entirely on
-            the server
-          </li>
           <li>
             Loaders run client-side &mdash; define them in{" "}
             <code>"use client"</code> modules and import them into your route
             definitions
           </li>
           <li>
-            Page components can be either server components or client components
-            depending on whether they need browser APIs or hooks
+            Page components can be either server components or client
+            components; if using server components, define them as React nodes
+            (e.g. <code>&lt;MyPage /&gt;</code>) instead of component references
+            (e.g. <code>MyPage</code>)
           </li>
           <li>
-            See also the{" "}
-            <a href="/learn/server-side-rendering">Server-Side Rendering</a>{" "}
-            guide for how the router handles SSR and hydration
+            See also the <a href="/learn/ssr">Server-Side Rendering</a> guide
+            for how the router handles SSR and hydration
           </li>
         </ul>
       </section>

package/dist/docs/LearnSsgPage.tsx

@@ -0,0 +1,133 @@
+import { CodeBlock } from "../components/CodeBlock.js";
+
+export function LearnSsgPage() {
+  return (
+    <div className="learn-content">
+      <h2>Static Site Generation</h2>
+
+      <p className="page-intro">
+        When your server or static site generator knows the URL being rendered,
+        you can use the <code>ssr</code> prop to match path-based routes during
+        SSR. This produces richer server-rendered HTML &mdash; users see page
+        content immediately instead of just the app shell.
+      </p>
+
+      <section>
+        <h3>
+          How the <code>ssr</code> Prop Works
+        </h3>
+        <p>
+          As described in the <a href="/learn/ssr">How SSR Works</a> guide, the
+          router normally has no URL during SSR and only renders pathless
+          routes. The <code>ssr</code> prop provides a pathname so path-based
+          routes can also match during SSR:
+        </p>
+        <CodeBlock language="tsx">{`// Server knows the requested URL and passes it to the router
+<Router routes={routes} ssr={{ path: "/about" }} />`}</CodeBlock>
+        <p>
+          When <code>ssr</code> is provided, the router matches path-based
+          routes against <code>ssr.path</code> just as it would match against
+          the real URL on the client. Route params are extracted normally.
+          Routes with loaders are skipped by default &mdash; the parent route
+          renders as a shell, and loader content fills in after hydration.
+        </p>
+        <p>
+          Once the client hydrates, the real URL from the Navigation API takes
+          over and <code>ssr</code> is ignored.
+        </p>
+      </section>
+
+      <section>
+        <h3>Example</h3>
+        <p>
+          Consider a route tree with a mix of static pages and loader-based
+          routes:
+        </p>
+        <CodeBlock language="tsx">{`const routes = [
+  route({
+    component: AppShell,
+    children: [
+      route({ path: "/", component: HomePage }),      // Matches ssr.path="/"
+      route({ path: "/about", component: AboutPage }),// Matches ssr.path="/about"
+      route({
+        path: "/dashboard",
+        component: DashboardPage,
+        loader: dashboardLoader, // Skipped during SSR (has loader)
+      }),
+    ],
+  }),
+];
+
+// With ssr={{ path: "/about" }}:
+// - AppShell renders (pathless, no loader) ✓
+// - AboutPage renders (path matches, no loader) ✓
+// - DashboardPage would NOT render with ssr={{ path: "/dashboard" }}
+//   because it has a loader`}</CodeBlock>
+      </section>
+
+      <section>
+        <h3>
+          When to Use <code>ssr</code>
+        </h3>
+        <p>
+          Use the <code>ssr</code> prop when your server or static site
+          generator knows the URL being rendered and you want to include
+          page-specific content in the SSR output. This is common for static
+          site generation, but can also be used in dynamic SSR scenarios where
+          the server can determine the URL at request time.
+        </p>
+        <p>This is particularly useful for:</p>
+        <ul>
+          <li>
+            Improving perceived performance by showing page content immediately
+            instead of a blank shell
+          </li>
+          <li>
+            SEO &mdash; search engine crawlers see the full page content rather
+            than just the app shell
+          </li>
+          <li>
+            Static site generation where each page is pre-rendered at a known
+            path
+          </li>
+        </ul>
+      </section>
+
+      <section>
+        <h3>Routes with Loaders</h3>
+        <p>
+          Routes with loaders are skipped by default during SSR. If your
+          application has a server runtime that can execute loaders at request
+          time, see the <a href="/learn/ssr/with-loaders">SSR with Loaders</a>{" "}
+          guide.
+        </p>
+        <p>
+          If you only need loaders to run at build time (not on the client),
+          consider using{" "}
+          <a href="/learn/react-server-components">React Server Components</a>{" "}
+          with SSG. RSC lets you fetch data on the server during the build and
+          send the result as static HTML, without shipping loader code to the
+          client.
+        </p>
+      </section>
+
+      <section>
+        <h3>Key Takeaways</h3>
+        <ul>
+          <li>
+            Use <code>ssr</code> to enable path-based route matching during SSR
+            for richer server-rendered output
+          </li>
+          <li>
+            Routes with loaders are skipped during SSR by default; the parent
+            route renders as a shell and loader content fills in after hydration
+          </li>
+          <li>
+            After hydration, the real URL from the Navigation API takes over and{" "}
+            <code>ssr</code> is ignored
+          </li>
+        </ul>
+      </section>
+    </div>
+  );
+}

package/dist/docs/{LearnSsrPage.tsx → LearnSsrBasicPage.tsx}

@@ -1,35 +1,29 @@
 import { CodeBlock } from "../components/CodeBlock.js";
 
-export function LearnSsrPage() {
+export function LearnSsrBasicPage() {
   return (
     <div className="learn-content">
-      <h2>Server-Side Rendering</h2>
+      <h2>How SSR Works</h2>
 
       <p className="page-intro">
         FUNSTACK Router supports server-side rendering with a two-stage model.
         During SSR, pathless (layout) routes without loaders render to produce
         an app shell, while path-based routes and loaders activate only after
-        client hydration. You can optionally provide an <code>ssrPathname</code>{" "}
-        prop to match path-based routes during SSR for richer server-rendered
-        output.
+        client hydration.
       </p>
 
       <section>
-        <h3>How SSR Works</h3>
+        <h3>Two-Stage Rendering</h3>
         <p>
           FUNSTACK Router uses a two-stage rendering model that separates what
           renders on the server from what renders on the client:
         </p>
         <p>
-          <strong>Stage 1 &mdash; Server:</strong> By default, no URL is
-          available on the server. The router matches only pathless routes
-          (routes without a <code>path</code> property) that do not have a
-          loader. This produces the app shell &mdash; layouts, headers,
-          navigation chrome, and other structural markup. When{" "}
-          <code>ssrPathname</code> is provided, the router also matches
-          path-based routes against that pathname, enabling richer
-          server-rendered content. In both cases, routes with loaders are always
-          skipped during SSR.
+          <strong>Stage 1 &mdash; Server:</strong> No URL is available on the
+          server. The router matches only pathless routes (routes without a{" "}
+          <code>path</code> property) that do not have a loader. This produces
+          the app shell &mdash; layouts, headers, navigation chrome, and other
+          structural markup.
         </p>
         <p>
           <strong>Stage 2 &mdash; Client hydration:</strong> Once the browser
@@ -42,8 +36,7 @@ export function LearnSsrPage() {
 // Stage 1 (Server)                   Stage 2 (Client)
 // ───────────────────────────        ─────────────────
 // App shell (pathless routes)        App shell (pathless)
-// + path routes if ssrPathname       ✓ Path routes match
-//   is provided (no loaders)
+//                                    ✓ Path routes match
 // ✗ No loaders                       ✓ Loaders execute
 // ✗ No URL available                 ✓ URL from Navigation API`}</CodeBlock>
       </section>
@@ -78,76 +71,6 @@ export function LearnSsrPage() {
         </p>
       </section>
 
-      <section>
-        <h3>
-          Path-Based SSR with <code>ssrPathname</code>
-        </h3>
-        <p>
-          By default, only pathless routes render during SSR because the server
-          has no URL. The <code>ssrPathname</code> prop lets you provide a
-          pathname so path-based routes can also match during SSR, producing
-          fuller server-rendered HTML.
-        </p>
-        <CodeBlock language="tsx">{`// Server knows the requested URL and passes it to the router
-<Router routes={routes} ssrPathname="/about" />`}</CodeBlock>
-        <p>
-          When <code>ssrPathname</code> is provided, the router matches
-          path-based routes against it just as it would match against the real
-          URL on the client. Route params are extracted normally. However,
-          routes with loaders are always skipped during SSR regardless of this
-          setting &mdash; there is no request context available to run them.
-        </p>
-        <p>
-          Once the client hydrates, the real URL from the Navigation API takes
-          over and <code>ssrPathname</code> is ignored.
-        </p>
-        <CodeBlock language="tsx">{`const routes = [
-  route({
-    component: AppShell,
-    children: [
-      route({ path: "/", component: HomePage }),      // Matches ssrPathname="/"
-      route({ path: "/about", component: AboutPage }),// Matches ssrPathname="/about"
-      route({
-        path: "/dashboard",
-        component: DashboardPage,
-        loader: dashboardLoader, // Skipped during SSR (has loader)
-      }),
-    ],
-  }),
-];
-
-// With ssrPathname="/about":
-// - AppShell renders (pathless, no loader) ✓
-// - AboutPage renders (path matches, no loader) ✓
-// - DashboardPage would NOT render even with ssrPathname="/dashboard"
-//   because it has a loader`}</CodeBlock>
-        <h4>When to use ssrPathname</h4>
-        <p>
-          Use <code>ssrPathname</code> when your server or static site generator
-          knows the URL being rendered and you want to include page-specific
-          content in the SSR output. This is particularly useful for:
-        </p>
-        <ul>
-          <li>
-            Improving perceived performance by showing page content immediately
-            instead of a blank shell
-          </li>
-          <li>
-            SEO &mdash; search engine crawlers see the full page content rather
-            than just the app shell
-          </li>
-          <li>
-            Static site generation where each page is pre-rendered at a known
-            path
-          </li>
-        </ul>
-        <p>
-          If your routes have loaders, those routes will still be skipped during
-          SSR. The parent route renders as a shell, and the loader content fills
-          in after hydration.
-        </p>
-      </section>
-
       <section>
         <h3>Hooks and SSR</h3>
         <p>
@@ -224,19 +147,40 @@ function HomePage() {
       </section>
 
       <section>
-        <h3>Key Takeaways</h3>
+        <h3>Going Beyond the App Shell</h3>
+        <p>
+          The default SSR behavior produces only the app shell. This is perfect
+          for ordinary SPAs where only one HTML page is served and the client
+          takes over all routing. SSR can still be useful in this scenario,
+          normally with a static site generator, to improve perceived
+          performance by showing the shell immediately while the rest of the
+          page loads.
+        </p>
+        <p>
+          If your server or build tool knows the URL being rendered, you can use
+          the <code>ssr</code> prop to match path-based routes during SSR for
+          richer output:
+        </p>
         <ul>
           <li>
-            By default, only pathless routes without loaders render during SSR
-            (no URL is available on the server)
+            <a href="/learn/ssr/static-site-generation">
+              Static Site Generation
+            </a>{" "}
+            &mdash; pre-render pages at known paths without running loaders
           </li>
           <li>
-            Use <code>ssrPathname</code> to enable path-based route matching
-            during SSR for richer server-rendered output
+            <a href="/learn/ssr/with-loaders">SSR with Loaders</a> &mdash;
+            render pages with loader data on the server for fully dynamic SSR
           </li>
+        </ul>
+      </section>
+
+      <section>
+        <h3>Key Takeaways</h3>
+        <ul>
           <li>
-            Routes with loaders are always skipped during SSR, regardless of{" "}
-            <code>ssrPathname</code>
+            Only pathless routes without loaders render during SSR (no URL is
+            available on the server)
           </li>
           <li>
             Pathless routes are ideal for app shell markup (headers, footers,