Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
redoc
✓ import { redoc } from 'redoc-express';
✗ import redoc from 'redoc-express';
The main middleware function is a named export, not a default export.
redoc
✓ const { redoc } = require('redoc-express');
✗ const redoc = require('redoc-express');
For CommonJS, use object destructuring as 'redoc' is a named export.
RedocOptions
✓ import { RedocOptions } from 'redoc-express';
TypeScript users can import type definitions for configuring ReDoc options.
This quickstart sets up a basic Express server, serves a minimal OpenAPI 3.0 specification, and integrates `redoc-express` to display interactive API documentation at the '/docs' endpoint. It demonstrates passing configuration options to ReDoc for customization.
import express from 'express';
import { redoc } from 'redoc-express';
import path from 'path';
const app = express();
const port = process.env.PORT || 3000;
// A minimal OpenAPI spec for demonstration
const openApiSpec = {
openapi: '3.0.0',
info: {
title: 'My Awesome API',
version: '1.0.0',
description: 'An example API to demonstrate redoc-express',
},
paths: {
'/hello': {
get: {
summary: 'Says hello',
responses: {
'200': {
description: 'A greeting message',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
message: { type: 'string' }
}
},
example: { message: 'Hello, World!' }
}
}
}
}
}
}
},
components: {
schemas: {}
}
};
// Serve the OpenAPI spec as a JSON file
app.get('/openapi.json', (req, res) => {
res.json(openApiSpec);
});
// Mount the redoc-express middleware
app.use(
'/docs',
redoc({
title: 'API Documentation',
specUrl: '/openapi.json', // URL where your OpenAPI spec is served
redocOptions: {
theme: {
colors: { primary: { main: '#607d8b' } },
typography: {
fontFamily: 'Montserrat, sans-serif'
}
}
}
})
);
// Basic route for the API itself
app.get('/hello', (req, res) => {
res.json({ message: 'Hello, World!' });
});
app.listen(port, () => {
console.log(`Server running on http://localhost:${port}`);
console.log(`API Docs available at http://localhost:${port}/docs`);
console.log(`API Endpoint: http://localhost:${port}/hello`);
});
Debug
Known issues
gotchaThe `specUrl` option for `redoc-express` expects a publicly accessible URL to your OpenAPI specification, not a local file path. If your spec is a local file, you must serve it via another Express route or a static file server first.fixEnsure your OpenAPI spec (JSON or YAML) is served at an HTTP/HTTPS endpoint, and provide that URL to `redoc-express` via the `specUrl` option. For local files, create an Express route like `app.get('/openapi.json', (req, res) => res.sendFile('path/to/spec.json'));` affects: >=1.0.0
breakingBreaking changes in the underlying ReDoc library (which `redoc-express` uses) might affect the `redocOptions` configuration. While `redoc-express` API tends to be stable, the shape of the `redocOptions` object can change between major ReDoc versions.fixAlways review the `redoc` library's release notes when updating `redoc-express` to check for changes in available options or their structure. Validate your `redocOptions` configuration against the latest `redoc` documentation.
affects: Consult `redoc` release notes
gotchaIncorrect Content Security Policy (CSP) headers on your server might block ReDoc from loading external resources or executing inline scripts, leading to a blank page or errors in the console. `redoc-express` offers `nonce` support.fixIf you have a strict CSP, ensure that the policy allows scripts from `cdn.jsdelivr.net` (or wherever ReDoc assets are loaded from) and permits the execution of the necessary inline scripts. Use the `nonce` option in `redoc-express` if your CSP requires nonces: `redoc({ ..., nonce: res.locals.cspNonce })`. affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'redoc-express'
The 'redoc-express' package has not been installed or is not correctly linked in your project.
fixRun `npm install redoc-express` or `yarn add redoc-express` in your project directory.
Something went wrong... Failed to fetch
The ReDoc UI could not fetch the OpenAPI specification from the `specUrl` provided. This often happens if the URL is incorrect, the server serving the spec is unreachable, or there are CORS issues.
fixVerify that the `specUrl` points to a valid and accessible OpenAPI JSON/YAML file. Test the URL directly in your browser. Ensure your server is running and configured to serve the spec at that endpoint, and that CORS policies allow the ReDoc page to fetch it if hosted on a different domain.
YAMLException: failed to parse YAML
The OpenAPI specification provided is not valid YAML or contains syntax errors.
fixValidate your OpenAPI specification using an online validator (e.g., Swagger Editor or Redocly CLI `lint` command) to identify and correct any syntax or structural errors before serving it.
Audit
Dependencies
expressrequiredThis package is an Express middleware and requires Express.js to function. It is compatible with Express 4.x and 5.x.