Integrations
How to embed OmniSpec depends on your stack. This page routes you to the right guide.
Decision guide
- React app → import the
<OmniSpecRenderer>React component directly from@apiboost/omnispec. - Non-React app (Vue, Angular, Svelte, vanilla HTML) → use the
framework-agnostic Web Component,
<omnispec-renderer>. - Docs site (Docusaurus, etc.) → use the framework-specific guide below. If the docs site is React-based, embed the React component inside a client-only boundary; otherwise use the Web Component.
If you are already in React, prefer the React component — there is no benefit to wrapping it in a custom element.
Where to go
| You are building | Use | Guide |
|---|---|---|
| A Docusaurus docs site | React component in <BrowserOnly> | Docusaurus |
| Another docs-site framework | see the guides below | Docs-as-Code |
| A React app (Vite, Next.js, CRA, …) | <OmniSpecRenderer> | App-framework recipes |
| Vue, Angular, Svelte, or vanilla HTML | <omnispec-renderer> | Web Component |
Docs-as-Code
Copy-paste embedding guides for the common documentation generators. Each one picks the right entry point for its stack and handles the client-only mount, theme sync, and sizing.
| Framework | Entry point | Guide |
|---|---|---|
| Docusaurus | React component | Docusaurus |
| VitePress | Web Component (Vue) | VitePress |
| Nextra | React component (Next.js) | Nextra |
| Astro / Starlight | Web Component or React island | Astro / Starlight |
| MkDocs | Web Component (no build) | MkDocs |
| Plain HTML | Web Component (no build) | Plain HTML |
The client-only gotcha
OmniSpec is client-rendered: it parses and renders the spec in the browser after mount. It does not crash under SSR/SSG, but it emits only a themed shell on the server, and it needs a client-only boundary to avoid a hydration mismatch (and, in strict static builds, to avoid pulling browser-only APIs into the server bundle):
- Next.js: add
'use client', ordynamic(() => import('@apiboost/omnispec').then((m) => m.OmniSpecRenderer), { ssr: false }). - Docusaurus / other SSG: wrap it in
<BrowserOnly>(see the Docusaurus guide).
See Getting Started → Server-side rendering for the full explanation.