@scalar/nuxt

Scalar API Reference Nuxt Module

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

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add @scalar/nuxt

That's it! You can now use @scalar/nuxt in your Nuxt app ✨

Configuration

If you are using nuxt server routes you can enable scalar simply by enabling openAPI in the nitro config in your nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  nitro: {
    experimental: {
      openAPI: true,
    },
  },
})

If you would like to add your own OpenAPI spec file you can do so with the following minimal config

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  scalar: {
    spec: {
      url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
    },
  },
})

By default the docs will be hosted at /docs but you an easily customize that, here's a more in depth config example.

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  scalar: {
    darkMode: true,
    hideModals: false,
    hideDownloadButton: false,
    metaData: {
      title: 'API Documentation by Scalar',
    },
    proxyUrl: 'https://proxy.scalar.com',
    searchHotKey: 'k',
    showSidebar: true,
    pathRouting: {
      basePath: '/scalar',
    },
    spec: {
      url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
    },
  },
})

For multiple references, pass in an array of configuration objects which extend on top of the base config.

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  scalar: {
    darkMode: true,
    metaData: {
      title: 'API Documentation by Scalar',
    },
    proxyUrl: 'https://proxy.scalar.com',
    configurations: [
      {
        spec: {
          url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml,
        },
        pathRouting: {
          basePath: '/yaml',
        },
      },
      {
        spec: {
          url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json',
        },
        pathRouting: {
          basePath: '/json',
        },
      },
    ],
  },
})

For theme configuration, you can pass a theme property to the configuration object. The default theme is nuxt, but you can also pass default to use the default theme.

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  scalar: {
    theme: 'nuxt',
  },
})

Troubleshooting

If you come across any **** not default export errors, its likely you are using pnpm. A temporary fix for this would be to enable shamefully-hoist until we sort out what is causing the package issues.

To do this, just create a .npmrc file in your project root and fill it with:

shamefully-hoist=true