fuma-nama/fumadocs @fumadocs/asyncapi@0.4.0

on GitHub

Headless API pages

API pages are now built on a headless layer, use it to build your own UI:

• createAsyncAPIRenderer() and <AsyncAPIProvider /> with your own components.
• the hooks of pages and operations: useAsyncAPI(), useComponents(), useRenderContext(), useServer(), useOperation() and useOperationSecurity().
• useServer() resolves server URLs: resolveUrl(id) fills in the variables of a server, and the selected one carries its title.

'use client';
import { createAsyncAPIRenderer } from '@fumadocs/asyncapi';

export const AsyncAPIPage = createAsyncAPIRenderer({
  components: { Operation, Markdown, CodeBlock, Heading, SchemaUI },
});

See Headless.

@fumadocs/asyncapi/ui renders through the layer, its options are unchanged except content.renderAPIExampleLayout, which was never rendered and is removed.

Install the UI

The UI of API pages can be installed with Fumadocs CLI and edited, reusing the components/ui files you already have:

npx @fumadocs/cli add fumadocs/asyncapi/page

It installs <AsyncAPIPage /> itself, import it from @/components/asyncapi/page in place of your components/api-page.tsx.

To replace parts of it, install fumadocs/asyncapi/operation or fumadocs/api-docs/schema and pass them to the new components options:

export const AsyncAPIPage = createAsyncAPIPage({
  components: { Operation, SchemaUI: Schema },
});

Remove generateTypeScriptDefinitions

The option was never rendered by API pages, and it is gone with its @fumari/json-schema-ts dependency. Passing it is now a type error, nothing else changes.

Client-safe package entry

generateFiles() reads and writes files, so the package entry ships a stubbed build under the browser condition. Client components can import createAsyncAPIRenderer() and the hooks without pulling node:fs into the bundle.

Highlighting out of the box

createAsyncAPIRenderer() highlights code blocks with the full Shiki bundle, pass a smaller shiki factory to trim it.

Default page components

createOpenAPIRenderer(), createAsyncAPIRenderer() and createGraphQLRenderer() fill the Markdown, CodeBlock and Heading components you didn't pass, rendering Markdown through Remark and code blocks through Shiki:

createOpenAPIRenderer({
  components: { SchemaUI, Operation },
});

shiki defaults to the full bundle, createOpenAPIBaseRenderer() takes the factory you pass instead and leaves the bundle out.

Installable UI

The UI an API page renders through is now part of the installation, instead of being imported from the package:

Select and Input follow the Shadcn UI API, so a project that already has them keeps its own. @fumadocs/story no longer ships a second copy of either.

labelVariants moved to the installed label component, leaving the input a plain Shadcn-compatible primitive.

The integrations share one implementation of these internally, instead of each keeping a copy: the selected server and its variables, the state of an async request, the coloured label of methods and kinds, and the plain-object check of both schema layers.

The request pipeline of the playground stays in the package too, so an installed playground drives it instead of copying it: encodeRequestData(), resolveMediaAdapter(), isMediaTypeSupported() and the request data types come from fumadocs-openapi/requests, and createBrowserFetcher() with usePlaygroundAuth() from fumadocs-openapi/playground.

@fumadocs/json-schema

The JSON Schema utilities of API pages are now their own package, with no Fumadocs dependencies:

import { dereference, matches, mergeAllOf, sample, stringify } from '@fumadocs/json-schema';
import { bundle } from '@fumadocs/json-schema/bundle';

bundle() is a separate entry because it reads files and URLs, everything else runs in the browser.

@fumadocs/json-schema/react renders a schema into the data an API page draws: generateSchemaUI() with the SchemaData and InfoTag types. It was in the Schema UI before, where every install copied it. A labelled tag can be prose, for values like a Markdown deprecation reason.

They were @fumadocs/api-docs/schema/* before, and the API was cleaned up while moving:

Trim code usages and TypeScript definitions

createOpenAPIBaseRenderer() from fumadocs-openapi registers no code usage generators and no TypeScript definitions, so a page built on it bundles only what you pass:

import { createCodeUsageGeneratorRegistry } from 'fumadocs-openapi/requests/generators';
import { curl } from 'fumadocs-openapi/requests/generators/curl';

createOpenAPIBaseRenderer({
  shiki,
  codeUsages: createCodeUsageGeneratorRegistry().register(curl),
  components: { ... },
});

createOpenAPIRenderer() and fumadocs-openapi/ui register every language and TypeScript definitions for you.

Remove useStorageKey()

The hook returned (name) => storageKeyPrefix + name. Read the prefix from the page instead:

const { storageKeyPrefix } = useOpenAPI();
localStorage.getItem(`${storageKeyPrefix}my-key`);

useAsyncAPI() works the same way.

@fumadocs/api-docs is no longer published

It held the UI the integrations share, and that UI is now either bundled into them or installed with Fumadocs CLI, so nothing imports it by name any more. If you imported it directly:

The CLI namespace is unchanged, fumadocs/api-docs/schema still installs the Schema UI.