Turborepo Summary

Generate human-readable markdown reports from Turborepo run summary JSON output.

Turborepo offers a flag (--summarize) that generates a JSON file in .turbo/runs containing metadata about the run, including:

• Affected packages
• Executed tasks (including their timings and hashes)
• All the files included in the cached artifacts

But it produces a JSON artifact that is not very human-readable, that's where this tool comes in.

This tool is particularly useful for:

• CI/CD Reporting — Generate markdown reports in GitHub Actions or other CI environments to visualize Turborepo performance
• Performance Analysis — Identify slow tasks and evaluate cache effectiveness
• Team Communication — Share human-readable build summaries with your team
• Documentation — Archive build statistics and track performance over time

Installation

npx turborepo-summary

[!NOTE] Requires Node >= 22.

Usage

[!TIP] If you are looking to generate a markdown report from Turborepo running on GitHub Actions, check this GitHub Action that does it for you: turborepo-summary-action

First, generate a Turborepo run summary JSON file by running any turbo command with the --summarize flag:

turbo run build --summarize

This creates a JSON file (typically in .turbo/runs/) containing execution data for your tasks.

Then, generate a markdown report from that JSON file:

# Explicit path
npx turborepo-summary .turbo/runs/[hash].json

# Or omit the file — the newest .turbo/runs/*.json is picked automatically
npx turborepo-summary

You can also read the summary from stdin, or write the report to a file:

# Read from stdin (useful for piping)
cat .turbo/runs/[hash].json | npx turborepo-summary -

# Write to a file instead of stdout
npx turborepo-summary --output REPORT.md

[!TIP] Running this CLI generates a markdown report, then you can view it at your convenience:

Pipe it to either your IDE (e.g., VS Code) to view it:

npx turborepo-summary | code -

Use a markdown terminal viewer tool, like glow:

npx turborepo-summary | glow -

CLI Options

Usage: turborepo-summary [options] [file]

Arguments:
  file                 Path to the Turbo run summary JSON file, "-" for stdin,
                       or omit to use the newest .turbo/runs/*.json

Options:
  -V, --version        output the version number
  -o, --output <path>  Write the markdown report to a file instead of stdout
  -h, --help           display help for command

Output

The tool generates a comprehensive markdown report with three main sections:

Summary Metrics

Shows key statistics including:

• Total execution duration
• Number of tasks executed
• Success/failure counts
• Cache hit/miss statistics

Execution Timeline

Provides a Mermaid Gantt chart visualizing task execution over time, showing:

• When each task started and ended
• Task duration
• Cache status
• Success/failure indicators

Detailed Results

A table with per-task information including task ID, duration, cache status, and execution status.

License

turborepo-summary is MIT licensed.