@canonical/summon-application 0.29.0-experimental.0

package/src/application/react/templates/src/lib/ThemeSelector/ThemeSelector.tsx

@@ -0,0 +1,30 @@
+import { usePreferredTheme } from "@canonical/react-hooks";
+import type { ChangeEvent, ReactElement } from "react";
+
+export default function ThemeSelector(): ReactElement {
+  const { value, source, set, reset } = usePreferredTheme();
+
+  function handleChange(event: ChangeEvent<HTMLSelectElement>) {
+    const selected = event.target.value;
+
+    if (selected === "system") {
+      reset();
+    } else {
+      set(selected as "light" | "dark");
+    }
+  }
+
+  const selectValue = source === "system" ? "system" : value;
+
+  return (
+    <select
+      aria-label="Color theme"
+      onChange={handleChange}
+      value={selectValue}
+    >
+      <option value="system">System</option>
+      <option value="light">Light</option>
+      <option value="dark">Dark</option>
+    </select>
+  );
+}

package/src/application/react/templates/src/lib/ThemeSelector/index.ts

@@ -0,0 +1 @@
+export { default } from "./ThemeSelector.js";

package/src/application/react/templates/src/lib/index.ts

@@ -0,0 +1,4 @@
+export { ExampleComponent } from "./ExampleComponent/index.js";
+export { default as LazyComponent } from "./LazyComponent/index.js";
+export { default as Navigation } from "./Navigation/index.js";
+export { default as ThemeSelector } from "./ThemeSelector/index.js";

package/src/application/react/templates/src/routes.tsx.ejs

@@ -0,0 +1,129 @@
+import {
+  type AnyRoute,
+  group,
+  type NavigationContext,
+  type RouteMiddleware,
+  type RouteParamValues,
+  redirect,
+  route,
+  wrapper,
+} from "@canonical/router-core";
+import type { ReactElement, ReactNode } from "react";
+import accountRoutes from "#domains/account/routes.js";
+<% if (forms) { -%>
+import contactRoutes from "#domains/contact/routes.js";
+<% } -%>
+import marketingRoutes from "#domains/marketing/routes.js";
+import Navigation from "#lib/Navigation/index.js";
+
+const protectedPaths = new Set(["/account"]);
+
+function hasDemoAuth(search: unknown): boolean {
+  const authValue = (search as Record<string, unknown>)?.auth;
+
+  return authValue === "1";
+}
+
+export function getAuthRedirectHref(input: string | URL): string | null {
+  // Absolute URLs are used as-is; relative paths resolve against a dummy base.
+  const url =
+    input instanceof URL ? input : new URL(input, "https://router.local");
+
+  if (
+    !protectedPaths.has(url.pathname) ||
+    hasDemoAuth({ auth: url.searchParams.get("auth") })
+  ) {
+    return null;
+  }
+
+  return `/login?from=${encodeURIComponent(url.pathname)}`;
+}
+
+export function withAuth(loginPath: string): RouteMiddleware {
+  return ((currentRoute: AnyRoute) => {
+    if (!protectedPaths.has(currentRoute.url)) {
+      return currentRoute;
+    }
+
+    const currentPrefetch = currentRoute.prefetch;
+
+    return {
+      ...currentRoute,
+      prefetch: (
+        params: unknown,
+        search: unknown,
+        context: NavigationContext,
+      ) => {
+        if (!hasDemoAuth(search)) {
+          const from = currentRoute.render(
+            (params ?? {}) as RouteParamValues | Record<string, never>,
+          );
+
+          redirect(`${loginPath}?from=${encodeURIComponent(from)}`, 302);
+        }
+
+        if (currentPrefetch) {
+          return currentPrefetch(params, search, context);
+        }
+      },
+    };
+  }) as RouteMiddleware;
+}
+
+const publicLayout = wrapper<ReactElement>({
+  id: "public-layout",
+  component: ({ children }: { children: ReactNode }) => (
+    <div className="subgrid app-shell">
+      <header className="subgrid shell-header">
+        <Navigation />
+      </header>
+      <main className="subgrid">{children}</main>
+    </div>
+  ),
+});
+
+const notFoundRoute = route({
+  url: "/not-found",
+  content: () => (
+    <section>
+      <h1>Page not found</h1>
+      <p>The page you are looking for does not exist.</p>
+    </section>
+  ),
+});
+
+const [guide, home] = group(publicLayout, [
+  marketingRoutes.guide,
+  marketingRoutes.home,
+] as const);
+
+const [account, login] = group(publicLayout, [
+  accountRoutes.account,
+  accountRoutes.login,
+] as const);
+
+<% if (forms) { -%>
+const [contact] = group(publicLayout, [contactRoutes.contact] as const);
+
+<% } -%>
+const appRoutes = {
+  guide,
+  home,
+  account,
+  login,
+<% if (forms) { -%>
+  contact,
+<% } -%>
+} as const;
+
+export type AppRoutes = typeof appRoutes;
+
+declare module "@canonical/router-react" {
+  interface RouterRegister {
+    routes: AppRoutes;
+  }
+}
+
+export const middleware = [withAuth("/login")] as const;
+
+export { appRoutes, notFoundRoute };

