scalar

Q: How do I install scalar?

Run npx skills add https://github.com/codewithmukesh/dotnet-claude-kit --skill scalar in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/scalar/ (personal) or .claude/skills/scalar/ (project).

by codewithmukeshFrontend & Design

Scalar API documentation UI for .NET 10 applications. Covers setup, themes, authentication prefill, multiple documents, layout options, and security. A modern replacement for Swagger UI. Load this skill when setting up API documentation UI, or when the user mentions "Scalar", "MapScalarApiReference", "API reference", "Swagger UI replacement", "API documentation UI", "Scalar theme", "interactive API docs", or "Try It".

Installs: 2.9K
Last 24h: +55
Trending rank: #3124
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/codewithmukesh/dotnet-claude-kit --skill scalar

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads scalar automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Scalar

Core Principles

Scalar replaces Swagger UI — Scalar is the recommended API documentation UI for .NET 10. Faster rendering, built-in dark mode, code generation for dozens of languages, and full OpenAPI 3.1 support.
Development only by default — Wrap MapScalarApiReference() in an IsDevelopment() check. API documentation exposes internal structure. If needed in production, add authorization.
Disable the proxy for sensitive APIs — Scalar's "Try It" feature routes through proxy.scalar.com by default. Disable it with .WithProxy(null) to keep auth headers local.
Security schemes come from OpenAPI — Scalar reads security schemes from the OpenAPI document. Configure them via document transformers, not in Scalar directly.

Patterns

Basic Setup

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();  // UI at /scalar/v1
}

app.Run();

Customized Configuration

app.MapScalarApiReference(options =>
{
    options
        .WithTitle("Checkout API")
        .WithTheme(ScalarTheme.Mars)
        .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient)
        .WithPreferredScheme("Bearer")
        .WithProxy(null)  // Disable external proxy
        .WithSidebar(true);
});

Authentication Prefill (Development Only)

Pre-fill credentials so developers don't have to paste tokens manually. The OpenAPI document must already include the security scheme via a document transformer.

if (app.Environment.IsDevelopment())
{
    app.MapScalarApiReference(options =>
    {
        options
            .WithPreferredScheme("Bearer")
            .AddHttpAuthentication("Bearer", auth =>
            {
                auth.Token = "dev-only-test-token";
            });
    });
}

Other auth types:

// API Key
options.WithApiKeyAuthentication(apiKey =>
{
    apiKey.Token = "dev-api-key";
});

// OAuth2
options.WithOAuth2Authentication(oauth =>
{
    oauth.ClientId = "your-client-id";
    oauth.Scopes = ["openid", "profile"];
});

Available Themes

// ScalarTheme options: Default, Moon, Purple, BluePlanet, Saturn, Mars, DeepSpace, Kepler, Solarized, Laserwave
options.WithTheme(ScalarTheme.Mars);

Multiple API Documents

// Register multiple OpenAPI documents
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2-beta");

// Scalar picks them up automatically
app.MapOpenApi();
app.MapScalarApiReference();
// Available at /scalar/v1 and /scalar/v2-beta

Or configure documents explicitly:

app.MapScalarApiReference(options =>
{
    options
        .AddDocument("v1", "Production API")
        .AddDocument("v2-beta", "Beta API", isDefault: true);
});

Custom Route Prefix

// Default is /scalar/{documentName}
app.MapScalarApiReference("/api-docs");
// Now at /api-docs/v1

Production with Authorization

// When partners need access to docs in production
app.MapOpenApi().RequireAuthorization("ApiDocs");
app.MapScalarApiReference().RequireAuthorization("ApiDocs");

Force Dark Mode

options.ForceDarkMode();

Classic Layout (Swagger-like)

options.WithClassicLayout();

Anti-patterns

Don't Expose Scalar in Production Without Auth

// BAD — anyone can see your API structure
app.MapOpenApi();
app.MapScalarApiReference();

// GOOD — development only
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

// GOOD — production with auth
app.MapOpenApi().RequireAuthorization("ApiDocs");
app.MapScalarApiReference().RequireAuthorization("ApiDocs");

Don't Pre-fill Real Credentials

// BAD — real tokens visible in browser
options.AddHttpAuthentication("Bearer", auth =>
{
    auth.Token = "eyJhbG...real-production-token";
});

// GOOD — dev-only test tokens
if (app.Environment.IsDevelopment())
{
    options.AddHttpAuthentication("Bearer", auth =>
    {
        auth.Token = "dev-only-test-token";
    });
}

Don't Forget the Security Scheme Transformer

// BAD — no auth UI in Scalar because OpenAPI doc has no security schemes
builder.Services.AddOpenApi();
app.MapScalarApiReference(options =>
{
    options.WithPreferredScheme("Bearer"); // Does nothing!
});

// GOOD — register the document transformer first
builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
});
app.MapScalarApiReference(options =>
{
    options.WithPreferredScheme("Bearer");
});

Don't Leave the Proxy Enabled for Sensitive APIs

// BAD — auth headers flow through proxy.scalar.com
app.MapScalarApiReference();

// GOOD — disable proxy for APIs with sensitive data
app.MapScalarApiReference(options =>
{
    options.WithProxy(null);
});

Don't Use Swagger UI for New .NET 10 Projects

// BAD — Swashbuckle removed from templates, maintenance concerns
builder.Services.AddSwaggerGen();
app.UseSwaggerUI();

// GOOD — built-in OpenAPI + Scalar
builder.Services.AddOpenApi();
app.MapOpenApi();
app.MapScalarApiReference();

Decision Guide

Scenario	Recommendation
API documentation UI	`MapScalarApiReference()` with `MapOpenApi()`
Development environment	Default setup with `IsDevelopment()` guard
Production API docs	Add `.RequireAuthorization()` to both endpoints
Auth testing in dev	`AddHttpAuthentication()` with test tokens
Dark theme preference	`.ForceDarkMode()` or `.WithTheme(ScalarTheme.Moon)`
Multiple API versions	Multiple `AddOpenApi()` calls — Scalar detects automatically
Sensitive APIs	`.WithProxy(null)` to disable external proxy
Swagger-like layout	`.WithClassicLayout()`
Custom route	`app.MapScalarApiReference("/api-docs")`

FAQ

What does the scalar skill do?

How do I install scalar?

Run npx skills add https://github.com/codewithmukesh/dotnet-claude-kit --skill scalar in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/scalar/ (personal) or .claude/skills/scalar/ (project).

Which AI agents can use scalar?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is scalar safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains scalar?

It is published by codewithmukesh in codewithmukesh/dotnet-claude-kit. It has 2,868 recorded installs.