@funstack/router 0.0.7 → 0.0.9

package/dist/docs/GettingStartedPage.tsx

@@ -26,8 +26,13 @@ yarn add @funstack/router`}</CodeBlock>
         <CodeBlock language="bash">{`npx funstack-router-skill-installer`}</CodeBlock>
         <p>
           The installer will guide you through setting up the skill for your
-          preferred AI agent.
+          preferred AI agent. Alternatively, if you prefer{" "}
+          <a href="https://skills.sh/" target="_blank">
+            npx skills
+          </a>
+          , you can install it with:
         </p>
+        <CodeBlock language="bash">{`npx skills add uhyo/funstack-router`}</CodeBlock>
       </section>
 
       <section>
@@ -113,34 +118,6 @@ const routes = [
     component: UserProfile,
   }),
 ];`}</CodeBlock>
-        <p>
-          Alternatively, you can use the <code>useParams</code> hook to access
-          parameters:
-        </p>
-        <CodeBlock language="tsx">{`import { useParams } from "@funstack/router";
-
-function UserProfile() {
-  const params = useParams<{ userId: string }>();
-  return <h1>User: {params.userId}</h1>;
-}`}</CodeBlock>
-      </section>
-
-      <section>
-        <h2>Programmatic Navigation</h2>
-        <p>
-          Use the <code>useNavigate</code> hook for programmatic navigation:
-        </p>
-        <CodeBlock language="tsx">{`import { useNavigate } from "@funstack/router";
-
-function MyComponent() {
-  const navigate = useNavigate();
-
-  const handleClick = () => {
-    navigate("/about");
-  };
-
-  return <button onClick={handleClick}>Go to About</button>;
-}`}</CodeBlock>
       </section>
 
       <section>
@@ -164,21 +141,21 @@ function UserProfilePage({
   data: Promise<User>;
   params: { userId: string };
 }) {
-  const user = use(data);
   return (
     <Suspense fallback={<div>Loading...</div>}>
-      <UserProfile user={user} params={params} />
+      <UserProfile data={data} params={params} />
     </Suspense>
   );
 }
 
 function UserProfile({
-  user,
+  data,
   params,
 }: {
-  user: User;
+  data: Promise<User>;
   params: { userId: string };
 }) {
+  const user = use(data);
   return (
     <div>
       <h1>{user.name}</h1>

package/dist/docs/LearnNavigationApiPage.tsx

@@ -155,15 +155,12 @@ function Navigation() {
         <p>
           While FUNSTACK Router handles navigation for you, you can interact
           directly with the Navigation API when needed. This is useful for
-          features like scroll-to-top behavior or analytics tracking.
+          features like analytics tracking.
         </p>
         <CodeBlock language="tsx">{`import { useEffect } from "react";
 
 function App() {
   useEffect(() => {
-    const navigation = window.navigation;
-    if (!navigation) return;
-
     const controller = new AbortController();
 
     // Listen for successful navigation completion

package/dist/docs/LearnNestedRoutesPage.tsx

@@ -338,7 +338,7 @@ const routes = [
         <CodeBlock language="tsx">{`import { use, Suspense } from "react";
 import { route, Outlet, useRouteData } from "@funstack/router";
 
-// Define the parent route with a loader
+// Define the parent route with a loader and child routes
 const teamRoute = route({
   id: "team",
   path: "/teams/:teamId",
@@ -347,9 +347,14 @@ const teamRoute = route({
     const response = await fetch(\`/api/teams/\${params.teamId}\`);
     return response.json();
   },
+  children: [
+    route({ path: "/", component: TeamOverview }),
+    route({ path: "/members", component: TeamMembers }),
+    route({ path: "/settings", component: TeamSettings }),
+  ],
 });
 
-// Parent layout loads team data once
+// Parent layout loads team data once, child routes render in <Outlet />
 function TeamLayoutContent({
   data,
 }: {
@@ -439,10 +444,7 @@ function TeamLayout(props: {
           Pathless routes also play a key role in server-side rendering. During
           SSR, only pathless routes render (since no URL is available on the
           server), making them ideal for defining the app shell. See the{" "}
-          <a href="/funstack-router/learn/server-side-rendering">
-            Server-Side Rendering
-          </a>{" "}
-          page for details.
+          <a href="/learn/ssr">Server-Side Rendering</a> page for details.
         </p>
       </section>
 

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,64 +168,77 @@ 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>
+          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>
       </section>
 
@@ -259,32 +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="/funstack-router/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,9 +1,9 @@
 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.
@@ -13,7 +13,7 @@ export function LearnSsrPage() {
       </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:
@@ -21,10 +21,9 @@ export function LearnSsrPage() {
         <p>
           <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. Pathless routes
-          with loaders are skipped because there is no request context to run
-          them. This produces the app shell &mdash; layouts, headers, navigation
-          chrome, and other structural markup.
+          <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
@@ -34,13 +33,12 @@ export function LearnSsrPage() {
         </p>
         <CodeBlock language="tsx">{`// What renders at each stage:
 
-// Stage 1 (Server)         Stage 2 (Client)
-// ─────────────────        ─────────────────
-// App shell (pathless      App shell (pathless)
-//   without loader)
-// ✗ No path routes         ✓ Path routes match
-// ✗ No loaders             ✓ Loaders execute
-// ✗ No URL available       ✓ URL from Navigation API`}</CodeBlock>
+// Stage 1 (Server)                   Stage 2 (Client)
+// ───────────────────────────        ─────────────────
+// App shell (pathless routes)        App shell (pathless)
+//                                    ✓ Path routes match
+// ✗ No loaders                       ✓ Loaders execute
+// ✗ No URL available                 ✓ URL from Navigation API`}</CodeBlock>
       </section>
 
       <section>
@@ -149,15 +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>
-            During SSR, only pathless routes without loaders render (no URL or
-            request context 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>
+            <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>
-            Path-based routes, loaders, and pathless routes with loaders
-            activate after client hydration
+            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,
@@ -170,8 +193,8 @@ function HomePage() {
             app shell
           </li>
           <li>
-            This two-stage model keeps SSR output lightweight while enabling
-            full interactivity on the client
+            Once the client hydrates, the real URL from the Navigation API takes
+            over
           </li>
         </ul>
       </section>