Contributing

Thank you for your interest in contributing to Runners! This guide will help you get started.

Development Setup

Prerequisites

Node.js 18+ (or 20+, 22+, 24+)
pnpm 10.20.0+
Rust (for schema-extractor and swc-plugin)

Clone and Install

git clone https://github.com/your-org/runners.git
cd runners
pnpm install

Build

# Build all packages
pnpm build

# Build specific package
pnpm --filter @runners/core build

# Watch mode
pnpm --filter @runners/core dev

Run Tests

# Run all tests
pnpm test

# Run specific package tests
pnpm --filter @runners/core test

# Watch mode
pnpm --filter @runners/core test:watch

Project Structure

runners/
├── packages/
│   ├── export/          # Main package (barrel exports)
│   ├── runners/
│   │   ├── core/        # Core execution engine
│   │   ├── http/        # HTTP handler
│   │   ├── nitro/       # Nitro integration
│   │   ├── playwright/  # Playwright integration
│   │   └── ...
│   ├── orchestrator/
│   │   ├── orchestrator/      # Orchestrator service
│   │   └── nitro-orchestrator/ # Nitro orchestrator
│   └── shared/
│       ├── cli/         # CLI implementation
│       ├── config/      # Configuration
│       ├── contracts/   # API contracts
│       └── ...
├── examples/            # Example projects
└── docs/                # Documentation

Code Style

We use Biome for formatting and linting:

# Format code
pnpm fmt

# Lint code
pnpm lint

# Fix issues
pnpm lint --fix

TypeScript

Use TypeScript strict mode
Prefer explicit types over any
Use Zod for runtime validation
Export types from types.ts files

Naming Conventions

Files: kebab-case.ts
Functions: camelCase
Types: PascalCase
Constants: UPPER_SNAKE_CASE

Adding Features

1. Create a Branch

git checkout -b feature/your-feature-name

2. Make Changes

Write code following project conventions
Add tests for new functionality
Update documentation
Update types if needed

3. Test Your Changes

# Run tests
pnpm test

# Build packages
pnpm build

# Test examples
cd examples/hono
pnpm dev

4. Commit Changes

We use conventional commits:

git commit -m "feat: add new feature"
git commit -m "fix: fix bug"
git commit -m "docs: update documentation"

5. Create Pull Request

Write a clear description
Reference related issues
Include screenshots if UI changes
Ensure CI passes

Writing Tests

Unit Tests

import { describe, it, expect } from "vitest";
import { myFunction } from "./my-module";

describe("myFunction", () => {
  it("should do something", () => {
    expect(myFunction()).toBe(expected);
  });
});

Integration Tests

import { describe, it, expect } from "vitest";
import { runRunners } from "runners";

describe("Runner Integration", () => {
  it("should execute runners", async () => {
    const result = await runRunners({
      runners: [myRunner],
    });
    
    expect(result.results).toHaveLength(1);
  });
});

Documentation

Updating Docs

Edit files in docs/
Use clear, concise language
Include code examples
Update table of contents if needed

Adding Examples

Create example in examples/
Add README with setup instructions
Ensure example works end-to-end
Link from main README

Package Development

Adding a New Package

Create directory in packages/
Add package.json with proper name
Add tsconfig.json extending shared config
Add rslib.config.ts for build
Export from main package if public

Updating Dependencies

# Add dependency
pnpm add package-name --filter @runners/core

# Add dev dependency
pnpm add -D package-name --filter @runners/core

# Update all dependencies
pnpm update

Rust Packages

schema-extractor

Located in packages/runners/schema-extractor/:

cd packages/runners/schema-extractor

# Build
cargo build

# Test
cargo test

# Build WASM
wasm-pack build --target nodejs

swc-plugin-runners

Located in packages/runners/swc-plugin-runners/:

cd packages/runners/swc-plugin-runners

# Build
cargo build

# Test
cargo test

# Build WASM
wasm-pack build --target nodejs

Debugging

Enable Debug Logging

DEBUG=true pnpm dev
RUNNERS_DEBUG=true pnpm dev
ORCHESTRATOR_DEBUG=true pnpm dev

VS Code Debugging

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Runner",
      "program": "${workspaceFolder}/packages/runners/core/src/index.ts",
      "env": {
        "DEBUG": "true"
      }
    }
  ]
}

Release Process

Update version in packages/export/package.json
Update CHANGELOG.md
Create release commit
Tag release
Publish to npm

# Version bump (handled by release script)
npm version patch|minor|major

# Publish
pnpm --filter runners publish

Getting Help

Issues: Open an issue on GitHub
Discussions: Use GitHub Discussions
Discord: Join our Discord server (if available)

Code of Conduct

Be respectful and inclusive
Welcome newcomers
Focus on constructive feedback
Follow project conventions

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Development Setup

Prerequisites

Node.js 18+ (or 20+, 22+, 24+)
pnpm 10.20.0+
Rust (for schema-extractor and swc-plugin)

Clone and Install

git clone https://github.com/your-org/runners.git
cd runners
pnpm install

Build

# Build all packages
pnpm build

# Build specific package
pnpm --filter @runners/core build

# Watch mode
pnpm --filter @runners/core dev

Run Tests

# Run all tests
pnpm test

# Run specific package tests
pnpm --filter @runners/core test

# Watch mode
pnpm --filter @runners/core test:watch

