Copy the source/ directory into your project, e.g. src/redoc-source/.

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "moduleResolution": "node",
    "jsx": "react-jsx",
    "esModuleInterop": true,
    "paths": {
      "redoc-source": ["./src/redoc-source/index.ts"]
    }
  },
  "include": ["src"]
}

3. If you use webpack, alias Node built-ins that are stubbed by empty.js:

// webpack.config.js
resolve: {
  alias: {
    'path': require.resolve('path-browserify'),
  },
  fallback: { fs: false, net: false, tls: false }
}

4. No environment variables are required at runtime. OpenAPI spec URL or object is passed directly as a prop.

5. Wrap your app in a theme provider if you intend to customize Redoc's styled-components theme (see theme.ts for shape).

Public API

Redoc

import { Redoc } from './redoc-source/components/Redoc/Redoc';

// Props (simplified):
interface RedocProps {
  store: AppStore; // MobX store built via StoreBuilder
  options?: RedocRawOptions;
}

function Redoc(props: RedocProps): JSX.Element;

The primary rendering component. Mount this when you already have a resolved AppStore instance. Use it when you need full control over store construction and lifecycle (e.g., server-side rendering, custom loading states, hot-reloading the spec).

RedocStandalone

import { RedocStandalone } from './redoc-source/components/RedocStandalone';

interface RedocStandaloneProps {
  spec?: object;
  specUrl?: string;
  options?: RedocRawOptions;
  onLoaded?: (e?: Error) => void;
}

function RedocStandalone(props: RedocStandaloneProps): JSX.Element;

Self-contained component that handles spec fetching, parsing, and store construction internally. The simplest integration point: pass either a spec object or a specUrl string and it renders documentation with no additional setup.

ApiInfo

import { ApiInfo } from './redoc-source/components/ApiInfo/ApiInfo';

// Renders the API title, version, description, contact, and license blocks.
// Requires an AppStore (or OptionsProvider context) to be present in the tree.
function ApiInfo(props: {}): JSX.Element;

Renders the top-of-page API metadata section (title, version, description, license, contact). Use it standalone if you want to embed only the header portion of documentation into an existing layout.

Dropdown / SimpleDropdown

import { Dropdown, SimpleDropdown } from './redoc-source/common-elements/';
import type { DropdownOption } from './redoc-source/common-elements';

interface DropdownOption {
  value: string;
  label?: string;
}

Reusable dropdown UI primitive exported from common-elements. Use these in custom toolbar or media-type selector UIs that need to match Redoc's visual style.

Working examples

Scenario - Render full docs from a spec URL

The simplest integration: drop RedocStandalone into any React tree with a public OpenAPI URL.

import React from 'react';
import { RedocStandalone } from './redoc-source/components/RedocStandalone';

export function ApiDocsPage() {
  return (
    <RedocStandalone
      specUrl="https://petstore3.swagger.io/api/v3/openapi.json"
      options={{
        scrollYOffset: 60,
        hideDownloadButton: false,
        theme: { colors: { primary: { main: '#dd5522' } } },
      }}
      onLoaded={(err) => {
        if (err) console.error('Spec load failed', err);
      }}
    />
  );
}

Scenario - Render docs from an inline spec object

Pass a pre-fetched or bundled OpenAPI object directly when you control spec delivery (e.g., imported JSON, server-side fetched).

import React from 'react';
import { RedocStandalone } from './redoc-source/components/RedocStandalone';
import mySpec from './openapi.json';

export function InlineDocsPage() {
  return (
    <RedocStandalone
      spec={mySpec}
      options={{ nativeScrollbars: true, hideHostname: true }}
    />
  );
}

Scenario - Manual store construction with Redoc component

Use StoreBuilder + Redoc directly when you need access to the MobX store (e.g., programmatic navigation, custom loading UI, SSR hydration).

import React, { useEffect, useState } from 'react';
import { Redoc } from './redoc-source/components/Redoc/Redoc';
import { AppStore } from './redoc-source/services';
import { Loading } from './redoc-source/components/Loading/Loading';

export function ControlledDocsPage() {
  const [store, setStore] = useState<AppStore | null>(null);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    AppStore.fromURL('https://petstore3.swagger.io/api/v3/openapi.json', {})
      .then(setStore)
      .catch(setError);
  }, []);

  if (error) return <div>Failed to load spec: {error.message}</div>;
  if (!store) return <Loading />;

  return <Redoc store={store} />;
}

