@webtypen/docsgenerator-renderer

React-Komponenten für docs-generator, Version 0.0.1. Lädt veröffentlichte Dokumentationen automatisch per Projekt-ID; Vorschauen sind ausdrücklich freizuschalten. Unterstützt React 18/19, Next.js App Router, klassische SSR, Webframez React und React Router. Keine Abhängigkeit vom Editor, Native Design oder privaten npm-Paketen.

Installation und Team-Key

npm install @webtypen/docsgenerator-renderer

In docs-generator unter Einstellungen → API & MCP → Renderer API-Keys ein Team und alle oder einzelne Projekte auswählen. Owner/Admins können Keys anlegen, Rechte nachträglich ändern und Keys widerrufen. „Alle Projekte“ umfasst zukünftige Projekte desselben Teams. Neue Keys laufen nach 365 Tagen ab. Der vollständige Key erscheint nur einmal. Bestehende persönliche MCP-/Skript-Tokens funktionieren nicht als Renderer-Key.

Speichere DOCSGENERATOR_API_KEY als Server-Umgebungsvariable. Niemals NEXT_PUBLIC_…, Vite-Clientvariablen, Client-Props oder URL-Parameter dafür verwenden. Browser-Komponenten laden über den mitgelieferten Same-Origin-Proxy. Server-Komponenten können direkt laden.

Next.js Server Component

// app/help/[[...path]]/page.tsx
import Link from 'next/link';
import { Documentation, createDocumentationClient } from '@webtypen/docsgenerator-renderer/server';
import '@webtypen/docsgenerator-renderer/styles.css'; // alternativ im Root-Layout

const client = createDocumentationClient({
  apiKey: process.env.DOCSGENERATOR_API_KEY!,
  baseUrl: 'https://docsgenerator.webtypen.de',
  cache: { ttlMs: 60_000 },
});

export default async function Page({ params }: { params: Promise<{ path?: string[] }> }) {
  const { path = [] } = await params;
  const [version, language, ...page] = path;
  return (
    <Documentation
      client={client}
      projectId="PROJECT_UUID"
      version={version}
      language={language || 'de'}
      pagePath={page.join('/') || undefined}
      basePath="/help"
      LinkComponent={Link}
      cache={{ ttlMs: 30_000 }}
    />
  );
}

Ohne Versionsangabe wird die neueste veröffentlichte Version nach Erstellungsdatum geladen. Explizit wählbar über version (Slug) oder versionId (UUID). pageId oder pagePath wählen die Seite; ohne beide erscheint die erste Inhaltsseite. language ist optional und verwendet sonst die erste veröffentlichte Sprache. Die Daten enthalten den aktiven unveränderlichen Veröffentlichungsstand, keine Entwurfsänderungen.

Die Server-Komponente kann alternativ apiKey und baseUrl direkt erhalten. Ein einmalig angelegter Client ist für gemeinsam genutzte Einstellungen, Request-Deduplizierung und invalidate() vorzuziehen. Für klassische SSR zuerst client.load(query) aufrufen und die Daten an DocumentationView übergeben. Das Root-Modul ist rein darstellend und lädt weder Node-Module noch React-Hooks.

Client-Komponente / Next.js Route Handler

// app/api/documentation/route.ts — ausschließlich Server
import {
  createDocumentationClient,
  createDocumentationHandler,
} from '@webtypen/docsgenerator-renderer/server';
const client = createDocumentationClient({ apiKey: process.env.DOCSGENERATOR_API_KEY! });
export const POST = createDocumentationHandler({
  client,
  projectIds: ['PROJECT_UUID'], // begrenzt, welche Teamprojekte diese Website ausliefert
  cache: { ttlMs: 60_000 },
  // Für private Dokumentationen: authorize: async (request, query) => checkSession(request),
});

'use client';
import Link from 'next/link';
import { Documentation } from '@webtypen/docsgenerator-renderer/client';
export default function Help() {
  return (
    <Documentation
      endpoint="/api/documentation"
      projectId="PROJECT_UUID"
      language="de"
      basePath="/help"
      LinkComponent={Link}
      cache={{ ttlMs: 15_000 }}
    />
  );
}