package/src/application/react/templates/src/server/entry.tsx

@@ -0,0 +1,45 @@
+import { HeadProvider } from "@canonical/react-head";
+import type { ServerEntrypointProps } from "@canonical/react-ssr/renderer";
+import { createStaticRouter } from "@canonical/router-core";
+import { Outlet, RouterProvider } from "@canonical/router-react";
+import { appRoutes, middleware, notFoundRoute } from "../routes.js";
+import "#styles/app.css";
+
+interface InitialData extends Record<string, unknown> {
+  readonly url?: string;
+  /** Colour-scheme preference resolved from the request cookie, if any. */
+  readonly theme?: "light" | "dark";
+}
+
+export default function EntryServer(props: ServerEntrypointProps<InitialData>) {
+  const initialData = props.initialData ?? {};
+  const url = initialData.url ?? "/";
+  const router = createStaticRouter(appRoutes, url, {
+    middleware: [...middleware],
+    notFound: notFoundRoute,
+  });
+
+  // Paint the cookie-resolved theme on <html> for a flash-free first render —
+  // the same element `usePreferredTheme` toggles on the client, and one React
+  // does not hydrate (only `#root` is), so there is no mismatch to reconcile.
+  return (
+    <html lang={props.lang} className={initialData.theme}>
+      <head>
+        {props.otherHeadElements}
+        {props.scriptElements}
+        {props.linkElements}
+      </head>
+      <body>
+        <div id="root">
+          <HeadProvider>
+            <RouterProvider router={router}>
+              <Outlet fallback={<p>Loading…</p>} />
+            </RouterProvider>
+          </HeadProvider>
+        </div>
+      </body>
+    </html>
+  );
+}
+
+export type { InitialData };

package/src/application/react/templates/src/server/preview.bun.ts

