Igniter Studio (API Playground)

Igniter Studio is an interactive UI based on Scalar API Reference that allows you to explore and test your API directly from the browser. It consumes your openapi.json and offers features like sending authenticated requests, viewing schemas, and executing examples.

Enable in development

Run your app with the flag:

Code
npx @igniter-js/cli dev --docs
  • By default, the UI will be available at /docs.
  • You can customize the output directory with --docs-output.

Enable in production

Configure the documentation using the .docs() method in your Igniter builder:

Code
import { Igniter } from '@igniter-js/core'
import openapi from './docs/openapi.json'

export const igniter = Igniter
  .context(createIgniterAppContext())
  .store(store)
  .logger(logger)
  .config({
    baseURL: process.env.NEXT_PUBLIC_IGNITER_API_URL || 'http://localhost:3000',
    basePATH: process.env.NEXT_PUBLIC_IGNITER_API_BASE_PATH || '/api/v1',
  })
  .docs({
    openapi,
    info: {
      title: 'My API',
      version: '1.0.0',
      description: 'API description',
      contact: {
        name: 'Your Team',
        email: 'team@example.com',
        url: 'https://github.com/your-org/your-repo'
      },
      license: {
        name: 'MIT',
        url: 'https://opensource.org/licenses/MIT'
      }
    },
    playground: {
      enabled: true,
      route: "/docs",
      security: ({ request }) => {
        // Return false to block
        // Or return an object with headers/query/cookies for requests made via UI
        const token = request.headers.get("authorization")
        if (!token) return false
        return { headers: { Authorization: token } }
      },
    },
  })
  .create()
  • In production, if security is not provided, Studio is automatically disabled to avoid exposure.
  • The security function is called on each Studio request and should decide whether to allow and which credentials to attach.

Customizing the UI

Igniter Studio uses Scalar API Reference under the hood. You can customize displayed metadata (title, description, version) through the info field in your .docs() configuration, as well as configure servers and securitySchemes to reflect your environment and authentication mechanisms.

Best practices

  • Protect the /docs route behind authentication when publicly exposed.
  • Don't expose secrets in the client; use the security function to inject only what's necessary.
  • Generate and publish openapi.json alongside your deploy to keep the UI synchronized.

Common issues