repository·main·Indexed 20 days ago
https://github.com/zuplo/zudokuAn open-source, customizable API documentation framework for creating developer experiences using OpenAPI or GraphQL schemas. Zudoku features integrated API playgrounds, MDX-based custom pages, and support for OpenID or OAuth2 authentication. It can be deployed via AWS Lambda SSR, Cloudflare Workers SSR, or used as a standalone React component via CDN. The framework includes a CLI for project scaffolding and a set of UI components such as Alert and Badge.
Cosmo Cargo provides logistics and shipping integration via API. Key capabilities include:
Zudoku is an open-source API documentation framework designed to build developer experiences around OpenAPI (and upcoming GraphQL) schemas. Key features include:
Cosmo Cargo's API provides several features for managing global logistics:
Zudoku provides bundle-level protection for sensitive routes. While protectedRoutes in your configuration prevents unauthenticated users from rendering content via the RouteGuard, it does not inherently stop a user from downloading the underlying JavaScript chunks from your static host.
To prevent this, Zudoku implements a pipeline that physically isolates the JavaScript for protected routes into a separate directory (_protected/) that is not served by the static host. Instead, these chunks are served through the SSR worker (e.g., AWS Lambda, Cloudflare Worker, or Node.js), which performs an authentication check before responding with the file. This ensures that the JS for gated routes is only accessible after a successful auth check.
During the build process (zudoku build --ssr), Zudoku identifies protected modules and re-routes them to a specific directory defined by PROTECTED_CHUNK_DIR (which is _protected).
Chunk Routing:
In the Rolldown configuration, chunks identified as protected are assigned a filename pattern like ${PROTECTED_CHUNK_DIR}/[name]-[hash].js instead of the standard assets/[name]-[hash].js.
Runtime URL Resolution:
To ensure the browser fetches these chunks through the SSR origin (where the auth check happens) rather than a public CDN, Zudoku uses experimental.renderBuiltUrl to rewrite the URLs. Any filename starting with _protected/ is rewritten to resolve through the basePath of the SSR application.
// Internal logic used for URL rewriting
if (filename.startsWith(`${PROTECTED_CHUNK_DIR}/`)) {
return joinUrl(config.basePath, `/${filename}`);
}Zudoku operates in two distinct deployment modes that determine how authentication state is managed and how cookies are handled. The mode is selected at build time.
/__z/auth/session endpoint is available.httpOnly cookies that JavaScript cannot access.zudoku build --ssr (retains the server bundle).localStorage. This is a weaker security posture as tokens in localStorage are vulnerable to XSS.zudoku build (prerenders and drops the server bundle).The client detects the mode at runtime via the window.ZUDOKU_SSR_AUTH object. The SSR server injects this object into the HTML whenever auth is configured. In SSG mode, this object is never injected.
Escalate a shipment to the rapid response team in the following scenarios:
protectedRoutes configuration option that gates specific routes behind an authentication layer. When a user attempts to access a protected route while unauthenticated, they will be directed through the configured authentication flow.To ensure a route is physically isolated into a protected chunk, you must load it via a dynamic import (() => import(...)). This dynamic import creates the 'lazy-boundary' that the build system uses to split the code into a protected chunk.
What is NOT protected:
{path: "/admin", element: <Admin />} but Admin is statically imported at the top of the file, the code for Admin will be included in the public bundle. The build will fail with an error from assertProtectedPatternsCovered to prevent this leak.type: "raw" inlines the schema into the main bundle, making it public.// CORRECT: Protected via dynamic import
{ path: "/admin", component: () => import("./Admin") }
// INCORRECT: Leaks into public bundle via static import
import { Admin } from "./Admin";
const routes = [{ path: "/admin", element: <Admin /> }];You can include JSX components inside Markdown headings. These components will render in both the sidebar navigation and the table of contents.
Note: For components to render correctly in headings, they must be registered via the mdx.components configuration option.
# My Page <Badge>New</Badge>Redirect behavior depends on how the visitor accesses the URL:
When a visitor loads a redirect path directly (e.g., via browser address bar or external link):
Location header. This is ideal for SEO.When a visitor clicks an internal link pointing to a redirect path, Zudoku handles the redirect entirely in the browser using client-side routing. This provides a seamless transition without a full page reload.
Zudoku uses a Vite transform to scan your code for specific patterns to determine which modules belong to which routes. To ensure your content is correctly isolated into protected chunks, use one of these two supported shapes:
path propertyAny object containing a string path property. All dynamic import() calls within the other properties of this object are registered as subtree-scoped to that path.
{ path: "/admin", lazy: () => import("./AdminPage") }An object where the keys are route-path strings (starting with / and containing no .) and the values are arrow functions calling import().
const fileImports = {
"/docs/intro": () => import("./intro.mdx"),
"/docs/guides": () => import("./guides.mdx"),
};// Shape A
{ path: "/admin", lazy: () => import("./AdminPage") }
// Shape B
const fileImports = {
"/docs/intro": () => import("./intro.mdx"),
"/docs/guides": () => import("./guides.mdx"),
};