@@ -0,0 +1,79 @@
+/**
+ * Bun preview server — serves the compiled production artifact.
+ *
+ * Read this `fetch` handler top-to-bottom as a chain of small, independent
+ * pieces snapped together — the first that can handle the request wins:
+ *
+ *   1. static file      — any extension-bearing path that exists under
+ *                          `dist/client` (`/robots.txt`, `/favicon.*`, the
+ *                          hashed `/assets/*`); extensionless routes fall through.
+ *   2. sitemap renderer — `/sitemap.xml` → the XML `SitemapRenderer`.
+ *   3. JSX app renderer — everything else → the HTML app.
+ *
+ * The two renderers are separate Lego bricks, each built and imported
+ * individually (`createAppRenderer` from the compiled `renderer.js`,
+ * `createSitemapRenderer` from the compiled `sitemap/renderer.js`). They know
+ * nothing about each other or about routing — this server is the only thing
+ * that looks at the URL and picks one, hard-coded right here. The dev server
+ * (`server.bun.ts`) makes the same pick the same way; only the module source
+ * differs (Vite `ssrLoadModule` there, compiled `dist` here).
+ *
+ * Run after `build:client` + `build:server` (the `preview:bun` script does
+ * both). This mirrors how a production deploy serves the same build, so
+ * `preview:bun` is a faithful pre-deploy check. Production itself uses platform
+ * adapters (Vercel, Cloudflare, …), not this server.
+ */
+import * as process from "node:process";
+import {
+  parseStaticPair,
+  resolveStaticFile,
+} from "@canonical/react-ssr/server";
+// The compiled renderers (built by `build:server`) — the same bundled artifacts
+// a production deploy ships. The build output has no `.d.ts`; each default
+// export matches its source factory.
+// @ts-expect-error — importing a build artifact with no declarations
+import createAppRenderer from "../../dist/server/renderer.js";
+// @ts-expect-error — importing a build artifact with no declarations
+import createSitemapRenderer from "../../dist/server/sitemap.js";
+
+type CreateAppRenderer = typeof import("./renderer.js").default;
+type CreateSitemapRenderer = typeof import("../sitemap/renderer.js").default;
+
+const PORT = Number(process.env.PORT) || 5174;
+const staticMount = parseStaticPair(":dist/client");
+
+declare const Bun: {
+  serve(options: {
+    port: number;
+    fetch: (req: Request) => Response | Promise<Response>;
+  }): unknown;
+  file(path: string): Blob & { exists(): Promise<boolean> };
+};
+
+Bun.serve({
+  port: PORT,
+  async fetch(req: Request) {
+    const url = new URL(req.url);
+
+    const filePath = resolveStaticFile(url.pathname, staticMount);
+    if (filePath) {
+      const file = Bun.file(filePath);
+      if (await file.exists()) {
+        return new Response(file);
+      }
+    }
+
+    const renderer =
+      url.pathname === "/sitemap.xml"
+        ? (createSitemapRenderer as CreateSitemapRenderer)()
+        : (createAppRenderer as CreateAppRenderer)(req);
+    const stream = await renderer.renderToReadableStream(req.signal);
+
+    return new Response(stream, {
+      status: renderer.statusCode,
+      headers: { "Content-Type": renderer.contentType },
+    });
+  },
+});
+
+console.log(`Bun preview server on http://localhost:${PORT}/`);

package/src/application/react/templates/src/server/preview.express.ts

@@ -0,0 +1,69 @@
+/**
+ * Express preview server — serves the compiled production artifact.
+ *
+ * The request path is a chain of small, independent pieces snapped together —
+ * the first that can handle the request wins:
+ *
+ *   1. static file      — any extension-bearing path that exists under
+ *                          `dist/client` (`/robots.txt`, `/favicon.*`, the
+ *                          hashed `/assets/*`); extensionless routes fall through.
+ *   2. sitemap renderer — `/sitemap.xml` → the XML `SitemapRenderer`.
+ *   3. JSX app renderer — everything else → the HTML app.
+ *
+ * The two renderers are separate Lego bricks, each built and imported
+ * individually (`createAppRenderer` from the compiled `renderer.js`,
+ * `createSitemapRenderer` from the compiled `sitemap/renderer.js`). They know
+ * nothing about each other or about routing — this server is the only thing
+ * that looks at the URL and picks one, hard-coded right here. The dev server
+ * (`server.express.ts`) makes the same pick the same way; only the module
+ * source differs (Vite `ssrLoadModule` there, compiled `dist` here), and only
+ * the transport differs from `preview.bun.ts` (express streams via
+ * `renderToPipeableStream`, Bun via `renderToReadableStream`).
+ *
+ * Run after `build:client` + `build:server` (the `preview:express` script does
+ * both). Production itself uses platform adapters (Vercel, Cloudflare, …), not
+ * this server.
+ */
+import * as process from "node:process";
+import express from "express";
+// The compiled renderers (built by `build:server`) — the same bundled artifacts
+// a production deploy ships. The build output has no `.d.ts`; each default
+// export matches its source factory.
+// @ts-expect-error — importing a build artifact with no declarations
+import createAppRenderer from "../../dist/server/renderer.js";
+// @ts-expect-error — importing a build artifact with no declarations
+import createSitemapRenderer from "../../dist/server/sitemap.js";
+
+type CreateAppRenderer = typeof import("./renderer.js").default;
+type CreateSitemapRenderer = typeof import("../sitemap/renderer.js").default;
+
+const PORT = Number(process.env.PORT) || 5174;
+
+const app = express();
+
+// Serve any real file under `dist/client` — `/robots.txt`, `/favicon.*`, the
+// hashed `/assets/*`. `express.static` falls through (calls `next`) when the
+// file does not exist, so extensionless routes and rendered ones like
+// `/sitemap.xml` (never written to `dist`) reach the renderers below.
+app.use(express.static("dist/client", { index: false }));
+
+app.use(async (req, res, next) => {
+  try {
+    const renderer =
+      req.path === "/sitemap.xml"
+        ? (createSitemapRenderer as CreateSitemapRenderer)()
+        : (createAppRenderer as CreateAppRenderer)(req);
+    const result = renderer.renderToPipeableStream();
+
+    await renderer.statusReady;
+    res.status(renderer.statusCode);
+    res.setHeader("content-type", renderer.contentType);
+    result.pipe(res);
+  } catch (error) {
+    next(error);
+  }
+});
+
+app.listen(PORT, () => {
+  console.log(`Express preview server on http://localhost:${PORT}/`);
+});

