AGENTS.md · scalar/scalar

Sections

1. Project Overview
2. Prerequisites
3. First-Time Setup
4. Commands
5. Key Commands
6. Development Servers
7. Test Servers
8. Architecture
9. Directory Structure
10. Code Standards
11. Testing
12. Git Workflow
13. PR Requirements
14. Visual Testing
15. AsyncAPI Rendering
16. OpenAPI Specification
17. OpenAPI Terminology
18. Cursor Cloud specific instructions
19. Further Reading

First lines (shown under the repo's MIT license)

# AGENTS.md - AI Agent Guide for Scalar

This file helps AI coding agents (Cursor, Claude Code, GitHub Copilot, etc.) work effectively in the Scalar codebase. It is the canonical agent guide for this repository.

## Project Overview

Scalar is a Vue 3 + TypeScript monorepo for API documentation and testing.

- It produces `@scalar/api-reference` (renders OpenAPI docs) and `@scalar/api-client` (API testing client)
- It includes 40+ supporting packages and 16 framework integrations (Express, Fastify, Hono, NestJS, Next.js, Nuxt, etc.)
- It uses pnpm workspaces, Turbo for build orchestration, Vite for Vue packages, and `tsc` for pure TypeScript packages

- **Frontend**: Vue 3, Composition API, TypeScript
- **Styling**: Tailwind CSS
- **Testing**: Vitest (unit), Playwright (E2E)
- **Linting**: ESLint (Vue) + Biome (TS)

## Prerequisites

- **Node.js**: v24 (see `.nvmrc`)
- **Package manager**: pnpm (v12.2.1+)

## First-Time Setup

```bash
pnpm install
pnpm build:packages
```

## Commands

```bash
pnpm install                    # Install dependencies
pnpm build:packages             # Build all packages (required before first dev)
pnpm clean:build                # Clean everything, reinstall, rebuild
```

## Key Commands

| Task | Command |
|------|---------|
| Build all packages | `pnpm build:packages` |
| Build integrations | `pnpm build:integrations` |
| Clean build | `pnpm clean:build` |
| Run unit tests | `pnpm test` |
| Run tests (single package, single run) | `pnpm vitest packages/helpers --run` |
| Run tests (single package, watch mode) | `pnpm vitest packages/api-client` |
| Run tests filtered by name | `pnpm test your-test-name` |
| Lint check | `pnpm lint:check` |
| Lint fix | `pnpm lint:fix` |
| Format | `pnpm format` |
| Type check | `pnpm types:check` |

## Development Servers

There is no single root `pnpm dev`. Run per package:

```bash
pnpm --filter @scalar/api-client dev
pnpm --filter @scalar/api-reference dev
pnpm --filter @scalar/components dev
```

| Package | Purpose |
|---------|---------|
| `api-client` | API testing client playground |
| `api-reference` | Main API reference playground |
| `components` | Storybook (port 5100) |
| `void-server` | HTTP mirror server (port 5052) |

## Test Servers

Some tests need `@scalar/void-server` (5052) and `proxy-scalar-com` (5051):

```bash
pnpm script run test-servers
pnpm script wait -p 5051 5052
```

## Architecture

### Workspace Layout

- `packages/` - Core libraries (43 packages). Each is an npm package under `@scalar/`.
- `integrations/` - Framework-specific wrappers (Express, Fastify, Next.js, Nuxt, etc.)
- `projects/` - Deployable apps (`scalar-app`, `proxy-scalar-com`, `galaxy-scalar-com`). `scalar-app` builds both the Electron desktop app and client.scalar.com.
- `examples/` - Usage examples for various frameworks
- `tooling/` - Internal build scripts and changelog generator

## Directory Structure

```text
packages/      # Core packages (@scalar/*)
integrations/  # Framework integrations (Express, FastAPI, etc.)
examples/      # Example apps
projects/      # Supporting projects (e.g. proxy-scalar-com)
tooling/       # Internal scripts and build helpers
```

### Build System

Two build strategies use standard tools directly (no custom build CLI):

1. **`tsc` + `tsc-alias`**
   - For pure TypeScript packages (helpers, types, openapi-parser, integrations)
   - Uses `tsconfig.build.json` per package
2. **`vite build`**
   - For Vue component packages (`components`, `api-reference`, `api-client`)
   - Uses Vite 8 + Rolldown, extracts CSS, preserves modules
   - Shared build helpers live in `tooling/scripts/vite-lib-config.ts`

Both strategies externalize dependencies (nothing is bundled into library output). `api-reference` is special because it has both a default build and a standalone build (`vite.standalone.config.ts`) that bundles everything for CDN usage.

Type checking uses `tsc --noEmit` (pure TS) or `vue-tsc --noEmit` (Vue packages).

### Key Package Relationships

- `@scalar/core` - Shared rendering logic consumed by `api-reference` and integrations
- `@scalar/themes` - CSS variables and design tokens used across UI packages
- `@scalar/components` - Vue component library (with Storybook)
- `@scalar/oas-utils` - OpenAPI utilities shared across `api-reference` and `api-client`
- `@scalar/types` - Shared TypeScript types; import from specific entry points (`@scalar/types/api-reference`, etc.), not the root

### Dependency Versioning

All workspace packages use `workspace:*` for internal dependencies. Shared third-party versions are defined in `pnpm-workspace.yaml` under `catalogs:` and referenced as `catalog:*` in `package.json` files.

### Tooling Split

- **Biome**: Linting and formatting for `.ts` files
- **ESLint**: Linting for `.vue` files
- **Prettier**: Formatting for `.vue`, `.md`, `.json`, `.css`, `.html`, `.yml` files
- **Lefthook**: Pre-commit hooks running Prettier + Biome on staged files

## Code Standards

### Reuse helpers before writing new ones

Before writing a new utility function, check `@scalar/helpers` (`packages/helpers/src/`) first. It already covers a wide range of common needs, organized by category:

| Category | Examples |
|----------|---------|
| `array` | array manipulation utilities |
| `dom` | DOM helpers |
| `errors` | error handling utilities |
| `file` | file utilities |
| `formatters` | value formatting |
| `general` | miscellaneous general utilities |
| `http` | HTTP methods, headers, status codes, MIME types |
| `json` | JSON pointer helpers, pretty-print |
| `markdown` | heading extraction |
| `node` | Node-only path helpers |
| `object` | deep equality, key helpers, path access, local storage |
| `playwright` | Playwright/Docker test helpers |
| `queue` | async queue |
| `regex` | variable finding/replacing |
| `storybook` | shared Storybook themes and toolbar globals |
| `string` | capitalize, hash, truncate, camel-to-title |
| `testing` | sleep, measure, console spies |
| `theme` | color mode classes, CSS variable loading |