Project Structure

runners/
├── packages/
│   ├── export/          # Main package (barrel exports)
│   ├── runners/
│   │   ├── core/        # Core execution engine
│   │   ├── http/        # HTTP handler
│   │   ├── nitro/       # Nitro integration
│   │   ├── playwright/  # Playwright integration
│   │   └── ...
│   ├── orchestrator/
│   │   ├── orchestrator/      # Orchestrator service
│   │   └── nitro-orchestrator/ # Nitro orchestrator
│   └── shared/
│       ├── cli/         # CLI implementation
│       ├── config/      # Configuration
│       ├── contracts/   # API contracts
│       └── ...
├── examples/            # Example projects
└── docs/                # Documentation

Code Style

We use Biome for formatting and linting:

# Format code
pnpm fmt

# Lint code
pnpm lint

# Fix issues
pnpm lint --fix

TypeScript

Use TypeScript strict mode
Prefer explicit types over any
Use Zod for runtime validation
Export types from types.ts files

Naming Conventions

Files: kebab-case.ts
Functions: camelCase
Types: PascalCase
Constants: UPPER_SNAKE_CASE

Adding Features

1. Create a Branch

git checkout -b feature/your-feature-name

2. Make Changes

Write code following project conventions
Add tests for new functionality
Update documentation
Update types if needed

3. Test Your Changes

# Run tests
pnpm test

# Build packages
pnpm build

# Test examples
cd examples/hono
pnpm dev

4. Commit Changes

We use conventional commits:

git commit -m "feat: add new feature"
git commit -m "fix: fix bug"
git commit -m "docs: update documentation"

5. Create Pull Request

Write a clear description
Reference related issues
Include screenshots if UI changes
Ensure CI passes

Writing Tests

Unit Tests

import { describe, it, expect } from "vitest";
import { myFunction } from "./my-module";

describe("myFunction", () => {
  it("should do something", () => {
    expect(myFunction()).toBe(expected);
  });
});

Integration Tests

import { describe, it, expect } from "vitest";
import { runRunners } from "runners";

describe("Runner Integration", () => {
  it("should execute runners", async () => {
    const result = await runRunners({
      runners: [myRunner],
    });
    
    expect(result.results).toHaveLength(1);
  });
});

Documentation

Updating Docs

Edit files in docs/
Use clear, concise language
Include code examples
Update table of contents if needed

Adding Examples

Create example in examples/
Add README with setup instructions
Ensure example works end-to-end
Link from main README

Package Development

Adding a New Package

Create directory in packages/
Add package.json with proper name
Add tsconfig.json extending shared config
Add rslib.config.ts for build
Export from main package if public

Updating Dependencies

# Add dependency
pnpm add package-name --filter @runners/core

# Add dev dependency
pnpm add -D package-name --filter @runners/core

# Update all dependencies
pnpm update

Rust Packages

schema-extractor

Located in packages/runners/schema-extractor/:

cd packages/runners/schema-extractor

# Build
cargo build

# Test
cargo test

# Build WASM
wasm-pack build --target nodejs

swc-plugin-runners

Located in packages/runners/swc-plugin-runners/:

cd packages/runners/swc-plugin-runners

# Build
cargo build

# Test
cargo test

# Build WASM
wasm-pack build --target nodejs

Debugging

Enable Debug Logging

DEBUG=true pnpm dev
RUNNERS_DEBUG=true pnpm dev
ORCHESTRATOR_DEBUG=true pnpm dev

VS Code Debugging

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Runner",
      "program": "${workspaceFolder}/packages/runners/core/src/index.ts",
      "env": {
        "DEBUG": "true"
      }
    }
  ]
}

Release Process

Update version in packages/export/package.json
Update CHANGELOG.md
Create release commit
Tag release
Publish to npm

# Version bump (handled by release script)
npm version patch|minor|major

# Publish
pnpm --filter runners publish

Getting Help

Issues: Open an issue on GitHub
Discussions: Use GitHub Discussions
Discord: Join our Discord server (if available)

Code of Conduct

Be respectful and inclusive
Welcome newcomers
Focus on constructive feedback
Follow project conventions

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Contributing

Development Setup

Prerequisites

Clone and Install

Build

Run Tests

Project Structure

Code Style

TypeScript

Naming Conventions

Adding Features

1. Create a Branch

2. Make Changes

3. Test Your Changes

4. Commit Changes

5. Create Pull Request

Writing Tests

Unit Tests

Integration Tests

Documentation

Updating Docs

Adding Examples

Package Development

Adding a New Package

Updating Dependencies

Rust Packages

schema-extractor

swc-plugin-runners

Debugging

Enable Debug Logging

VS Code Debugging

Release Process

Getting Help

Code of Conduct

License

See Also

Contributing

Development Setup

Prerequisites

Clone and Install

Build

Run Tests

Project Structure

Code Style

TypeScript

Naming Conventions

Adding Features

1. Create a Branch

2. Make Changes

3. Test Your Changes

4. Commit Changes

5. Create Pull Request

Writing Tests

Unit Tests

Integration Tests

Documentation

Updating Docs

Adding Examples

Package Development

Adding a New Package

Updating Dependencies

Rust Packages

schema-extractor

swc-plugin-runners

Debugging

Enable Debug Logging

VS Code Debugging

Release Process

Getting Help

Code of Conduct

License

See Also