@lukoweb/apitogo 0.2.49 → 0.2.51

package/dist/declarations/lib/plugins/openapi/util/createHttpSnippet.d.ts

@@ -1,5 +1,7 @@
 import { HTTPSnippet } from "@zudoku/httpsnippet";
 import type { OperationsFragmentFragment } from "../graphql/graphql.js";
+export declare const KEY_HEADER_EXTENSION = "x-apitogo-key-header";
+export declare const KEY_PLACEHOLDER = "YOUR_API_KEY";
 export declare const createHttpSnippet: ({ operation, selectedServer, exampleBody, }: {
     operation: OperationsFragmentFragment;
     selectedServer: string;

package/docs/cli/shape.md

@@ -41,12 +41,12 @@ ready to go live.
 On a TTY, bare `npx apitogo config` opens the wizard. Each choice is written immediately; the loop
 continues until you type `done`:
 
-| Choice    | What it does                                                             |
-| --------- | ------------------------------------------------------------------------ |
-| `backend` | Set `gateway.origin`: API code folder, runtime and runtime version       |
-| `openapi` | Add an OpenAPI file to `gateway.specs`                                   |
-| `page`    | Create `apitogo/portal/pages/<slug>.mdx` (the sidebar follows the files) |
-| `plan`    | Add a plan to `apitogo/plans.json` (title, price, rate limit, quota)     |
+| Choice    | What it does                                                                            |
+| --------- | --------------------------------------------------------------------------------------- |
+| `backend` | Set `gateway.origin`: API code folder, runtime and runtime version                      |
+| `openapi` | Add an OpenAPI file to `gateway.specs`                                                  |
+| `page`    | Create the React page `apitogo/portal/pages/<slug>.tsx` (the sidebar follows the files) |
+| `plan`    | Add a plan to `apitogo/plans.json` (title, price, rate limit, quota)                    |
 
 Fonts and colors are **not** prompted. See [Colors & theme](../customization/colors-theme.mdx).
 
@@ -88,7 +88,7 @@ After `npx apitogo config`, edit the manifest and site files directly:
 
 - **Services, backend, OpenAPI files** — `apitogo.config.json`
 - **Plans** — `apitogo/plans.json`
-- **Docs pages** — `apitogo/portal/pages/**/*.mdx`
+- **Docs pages** — `apitogo/portal/pages/**/*.{md,mdx,tsx}` (`.tsx` files are React pages)
 - **Home page** — the file in `portal.landing` (for example
   `apitogo/portal/landing/LandingPage.tsx`)
 

package/docs/configuration/make-config.mdx

@@ -19,16 +19,18 @@ version 1 config, it stops and points to `apitogo create`.
 
 ## What goes where
 
-| You change          | Where it is written                                              |
-| ------------------- | ---------------------------------------------------------------- |
-| Portal display name | `portal.name` in `apitogo.config.json`                           |
-| API code (backend)  | `gateway.origin` (`mode: managed`, `source`, `runtime`, version) |
-| OpenAPI file        | `gateway.specs` in `apitogo.config.json`                         |
-| Docs page           | `apitogo/portal/pages/<slug>.mdx` (the config does not change)   |
-| Plan                | `apitogo/plans.json` (or the file in `plans.file`)               |
+| You change          | Where it is written                                                |
+| ------------------- | ------------------------------------------------------------------ |
+| Portal display name | `portal.name` in `apitogo.config.json`                             |
+| API code (backend)  | `gateway.origin` (`mode: managed`, `source`, `runtime`, version)   |
+| OpenAPI file        | `gateway.specs` in `apitogo.config.json`                           |
+| Docs page           | `apitogo/portal/pages/<slug>.tsx`, a React page (config unchanged) |
+| Plan                | `apitogo/plans.json` (or the file in `plans.file`)                 |
 
 The portal builds its sidebar from the pages folder, so adding a page needs no navigation entry. A
-page in `guides/quickstart.mdx` shows under a **Guides** section at `/guides/quickstart`.
+page in `guides/quickstart.tsx` shows under a **Guides** section at `/guides/quickstart`. New pages
+are React components by default; pass `--page-format mdx` for a Markdown page. See
+[Custom pages](../guides/custom-pages.md).
 
 Changing a gateway or plan needs that service in the project. Add it first with
 `apitogo add gateway` or `apitogo add plans`.
@@ -40,7 +42,7 @@ On a TTY, bare `npx apitogo config` opens the wizard. Each answer is applied at
 
 - **`backend`**: folder of your API code, runtime (`nodejs` / `python` / `dotnet`) and version
 - **`openapi`**: an OpenAPI file to add to `gateway.specs`
-- **`page`**: page title and URL path; writes `apitogo/portal/pages/<slug>.mdx`
+- **`page`**: page title and URL path; writes the React page `apitogo/portal/pages/<slug>.tsx`
 - **`plan`**: title, fixed or custom price, rate limit per minute, quota per 30 days; added to
   `plans.json`
 
@@ -58,7 +60,8 @@ plans also need Starter or Professional platform hosting.
 | `--runtime <name>`          | Runtime of `--source`: `nodejs` (default), `python` or `dotnet`       |
 | `--runtime-version <v>`     | Runtime version, for example `NODE_22_LTS`                            |
 | `--openapi <file>`          | Add an OpenAPI file to `gateway.specs`                                |
-| `--page-slug <path>`        | Add a page at `apitogo/portal/pages/<path>.mdx`                       |
+| `--page-slug <path>`        | Add a page at `apitogo/portal/pages/<path>.tsx`                       |
+| `--page-format <tsx\|mdx>`  | Format of a new page: `tsx` (React, the default) or `mdx`             |
 | `--page-title <title>`      | Title of the page (required when adding)                              |
 | `--page-content <markdown>` | Markdown body of the page                                             |
 | `--page-update`             | Change an existing page instead of adding one                         |

package/docs/configuration/navigation.mdx

@@ -61,7 +61,7 @@ one of several types. At the simplest level you may only have links and categori
 In a config version 2 project, the portal builds the sidebar from the pages under
 `apitogo/portal/pages/`: the index page first, then the other pages by name, then one section per
 folder. There is no `navigation` key to maintain. Add a page with **`npx apitogo config`** (see
-**[Make config (CLI)](./make-config.mdx)**) or by creating the `.md` / `.mdx` file.
+**[Make config (CLI)](./make-config.mdx)**) or by creating the `.md`, `.mdx` or `.tsx` (React) file.
 
 ## Navigation Items
 

package/docs/guides/custom-pages.md

@@ -11,16 +11,45 @@ components that APIToGo already has such as buttons, links and headers.
 
 Start by creating the page you want to add.
 
+## React pages in a project made by `apitogo create`
+
+Put a `.tsx` file next to your Markdown pages, in `apitogo/portal/pages/` (or any folder in
+`portal.docs.content`). Its default export is the page, and `export const title` is its label in the
+sidebar. The page's address follows its path, like a Markdown page: `guides/quickstart.tsx` is
+`/guides/quickstart`, under a **Guides** section.
+
+```tsx title="apitogo/portal/pages/guides/quickstart.tsx"
+import { useState } from "react";
+import { Button, Heading, Typography } from "@lukoweb/apitogo/components";
+
+export const title = "Quickstart";
+
+export default function QuickstartPage() {
+  const [count, setCount] = useState(0);
+  return (
+    <Typography>
+      <Heading level={1}>{title}</Heading>
+      <Button onClick={() => setCount(count + 1)}>Clicked {count} times</Button>
+    </Typography>
+  );
+}
+```
+
+- A file or folder whose name starts with `_` is not a page, so keep shared components there, for
+  example `apitogo/portal/pages/_components/Chart.tsx`. Test and story files are not pages either.
+- When a Markdown page and a React page have the same address, the Markdown page wins.
+- Nothing in `apitogo.config.json` changes: the sidebar is built from the files.
+
 ## CLI scaffold
 
-`npx apitogo config` can create a starter Markdown page at `apitogo/portal/pages/<slug>.mdx`. Choose
-`page` in the wizard loop, or pass `--page-slug` and `--page-title`. The sidebar is built from the
-pages folder, so no navigation entry is needed.
+`npx apitogo config` creates a starter React page at `apitogo/portal/pages/<slug>.tsx`. Choose
+`page` in the wizard loop, or pass `--page-slug` and `--page-title`. Add `--page-format mdx` for a
+Markdown page instead.
 
 Predefined UI components (Callout, Card, Button, Heading, and more) are documented under
 [/docs/components](/docs/components).
 
-## Setup a custom page
+## Setup a custom page (version 1 projects)
 
 Each custom page is a page component of its own and lives in a `src` directory at the root of your
 project. Let's create the `<MyCustomPage />` component as an example.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.49",
+  "version": "0.2.51",
   "type": "module",
   "sideEffects": [
     "**/*.css",

package/src/config/v2/docs-navigation.ts

@@ -3,9 +3,13 @@ import type { InputNavigationItem } from "../validators/InputNavigationSchema.js
 /** Label of the one header tab that holds the sidebar made from the docs pages. */
 export const DOCS_NAVIGATION_LABEL = "Documentation";
 
-type Branch = { pages: Set<string>; folders: Map<string, Branch> };
+/** A React page in the sidebar. `element` is the placeholder the generated wrapper replaces with the component. */
+export type CustomDocsPage = { route: string; label: string; element: string };
 
-const emptyBranch = (): Branch => ({ pages: new Set(), folders: new Map() });
+type Page = { kind: "doc" } | ({ kind: "custom" } & CustomDocsPage);
+type Branch = { pages: Map<string, Page>; folders: Map<string, Branch> };
+
+const emptyBranch = (): Branch => ({ pages: new Map(), folders: new Map() });
 
 /** "getting-started" becomes "Getting started". */
 export function folderLabel(name: string): string {
@@ -16,22 +20,28 @@ export function folderLabel(name: string): string {
 const byName = (a: string, b: string) => a.localeCompare(b);
 
 const toItems = (branch: Branch, prefix: string): InputNavigationItem[] => {
-  const pages = [...branch.pages].sort((a, b) =>
+  const names = [...branch.pages.keys()].sort((a, b) =>
     a === "index" ? -1 : b === "index" ? 1 : byName(a, b),
   );
   const folders = [...branch.folders.keys()].sort(byName);
+  const folderPath = prefix === "" ? "/" : `/${prefix.slice(0, -1)}`;
   return [
-    // The index page of a folder is the folder's own address, so the sidebar also shows on `/`.
-    ...pages.map(
-      (page): InputNavigationItem =>
-        page === "index"
-          ? {
-              type: "doc",
-              file: `${prefix}${page}`,
-              path: prefix === "" ? "/" : `/${prefix.slice(0, -1)}`,
-            }
-          : `${prefix}${page}`,
-    ),
+    ...names.map((name): InputNavigationItem => {
+      const page = branch.pages.get(name) as Page;
+      if (page.kind === "custom") {
+        return {
+          type: "custom-page",
+          // The index page of a folder is the folder's own address.
+          path: name === "index" ? folderPath : page.route,
+          label: page.label,
+          element: page.element,
+        };
+      }
+      // The index page of a folder is the folder's own address, so the sidebar also shows on `/`.
+      return name === "index"
+        ? { type: "doc", file: `${prefix}${name}`, path: folderPath }
+        : `${prefix}${name}`;
+    }),
     ...folders.map(
       (folder): InputNavigationItem => ({
         type: "category",
@@ -47,23 +57,36 @@ const toItems = (branch: Branch, prefix: string): InputNavigationItem[] => {
   ];
 };
 
+const branchOf = (root: Branch, route: string) => {
+  const parts = route.split("/").filter(Boolean);
+  const page = parts.pop();
+  const branch = parts.reduce((current, folder) => {
+    const next = current.folders.get(folder) ?? emptyBranch();
+    current.folders.set(folder, next);
+    return next;
+  }, root);
+  return { branch, page };
+};
+
 /**
  * The sidebar for hosted docs, made from the pages themselves: the index page first, then the other pages by
- * name, then one section per folder. `routes` are the docs plugin's route paths (`/overview`, `/guides/style`).
+ * name, then one section per folder. `routes` are the docs plugin's route paths (`/overview`, `/guides/style`);
+ * `customPages` are React pages placed the same way. A Markdown page wins over a React page at the same address.
  * Without pages there is nothing to navigate, so the result is empty.
  */
-export function docsNavigation(routes: string[]): InputNavigationItem[] {
+export function docsNavigation(
+  routes: string[],
+  customPages: readonly CustomDocsPage[] = [],
+): InputNavigationItem[] {
   const root = emptyBranch();
   for (const route of routes) {
-    const parts = route.split("/").filter(Boolean);
-    const page = parts.pop();
-    if (!page) continue;
-    const branch = parts.reduce((current, folder) => {
-      const next = current.folders.get(folder) ?? emptyBranch();
-      current.folders.set(folder, next);
-      return next;
-    }, root);
-    branch.pages.add(page);
+    const { branch, page } = branchOf(root, route);
+    if (page) branch.pages.set(page, { kind: "doc" });
+  }
+  for (const custom of customPages) {
+    const { branch, page } = branchOf(root, custom.route);
+    if (page && !branch.pages.has(page))
+      branch.pages.set(page, { kind: "custom", ...custom });
   }
   const items = toItems(root, "");
   return items.length === 0

package/src/config/v2/full-server.ts

@@ -105,7 +105,7 @@ export const FULL_SPEC = (name: string) => `openapi: 3.1.0
 info:
   title: ${JSON.stringify(name)}
   version: 1.0.0
-  description: A small sample API. Edit server/index.js and this file together.
+  description: A sample API with a greeting and a list of items.
 paths:
   /health:
     get:

package/src/config/v2/gateway-reference.ts

@@ -18,7 +18,13 @@ export type ReferenceOptions = {
 };
 
 /** Header of the API key when the gateway does not say otherwise (same as the platform's OpenAPI export). */
-export const DEFAULT_KEY_HEADER = "Ocp-Apim-Subscription-Key";
+export const DEFAULT_KEY_HEADER = "X-API-Key";
+
+/**
+ * Operation extension naming the header a protected operation's key goes in. The API page's code samples read it
+ * (`createHttpSnippet`), so they show the header with a placeholder key.
+ */
+export const KEY_HEADER_EXTENSION = "x-apitogo-key-header";
 
 const METHODS = [
   "get",
@@ -175,10 +181,17 @@ export function buildReferenceSpec(
   else delete doc.components;
   // One requirement with both schemes means both are needed together.
   doc.security = Object.keys(requirement).length > 0 ? [requirement] : [];
-  for (const [, item, method] of operationsOf(paths)) {
+  for (const [path, item, method] of operationsOf(paths)) {
     const operation = item[method] as Json;
     if (Array.isArray(operation.security) && operation.security.length > 0)
       delete operation.security;
+    // The page's code samples add this header, so a copied sample works once the key is filled in (API-120).
+    if (
+      options.apiKeyRequired &&
+      !options.publicOperations.has(actionKey(method, path))
+    )
+      operation[KEY_HEADER_EXTENSION] = options.apiKeyHeader;
+    else delete operation[KEY_HEADER_EXTENSION];
   }
 
   return JSON.parse(hideOrigin(JSON.stringify(doc), options)) as Json;

package/src/config/v2/index.ts

@@ -101,6 +101,7 @@ export {
   requiredPackages,
   WRAPPER_FILE,
 } from "./wrapper.js";
+export { findTsxPages, type TsxPage, tsxPagePatterns } from "./tsx-pages.js";
 export { materializeWorkspace, portalArtifactHash } from "./workspace.js";
 export {
   type AddOptions,

package/src/config/v2/init.ts

@@ -59,7 +59,7 @@ title: Welcome
 
 # ${name}
 
-This page was created by \`apitogo init\`. Edit it, and add more \`.md\` or \`.mdx\` files next to it: each one becomes a page of your portal.
+Welcome to the ${name} developer portal. Here you will find guides, the API reference, and everything you need to get an API key and make your first call.
 `;
 }
 

package/src/config/v2/rules.ts

@@ -6,6 +6,7 @@ import { billingNeeded, stripeKeySecretName } from "./billing.js";
 import type { ConfigIssue } from "./errors.js";
 import { type ResolvedConfigV2, toGlobPath } from "./resolve.js";
 import type { ConfigV2 } from "./schema.js";
+import { findTsxPages } from "./tsx-pages.js";
 
 /**
  * The rules of `apitogo check` that need no network (Reference, section 2). Online rules (provider capabilities,
@@ -277,6 +278,8 @@ async function docsContentRule(
       ? await glob(include, { nodir: true, ignore, absolute: true })
       : [];
   if (matches.length > 0) return;
+  // React pages (.tsx) next to the docs count too.
+  if ((await findTsxPages(patterns)).length > 0) return;
 
   const shown = config.portal?.docs?.content ?? [
     path.relative(resolved.configDir, patterns[0] ?? ""),
@@ -285,7 +288,7 @@ async function docsContentRule(
     code: "PORTAL_DOCS_EMPTY",
     path: "portal.docs",
     message: `portal.docs matched 0 files (${shown.join(", ")}). The site will only contain the API reference.`,
-    hint: "Add .md or .mdx files, or point docs.content at your existing docs.",
+    hint: "Add .md, .mdx or .tsx pages, or point docs.content at your existing docs.",
   });
 }
 

package/src/config/v2/starter-landing.ts

@@ -9,15 +9,22 @@ export function starterLandingPage(options: {
 }): string {
   const name = JSON.stringify(options.name);
   const plansImport = options.withPlans
-    ? 'import { usePlansPreview } from "@lukoweb/apitogo-plugin-dev-portal-billing";\n'
+    ? 'import {\n  useGatewayCall,\n  usePlansPreview,\n} from "@lukoweb/apitogo-plugin-dev-portal-billing";\n'
     : "";
   const plansHook = options.withPlans
-    ? "  // The plans of the project's catalog: the same ones the pricing page shows.\n  const plans = usePlansPreview();\n\n"
+    ? "  // The plans of the project's catalog: the same ones the pricing page shows.\n  const plans = usePlansPreview();\n  // The real gateway address and key header, so the sample works when it is pasted with a key.\n  const gateway = useGatewayCall();\n\n"
     : "";
+  // Without the plans service the page cannot learn the gateway, so the sample names the platform's default header.
+  const sampleUrl = options.withPlans
+    ? '${gateway.baseUrl ?? "https://YOUR-GATEWAY"}'
+    : "https://YOUR-GATEWAY";
+  const sampleHeader = options.withPlans ? "${gateway.keyHeader}" : "X-API-Key";
   const plansSection = options.withPlans
     ? "      <PlansPreviewSection plans={plans} />\n"
     : "";
-  return `import {
+  return `// Your portal's home page. Edit this file (apitogo/portal/landing/LandingPage.tsx) to make it yours: everything
+// on it is public, so keep notes for yourself in comments like this one.
+import {
   ApiShowcaseSection,
   FeaturesSection,
   HeroSection,
@@ -47,8 +54,8 @@ ${plansHook}  return (
           {
             filename: "Call the API",
             language: "bash",
-            code: \`$ curl https://your-api.example.com/health \\\\
-  -H "x-api-key: YOUR_API_KEY"
+            code: \`$ curl ${sampleUrl}/health \\\\
+  -H "${sampleHeader}: YOUR_API_KEY"
 # { "status": "ok" }\`,
           },
         ]}
@@ -58,7 +65,7 @@ ${plansHook}  return (
           label: "What you get",
           title: "A developer portal that is ready on day one",
           description:
-            "Edit this page in apitogo/portal/landing/LandingPage.tsx to make it yours.",
+            "Docs, a live API reference, self-service API keys and clear plans, all in one place.",
         }}
         features={[
           {

package/src/config/v2/tsx-pages.ts

@@ -0,0 +1,100 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { glob } from "glob";
+import globParent from "glob-parent";
+import { folderLabel } from "./docs-navigation.js";
+import { toGlobPath } from "./resolve.js";
+
+/**
+ * React pages next to the Markdown docs: a `.tsx` file in a docs folder is a page whose default export is the page
+ * component. Its address follows the same rule as a Markdown page (the path inside the folder, without the extension),
+ * so `pages/guides/quickstart.tsx` is `/guides/quickstart`. A file or folder whose name starts with `_` is a helper
+ * (shared components, hooks), not a page.
+ */
+export type TsxPage = {
+  /** `/guides/quickstart`. */
+  route: string;
+  /** Absolute path of the component file. */
+  file: string;
+  /** Sidebar label: `export const title = "..."` in the file, or the file name. */
+  label: string;
+};
+
+const IGNORED = ["**/node_modules/**", "**/dist/**", "**/.git/**"];
+
+/**
+ * A helper next to the pages, not a page: anything under a name that starts with `_`, tests and stories. Checked on
+ * the path inside the docs folder (the glob library's `ignore` does not match absolute Windows paths).
+ */
+export function isTsxHelper(relative: string): boolean {
+  return (
+    relative.split("/").some((part) => part.startsWith("_")) ||
+    /\.(test|spec|stories)\.tsx$/.test(relative) ||
+    relative.split("/").includes("node_modules")
+  );
+}
+
+/** The `.tsx` patterns for the docs content globs: every file below each glob's folder. Negated globs stay as they are. */
+export function tsxPagePatterns(contentGlobs: readonly string[]): string[] {
+  const globs = contentGlobs.map(toGlobPath);
+  const included = globs.filter((pattern) => !pattern.startsWith("!"));
+  const excluded = globs.filter((pattern) => pattern.startsWith("!"));
+  return [
+    ...new Set(
+      included.map((pattern) =>
+        path.posix.join(globParent(pattern), "**", "*.tsx"),
+      ),
+    ),
+    ...excluded,
+  ];
+}
+
+const TITLE =
+  /export\s+const\s+title\s*(?::\s*string\s*)?=\s*(["'`])((?:\\.|(?!\1).)*)\1/;
+
+/** The label a page shows in the sidebar. */
+export function tsxPageLabel(source: string, file: string): string {
+  const match = TITLE.exec(source);
+  if (match?.[2]) return match[2].replace(/\\(.)/g, "$1");
+  const name = path.basename(file, ".tsx");
+  return folderLabel(
+    name === "index" ? path.basename(path.dirname(file)) : name,
+  );
+}
+
+/** The React pages the docs content globs reach, sorted by address. */
+export async function findTsxPages(
+  contentGlobs: readonly string[],
+): Promise<TsxPage[]> {
+  const patterns = tsxPagePatterns(contentGlobs);
+  const ignore = [
+    ...IGNORED,
+    ...patterns
+      .filter((pattern) => pattern.startsWith("!"))
+      .map((pattern) => pattern.slice(1)),
+  ];
+  const found = new Map<string, TsxPage>();
+  for (const pattern of patterns.filter((p) => !p.startsWith("!"))) {
+    const parent = globParent(pattern);
+    const files = await glob(pattern, {
+      absolute: true,
+      posix: true,
+      nodir: true,
+      ignore,
+    });
+    for (const raw of files.sort()) {
+      // On Windows the glob library answers with the extended form `//?/C:/...`, which would not relate to `parent`.
+      const file = raw.replace(/^\/\/\?\//, "");
+      const relative = path.posix.relative(parent, file);
+      if (isTsxHelper(relative)) continue;
+      const route = `/${relative.replace(/\.tsx$/, "")}`;
+      if (found.has(route)) continue;
+      const source = await readFile(file, "utf8").catch(() => "");
+      found.set(route, { route, file, label: tsxPageLabel(source, file) });
+    }
+  }
+  return [...found.values()].sort((a, b) => a.route.localeCompare(b.route));
+}
+
+/** The placeholder a sidebar item carries until the generated wrapper puts the component in its place. */
+export const TSX_PAGE_ELEMENT_PREFIX = "apitogo:tsx-page:";

package/src/config/v2/workspace.ts

@@ -5,6 +5,7 @@ import { glob } from "glob";
 import { ensureStateDir } from "./layout.js";
 import { linkDirectory } from "./link-directory.js";
 import type { ResolvedConfigV2 } from "./resolve.js";
+import { tsxPagePatterns } from "./tsx-pages.js";
 import { CONTENT_LINK, type PreparedPortal } from "./wrapper.js";
 
 const exists = (file: string) =>
@@ -92,6 +93,10 @@ export async function portalArtifactHash(
   const portal = resolved.portal;
   const patterns = [
     ...(portal?.docs.content ?? []),
+    // React docs pages and the helpers next to them are imported by the wrapper, so their contents decide the build too.
+    ...(portal?.docs.provider === "apitogo"
+      ? tsxPagePatterns(portal.docs.content)
+      : []),
     ...(resolved.gateway?.specs ?? []),
     ...(portal
       ? [portal.theme, path.join(portal.dir, "public", "**", "*")]