Next.js

Next.js enables you to create high-quality web applications with the power of React components. And Scalar enables you to create high-quality API references. What a match, isn’t it?

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

InstallationCopied!

npm install @scalar/nextjs-api-reference

CompatibilityCopied!

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.

UsageCopied!

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 = {
  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 = {
  content: '{ "openapi": "3.1.1", … }',
}

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.

ThemesCopied!

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 routerCopied!

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

npm install @scalar/api-reference-react

'use client'

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

import '@scalar/api-reference-react/style.css'

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

Specific CDN versionCopied!

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

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

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

export const GET = ApiReference(config)

GuideCopied!

Create a new Next.js project (optional)Copied!

Sometimes, it’s great to start on a blank slate and set up a new project:

npx create-next-app@latest my-awesome-app

You’ll get some questions, you can leave all the default answers – or pick what you prefer:

? Would you like to use TypeScript? › No
? Would you like to use ESLint? › No
? Would you like to use Tailwind CSS? … No
? Would you like to use `src/` directory? › No
? Would you like to use App Router? (recommended) › Yes
? Would you like to customize the default import alias (@/*)? … No

That should be it. Jump into the folder and start the development server:

cd my-awesome-app
npm run dev

Great! Open http://localhost:3000 and see the default Next.js homepage. :)

Render your OpenAPI reference with ScalarCopied!

Ready to add your API reference? Cool, there are a few options to integrate your API reference. The recommended way is to use our Next.js integration for app routing:

Recommended: App router

Install the package:

npm add @scalar/nextjs-api-reference

… and add a new app route:

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

const config = {
  url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
}

export const GET = ApiReference(config)

Open http://localhost:3000/reference and there it is: Your new API reference. :)

Alternative: Pages router

But you can also just use our React integration and add a page route:

npm add @scalar/api-reference-react

… and add a new page route:

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

import '@scalar/api-reference-react/style.css'

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