=> ({
+ highlights: [
+ "SSR and hydration share one route map.",
+ "Protected routes redirect through local middleware.",
+ "Domain modules compose into a single app shell.",
+ ],
+ }),
+ content: ({ data }: { data: HomeData }): ReactElement => {
+ return (
+
+ Router boilerplate
+ Canonical router integration demo
+
+ This boilerplate demonstrates SSR, hydration, hover prefetch, and an
+ auth redirect using the new router packages.
+
+
+ {data.highlights.map((highlight: string) => (
+ - {highlight}
+ ))}
+
+
+ );
+ },
+ }),
+} as const;
+
+export default marketingRoutes;
diff --git a/apps/react/boilerplate-vite/src/index.css b/apps/react/boilerplate-vite/src/index.css
index 886796f19..2f2035778 100644
--- a/apps/react/boilerplate-vite/src/index.css
+++ b/apps/react/boilerplate-vite/src/index.css
@@ -1 +1,17 @@
@import url("@canonical/styles");
+
+:root {
+ background:
+ radial-gradient(circle at top, rgba(15, 98, 254, 0.12), transparent 28%),
+ linear-gradient(180deg, #f8fafc 0%, #eef2ff 100%);
+ color: #111827;
+ font-family: Inter, "Segoe UI", sans-serif;
+}
+
+body {
+ margin: 0;
+}
+
+a {
+ color: inherit;
+}
diff --git a/apps/react/boilerplate-vite/src/routes.test.tsx b/apps/react/boilerplate-vite/src/routes.test.tsx
new file mode 100644
index 000000000..a8b437d64
--- /dev/null
+++ b/apps/react/boilerplate-vite/src/routes.test.tsx
@@ -0,0 +1,154 @@
+import { route } from "@canonical/router-core";
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+ appRoutes,
+ createHydratedAppRouter,
+ createServerAppRouter,
+ getAuthRedirectHref,
+ hasDemoAuth,
+ normalizeRequestHref,
+ withAuth,
+} from "./routes.js";
+
+describe("app routes", () => {
+ afterEach(() => {
+ delete (window as Window & { __INITIAL_DATA__?: unknown }).__INITIAL_DATA__;
+ window.history.replaceState({}, "", "/");
+ });
+
+ it("renders the home route on the server router", async () => {
+ const router = createServerAppRouter();
+ const result = await router.load("/");
+
+ render({router.render(result) as ReactNode}
);
+
+ expect(
+ screen.getByRole("heading", {
+ name: "Canonical router integration demo",
+ }),
+ ).toBeInTheDocument();
+ });
+
+ it("redirects the protected route to login when auth is missing", async () => {
+ const router = createServerAppRouter();
+ const result = await router.load("/account");
+
+ render({router.render(result) as ReactNode}
);
+
+ expect(result.location.href).toBe("/login?from=%2Faccount");
+ expect(
+ screen.getByRole("heading", {
+ name: "Sign in to the demo account",
+ }),
+ ).toBeInTheDocument();
+ expect(screen.getByText("/account")).toBeInTheDocument();
+ });
+
+ it("loads the protected route when the demo auth token is present", async () => {
+ const router = createServerAppRouter();
+ const result = await router.load("/account?auth=1");
+
+ render({router.render(result) as ReactNode}
);
+
+ expect(result.location.href).toBe("/account?auth=1");
+ expect(
+ screen.getByRole("heading", {
+ name: "Protected account workspace",
+ }),
+ ).toBeInTheDocument();
+ });
+
+ it("hydrates the current route from window.__INITIAL_DATA__", async () => {
+ const serverRouter = createServerAppRouter();
+
+ await serverRouter.load("/guides/router-core");
+
+ (window as Window & { __INITIAL_DATA__?: unknown }).__INITIAL_DATA__ =
+ serverRouter.dehydrate();
+ window.history.replaceState({}, "", "/guides/router-core");
+
+ const router = createHydratedAppRouter();
+
+ render({router.render() as ReactNode}
);
+
+ expect(
+ screen.getByRole("heading", {
+ name: "Guide: router-core",
+ }),
+ ).toBeInTheDocument();
+ });
+
+ it("renders the login page for direct visits and the not-found route for misses", async () => {
+ const loginRouter = createServerAppRouter();
+ const loginResult = await loginRouter.load("/login");
+
+ render({loginRouter.render(loginResult) as ReactNode}
);
+
+ expect(screen.getByText("direct visit")).toBeInTheDocument();
+
+ const missingRouter = createServerAppRouter();
+ const missingResult = await missingRouter.load("/missing");
+
+ render({missingRouter.render(missingResult) as ReactNode}
);
+
+ expect(
+ screen.getByRole("heading", {
+ name: "Page not found",
+ }),
+ ).toBeInTheDocument();
+ });
+
+ it("covers helper edge cases and middleware passthrough behavior", async () => {
+ const middleware = withAuth("/login");
+ const publicRoute = route({
+ url: "/public",
+ content: () => "public",
+ });
+ const bareProtectedRoute = route({
+ url: "/account",
+ content: () => "account",
+ });
+ const wrappedPublicRoute = middleware(publicRoute);
+ const wrappedProtectedRoute = middleware(bareProtectedRoute);
+
+ expect(wrappedPublicRoute).toBe(publicRoute);
+
+ // Call the middleware-wrapped fetch directly. The middleware operates on
+ // `unknown` params/search internally, so we cast to exercise the auth
+ // check paths without satisfying the route's own strict param types.
+ const fetch = wrappedProtectedRoute.fetch as (
+ params: unknown,
+ search: unknown,
+ context: { signal: AbortSignal },
+ ) => Promise;
+
+ await expect(
+ fetch({}, { auth: "1" }, { signal: new AbortController().signal }),
+ ).resolves.toBeNull();
+ await expect(
+ fetch({}, {}, { signal: new AbortController().signal }),
+ ).rejects.toMatchObject({
+ status: 302,
+ to: "/login?from=%2Faccount",
+ });
+ expect(hasDemoAuth({ auth: "1" })).toBe(true);
+ expect(hasDemoAuth({ auth: "0" })).toBe(false);
+ expect(getAuthRedirectHref("/account")).toBe("/login?from=%2Faccount");
+ expect(getAuthRedirectHref("/account?auth=1")).toBeNull();
+ expect(getAuthRedirectHref("/guides/router-core")).toBeNull();
+ expect(
+ getAuthRedirectHref(new URL("https://example.com/account?auth=1#top")),
+ ).toBeNull();
+ expect(
+ normalizeRequestHref(new URL("https://example.com/account?auth=1#top")),
+ ).toBe("/account?auth=1#top");
+ expect(normalizeRequestHref("https://example.com/guides/router-core")).toBe(
+ "/guides/router-core",
+ );
+ expect(appRoutes.guide.render({ slug: "router-core" })).toBe(
+ "/guides/router-core",
+ );
+ });
+});
diff --git a/apps/react/boilerplate-vite/src/routes.tsx b/apps/react/boilerplate-vite/src/routes.tsx
new file mode 100644
index 000000000..a3a3b4bbb
--- /dev/null
+++ b/apps/react/boilerplate-vite/src/routes.tsx
@@ -0,0 +1,152 @@
+import {
+ type AnyRoute,
+ createRouter,
+ group,
+ type NavigationContext,
+ type RouteMap,
+ type RouteMiddleware,
+ type RouteParamValues,
+ type RouterDehydratedState,
+ redirect,
+ route,
+ wrapper,
+} from "@canonical/router-core";
+import { createHydratedRouter } from "@canonical/router-react";
+import type { ReactElement, ReactNode } from "react";
+import accountRoutes from "./domains/account/routes.js";
+import marketingRoutes from "./domains/marketing/routes.js";
+
+const protectedPaths = new Set(["/account"]);
+
+function toUrl(input: string | URL): URL {
+ if (input instanceof URL) {
+ return input;
+ }
+
+ if (input.startsWith("http://") || input.startsWith("https://")) {
+ return new URL(input);
+ }
+
+ return new URL(input, "https://router.local");
+}
+
+function toHref(input: string | URL): string {
+ const url = toUrl(input);
+
+ return `${url.pathname}${url.search}${url.hash}`;
+}
+
+export function hasDemoAuth(search: unknown): boolean {
+ const authValue = (search as Record)?.auth;
+
+ return authValue === "1";
+}
+
+export function getAuthRedirectHref(input: string | URL): string | null {
+ const url = toUrl(input);
+
+ 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 currentFetch = currentRoute.fetch;
+
+ return {
+ ...currentRoute,
+ fetch: async (
+ params: unknown,
+ search: unknown,
+ context: NavigationContext,
+ ) => {
+ if (!hasDemoAuth(search)) {
+ const from = currentRoute.render(
+ (params ?? {}) as RouteParamValues | Record,
+ );
+
+ redirect(`${loginPath}?from=${encodeURIComponent(from)}`, 302);
+ }
+
+ if (currentFetch) {
+ return currentFetch(params, search, context);
+ }
+
+ return null;
+ },
+ };
+ }) as RouteMiddleware;
+}
+
+const publicLayout = wrapper({
+ id: "public-layout",
+ component: ({ children }: { children: ReactNode }): ReactElement => (
+ {children}
+ ),
+});
+
+const [guide, home] = group(publicLayout, [
+ marketingRoutes.guide,
+ marketingRoutes.home,
+] as const);
+
+export const appRoutes = {
+ guide,
+ home,
+ ...accountRoutes,
+} as const;
+
+export type AppRoutes = typeof appRoutes;
+export type AppInitialData = RouterDehydratedState;
+
+declare module "@canonical/router-react" {
+ interface RouterRegister {
+ routes: AppRoutes;
+ }
+}
+
+const notFoundRoute = route({
+ url: "/404",
+ content: (): ReactElement => {
+ return (
+
+ Fallback route
+ Page not found
+
+ The boilerplate also wires a typed not-found route for unmatched URLs.
+
+
+ );
+ },
+});
+
+export function createServerAppRouter(
+ initialData?: RouterDehydratedState,
+) {
+ return createRouter(appRoutes, {
+ hydratedState: initialData,
+ middleware: [withAuth("/login")],
+ notFound: notFoundRoute,
+ });
+}
+
+export function createHydratedAppRouter() {
+ return createHydratedRouter(appRoutes, {
+ middleware: [withAuth("/login")],
+ notFound: notFoundRoute,
+ });
+}
+
+export function normalizeRequestHref(input: string | URL): string {
+ return toHref(input);
+}
diff --git a/apps/react/boilerplate-vite/src/ssr/Shell.tsx b/apps/react/boilerplate-vite/src/ssr/Shell.tsx
index e39d7ca98..aac6bc559 100644
--- a/apps/react/boilerplate-vite/src/ssr/Shell.tsx
+++ b/apps/react/boilerplate-vite/src/ssr/Shell.tsx
@@ -1,37 +1,34 @@
import type { ServerEntrypointProps } from "@canonical/react-ssr/renderer";
-import Application from "../Application.js";
+import type { ReactElement, ReactNode } from "react";
+
+interface ShellProps extends ServerEntrypointProps> {
+ readonly children: ReactNode;
+ readonly navigation: ReactNode;
+}
export type InitialData = Record;
-/**
- * This function returns the component that renders the full page both in the Server and in the
- * Client (as it needs to match exactly for hydration to work).
- * If you need to pass the initial data to the Renderer constructor.
- *
- * @param props props can be all automatically extracted by the renderer from the HTML index page
- * or can be provided programmatically to the renderer constructor.
- * @returns root component containing all the HTML of the page to be rendered.
- */
-function Shell(props: ServerEntrypointProps) {
+export default function Shell(props: ShellProps): ReactElement {
return (
- Canonical React Vite Boilerplate
+ Canonical router boilerplate
+
{props.otherHeadElements}
{props.scriptElements}
{props.linkElements}
- {
- // Add the following to pass initial data to the Application:
- //
- }
-
+
+ {props.navigation}
+ {props.children}
+