Die Client-Komponente lädt beim Mount und bei Änderungen von Projekt/Version/Sprache/Vorschau. pageId/pagePath wählen aus dem bereits geladenen Dokument. Sie unterstützt loading, errorFallback(error) und initialData für SSR-Hydration. initialData muss zur übergebenen Query gehören. Bei geänderten Parametern wird keine Seite des vorherigen Projekts eingeblendet. Für mehrere Komponenten einen createBrowserClient({ endpoint }) einmalig erstellen und als client übergeben. Pro angemeldetem Nutzer einen eigenen Browser-Client/Cache verwenden und beim Abmelden verwerfen.

Der Proxy liefert ohne authorize die freigegebenen veröffentlichten Projekte öffentlich aus. Für geschützte Inhalte immer die eigene Sitzungsprüfung setzen. Diese läuft vor jedem Cache-Zugriff. Fehlerantworten enthalten keine Keys oder internen Serverfehler.

Webframez React / simplebis-website

import { createDocumentationClient } from '@webtypen/docsgenerator-renderer/server';
import {
  DocumentationView,
  type DocumentationData,
  type DocumentationLinkProps,
} from '@webtypen/docsgenerator-renderer';
import { Link } from '@webtypen/webframez-react/navigation';

const client = createDocumentationClient({ apiKey: process.env.DOCSGENERATOR_API_KEY! });
export async function Data() {
  return client.load({ projectId: 'PROJECT_UUID', language: 'de' }, { ttlMs: 60_000 });
}
function RouterLink({ href, ...props }: DocumentationLinkProps) {
  return <Link to={href} {...props} />;
}
export default function Page({ data }: { data: DocumentationData }) {
  return <DocumentationView data={data} basePath="/hilfe" LinkComponent={RouterLink} />;
}

In Webframez den RouterLink bei Bedarf in eine eigene 'use client'-Datei legen. Der API-Key bleibt im Data-Loader. Das Beispiel entspricht dem bestehenden Data/Page-Muster der simplebis-website; die alte API aus docsGeneratorHelper.ts ist ein anderes Format und wird nicht automatisch überschrieben. Eine vollständige Integration samt Projektzuordnung folgt im Website-Projekt.

Für Client-Laden in Webframez kann der Fetch-API-Handler an eine Core-Route adaptiert werden; siehe examples/webframez-proxy.ts. Für React Router denselben href → to-Adapter mit dessen Link verwenden. Next.js Link akzeptiert href direkt. pageHref(page, data) erlaubt ein eigenes URL-Schema; alle Navigationseinträge, vorherige/nächste Seiten und #doc/PAGE_ID/BLOCK_ID-Referenzen verwenden es. Stabile Anker entsprechen docs-generator. Fehlende Referenzen erscheinen als Text. Externe Links bleiben normale <a>-Elemente.

Vorschau und Medien

1. Am Team-Key Zusätzlich unveröffentlichte Entwürfe lesen aktivieren.
2. preview={true} übergeben. Ohne versionId/version wird dann die neueste Entwurfsversion geladen.
3. Für einen Browser-Proxy zusätzlich allowPreview: true und eine authorize-Funktion setzen. Die Vorschau selbst muss in der Host-Anwendung geschützt sein.

Vorschau-Daten werden unabhängig von der Cache-Konfiguration immer frisch geladen. Browser-/Framework-Fetch-Caches sind deaktiviert. Bei serverseitiger Vorschau die Seite mit der eigenen Authentifizierung schützen und keinen öffentlichen Full-Page-Cache aktivieren.

Veröffentlichte Medien laden absolut von der docs-generator-Instanz. Private Vorschau-Medien benötigen einen authentifizierten Proxy:

import { createDocumentationMediaHandler } from '@webtypen/docsgenerator-renderer/server';
export const GET = createDocumentationMediaHandler({
  apiKey: process.env.DOCSGENERATOR_API_KEY!,
  projectIds: ['PROJECT_UUID'],
  authorize: async (request, projectId) => checkPreviewSession(request, projectId),
});

<Documentation
  /* übrige Props */ preview
  mediaUrl={(url, data) =>
    url.startsWith('/media/')
      ? `/api/documentation-media?projectId=${encodeURIComponent(data.project.id)}&mediaId=${encodeURIComponent(url.slice(7))}`
      : url
  }
/>

