Guide to Scalar’s Codebase

My first time contributing to open source was through Scalar in October 2025. I spent this month living in the codebase and solving small issues. I made this guide to synthesize what I learnt and help new contributors. If you don’t feel ready to contribute to open source, chances are you already are. Read my other essay on this topic if you are hesitant.

You Don’t Need to be Cracked to Contribute to Open Source (2025)

Why Scalar? It is an open source project that creates world-class API Docs with a built-in interactive playground which seamlessly turns to a full-featured API Client.

It is also offline. If you were frustrated recently by the AWS outage and Postman not working… Scalar is for you. I chose this project because 1) I love using it 2) I want to learn API design

Architecture Overview

Scalar is a monorepo with 3 main product layers:

API Reference - Documentation generator

API Client - API testing tool

Supporting Infrastructure - Parsers, utilities, integrations

Core Components Structure

1. API Reference Package (packages/api-reference)

Purpose: Generates beautiful, interactive API documentation from OpenAPI specs

Entry Points:

src/index.ts:7 - createApiReference() - Main initialization function

src/standalone/lib/html-api.ts:178 - Handles HTML/CDN usage

Key Components:

src/components/ApiReference.vue - Root Vue component

src/components/ApiReferenceLayout.vue - Layout wrapper

src/features/Operation/Operation.vue - Individual API operation display

src/features/sidebar/components/Sidebar.vue - Navigation sidebar

src/features/Search/SearchModal.vue - Search functionality

State Management:

Uses @scalar/workspace-store for centralized state

src/stores/useHttpClientStore.ts - HTTP client state

2. API Client Package (packages/api-client)

Purpose: Full-featured API testing client (Postman alternative)

Entry Points:

src/index.ts - Exports App and Modal layouts

src/layouts/App.ts - Full app mode

src/layouts/Modal.ts - Modal/embedded mode

Store Architecture (src/store/store.ts:45):


createWorkspaceStore()
├── collections - Groups of requests
├── tags - Organize operations
├── requests - API request definitions
├── requestExamples - Sample requests
├── cookies - Cookie management
├── environments - Variable environments
├── servers - Server configurations
├── securitySchemes - Auth methods
└── workspaces - Top-level containers

Router:

src/router - Vue Router for navigation between requests

3. OpenAPI Parser (packages/openapi-parser)

Purpose: Parse, validate, and transform OpenAPI specifications

Main Functions (src/index.ts):

load() - Load OpenAPI spec from URL/file/string

validate() - Validate against OpenAPI schema

dereference() - Resolve $ref pointers

bundle() - Combine external references

upgrade() - Convert Swagger 2.0 → OpenAPI 3.x

normalize() - Standardize format

filter() - Extract specific parts

🔄 Data Flow Architecture

Flow 1: API Reference - OpenAPI to UI


1. User provides OpenAPI spec
   ↓
2. createApiReference() initialization
   [packages/api-reference/src/standalone/lib/html-api.ts:178]
   ↓
3. Parse configuration from HTML attributes
   [packages/api-reference/src/standalone/lib/html-api.ts:18]
   ↓
4. Mount Vue app with ApiReference component
   [packages/api-reference/src/standalone/lib/html-api.ts:191]
   ↓
5. Load OpenAPI spec via @scalar/openapi-parser
   ↓
6. Parse and transform document
   [packages/api-reference/src/helpers/parse.ts:15]
   ↓
7. Store in workspace store
   [@scalar/workspace-store]
   ↓
8. Render components:
   - Sidebar → Operation list
   - Content → Operation details
   - ExampleRequest → Code samples
   - ExampleResponse → Response schemas

Key Data Transformation:


OpenAPI Spec (JSON/YAML)
  → @scalar/openapi-parser.load()
  → Dereferenced OpenAPI Document
  → parse() transforms to Spec type
  → Workspace Store (reactive state)
  → Vue Components render UI

Flow 2: API Client - Making Requests


1. User opens API Client
   ↓
2. createApiClientApp() initializes
   [packages/api-client/src/layouts/App.ts]
   ↓
3. Import OpenAPI spec (optional)
   [packages/api-client/src/store/import-spec.ts]
   ↓
4. Workspace Store populated with:
   - Requests, Collections, Servers, Auth
   ↓
5. User selects/creates request
   ↓
6. Configure:
   - Method, URL, Headers, Body
   - Authentication
   - Parameters
   ↓
7. Send request (via proxy if needed)
   ↓
8. Receive response
   ↓
9. Display:
   - Status, Headers, Body
   - Formatted JSON/XML
   - Syntax highlighting

Flow 3: Framework Integration

