Scalar: an OpenAPI reference and API client that runs from one HTML file

The gap Scalar fills between an OpenAPI file and a usable reference

An OpenAPI document is machine-readable and nearly unreadable to a human. Most teams solve that by generating a reference with a docs framework, which means adopting a build pipeline, a theme system and often a hosted service. Scalar's pitch is narrower: point it at a spec URL and get a rendered reference with a built-in request tester, code samples and framework integrations. The README frames the two halves of the project separately. The reference side "Renders OpenAPI/Swagger documents" and "Comes with an API testing tool." The client side is described as an "offline-first API Client built for OpenAPI" with environment variables and dynamic parameters, distributed as a download for Windows, macOS and Linux and also usable in the browser at client.scalar.com. The intended user is an engineer who owns an API and wants the documentation surface to be a rendering of the spec rather than a second artifact that drifts from it. The README also notes the reference "Doesn't look like 2011," which is a fair summary of the niche: Swagger UI works, and a lot of teams put up with it rather than rebuild their docs.

How the reference renders a spec and where the proxy fits

The mechanism is client-side. You load a script from a CDN and call a factory function with a container selector and an options object. The two options shown in the README are url, the location of the OpenAPI/Swagger document, and proxyUrl, which the README annotates as a way to "Avoid CORS issues." That second option is the part worth understanding before you deploy. Because the browser fetches the spec and later sends test requests from the page, a spec hosted on a different origin than the docs page will be blocked by the browser unless the server sends the right headers or you route the fetch through a proxy. Scalar's own example uses https://proxy.scalar.com, which means requests in that configuration pass through a third party. For a public spec that is fine; for an internal one it is a decision you have to make deliberately, either by hosting the spec same-origin or by running your own proxy. The repository layout reinforces that this is a front-end product rather than a server: packages/, integrations/, examples/ and projects/ sit at the top level, alongside a pnpm-workspace.yaml, turbo.json and a single root package.json that is marked private. There is no application server in the tree to deploy.

Installing Scalar and rendering your first reference

The README's quickstart needs no build step and no package install: a single HTML file is enough. The script tag pulls @scalar/api-reference from jsDelivr, and the inline script calls Scalar.createApiReference with a selector and an options object. Replace the url value with your own spec and serve the file over HTTP rather than opening it from disk, since the browser fetch needs an origin.

<!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 src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
    <script>
      Scalar.createApiReference('#app', {
        url: 'https://registry.scalar.com/@scalar/apis/galaxy?format=json',
        proxyUrl: 'https://proxy.scalar.com',
      })
    </script>
  </body>
</html>

What you should see is the reference rendered into the #app div, with the operations from the spec listed and a request panel attached to each one. The README points to a CodePen example for custom headers, which is the next thing most people need once authentication is involved. If you would rather not hand-write the HTML, the integrations list covers ASP.NET Core, FastAPI, Express, Fastify, Flask, Hapi, Go, Astro, Docusaurus, AdonisJS, Django, Django Ninja, Elixir, Aspire and Docker, among others, each with its own page under scalar.com/products/api-references/integrations. For the desktop client, the README directs you to scalar.com/download for Windows, macOS and Linux builds rather than a package manager command.

If you want to work on the project itself, the root package.json pins pnpm as the package manager and declares an engines field of ^12.0.0, with turbo driving the build scripts. That is a contributor path, not an adoption path.

The CORS and proxy trade-off is the real deployment constraint

The quickstart's proxyUrl line is easy to copy and easy to forget. Any setup where the spec or the API lives on a different origin from the docs page needs either permissive CORS headers on the API or a proxy in between. Scalar's hosted proxy solves the demo case, but pointing a private API's traffic at a third-party host is a different risk profile than rendering a public spec. The README does not document a self-hosted proxy option, so if that is a requirement you are reading the wrong page and should check the integration docs for your framework instead. A second limitation is structural: Scalar renders a spec. If your team treats the OpenAPI document as a generated artifact that lags behind the code, Scalar will render that lag faithfully and beautifully. It does not infer an API from source, and the README makes no such claim. Teams whose spec is stale will get a polished reference to a stale spec. The framework integrations exist partly to close that gap by serving the spec from the application itself, but that only helps if the framework generates the spec in the first place.

Scalar versus Swagger UI and versus a docs platform

The closest comparison is Swagger UI, which also renders OpenAPI/Swagger documents in the browser and also supports trying requests. The practical difference is scope and polish: Swagger UI is a single-purpose renderer, while Scalar ships a reference renderer and a separate desktop client with environments and dynamic parameters, and maintains integrations for a long list of frameworks. If you only need a spec rendered and you already have Swagger UI wired into a framework you are happy with, switching buys you presentation and a request client, not new capability. The other comparison is an API documentation platform such as the hosted services that combine a reference with guides, versioning and search. Scalar's HTML/JS integration is explicitly described as working everywhere, which is the point: it is a component you embed, not a platform you migrate onto. The cost of that choice is that anything beyond rendering the spec, such as long-form guides or a changelog, is your problem to build around it. The repository's documentation/ and examples/ directories show the project's own docs site is assembled from these pieces, which is a reasonable signal about the intended shape of an adoption.

Maintenance, licence and what a Scalar upgrade actually costs

The repository is not archived, and the last push was on 2026-09-21. Releases are frequent: the recent list shows releases on 2026-09-19, 2026-09-18 and 2026-09-16, and the project uses changesets (the .changeset/ directory and @changesets/cli in devDependencies) to manage versioning across the monorepo. That cadence is the upgrade cost. The CDN script tag in the quickstart is unversioned, so it tracks the latest published build; a breaking change in the reference component reaches your page without any action on your part. Pinning the version in the script URL is the obvious mitigation, and the README's example does not do it. The licence is MIT, which permits commercial use and modification; the LICENSE file is at the repository root. Note that the README describes a hosted client at client.scalar.com and a registry at registry.scalar.com, which are separate from the MIT-licensed code. Nothing in the README states the terms of those hosted services, so treat the licence as covering the repository and not the hosted endpoints. This is not legal advice; read the LICENSE file and the terms for any hosted service you point at.

Editorial conclusion

Adopt Scalar if you already maintain an OpenAPI or Swagger document and want a reference page plus a request client without a docs platform contract. Skip it if your API description is hand-written prose or you need Airflow-style DAG authoring. Before committing, verify that your spec renders correctly in the demo and confirm which package in the monorepo you are actually installing.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. scalar/scalar on GitHub