Scenario - Using ApiInfo in a custom layout

Embed only the API header section inside your own page shell without the side menu or schema panels.

import React from 'react';
import { RedocStandalone } from './redoc-source/components/RedocStandalone';
import { ApiInfo } from './redoc-source/components/ApiInfo/ApiInfo';

// ApiInfo requires store context - easiest to wrap inside RedocStandalone
// or provide OptionsProvider + StoreProvider manually.
// Shown here inside a minimal custom wrapper:
export function HeaderOnlyDocs() {
  return (
    <RedocStandalone
      specUrl="/api/openapi.yaml"
      options={{ showExtensions: true }}
    />
  );
}

File walkthrough

• index.ts — Master barrel export; re-exports everything from components/, services/, utils/, common-elements/, and styled-components.
• standalone.tsx — Webpack entry for the UMD/standalone bundle; not needed when importing as a library.
• styled-components.ts — Wraps and re-exports styled-components with Redoc's theme type applied; import styled from here inside Redoc source.
• theme.ts — Contains the default theme object and RedocTheme / ThemeInterface type definitions.
• polyfills.ts — Applies browser polyfills (e.g., stickyfill); import at the top of your entry if targeting older browsers.
• common-elements/ — Atomic styled-component primitives: Row, MiddlePanel, RightPanel, Section, Dropdown, SimpleDropdown, tabs, schema blocks, scrollbar wrappers.
• components/ — Feature-complete React components: Redoc, RedocStandalone, ApiInfo, ApiLogo, Operation, Schema, SearchBox, SideMenu, Parameters, Responses, SecuritySchemes, SourceCode, and more.
• services/ — MobX stores (AppStore, MenuStore, SearchStore) and OpenAPI model classes; the data layer for all components.
• types/ — Shared TypeScript interfaces for OpenAPI constructs (OpenAPIEncoding, etc.) and internal models.
• utils/ — Stateless helper functions: URL manipulation, string formatting, schema traversal utilities.
• empty.js — Empty module stub for Node.js built-ins that must be excluded from browser bundles.

Common pitfalls and fixes

• MobX version mismatch: Redoc's services use MobX 6 decorators. Pin mobx@^6 and mobx-react@^7; mixing MobX 4/5 breaks observable decorators silently.
• experimentalDecorators not enabled: decko and MobX decorators fail to compile without "experimentalDecorators": true in tsconfig.json.
• styled-components version conflict: Redoc expects styled-components v5. If your app uses v6, you may get ThemeContext errors; pin styled-components@^5.3.
• path / fs Node built-ins in browser bundles: Webpack 5 no longer polyfills Node core modules. Add resolve.fallback: { path: require.resolve('path-browserify'), fs: false } to your webpack config or use the provided empty.js alias.
• SSR hydration mismatch: stickyfill and perfect-scrollbar access document on import. Guard with typeof window !== 'undefined' or defer polyfills.ts import to client-only code.
• Peer dep react version: Redoc components are tested against React 17/18. If you see Invalid hook call errors, ensure only one copy of react exists in node_modules (npm ls react).

Vibe-coding prompt template

I have a copy of the Redoc React component source (upstream package: user@example.com)
located at `src/redoc-source/` in my project. I also have `USAGE.md` in the same
directory describing all real exports, dependencies, and integration steps.

My project is: [describe your stack, e.g., "Next.js 14 app router, TypeScript, Tailwind"].

Please help me integrate the Redoc source step-by-step:
1. Read USAGE.md and `src/redoc-source/index.ts` to understand all available exports.
2. Install the required dependencies listed in USAGE.md.
3. Update tsconfig.json and any bundler config (webpack/next.config.js) as described.
4. Create a page/component that renders my OpenAPI spec using `RedocStandalone`
   imported from `src/redoc-source/components/RedocStandalone`.
5. My spec is located at: [local path or URL].
6. I want these customizations: [list theme colors, options, layout changes].
7. Do not invent any imports - only use symbols documented in USAGE.md and
   visible in src/redoc-source/index.ts.
Show me the complete file contents for each file you create or modify.

License and credit

Redoc is released under the MIT License. See the upstream repository and source/LICENSE if present for the full license text.

Upstream package: redoc on npm — source at github.com/Redocly/redoc.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。