zudoku 0.3.0-dev.31 → 0.3.0-dev.32

package/lib/zudoku.plugin-markdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"zudoku.plugin-markdown.js","sources":["../src/lib/plugins/markdown/generateRoutes.tsx","../src/lib/plugins/markdown/index.tsx"],"sourcesContent":["import { Navigate, type RouteObject } from \"react-router-dom\";\nimport { useTopNavigationItem } from \"../../components/context/DevPortalProvider.js\";\nimport { isPathItem } from \"../../components/navigation/util.js\";\nimport { traverseNavigation } from \"../../util/traverseNavigation.js\";\n\nimport {\n  MarkdownPluginDefaultOptions,\n  MarkdownPluginOptions,\n} from \"./index.js\";\n\nexport const generateRoutes = (\n  markdownFiles: MarkdownPluginOptions[\"markdownFiles\"],\n  defaultOptions?: MarkdownPluginDefaultOptions,\n): RouteObject[] => {\n  const routes = Object.entries(markdownFiles).flatMap(\n    ([file, importPromise]) => {\n      // @todo we can pass in the folder name and then filter the markdown files based on that path\n      const match = file.match(/pages\\/(.*).mdx?$/);\n      const path = match?.at(1);\n\n      if (!path) return [];\n\n      const pathSegments = path.split(\"/\");\n      const isIndexFile = pathSegments.at(-1) === \"index\";\n      const routePath = isIndexFile\n        ? pathSegments.slice(0, -1).join(\"/\")\n        : path;\n\n      return {\n        path: routePath,\n        lazy: async () => {\n          const { MdxPage } = await import(\"./MdxPage.js\");\n          const { default: Component, ...props } = await importPromise();\n          return {\n            element: (\n              <MdxPage\n                mdxComponent={Component}\n                {...props}\n                defaultOptions={defaultOptions}\n              />\n            ),\n          };\n        },\n      } satisfies RouteObject;\n    },\n  );\n\n  const rootRoutes = Array.from(\n    new Set(routes.map((route) => route.path.split(\"/\").at(0))),\n  ).map((dir) => ({\n    path: `/${dir}`,\n    element: <Redirect />,\n  }));\n\n  return [...routes, ...rootRoutes];\n};\n\nconst Redirect = () => {\n  const navItem = useTopNavigationItem();\n\n  if (!navItem) return null;\n\n  return traverseNavigation(navItem, (node, fullPath) => {\n    if (\"children\" in node || !isPathItem(node)) return;\n    return <Navigate to={fullPath} replace />;\n  });\n};\n","import type { Toc } from \"@stefanprobst/rehype-extract-toc\";\nimport type { MDXProps } from \"mdx/types.js\";\nimport type { DevPortalPlugin } from \"../../core/plugins.js\";\nimport { generateRoutes } from \"./generateRoutes.js\";\n\nexport type MarkdownPluginOptions = {\n  markdownFiles: Record<string, () => Promise<MDXImport>>;\n  defaultOptions?: MarkdownPluginDefaultOptions;\n};\nexport type MarkdownPluginDefaultOptions = Pick<\n  Frontmatter,\n  \"toc\" | \"disablePager\"\n>;\n\nexport type Frontmatter = {\n  title?: string;\n  description?: string;\n  category?: string;\n  toc?: boolean;\n  disablePager?: boolean;\n};\n\nexport type MDXImport = {\n  tableOfContents: Toc;\n  frontmatter: Frontmatter;\n  default: (props: MDXProps) => JSX.Element;\n};\n\nexport const markdownPlugin = ({\n  markdownFiles,\n  defaultOptions,\n}: MarkdownPluginOptions): DevPortalPlugin => {\n  return {\n    getRoutes() {\n      return generateRoutes(markdownFiles, defaultOptions);\n    },\n  };\n};\n"],"names":["generateRoutes","markdownFiles","defaultOptions","routes","file","importPromise","match","path","pathSegments","MdxPage","Component","props","jsx","rootRoutes","route","dir","Redirect","navItem","useTopNavigationItem","traverseNavigation","node","fullPath","isPathItem","Navigate","markdownPlugin"],"mappings":";;;;AAUa,MAAAA,IAAiB,CAC5BC,GACAC,MACkB;AAClB,QAAMC,IAAS,OAAO,QAAQF,CAAa,EAAE;AAAA,IAC3C,CAAC,CAACG,GAAMC,CAAa,MAAM;AAEnB,YAAAC,IAAQF,EAAK,MAAM,mBAAmB,GACtCG,IAAOD,KAAA,gBAAAA,EAAO,GAAG;AAEnB,UAAA,CAACC,EAAM,QAAO;AAEZ,YAAAC,IAAeD,EAAK,MAAM,GAAG;AAM5B,aAAA;AAAA,QACL,MANkBC,EAAa,GAAG,EAAE,MAAM,UAExCA,EAAa,MAAM,GAAG,EAAE,EAAE,KAAK,GAAG,IAClCD;AAAA,QAIF,MAAM,YAAY;AAChB,gBAAM,EAAE,SAAAE,EAAA,IAAY,MAAM,OAAO,uBAAc,GACzC,EAAE,SAASC,GAAW,GAAGC,EAAM,IAAI,MAAMN;AACxC,iBAAA;AAAA,YACL,SACEO,gBAAAA,EAAA;AAAA,cAACH;AAAA,cAAA;AAAA,gBACC,cAAcC;AAAA,gBACb,GAAGC;AAAA,gBACJ,gBAAAT;AAAA,cAAA;AAAA,YACF;AAAA,UAAA;AAAA,QAGN;AAAA,MAAA;AAAA,IAEJ;AAAA,EAAA,GAGIW,IAAa,MAAM;AAAA,IACvB,IAAI,IAAIV,EAAO,IAAI,CAACW,MAAUA,EAAM,KAAK,MAAM,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAAA,EAAA,EAC1D,IAAI,CAACC,OAAS;AAAA,IACd,MAAM,IAAIA,CAAG;AAAA,IACb,+BAAUC,GAAS,EAAA;AAAA,EACnB,EAAA;AAEF,SAAO,CAAC,GAAGb,GAAQ,GAAGU,CAAU;AAClC,GAEMG,IAAW,MAAM;AACrB,QAAMC,IAAUC;AAEZ,SAACD,IAEEE,EAAmBF,GAAS,CAACG,GAAMC,MAAa;AACrD,QAAI,gBAAcD,KAAQ,CAACE,EAAWF,CAAI;AAC1C,aAAQR,gBAAAA,EAAAA,IAAAW,GAAA,EAAS,IAAIF,GAAU,SAAO,GAAC,CAAA;AAAA,EAAA,CACxC,IALoB;AAMvB,GCtCaG,IAAiB,CAAC;AAAA,EAC7B,eAAAvB;AAAA,EACA,gBAAAC;AACF,OACS;AAAA,EACL,YAAY;AACH,WAAAF,EAAeC,GAAeC,CAAc;AAAA,EACrD;AAAA;"}
+{"version":3,"file":"zudoku.plugin-markdown.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/lib/zudoku.plugin-openapi.js

@@ -1,8 +1,10 @@
-import "./jsx-runtime-SV6hXQua.js";
-import { o as t } from "./index-Cpdpun6t.js";
+import "./jsx-runtime-CM0TzjGp.js";
+import { o as n } from "./index-BoWzKb_9.js";
 import "./urql-DMlBWUKL.js";
 import "virtual:zudoku-openapi-worker";
+import "./MdxComponents-Ev_hBHb2.js";
+import "./router-CcYTwKjf.js";
 export {
-  t as openApiPlugin
+  n as openApiPlugin
 };
 //# sourceMappingURL=zudoku.plugin-openapi.js.map

package/lib/zudoku.plugin-openapi.js.map

@@ -1 +1 @@
-{"version":3,"file":"zudoku.plugin-openapi.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}
+{"version":3,"file":"zudoku.plugin-openapi.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;"}

package/lib/zudoku.plugin-redirect.js

@@ -1,12 +1,11 @@
-import { j as s } from "./jsx-runtime-SV6hXQua.js";
-import { N as i } from "./index-DLS6fPwU.js";
-const p = (t) => ({
-  getRoutes: () => t.redirects.map(({ from: e, to: r, replace: o }) => ({
-    path: e,
-    element: /* @__PURE__ */ s.jsx(i, { to: r, replace: o })
+import { b as o } from "./router-CcYTwKjf.js";
+const i = (e) => ({
+  getRoutes: () => e.redirects.map(({ from: r, to: t, replace: a }) => ({
+    path: r,
+    loader: () => o(t)
   }))
 });
 export {
-  p as redirectPlugin
+  i as redirectPlugin
 };
 //# sourceMappingURL=zudoku.plugin-redirect.js.map

package/lib/zudoku.plugin-redirect.js.map

@@ -1 +1 @@
-{"version":3,"file":"zudoku.plugin-redirect.js","sources":["../src/lib/plugins/redirect/index.tsx"],"sourcesContent":["import { Navigate } from \"react-router-dom\";\nimport type { DevPortalPlugin } from \"../../core/plugins.js\";\n\nexport type Redirect = {\n  from: string;\n  to: string;\n  replace?: boolean;\n};\n\nexport const redirectPlugin = (options: {\n  redirects: Redirect[];\n}): DevPortalPlugin => {\n  return {\n    getRoutes: () =>\n      options.redirects.map(({ from, to, replace }) => ({\n        path: from,\n        element: <Navigate to={to} replace={replace} />,\n      })),\n  };\n};\n"],"names":["redirectPlugin","options","from","to","replace","jsx","Navigate"],"mappings":";;AASa,MAAAA,IAAiB,CAACC,OAGtB;AAAA,EACL,WAAW,MACTA,EAAQ,UAAU,IAAI,CAAC,EAAE,MAAAC,GAAM,IAAAC,GAAI,SAAAC,SAAe;AAAA,IAChD,MAAMF;AAAA,IACN,SAASG,gBAAAA,EAAAA,IAACC,GAAS,EAAA,IAAAH,GAAQ,SAAAC,EAAkB,CAAA;AAAA,EAAA,EAC7C;AAAA;"}
+{"version":3,"file":"zudoku.plugin-redirect.js","sources":["../src/lib/plugins/redirect/index.tsx"],"sourcesContent":["import { redirect } from \"react-router-dom\";\nimport type { DevPortalPlugin } from \"../../core/plugins.js\";\n\nexport type Redirect = {\n  from: string;\n  to: string;\n  replace?: boolean;\n};\n\nexport const redirectPlugin = (options: {\n  redirects: Redirect[];\n}): DevPortalPlugin => {\n  return {\n    getRoutes: () =>\n      options.redirects.map(({ from, to, replace }) => ({\n        path: from,\n        loader: () => redirect(to),\n      })),\n  };\n};\n"],"names":["redirectPlugin","options","from","to","replace","redirect"],"mappings":";AASa,MAAAA,IAAiB,CAACC,OAGtB;AAAA,EACL,WAAW,MACTA,EAAQ,UAAU,IAAI,CAAC,EAAE,MAAAC,GAAM,IAAAC,GAAI,SAAAC,SAAe;AAAA,IAChD,MAAMF;AAAA,IACN,QAAQ,MAAMG,EAASF,CAAE;AAAA,EAAA,EACzB;AAAA;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.3.0-dev.31",
+  "version": "0.3.0-dev.32",
   "type": "module",
   "files": [
     "dist",
@@ -64,6 +64,7 @@
   "dependencies": {
     "@envelop/core": "5.0.1",
     "@graphql-typed-document-node/core": "3.2.0",
+    "@hiogawa/vite-plugin-ssr-css": "0.0.0",
     "@lekoarts/rehype-meta-as-attributes": "3.0.1",
     "@mdx-js/react": "3.0.1",
     "@mdx-js/rollup": "3.0.1",

package/src/app/entry.client.tsx

@@ -0,0 +1,51 @@
+import { StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { HelmetProvider } from "react-helmet-async";
+import {
+  createBrowserRouter,
+  matchRoutes,
+  type RouteObject,
+  RouterProvider,
+} from "react-router-dom";
+import "virtual:vite-zudoku-custom-css.css";
+import config from "virtual:zudoku-config";
+
+import "virtual:vite-zudoku-custom-css.css";
+import "./main.css";
+
+import { getRoutesByConfig } from "./main.js";
+
+void hydrate();
+
+export async function hydrateLazyRoutes(routes: RouteObject[]) {
+  const lazyMatches = matchRoutes(routes, window.location)?.filter(
+    (m) => m.route.lazy,
+  );
+
+  if (lazyMatches?.length) {
+    await Promise.all(
+      lazyMatches.map(async (m) => {
+        const routeModule = await m.route.lazy!();
+        Object.assign(m.route, { ...routeModule, lazy: undefined });
+      }),
+    );
+  }
+}
+
+async function hydrate() {
+  const routes = getRoutesByConfig(config);
+
+  await hydrateLazyRoutes(routes);
+
+  const router = createBrowserRouter(routes);
+  const root = document.getElementById("root")!;
+
+  hydrateRoot(
+    root,
+    <StrictMode>
+      <HelmetProvider>
+        <RouterProvider router={router} />
+      </HelmetProvider>
+    </StrictMode>,
+  );
+}

package/src/app/entry.server.tsx

@@ -0,0 +1,158 @@
+import type express from "express";
+import logger from "loglevel";
+import { Transform } from "node:stream";
+import { StrictMode } from "react";
+import { renderToPipeableStream, renderToStaticMarkup } from "react-dom/server";
+import { HelmetData, HelmetProvider } from "react-helmet-async";
+import { isRouteErrorResponse } from "react-router-dom";
+import {
+  createStaticHandler,
+  createStaticRouter,
+  StaticRouterProvider,
+} from "react-router-dom/server.js";
+import "virtual:vite-zudoku-custom-css.css";
+import config from "virtual:zudoku-config";
+import { ServerError } from "../lib/errors/ServerError.js";
+import "./main.css";
+import { getRoutesByConfig } from "./main.js";
+
+export const render = async ({
+  template,
+  expressRequest,
+  fetchRequest,
+  response,
+}: {
+  template: string;
+  expressRequest?: express.Request;
+  fetchRequest?: Request;
+  response: express.Response;
+}) => {
+  const routes = getRoutesByConfig(config);
+  const { query, dataRoutes } = createStaticHandler(routes);
+
+  const request = expressRequest
+    ? createFetchRequest(expressRequest, response)
+    : fetchRequest;
+
+  if (!request) {
+    throw new Error("Either fetchRequest or expressRequest must be provided");
+  }
+  const context = await query(request);
+  let status = 200;
+
+  if (context instanceof Response) {
+    if ([301, 302, 303, 307, 308].includes(context.status)) {
+      return response.redirect(
+        context.status,
+        context.headers.get("Location")!,
+      );
+    }
+
+    throw context;
+  } else if (context.errors) {
+    // when throwing a Response from a loader it will be caught here
+    // unfortunately it is not `instanceof Response` for some reason
+    const firstError = Object.values(context.errors).find(isRouteErrorResponse);
+
+    if (firstError?.status) {
+      status = firstError.status;
+    }
+  }
+
+  const router = createStaticRouter(dataRoutes, context);
+  const helmetContext = {} as HelmetData["context"];
+
+  const { pipe } = renderToPipeableStream(
+    <StrictMode>
+      <HelmetProvider context={helmetContext}>
+        <StaticRouterProvider router={router} context={context} />
+      </HelmetProvider>
+    </StrictMode>,
+    {
+      onShellError(error) {
+        response.status(500);
+        response.set({ "Content-Type": "text/html" });
+
+        const html = renderToStaticMarkup(<ServerError error={error} />);
+
+        response.send(html);
+      },
+      // for SSG we could use onAllReady instead of onShellReady
+      // https://react.dev/reference/react-dom/server/renderToPipeableStream#waiting-for-all-content-to-load-for-crawlers-and-static-generation
+      onShellReady() {
+        response.set({ "Content-Type": "text/html" });
+        response.status(status);
+
+        const transformStream = new Transform({
+          transform(chunk, encoding, callback) {
+            response.write(chunk, encoding);
+            callback();
+          },
+        });
+
+        const [htmlStart, htmlEnd] = template.split("<!--app-html-->");
+
+        response.write(
+          htmlStart.replace(
+            "<!--app-helmet-->",
+            [
+              helmetContext.helmet.title.toString(),
+              helmetContext.helmet.meta.toString(),
+              helmetContext.helmet.link.toString(),
+              helmetContext.helmet.style.toString(),
+              helmetContext.helmet.script.toString(),
+            ].join("\n"),
+          ),
+        );
+
+        transformStream.on("finish", () => {
+          response.end(htmlEnd);
+        });
+
+        pipe(transformStream);
+      },
+      onError(error) {
+        status = 500;
+        logger.error(error);
+      },
+    },
+  );
+};
+
+export function createFetchRequest(
+  req: express.Request,
+  res: express.Response,
+): Request {
+  const origin = `${req.protocol}://${req.get("host")}`;
+  // Note: This had to take originalUrl into account for presumably vite's proxying
+  const url = new URL(req.originalUrl || req.url, origin);
+
+  const controller = new AbortController();
+  res.on("close", () => controller.abort());
+
+  const headers = new Headers();
+
+  for (const [key, values] of Object.entries(req.headers)) {
+    if (values) {
+      if (Array.isArray(values)) {
+        for (const value of values) {
+          headers.append(key, value);
+        }
+      } else {
+        headers.set(key, values);
+      }
+    }
+  }
+
+  const init: RequestInit = {
+    method: req.method,
+    headers,
+    signal: controller.signal,
+  };
+
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    init.body = req.body;
+  }
+
+  return new Request(url.href, init);
+}

package/src/app/main.tsx

@@ -1,51 +1,73 @@
-import { StrictMode } from "react";
-import { createRoot } from "react-dom/client";
-
-// Styles
-import "./main.css";
-
-// Logger
-import "../lib/util/logInit.js";
-
-// Config
-import config from "virtual:zudoku-config";
-
-// Plugins
+import { type RouteObject } from "react-router-dom";
 import { configuredApiKeysPlugin } from "virtual:zudoku-api-keys-plugin";
 import { configuredApiPlugins } from "virtual:zudoku-api-plugins";
 import { configuredAuthProvider } from "virtual:zudoku-auth";
 import { configuredDocsPlugins } from "virtual:zudoku-docs-plugins";
 import { configuredRedirectPlugin } from "virtual:zudoku-redirect-plugin";
-
-// Base React Component
 import { DevPortal } from "zudoku/components";
+import type { ZudokuConfig } from "../config/config.js";
+import { Layout } from "../lib/components/Layout.js";
+import { isNavigationPlugin } from "../lib/core/plugins.js";
+import { RouterError } from "../lib/errors/RouterError.js";
+
+import "virtual:vite-zudoku-custom-css.css";
+
+export const convertZudokuConfigToOptions = (config: ZudokuConfig) => {
+  return {
+    page: {
+      logo: config.page?.logo ?? "https://cdn.zudoku.dev/logos/icon.svg",
+      pageTitle: "Developer Portal",
+      ...config.page,
+    },
+    metadata: {
+      favicon: "https://cdn.zudoku.dev/logos/icon.svg",
+      title: "%s | Developer Portal",
+      ...config.metadata,
+    },
+    navigation: config.navigation ?? [],
+    authentication: configuredAuthProvider,
+    plugins: [
+      ...configuredDocsPlugins,
+      ...configuredApiPlugins,
+      ...(configuredRedirectPlugin ? [configuredRedirectPlugin] : []),
+      ...(configuredApiKeysPlugin ? [configuredApiKeysPlugin] : []),
+      ...(configuredAuthProvider ? [configuredAuthProvider] : []),
+    ],
+  };
+};
+
+export const getRoutesByConfig = (config: ZudokuConfig): RouteObject[] => {
+  const options = convertZudokuConfigToOptions(config);
+
+  const allPlugins = [
+    ...options.plugins,
+    ...(options.authentication ? [options.authentication] : []),
+  ];
 
-// IMPORTANT: This component must not contain tailwind classes
-// This directory is not processed by the tailwind plugin
+  const routes = allPlugins
+    .flatMap((plugin) => (isNavigationPlugin(plugin) ? plugin.getRoutes() : []))
+    .concat({
+      path: "*",
+      loader: () => {
+        throw new Response("Not Found", { status: 404 });
+      },
+    });
 
-createRoot(document.getElementById("root")!).render(
-  <StrictMode>
-    <DevPortal
-      page={{
-        logo: config.page?.logo ?? "https://cdn.zudoku.dev/logos/icon.svg",
-        pageTitle: "Developer Portal",
-        ...config.page,
-      }}
-      metadata={{
-        favicon: "https://cdn.zudoku.dev/logos/icon.svg",
-        title: "%s | Developer Portal",
-        ...config.metadata,
-      }}
-      navigation={config.navigation ?? []}
-      authentication={configuredAuthProvider}
-      mdxComponents={config.mdx?.components}
-      plugins={[
-        ...configuredDocsPlugins,
-        ...configuredApiPlugins,
-        configuredRedirectPlugin,
-        ...(configuredApiKeysPlugin ? [configuredApiKeysPlugin] : []),
-        ...(configuredAuthProvider ? [configuredAuthProvider] : []),
-      ]}
-    />
-  </StrictMode>,
-);
+  return [
+    {
+      element: (
+        <DevPortal {...options}>
+          <Layout />
+        </DevPortal>
+      ),
+      errorElement: (
+        <DevPortal {...options}>
+          <Layout>
+            <RouterError />
+          </Layout>
+        </DevPortal>
+      ),
+      children: routes,
+    },
+  ];
+};

package/src/app/tailwind.ts

@@ -2,8 +2,14 @@ import typographyPlugin from "@tailwindcss/typography";
 import type { Config } from "tailwindcss";
 import defaultTheme from "tailwindcss/defaultTheme.js";
 
+const content = [
+  "./src/**/*.{js,ts,jsx,tsx,md,mdx}",
+  "./node_modules/zudoku/dist/**/*.{js,ts,jsx,tsx,md,mdx}",
+];
+
 const config: Omit<Config, "content"> = {
   darkMode: "selector",
+  content,
   theme: {
     extend: {
       fontFamily: {

package/src/app/zudoku-manifest.ts

@@ -0,0 +1,22 @@
+import type { RouteObject } from "react-router-dom";
+import config from "virtual:zudoku-config";
+import { getRoutesByConfig } from "./main.js";
+
+const routes = getRoutesByConfig(config);
+
+const flattenPaths = (routes: RouteObject[], basePath = "") => {
+  return routes.reduce<string[]>((acc, route) => {
+    if (route.path) {
+      const fullPath = `${basePath}/${route.path}`.replace(/\/+/g, "/");
+      route.path !== "/" && acc.push(fullPath);
+      if (route.children) {
+        acc = acc.concat(flattenPaths(route.children, fullPath));
+      }
+    } else if (route.children) {
+      acc = acc.concat(flattenPaths(route.children, basePath));
+    }
+    return acc;
+  }, []);
+};
+
+export const paths = flattenPaths(routes);

package/src/lib/authentication/providers/clerk.tsx

@@ -9,6 +9,7 @@ const clerkAuth: AuthenticationProviderInitializer<
   let clerkApi: Clerk;
 
   const ensureLoaded = (async () => {
+    if (import.meta.env.SSR) return;
     const { Clerk } = await import("@clerk/clerk-js");
     clerkApi = new Clerk(clerkPubKey);
 

package/src/lib/components/DevPortal.tsx

@@ -1,8 +1,14 @@
 import { MDXProvider } from "@mdx-js/react";
 import { QueryClientProvider } from "@tanstack/react-query";
-import { Fragment, memo, Suspense, useEffect, useMemo } from "react";
+import {
+  Fragment,
+  memo,
+  type PropsWithChildren,
+  useEffect,
+  useMemo,
+} from "react";
 import { ErrorBoundary } from "react-error-boundary";
-import { Helmet, HelmetProvider } from "react-helmet-async";
+import { Helmet } from "react-helmet-async";
 import {
   DevPortalContext,
   queryClient,
@@ -18,9 +24,8 @@ import {
 import { DevPortalProvider } from "./context/DevPortalProvider.js";
 import { ThemeProvider } from "./context/ThemeContext.js";
 import { ViewportAnchorProvider } from "./context/ViewportAnchorContext.js";
-import { Router } from "./Router.js";
 
-const DevPortalSystemPaths = {
+export const DevPortalSystemPaths = {
   Settings: "/settings",
 } as const;
 
@@ -28,7 +33,10 @@ export type DevPortalPath =
   | string
   | (typeof DevPortalSystemPaths)[keyof typeof DevPortalSystemPaths];
 
-const DevPortalInner = (props: ZudokuContextOptions) => {
+const DevPortalInner = ({
+  children,
+  ...props
+}: PropsWithChildren<ZudokuContextOptions>) => {
   const components = useMemo(
     () => ({ ...DEFAULT_COMPONENTS, ...props.overrides }),
     [props.overrides],
@@ -52,39 +60,23 @@ const DevPortalInner = (props: ZudokuContextOptions) => {
 
   return (
     <QueryClientProvider client={queryClient}>
-      <HelmetProvider>
-        <Helmet>{heads}</Helmet>
-        <DevPortalProvider value={devPortalContext}>
-          <MDXProvider components={mdxComponents}>
-            <ThemeProvider>
-              <ComponentsProvider value={components}>
-                <ViewportAnchorProvider>
-                  <Suspense
-                    fallback={
-                      <div className="grid place-items-center h-full">
-                        Loading...
-                      </div>
-                    }
-                  >
-                    <Router
-                      plugins={[
-                        ...(props.plugins ?? []),
-                        ...(props.authentication ? [props.authentication] : []),
-                      ]}
-                    />
-                  </Suspense>
-                </ViewportAnchorProvider>
-              </ComponentsProvider>
-            </ThemeProvider>
-          </MDXProvider>
-        </DevPortalProvider>
-      </HelmetProvider>
+      <Helmet>{heads}</Helmet>
+      <DevPortalProvider value={devPortalContext}>
+        <MDXProvider components={mdxComponents}>
+          <ThemeProvider>
+            <ComponentsProvider value={components}>
+              <ViewportAnchorProvider>{children}</ViewportAnchorProvider>
+            </ComponentsProvider>
+          </ThemeProvider>
+        </MDXProvider>
+      </DevPortalProvider>
     </QueryClientProvider>
   );
 };
 
+const Inner = memo(DevPortalInner);
+
 const DevPortal = (props: ZudokuContextOptions) => {
-  const Inner = memo(DevPortalInner);
   return (
     <ErrorBoundary FallbackComponent={TopLevelError}>
       <Inner {...props} />

package/src/lib/components/ErrorPage.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import { Link } from "react-router-dom";
+import { CategoryHeading } from "./CategoryHeading.js";
+import { Heading } from "./Heading.js";
+import { ProseClasses } from "./Markdown.js";
+
+export const ErrorPage = ({
+  title = "An error occurred",
+  message,
+  category,
+}: {
+  title?: ReactNode;
+  message?: ReactNode;
+  category?: ReactNode;
+}) => {
+  return (
+    <div className={ProseClasses + " h-full pt-[--padding-content-top]"}>
+      {category && <CategoryHeading>{category}</CategoryHeading>}
+      {title && (
+        <Heading level={1} className="flex gap-3.5 items-center">
+          {title}
+        </Heading>
+      )}
+      <p>{message}</p>
+      <Link to="/">Go back home</Link>
+    </div>
+  );
+};

package/src/lib/components/InlineCode.tsx

@@ -0,0 +1,19 @@
+import type { ReactNode } from "react";
+import { cn } from "../util/cn.js";
+
+export const InlineCode = ({
+  className,
+  children,
+}: {
+  className?: string;
+  children: ReactNode;
+}) => (
+  <code
+    className={cn(
+      className,
+      "font-mono border border-border p-1 py-0.5 rounded bg-border/50 dark:bg-border/70 whitespace-nowrap",
+    )}
+  >
+    {children}
+  </code>
+);

package/src/lib/components/Layout.tsx

@@ -1,6 +1,7 @@
 import { Suspense, useEffect, useRef, type ReactNode } from "react";
 import { Helmet } from "react-helmet-async";
 import { Outlet, useLocation } from "react-router-dom";
+import { cn } from "../util/cn.js";
 import { useScrollToAnchor } from "../util/useScrollToAnchor.js";
 import { useScrollToTop } from "../util/useScrollToTop.js";
 import { useDevPortal } from "./context/DevPortalProvider.js";
@@ -47,10 +48,12 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
         >
           <SideNavigation />
           <main
-            className="dark:border-white/10 translate-x-0 h-full
-          lg:overflow-visible
-          lg:peer-data-[navigation=true]:w-[calc(100%-var(--side-nav-width))]
-          lg:peer-data-[navigation=true]:translate-x-[--side-nav-width] peer-data-[navigation=true]:pl-12"
+            className={cn(
+              "dark:border-white/10 translate-x-0 h-full",
+              "lg:overflow-visible",
+              "lg:peer-data-[navigation=true]:w-[calc(100%-var(--side-nav-width))]",
+              "lg:peer-data-[navigation=true]:translate-x-[--side-nav-width] peer-data-[navigation=true]:pl-12",
+            )}
           >
             {children ?? <Outlet />}
           </main>

package/src/lib/components/NotFoundPage.tsx

@@ -0,0 +1,39 @@
+import { UnlinkIcon } from "lucide-react";
+import { Link, useParams } from "react-router-dom";
+import { Callout } from "../ui/Callout.js";
+import { CategoryHeading } from "./CategoryHeading.js";
+import { Heading } from "./Heading.js";
+import { ProseClasses } from "./Markdown.js";
+
+export const NotFoundPage = () => {
+  const params = useParams();
+
+  return (
+    <div className={ProseClasses + " h-full pt-[--padding-content-top]"}>
+      <CategoryHeading>404</CategoryHeading>
+      <Heading level={1} className="flex gap-3.5 items-center">
+        Page not found
+        <UnlinkIcon size={24} />
+      </Heading>
+      {import.meta.env.DEV && (
+        <Callout type="caution" title="Developer hint">
+          Start by adding a file at{" "}
+          <code>
+            {"{PROJECT_ROOT}"}/{params["*"]}.mdx
+          </code>{" "}
+          and add some content to make this error go away.
+          <br />
+          <small className="italic">
+            Note: This hint is only shown in development mode.
+          </small>
+        </Callout>
+      )}
+      <p>
+        It seems that the page you are looking for does not exist or may have
+        been moved. Please check the URL for any typos or use the navigation
+        menu to find the correct page.
+      </p>
+      <Link to="/">Go back home</Link>
+    </div>
+  );
+};