Example: Express Integration


1. Developer installs @scalar/express-api-reference
   ↓
2. Adds middleware to Express app:
   app.use('/api-docs', apiReference({
     spec: { url: '/openapi.json' }
   }))
   ↓
3. Middleware serves HTML page
   ↓
4. HTML loads @scalar/api-reference
   ↓
5. API Reference fetches OpenAPI spec
   ↓
6. Renders interactive documentation

Integration packages:

Handle framework-specific routing

Serve HTML with embedded config

Often watch for spec changes

Package Dependency Graph


@scalar/api-reference
├── @scalar/workspace-store (state management)
├── @scalar/openapi-parser (spec parsing)
├── @scalar/components (UI library)
├── @scalar/themes (styling)
├── @scalar/snippetz (code generation)
├── @scalar/use-codemirror (code editor)
└── @scalar/oas-utils (OpenAPI utilities)

@scalar/api-client
├── @scalar/workspace-store (state management)
├── @scalar/openapi-parser (spec parsing)
├── @scalar/components (UI library)
├── @scalar/themes (styling)
└── Vue Router (navigation)

@scalar/[framework]-api-reference
├── @scalar/api-reference
└── Framework-specific APIs

Directory Structure Guide


packages/
├── api-reference/           # Documentation generator
│   ├── src/
│   │   ├── components/      # Vue components
│   │   ├── features/        # Feature modules (sidebar, search, etc.)
│   │   ├── stores/          # State management
│   │   ├── helpers/         # Utility functions
│   │   ├── standalone/      # HTML/CDN entry point
│   │   └── v2/              # New architecture (WIP)
│   └── index.html          # Development playground
│
├── api-client/              # API testing client
│   ├── src/
│   │   ├── layouts/         # App layouts (full, modal)
│   │   ├── store/           # Workspace store implementation
│   │   ├── router/          # Vue Router config
│   │   └── views/           # Page components
│
├── openapi-parser/          # OpenAPI parser
│   └── src/
│       └── utils/           # Parser functions
│
├── workspace-store/         # Centralized state management
│   └── src/
│       ├── store/           # Store implementation
│       └── entities/        # Data models
│
├── components/              # Shared UI components
│   └── src/
│       └── components/      # Buttons, modals, inputs, etc.
│
├── themes/                  # Styling system
│   └── src/
│       └── styles/          # CSS variables, themes
│
└── [30+ utility packages]   # Supporting libraries

Key Concepts

1. Workspace Store Pattern

The workspace store is the central nervous system of Scalar:


// Centralized reactive state
const store = createWorkspaceStore({
  useLocalStorage: true,  // Persist data
  proxyUrl: '...',        // CORS proxy
  theme: 'default'
})

// Everything flows through the store
store.collections.add(...)
store.requests.update(...)
store.environments.set(...)

Located in: @scalar/workspace-store package

2. OpenAPI Parsing Pipeline


// Load spec
const { filesystem } = await load(spec)

// Validate
await validate(filesystem)

// Dereference $refs
const { specification } = await dereference(filesystem)

// Now ready for rendering

Located in: @scalar/openapi-parser package

3. Component System

Scalar uses scoped CSS to allow embedding:


<!-- All styles scoped to .scalar-app class -->
<div class="scalar-app">
  <ScalarButton />
  <ScalarModal />
</div>

This prevents style conflicts when embedded in other apps.

4. Theme System


// Themes use CSS variables
<div data-theme="purple">
  <!-- All colors come from CSS vars -->
</div>

Located in: @scalar/themes package

How to Explore the Code

Want to understand API Reference?

Start: packages/api-reference/src/standalone/lib/html-api.ts

Then: packages/api-reference/src/components/ApiReference.vue

Explore: packages/api-reference/src/features/

Want to understand API Client?

Start: packages/api-client/src/layouts/App.ts

Then: packages/api-client/src/store/store.ts

Explore request handling in stores

Want to understand OpenAPI parsing?

Start: packages/openapi-parser/src/index.ts

Explore: packages/openapi-parser/src/utils/

Want to understand integrations?

Pick one: integrations/express/

See how it wraps @scalar/api-reference

Pattern is similar across all frameworks

💡 Quick Reference

Main Technologies:

Vue 3 (Composition API) - Frontend framework

TypeScript - Type safety

Vite - Build tool

pnpm + Turbo - Monorepo management

Tailwind CSS - Styling

State Management:

Custom reactive stores (not Vuex/Pinia)

Located in @scalar/workspace-store

Uses Vue's reactive() and ref()

Testing:

Vitest - Unit tests

Playwright - E2E tests

Yours,

Nour