Scalar Next.js API Reference Handler

This plugin provides an easy way to render a beautiful API reference based on an OpenAPI/Swagger file with Next.js.

Installation

1npm install @scalar/nextjs-api-reference

Compatibility

This package is compatible with Next.js 15 and is untested on Next.js 14. If you want guaranteed Next.js 14 support please use version 0.4.106 of this package.

Usage

If you have a OpenAPI/Swagger file already, you can pass a URL to the plugin in an API Route:

1// app/reference/route.ts
2import { ApiReference } from '@scalar/nextjs-api-reference'
3
4const config = {
5  spec: {
6    url: '/openapi.json',
7  },
8}
9
10export const GET = ApiReference(config)

Or, if you just have a static OpenAPI spec, you can directly pass it as well:

1const config = {
2  spec: {
3    content: '...',
4  },
5}

We wrote a detailed integration guide for Next.js.

The Next.js handler takes our universal configuration object, read more about configuration in the core package README.

Themes

By default, we’re using a custom Next.js theme and it’s beautiful. But you can choose one of our other themes, too:

1const config = {
2  theme: 'purple',
3}

Pages router

If you are using the pages router, you can import the React component

1npm install @scalar/api-reference-react

1'use client'
2
3import { ApiReferenceReact } from '@scalar/api-reference-react'
4import '@scalar/api-reference-react/style.css'
5
6export default function References() {
7  return (
8    <ApiReferenceReact
9      configuration={{
10        spec: {
11          url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json',
12        },
13      }}
14    />
15  )
16}

Specific CDN version

By default, this integration will use the latest version of the @scalar/api-reference.

You can also pin the CDN to a specific version by specifying it in the CDN string like https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.28

You can find all available CDN versions here

1// app/reference/route.ts
2import { ApiReference } from '@scalar/nextjs-api-reference'
3
4const config = {
5  spec: {
6    url: '/openapi.json',
7  },
8  cdn: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest',
9}
10
11export const GET = ApiReference(config)