@luckystack/docs-ui

Dev-only API docs UI for LuckyStack.

Mounts a single page at /_docs that fetches the framework's generated apiDocs.generated.json and renders every API endpoint grouped by page, with HTTP method, auth requirements, rate limit, input shape, and output shape.

Install

npm install @luckystack/docs-ui

Peer deps (already installed if you have any other LuckyStack package):

• @luckystack/core
• @luckystack/server (the docs UI is mounted via createLuckyStackServer's customRoutes option)

Quickstart

// luckystack/docs-ui/index.ts (overlay file — auto-imported by bootstrapLuckyStack)
import { mountDocsUi } from '@luckystack/docs-ui';

export const docsUiHandler = mountDocsUi({
  // Title shown in the header + browser tab. Defaults to 'LuckyStack — API docs'.
  // Pass your project name explicitly — there's no implicit lookup from
  // ProjectConfig because consumer config shapes vary too widely to introspect.
  pageTitle: 'My App — API docs',
});

// server/server.ts
import { docsUiHandler } from '../luckystack/docs-ui';
import { bootstrapLuckyStack } from '@luckystack/server';
import { serveFile, serveFavicon } from './prod/serveFile';

await (await bootstrapLuckyStack({
  serveFile,
  serveFavicon,
  customRoutes: docsUiHandler,
})).listen();

Open http://localhost/_docs and you'll see every API in your project, grouped by page, with one-click expand for each endpoint's input/output.

Production

By default the route returns 404 in production (NODE_ENV === 'production'). Pass { enabledInProd: true } to render it anyway — useful for an internal developer-portal deployment, but never safe on a public surface unless your APIs are intentionally documented to the world.

Options

| Option | Default | Notes | | --- | --- | --- | | routePath | /_docs | Path the page is served from. The JSON is at ${routePath}/api.json. | | pageTitle | LuckyStack — API docs | Shown in the header + browser tab. Pass your project name explicitly — there is no implicit lookup from ProjectConfig. | | enabledInProd | false | Set to true to render the docs in production. | | apiDocsPath | getGeneratedApiDocsPath() | Override the JSON file path. Default reads from ProjectConfig.paths.generatedApiDocs. |

How it works

The docs page is a single embedded HTML file (no build step, no React, no external dependencies). It fetches ${routePath}/api.json at runtime, which is served from the project's apiDocs.generated.json — generated by @luckystack/devkit's type-map emitter on every dev-server reload and on every npm run generateArtifacts.

The handler is a customRoutes predicate: it returns true when it matches the configured paths, false otherwise — so it composes cleanly with any other custom HTTP handler.

Related architecture docs

• docs/ARCHITECTURE_API.md — the lifecycle these endpoints document.
• docs/ARCHITECTURE_PACKAGING.md — how apiDocs.generated.json is produced.

License

MIT — see the repository LICENSE.