package/src/application/react/templates/src/server/renderer.tsx

@@ -0,0 +1,50 @@
+/**
+ * Compiled JSX app renderer for production / preview.
+ *
+ * Read once at module load, the built `dist/client/index.html` shell carries
+ * the hashed `<script>`/`<link>` tags Vite injected at build time; the renderer
+ * extracts them and injects them into the streamed output.
+ *
+ * This is one Lego brick — a pure renderer. It knows nothing about routing or
+ * about the sitemap renderer; it just turns a request into the rendered app.
+ * The server (`src/server/index.ts` for preview, `server.bun.ts` /
+ * `server.express.ts` for dev) is what looks at the URL and picks a renderer.
+ *
+ * It reuses the same `EntryServer` (`src/server/entry.tsx`) the dev servers
+ * load via `ssrLoadModule` — the renderer is the invariant across dev and
+ * production; only the HTML shell source differs.
+ */
+import fs from "node:fs";
+import type { IncomingMessage } from "node:http";
+import path from "node:path";
+import { extractPreferences } from "@canonical/react-hooks";
+import { JSXRenderer } from "@canonical/react-ssr/renderer";
+import { getRequestUrl } from "@canonical/react-ssr/server";
+import EntryServer, { type InitialData } from "./entry.js";
+
+const htmlString = fs.readFileSync(
+  path.join(process.cwd(), "dist", "client", "index.html"),
+  "utf-8",
+);
+
+/** Read the `Cookie` header from either a Web `Request` or a Node request. */
+function cookieHeader(request: Request | IncomingMessage): string | null {
+  return typeof (request as Request).headers?.get === "function"
+    ? (request as Request).headers.get("cookie")
+    : ((request as IncomingMessage).headers?.cookie ?? null);
+}
+
+/**
+ * Per-request factory for the JSX app renderer. Accepts either a Web `Request`
+ * (`serve-bun`) or a Node `IncomingMessage` (`serve-express`); it derives the
+ * URL for routing and the cookie-backed theme so the first paint matches the
+ * user's preference, passing both as the renderer's initial data.
+ */
+export default function createAppRenderer(request: Request | IncomingMessage) {
+  const { theme } = extractPreferences(cookieHeader(request));
+  const initialData: InitialData = {
+    url: getRequestUrl(request),
+    theme: theme === "light" || theme === "dark" ? theme : undefined,
+  };
+  return new JSXRenderer(EntryServer, initialData, { htmlString });
+}

package/src/application/react/templates/src/server/server.bun.ts

