helpgenai-runtime-react

React (Next.js App Router) display runtime for helpgenai. Reads generated help bundles off disk and renders them as /help + /help/<page> routes. Mirrors the Blazor runtime's display contract — bundles generated against either runtime are interchangeable.

License: Polyform Free Trial 1.0.0 + commercial-licensing addendum. 32-day free evaluation; any continued use requires a paid license. See LICENSE and contact [email protected].

Install

npm install helpgenai-runtime-react

Peer deps: react ^18 (or ^19) and react-dom.

Quick start (Next.js App Router)

// app/help/[pageKey]/page.tsx
import * as path from "node:path";
import { HelpPageView } from "helpgenai-runtime-react";
import { loadHelpPage } from "helpgenai-runtime-react/server";

const helpRoot = path.join(process.cwd(), "public", "help");

export default async function HelpPage({
  params,
}: {
  params: { pageKey: string };
}) {
  const bundle = await loadHelpPage(params.pageKey, { helpRoot });
  return <HelpPageView bundle={bundle} />;
}

// app/help/page.tsx
import * as path from "node:path";
import { HelpIndex } from "helpgenai-runtime-react";
import { loadHelpMap } from "helpgenai-runtime-react/server";

const helpRoot = path.join(process.cwd(), "public", "help");

export default async function HelpIndexPage() {
  const helpMap = await loadHelpMap({ helpRoot });
  return <HelpIndex helpMap={helpMap} />;
}

// app/layout.tsx — import the runtime CSS once
import "helpgenai-runtime-react/styles.css";

// next.config.mjs — let Next.js transpile the runtime's ESM
export default {
  transpilePackages: ["helpgenai-runtime-react"],
};

That's the whole integration. Run npx helpgenai build <page> from your tools/helpgen/ workspace and the bundle lands in public/help/<page>/ where the loader expects it.

Two entry points

• helpgenai-runtime-react — React components. Pure JSX. Safe to import from Server Components, Client Components, or any React tree.
• helpgenai-runtime-react/server — Server-only filesystem loaders (loadHelpMap, loadHelpPage, resolveScreenshotPath). Uses node:fs, so importing it from a "use client" module fails at build time.

Component reference

| Component | Where | What it does | | ------------------------ | --------- | ------------------------------------------------------- | | HelpPageView | server/client | Full per-page layout: breadcrumb, tabs, prose, panels, TOC, back-to-top | | HelpIndex | server/client | /help landing page grouped by helpmap.yaml | | MarkdownHelpContent | server/client | Renders the engine's prose markdown body | | IconLegendPanel | server/client | Renders icons.json typed reference panel | | CellStatesPanel | server/client | Renders cell-states.json typed reference panel | | BackToTop | client | Floating button shown after the user scrolls |

v1 scope

What's in:

• The full display layer for /help + /help/<page>.
• Server-side filesystem loaders for the engine's bundle layout.
• The same editorial CSS shipped by the Blazor runtime, vendored verbatim.

What's deferred to v2:

• Admin settings UI (helpmap / styleguide / hints / CONTENT-STYLE editor).
• In-app guidance editor (per-section + per-page authoring).
• Screenshot lightbox (delegated click handler).

If you need any of these today, the Blazor runtime ships them all — either render help from Blazor and the app from React, or open an issue and the v2 port can be prioritized.

Bundle layout

The engine writes:

<output_root>/
  _assets/
    helpmap.json            ← consumed by loadHelpMap()
    search-index.json
  <page-key>/
    metadata.json           ← consumed by loadHelpPage()
    <page-key>.md           ← prose body
    icons.json              ← optional typed-panel data
    cell-states.json        ← optional typed-panel data
    screenshots/*.png

Point helpRoot at <output_root> (typically public/help for a Next.js app) and the loaders find everything by convention.

Working example

See examples/react-todo in the helpgen monorepo — a runnable Next.js app that mirrors the Blazor todo example.