Getting Started

Installation

Install modestbench as a development dependency:

npm install --save-dev modestbench

Initialize Your Project (Optional)

The modestbench init command sets up your project with configuration and examples:

# Initialize with defaults
modestbench init

# Or specify project type and config format
modestbench init advanced --config-type typescript

Project Types:

basic - Simple setup for small projects (100 iterations, human reporter)
advanced - Feature-rich with multiple reporters and structured output
library - Optimized for library performance testing (5000 iterations, high warmup)

The init command will:

Generate a configuration file in your chosen format
Create an example benchmark file
Add .modestbench/ to .gitignore to exclude historical data

Your First Benchmark

Simplified Format (Recommended)

For quick benchmarks with just a few tasks:

export default {
  'Array.push()': () => {
    const arr = [];
    for (let i = 0; i < 1000; i++) {
      arr.push(i);
    }
    return arr;
  },

  'Array spread': () => {
    let arr = [];
    for (let i = 0; i < 1000; i++) {
      arr = [...arr, i];
    }
    return arr;
  },
};

Suite-Based Format

When you need to organize benchmarks into groups with setup/teardown hooks:

const state = { data: [] };

export default {
  suites: {
    'Array Operations': {
      setup() {
        state.data = [];
      },

      benchmarks: {
        'Array.push()': () => {
          const arr = [];
          for (let i = 0; i < 1000; i++) {
            arr.push(i);
          }
          return arr;
        },

        'Array spread': () => {
          let arr = [];
          for (let i = 0; i < 1000; i++) {
            arr = [...arr, i];
          }
          return arr;
        },
      },
    },
  },
};

When to use each format:

Simplified format: Quick benchmarks, single file with related tasks, no setup/teardown needed
Suite format: Complex projects, multiple groups of benchmarks, need setup/teardown hooks

Running Benchmarks

Run all benchmarks in the current directory:

modestbench

Run benchmarks with options:

modestbench --iterations 5000 --reporters human,json

Choosing an Engine

modestbench provides two engines with different trade-offs:

# Default: tinybench (fast, good for development)
modestbench

# Accurate engine (higher precision, recommended for production benchmarks)
node --allow-natives-syntax ./node_modules/.bin/modestbench --engine accurate

Engine Comparison:

Feature	`tinybench` (default)	`accurate`
Speed	⚡ Very fast	🐢 Slower (more thorough)
Statistical Quality	✅ Good	⭐ Excellent
Outlier Removal	✅ IQR-based	✅ IQR-based
V8 Optimization Guards	❌ No	✅ Yes (prevents JIT interference)
Requirements	None	`--allow-natives-syntax` flag
Best For	Development, CI	Production benchmarks, publications

Run specific files or directories:

# Run a specific file
modestbench benchmarks/critical.bench.js

# Run all benchmarks in a directory (searches recursively)
modestbench benchmarks/

# Run multiple paths
modestbench benchmarks/ tests/perf/

# Use glob patterns
modestbench "tests/**/*.bench.ts"

View Results

modestbench provides clean, colorized output in interactive terminals:

Common Options

Control Benchmark Duration

# Limit by iteration count (fast, predictable sample size)
modestbench --iterations 100

# Limit by time budget (ensures consistent time investment)
modestbench --time 5000

# Limit by whichever comes first (safety bounds)
modestbench --iterations 1000 --time 10000

Filter by Tags

# Run only fast benchmarks
modestbench --tags fast

# Run benchmarks with multiple tags (OR logic)
modestbench --tags string,array,algorithm

# Exclude specific benchmarks
modestbench --exclude-tags slow,experimental

Multiple Output Formats

# Generate multiple reports at once
modestbench --reporters human,json,csv

# Save reports to a specific directory
modestbench --reporters json,csv --output ./results

Next Steps

Learn about Configuration options
Explore the CLI Reference for all commands and flags
Understand Output Formats for integrations
Check out Advanced Usage for complex scenarios