@@ -0,0 +1,105 @@
+/**
+ * Bun development server with SSR and streaming.
+ *
+ * Read this `fetch` handler top-to-bottom as a chain of small, independent
+ * pieces snapped together — each tries to handle the request, and the first
+ * that can, wins:
+ *
+ *   1. `handleAsset`     — Vite client assets + HMR (/@vite/client, /src/**,
+ *                          /@id/**, /@fs/**, /@react-refresh, /node_modules/.vite/**).
+ *   2. sitemap renderer  — `/sitemap.xml` → the XML `SitemapRenderer`.
+ *   3. JSX app renderer  — everything else → the HTML app.
+ *
+ * The two renderers are separate Lego bricks: the sitemap renderer
+ * (`src/sitemap/renderer.ts`) and the app renderer (`src/server/renderer.tsx`)
+ * know nothing about each other or about routing — this server is the only
+ * thing that looks at the URL and picks one. Swap a brick, add a `/robots.txt`
+ * brick, or reorder them without touching the others. The same three pieces
+ * appear in the same order in `server.express.ts` and in the compiled server
+ * entrypoint (`src/server/index.ts`) the preview bins use, so dev and preview
+ * behave identically.
+ *
+ * Bun.serve() is the HTTP layer; Vite runs in middleware mode for transforms +
+ * HMR; server modules load via vite.ssrLoadModule() so edits are picked up
+ * without a restart. Production deploys use platform adapters (Vercel,
+ * Cloudflare, …), not this server.
+ */
+import fs from "node:fs";
+import * as process from "node:process";
+import { viteFetchMiddleware } from "@canonical/react-ssr/server";
+import { createServer as createViteServer } from "vite";
+
+const PORT = Number(process.env.PORT) || 5174;
+
+const vite = await createViteServer({
+  server: { middlewareMode: true },
+  appType: "custom",
+});
+
+// Serve Vite's client assets/HMR; returns null for page routes (→ SSR below).
+const handleAsset = viteFetchMiddleware(vite);
+
+Bun.serve({
+  port: PORT,
+  async fetch(req: Request) {
+    const url = new URL(req.url);
+    const requestUrl = url.pathname + url.search;
+
+    try {
+      const asset = await handleAsset(req);
+      if (asset) return asset;
+
+      if (url.pathname === "/sitemap.xml") {
+        const { default: createSitemapRenderer } = await vite.ssrLoadModule(
+          "/src/sitemap/renderer.ts",
+        );
+        const renderer = createSitemapRenderer();
+        const stream = await renderer.renderToReadableStream(req.signal);
+
+        return new Response(stream, {
+          status: renderer.statusCode,
+          headers: { "Content-Type": renderer.contentType },
+        });
+      }
+
+      const template = fs.readFileSync("index.html", "utf-8");
+      const html = await vite.transformIndexHtml(requestUrl, template);
+
+      const { default: EntryServer } = await vite.ssrLoadModule(
+        "/src/server/entry.tsx",
+      );
+      const { JSXRenderer } = await vite.ssrLoadModule(
+        "@canonical/react-ssr/renderer",
+      );
+      const { extractPreferences } = await vite.ssrLoadModule(
+        "@canonical/react-hooks",
+      );
+
+      const { theme } = extractPreferences(req.headers.get("cookie"));
+      const renderer = new JSXRenderer(
+        EntryServer,
+        // The cookie is client-controlled, so only the known theme values reach
+        // the SSR `<html class>` — anything else is dropped (matches the
+        // compiled renderer in `renderer.tsx`).
+        {
+          url: requestUrl,
+          theme: theme === "light" || theme === "dark" ? theme : undefined,
+        },
+        { htmlString: html },
+      );
+      const stream = await renderer.renderToReadableStream(req.signal);
+
+      return new Response(stream, {
+        status: renderer.statusCode,
+        headers: { "Content-Type": renderer.contentType },
+      });
+    } catch (error) {
+      vite.ssrFixStacktrace(error as Error);
+      console.error(error);
+
+      return new Response("Internal server error", { status: 500 });
+    }
+  },
+});
+
+console.log(`Bun dev server on http://localhost:${PORT}/`);

package/src/application/react/templates/src/server/server.express.ts

