Cloud Agents Starter
Developmentcloud-agents-starterCloud 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
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:
| Package | Dev command | Notes |
|---|---|---|
api-client | pnpm dev | Runs playground:v2:web (Vite) |
api-reference | pnpm dev | Main API reference playground |
components | pnpm dev | Storybook on port 5100 |
mock-server | pnpm dev | Mock server playground |
void-server | pnpm dev | HTTP mirror server (port 5052) |
galaxy | pnpm dev | Serves 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=1for CI-like behavior (e.g. test servers, some Playwright runs). - NODE_OPTIONS:
openapi-parsertests useNODE_OPTIONS=--max_old_space_size=8192for 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:
- Add to the appropriate section (root, packages, integrations, E2E, environment).
- Use concrete commands – copy-pasteable, with package names and paths.
- Note edge cases – e.g. "Python integrations need Python 3.11", "openapi-parser needs NODE_OPTIONS".
- Keep it minimal – only include what agents need to run and test quickly.
- 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.