Das mediaUrl-Mapping unterstützt auch eigene CDN-/Proxy-URLs. API-Keys werden niemals an Medien-URLs angehängt.

Cache-Verhalten

• Standard: 60 Sekunden, begrenzter In-Memory-LRU-Cache mit 100 Einträgen, Deduplizierung gleichzeitiger Requests pro Client.
• cache={{ ttlMs: 5000 }} pro Client oder Komponentenaufruf; cache={false}/ttlMs: 0 deaktiviert Lesen und Schreiben des Caches.
• Cache-Schlüssel trennen Serverinstanz, gehashten API-Key, Projekt, Version, Sprache und Vorschau. Rohschlüssel werden nicht gespeichert.
• await client.invalidate(query) entfernt einen Eintrag und verhindert, dass ein älterer laufender Request ihn wieder füllt. Fehler werden nicht gecacht.
• Rechteänderungen, Widerruf und neue Veröffentlichungen werden bei der nächsten API-Abfrage wirksam. Ein bereits gefüllter Host-Cache kann Inhalte bis zum TTL-Ablauf anzeigen. Für sofortige Aktualität Cache deaktivieren oder invalidieren; bei mehreren Prozessen jeden Cache invalidieren oder einen gemeinsamen Adapter einsetzen.
• cacheAdapter akzeptiert get, set, delete mit synchronen oder asynchronen Ergebnissen; CacheEntry enthält data, storedAt, expiresAt. Redis/externen Storage selbst anbinden. Der In-Memory-Cache gilt nur im jeweiligen Prozess bzw. Browser-Client.
• Browser und Proxy besitzen getrennte TTLs. Für strengere Aktualität beide konfigurieren. Kein impliziter Hintergrund-Poll, keine Datenbank oder Dateisystem-Abhängigkeit.

Darstellung und Erweiterung

styles.css ist optional und auf .dgr begrenzt. Unterstützt Absätze, Überschriften, verschachtelte Listen, Checklisten (read-only), Zitate, Code, Trennlinien, Callouts, Bilder, Dateien, Tabellen und Inline-Formatierungen. blockRenderers überschreibt einzelne Blocktypen. navigation={false} rendert nur den Artikel. notFound, className, pageHref und mediaUrl erlauben Host-Anpassungen. HTML wird nicht ungeprüft eingesetzt; gefährliche Linkprotokolle werden verworfen.

Build und spätere Veröffentlichung

cd packages/docsgenerator-renderer
npm ci
npm test
npm pack

Der GitHub-Workflow .github/workflows/renderer-package.yml baut/testet nur dieses eigenständige Paket. Push auf main/PR/manueller Start erzeugt ausschließlich ein Paketartefakt. Erst ein Tag renderer-v0.0.1 veröffentlicht dasselbe geprüfte Tarball auf npmjs.org und npm.pkg.github.com. Kein Release-Tag wird durch den Build erstellt.

Vor der ersten Veröffentlichung:

• npm-Scope @webtypen und Berechtigung zum öffentlichen Publish bereitstellen. npm-release-Environment mit NPM_TOKEN für das erste Release konfigurieren, danach npm Trusted Publishing für Repository webtypen/docs-generator, Workflow renderer-package.yml, Environment npm-release einrichten und Token entfernen. Node 24 liefert eine OIDC-fähige npm-Version.
• GitHub-Environment github-packages-release einrichten. Der Workflow verwendet GITHUB_TOKEN mit packages: write. Bestehende gleichnamige Packages müssen diesem Repository Actions-Zugriff gewähren. GitHub-Package-Sichtbarkeit separat prüfen; npmjs wird ausdrücklich öffentlich veröffentlicht.
• Beide Registries müssen für die neue Version frei sein. Bei einem Teilerfolg nur den fehlgeschlagenen Publish-Job erneut ausführen, keine bereits veröffentlichte Version überschreiben.
• Versionsnummer erhöhen, Änderungen prüfen, committen und erst dann den passenden renderer-v…-Tag pushen.

Die Repository-Zuordnung bleibt webtypen/docs-generator; der Paketname ist in beiden Registries @webtypen/docsgenerator-renderer.

Quellen zur Release-Konfiguration: npm Trusted Publishing, GitHub npm Registry. Zur Server-/Client-Trennung: Next.js Server and Client Components.