@@ -0,0 +1,102 @@
+/**
+ * Express development server with SSR and HMR.
+ *
+ * The request path is a chain of small, independent pieces snapped together —
+ * the first that can handle the request wins:
+ *
+ *   1. `vite.middlewares` — Vite client assets, module transforms, HMR.
+ *   2. sitemap renderer   — `/sitemap.xml` → the XML `SitemapRenderer`.
+ *   3. JSX app renderer   — everything else → the HTML app.
+ *
+ * The two renderers are separate Lego bricks: the sitemap renderer
+ * (`src/sitemap/renderer.ts`) and the app renderer (`src/server/renderer.tsx`)
+ * know nothing about each other or about routing — this middleware is the only
+ * thing that looks at the URL and picks one. Add a `/robots.txt` brick or swap
+ * a renderer without touching the others. The same pieces, in the same order,
+ * appear in `server.bun.ts` and in the compiled server entrypoint
+ * (`src/server/index.ts`) the preview bins use, so dev and preview behave
+ * identically — only the transport differs (express streams via
+ * `renderToPipeableStream`, Bun via `renderToReadableStream`).
+ *
+ * Vite handles client HMR + module transforms; server modules load via
+ * vite.ssrLoadModule() so edits are picked up without a restart. Production
+ * deploys use platform adapters (Vercel, Cloudflare, …), not this server.
+ */
+import fs from "node:fs";
+import * as process from "node:process";
+import express from "express";
+import { createServer as createViteServer } from "vite";
+
+const PORT = Number(process.env.PORT) || 5174;
+
+async function start() {
+  const app = express();
+
+  const vite = await createViteServer({
+    server: { middlewareMode: true },
+    appType: "custom",
+  });
+
+  app.use(vite.middlewares);
+
+  app.use(async (req, res, next) => {
+    const url = req.originalUrl || "/";
+
+    try {
+      if (url.split("?")[0] === "/sitemap.xml") {
+        const { default: createSitemapRenderer } = await vite.ssrLoadModule(
+          "/src/sitemap/renderer.ts",
+        );
+        const renderer = createSitemapRenderer();
+        const result = renderer.renderToPipeableStream();
+
+        await renderer.statusReady;
+        res.status(renderer.statusCode);
+        res.setHeader("content-type", renderer.contentType);
+        result.pipe(res);
+        return;
+      }
+
+      const template = fs.readFileSync("index.html", "utf-8");
+      const html = await vite.transformIndexHtml(url, template);
+
+      const { default: EntryServer } = await vite.ssrLoadModule(
+        "/src/server/entry.tsx",
+      );
+      const { JSXRenderer } = await vite.ssrLoadModule(
+        "@canonical/react-ssr/renderer",
+      );
+      const { extractPreferences } = await vite.ssrLoadModule(
+        "@canonical/react-hooks",
+      );
+
+      const { theme } = extractPreferences(req.headers.cookie ?? null);
+      const renderer = new JSXRenderer(
+        EntryServer,
+        // The cookie is client-controlled, so only the known theme values reach
+        // the SSR `<html class>` — anything else is dropped (matches the
+        // compiled renderer in `renderer.tsx`).
+        {
+          url,
+          theme: theme === "light" || theme === "dark" ? theme : undefined,
+        },
+        { htmlString: html },
+      );
+      const result = renderer.renderToPipeableStream();
+
+      await renderer.statusReady;
+      res.status(renderer.statusCode);
+      res.setHeader("content-type", renderer.contentType);
+      result.pipe(res);
+    } catch (error) {
+      vite.ssrFixStacktrace(error as Error);
+      next(error);
+    }
+  });
+
+  app.listen(PORT, () => {
+    console.log(`Express dev server on http://localhost:${PORT}/`);
+  });
+}
+
+start();

package/src/application/react/templates/src/sitemap/getSitemapItems.ts.ejs

@@ -0,0 +1,31 @@
+import type { SitemapItem } from "@canonical/react-ssr/renderer";
+
+/**
+ * Returns sitemap entries for all known routes.
+ *
+ * Update this list as you add domains and routes. For dynamic content
+ * (blog posts, product pages), fetch entries from your data source.
+ *
+ * @example
+ * const posts = await fetchPosts();
+ * return [
+ *   ...staticEntries,
+ *   ...posts.map((post) => ({
+ *     loc: `/blog/${post.slug}`,
+ *     lastmod: post.updatedAt,
+ *     changefreq: "weekly" as const,
+ *     priority: 0.7,
+ *   })),
+ * ];
+ */
+export default async function getSitemapItems(): Promise<SitemapItem[]> {
+  return [
+    { loc: "/", changefreq: "weekly", priority: 1.0 },
+    { loc: "/guides/router-core", changefreq: "monthly", priority: 0.8 },
+<% if (forms) { -%>
+    { loc: "/contact", changefreq: "monthly", priority: 0.7 },
+<% } -%>
+    { loc: "/account", changefreq: "monthly", priority: 0.5 },
+    { loc: "/login", changefreq: "yearly", priority: 0.3 },
+  ];
+}