Guide · Open source

How to use Scalar: render and test an OpenAPI spec

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Scalar is an open-source project that takes an OpenAPI (Swagger) description of a web API and turns it into a browsable, interactive reference page. It also includes an API client for sending test requests. This guide explains what you need before starting, how to set up a single HTML page that renders your spec, and how to use the client to try endpoints.

Scalarscalar/scalar · ★ 16.4k · MIT Install options & downloads

Quick start

1Prepare an OpenAPI document. Make sure you have an OpenAPI or Swagger document reachable at a URL. Scalar renders existing specs rather than writing them.
2Create an HTML file. Make a single HTML file with a div that has the id app. No build step is needed.
3Load the Scalar ESM build. Import createApiReference from the jsDelivr CDN path shown in the README inside a module script.
4Point Scalar at your spec. Set the url option to your OpenAPI document and keep proxyUrl if you need to avoid CORS issues.
5Open the page in a browser. Load the HTML file and check that the API reference displays your endpoints.
6Send a test request. Use the API client to try an endpoint from the reference page.

What you need before you start

Scalar works from an OpenAPI or Swagger document. The README centers on rendering existing OpenAPI specs rather than writing them, so if you don't have a spec yet, you will need to create one or generate it from your server framework first.

The source does not list any prerequisites for the HTML setup beyond a web browser and the ability to create a single HTML file.

An OpenAPI or Swagger document with a URL the browser can reach
A text editor to create one HTML file
An internet connection, since the quickstart loads assets from a CDN and a proxy

Set up Scalar with a single HTML file

The simplest route is one HTML file that loads the ESM build from the jsDelivr CDN. The README says no build step is required. Point the url option at your OpenAPI document. The example in the README uses a sample document hosted on scalar.com.

The proxyUrl option is there to avoid CORS issues. The README's example uses a proxy hosted by scalar.com, so review that before using it in a production setup.

Replace the example url value with the address of your own OpenAPI document
Keep the proxyUrl option if your spec is on a different origin, or review the README for alternatives

<!doctype html>
<html>
  <head>
    <title>Scalar API Reference</title>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1" />
  </head>

  <body>
    <div id="app"></div>

    <script type="module">
      import { createApiReference } from 'https://cdn.jsdelivr.net/npm/@scalar/api-reference/esm.js'

      createApiReference('#app', {
        // The URL of the OpenAPI document
        url: 'https://registry.scalar.com/@scalar/apis/galaxy?format=json',
        // Avoid CORS issues
        proxyUrl: 'https://proxy.scalar.com',
      })
    </script>
  </body>
</html>

Use Scalar with your web framework

If your backend already runs a supported framework, you can use an integration instead of the HTML file. The source lists integrations for frameworks including Express, FastAPI, Hono, Fastify, Flask, Django, Laravel, and NestJS, plus an HTML/JS option that works everywhere.

The README also describes a coding agent skill. Its install command is shown below as optional. The agent prompt in the README asks the agent to inspect your project, choose a matching integration, serve the reference at /scalar, and connect it to your OpenAPI document.

Pick the integration page that matches your framework from the README's integrations list
Use the HTML/JS integration if your framework is not listed

npx skills add scalar/scalar --skill scalar-api-reference

Test endpoints with the API client

Scalar includes an offline-first API client built for OpenAPI. The README lists environment variables and dynamic parameters among its features. It also says the client can be used in the browser or downloaded as a desktop app for Windows, macOS, and Linux.

The README also mentions a Watch Mode that syncs with your server framework. Check the Scalar documentation for how to enable and use it, since the README only names the feature.

Try the client in the browser at client.scalar.com
Download the desktop app for Windows, macOS, or Linux from scalar.com/download
Use environment variables and dynamic parameters to reuse values across requests

Generate code examples and customise the look

The README says Scalar can generate code examples for many languages and frameworks, which helps readers of your docs copy working requests. It also links to configuration and theme guides on the Scalar site.

The README does not give details of the configuration options beyond the examples shown, so consult the configuration and themes pages for specific settings.

Code examples: generated for many languages and frameworks, according to the README
Configuration and themes: documented on the Scalar website

Get the source code

If you want to work with the project itself, the README gives a clone command for the GitHub repository. The project is licensed under MIT and written in TypeScript.

git clone https://github.com/scalar/scalar

What people use it for

Publishing interactive docs for an internal REST API from its OpenAPI file
Letting developers send test requests from the same page they read the docs on
Generating copyable code examples for an API reference
Adding a documentation route to a backend built with a supported framework

Frequently asked questions

Is Scalar free to use?

The README lists Scalar as free and open-source, and the repository is licensed under MIT. Check the LICENSE file in the repository for the full terms.

What do I need to use Scalar?

The source lists no prerequisites. You need an OpenAPI or Swagger document, since the README centers on rendering existing specs, and a browser for the HTML setup.

Does Scalar work without an OpenAPI document?

The README says Scalar centers on rendering existing OpenAPI specs rather than writing them. Without a document, you would need to create one first or use a different workflow.

Is Scalar a good choice for a fully self-hosted setup?

Review the README before choosing it for that use. The quickstart example loads assets and a proxy from scalar.com and the jsDelivr CDN, so you need to check which parts you can host yourself.

What are the alternatives to Scalar?

The comparable projects named in the source are Swagger UI, Redoc, and Stoplight Elements. All of them render API documentation from specifications.

Can I use Scalar with FastAPI or Express?

Yes. The README lists integrations for both FastAPI and Express, along with an HTML/JS option for any other setup.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Scalar suits developers and teams who already maintain an OpenAPI or Swagger document and want readable, interactive docs with testing in the same place. If you don't have a spec, or you need a setup that avoids external CDNs and proxies, look at the alternatives such as Swagger UI, Redoc, or Stoplight Elements.

Install options & downloads