API Reference for Nuxt

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 document you can do so with the following minimal config

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  scalar: {
    url: 'https://registry.scalar.com/@scalar/apis/galaxy?format=yaml',
  },
})

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

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  scalar: {
    darkMode: true,
    hideModels: false,
    metaData: {
      title: 'API Documentation by Scalar',
    },
    proxyUrl: 'https://proxy.scalar.com',
    searchHotKey: 'k',
    showSidebar: true,
    pathRouting: {
      basePath: '/scalar',
    },
    url: 'https://registry.scalar.com/@scalar/apis/galaxy?format=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: [
      {
        url: 'https://registry.scalar.com/@scalar/apis/galaxy?format=yaml',
        pathRouting: {
          basePath: '/yaml',
        },
      },
      {
        url: 'https://registry.scalar.com/@scalar/apis/galaxy?format=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',
  },
})

Using with Tailwind CSS

If your Nuxt project uses Tailwind CSS v4, you need to set the CSS layer order so that Tailwind's utility classes take priority over Scalar's styles. Add this to the top of your main CSS file (for example, assets/css/main.css):

@layer scalar-base, scalar-theme, scalar-config, theme, base, components, utilities;
@import "tailwindcss";

For full details, see Embedding with CSS Frameworks.

Troubleshooting

If you come across any **** not default export errors, it's 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

Nitro

Platformatic