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

npm 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:

// app/reference/route.ts
import { ApiReference } from '@scalar/nextjs-api-reference'

const config = {
  spec: {
    url: '/openapi.json',
  },
}

export const GET = ApiReference(config)

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

const config = {
  spec: {
    content: '...',
  },
}

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:

const config = {
  theme: 'purple',
}

Pages router

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

npm install @scalar/api-reference-react

import { ApiReferenceReact } from '@scalar/api-reference-react'
import '@scalar/api-reference-react/style.css'

export default function References() {
  return (
    <ApiReferenceReact
      configuration={{
        spec: {
          url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json',
        },
      }}
    />
  )
}

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/[email protected]

You can find all available CDN versions here

// app/reference/route.ts
import { ApiReference } from '@scalar/nextjs-api-reference'

const config = {
  spec: {
    url: '/openapi.json',
  },
  cdn: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest',
}

export const GET = ApiReference(config)