OpenParable
Skip to content
← Back to skills

Cloud Agents Starter

Development
cloud-agents-starter

Cloud Agents Starter is an Agent Skill for development published in the scalar/scalar repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Minimal starter runbook for cloud agents to install dependencies, run packages, execute tests, and troubleshoot the Scalar monorepo quickly.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/scalar/scalar/blob/HEAD/.agents/skills/cloud-agents-starter/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/cloud-agents-starter, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Cloud Agents Starter Skill - Scalar Codebase

Practical setup and execution instructions for running and testing this codebase. Use this as the first reference when starting the app, running tests, or debugging workflows.

Prerequisites

  • Node.js: v24 (see .nvmrc)
  • Package manager: pnpm (v10.16.1+)
  • First-time setup:
    pnpm install
    pnpm build:packages
    

1. Root / Monorepo

Start development

There is no single root pnpm dev. Each package has its own dev script. To run a specific package:

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

Build

pnpm build:packages      # Build all packages (required before dev)
pnpm build:integrations # Build integrations
pnpm clean:build        # Clean, reinstall, and rebuild

Lint & format

pnpm lint:check         # Check lint
pnpm lint:fix           # Auto-fix lint
pnpm format:check       # Check formatting
pnpm format             # Apply formatting
pnpm types:check        # TypeScript check

2. Packages (packages/*)

Run a package dev server

cd packages/<package-name>
pnpm dev

Common entrypoints:

PackageDev commandNotes
api-clientpnpm devRuns playground:v2:web (Vite)
api-referencepnpm devMain API reference playground
componentspnpm devStorybook on port 5100
mock-serverpnpm devMock server playground
void-serverpnpm devHTTP mirror server (port 5052)
galaxypnpm devServes OpenAPI doc with @scalar/cli

Unit tests (Vitest)

pnpm test                           # Run all tests (packages + integrations)
pnpm vitest packages/*              # Packages only
pnpm vitest packages/api-client     # Single package
pnpm vitest packages/api-client --run  # Single run, no watch
pnpm test your-test-name            # Filter by test name

Test servers required: Some tests need @scalar/void-server (5052) and proxy-scalar-com (5051). Start them in a separate terminal:

pnpm script run test-servers

Then wait for ports: pnpm script wait -p 5051 5052


3. Integrations (integrations/*)

Run integration dev servers

pnpm --filter @scalar/express-api-reference dev
pnpm --filter @scalar/fastify-api-reference dev
pnpm --filter @scalar/nuxt dev
pnpm --filter @scalar/nextjs-api-reference dev

Integration tests

pnpm vitest integrations/*          # All integrations
pnpm vitest integrations/express   # Single integration

Python integrations (FastAPI, Django Ninja): Require Python 3.11. Run python run_tests.py in the integration directory.

Rust/Java/.NET: Have separate CI jobs; typically run via their native toolchains (cargo, mvn, dotnet).


4. E2E & Playwright

API Reference E2E

cd packages/api-reference
pnpm test:e2e              # Local (needs Playwright browser)
pnpm test:e2e:ci          # CI mode
pnpm test:e2e:update-snapshots  # Update snapshots

Components E2E (Storybook)

cd packages/components
pnpm test:e2e              # Local
pnpm test:e2e:ci           # CI mode
pnpm test:e2e:update       # Update snapshots

Nuxt E2E

pnpm --filter @scalar/nuxt test:e2e

Playwright uses PW_TEST_CONNECT_WS_ENDPOINT=ws://127.0.0.1:5001/ for browser connection in local runs.


5. Environment & Workflow

Environment variables

  • CI: Set CI=1 for CI-like behavior (e.g. test servers, some Playwright runs).
  • NODE_OPTIONS: openapi-parser tests use NODE_OPTIONS=--max_old_space_size=8192 for large specs.
  • TEST_MODE=CDN: Used for CDN snapshot tests in api-reference.

Scripts (tooling/scripts)

pnpm script run test-servers   # Start void-server + proxy-scalar-com
pnpm script wait -p 5051 5052  # Wait for ports
pnpm script generate-readme    # Regenerate integration READMEs

Feature flags

This codebase does not use feature flags. Configuration is via package options, OpenAPI spec extensions, or environment variables as noted above.


6. Projects & Examples

  • proxy-scalar-com (Go): cd projects/proxy-scalar-com && go run main.go (port 5051)
  • Examples (examples/*): Each has its own pnpm dev (e.g. examples/web, examples/react)

7. CI Parity (run like CI)

To approximate CI locally:

pnpm install
pnpm build:packages
pnpm vitest packages/* --silent
pnpm vitest integrations/* --silent
pnpm types:check
pnpm lint:check
pnpm format:check

8. Updating This Skill

When you discover new testing tricks, runbook steps, or environment requirements:

  1. Add to the appropriate section (root, packages, integrations, E2E, environment).
  2. Use concrete commands – copy-pasteable, with package names and paths.
  3. Note edge cases – e.g. "Python integrations need Python 3.11", "openapi-parser needs NODE_OPTIONS".
  4. Keep it minimal – only include what agents need to run and test quickly.
  5. Cross-reference – if a step depends on another (e.g. test-servers before package tests), state it clearly.

Preferred location for this skill: .agents/skills/cloud-agents-starter/SKILL.md.