# Share a Lighthouse Report — A Link Your Team Can Comment On

Canonical: https://commareports.com/share-lighthouse-report
Published: 2026-08-18

> Lighthouse JSON is unreadable and the HTML report is a JavaScript app. Publish a static performance digest to Comma: one stable URL per site, anchored comments on each opportunity, and a revision per run.

# Share a Lighthouse report

Lighthouse gives you two outputs, and neither of them is shareable.

The JSON is a machine artifact — thousands of lines, no one reads it. The
HTML report is a self-rendering JavaScript application: to share it you
either host it somewhere, mail a file around, or tell your colleague to
drag it into the Lighthouse Viewer. In practice, most teams do none of
these. They screenshot the four coloured circles into Slack and the
underlying opportunities — the part with the actual work in it — get lost.

## Publish a digest, not the app

The pattern that works is the same one that works for [test
reports](/share-playwright-report): render a small static HTML summary
from the JSON, publish it, and attach the heavy originals.

```bash
lighthouse https://example.com \
  --output json --output html \
  --output-path ./lh

# lh.report.json  →  digest.html  (a ~30-line script: scores + opportunities)

curl -fsS -X POST https://commareports.com/api/v1/reports \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html digest.html \
        '{title: "Performance — example.com", html: $html}')"
```

A useful digest is a table, not a dashboard: the five category scores,
Core Web Vitals (LCP, CLS, INP, TBT), and the top opportunities with their
estimated savings. Attach `lh.report.json` and `lh.report.html` as
[assets](/docs/api) — 25 MB per file — so the full interactive report is
one download away when someone needs to dig.

Store the token in your CI secret store as a [scoped
token](/docs/api-tokens) with only `reports:write`. The mechanics are the
same in any pipeline; see [publish from CI](/docs/ci).

## Why not just send a PageSpeed link?

Because a PageSpeed Insights URL re-runs the audit every time it's opened.
By the time your colleague clicks it, they are looking at a different run
against a different deploy, and the number you were discussing is gone. A
published report is the run you actually took, on the commit you actually
took it against, and it stays that way.

## Scores over time, without a dashboard

Create the report once, save its id, and `PATCH` it on every run:

```bash
curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html digest.html '{html: $html}')"
```

One URL per site or per key page. Every run appends a revision, and any
two revisions can be [diffed](/docs/ci) — so "LCP went from 1.9s to 3.4s
somewhere in the last two weeks" is a visible change rather than a
suspicion. Add a [webhook](/docs/api) on `revision.created` and the run
announces itself in Slack.

If nobody owns running it, a [routine](/features/routines) will: schedule
the refresh, and the report keeps itself current at the same URL.

## The opportunities are where the comments go

A Lighthouse score is a number to react to. The opportunities list is a
backlog — and a backlog belongs somewhere you can argue with it.

Comma renders the digest with an [anchored comment layer](/comment-on-html)
on top. Someone highlights "Eliminate render-blocking resources — 1.2s"
and pins a thread: "that's the marketing tag manager, ticket in #612."
Someone else highlights the CLS row: "hero image has no dimensions,
one-line fix." Each thread is attached to the row it's about, and it
survives the next run — so the report becomes the record of what was
decided, not just what was measured.

Agents can participate on the same surface. An assistant attached through
[Comma's MCP server](/mcp) can read the threads with `list_comments`, ship
the fix, and reply on the thread with the commit.

## Try it

Comma is free — unlimited reports, unlimited commenters, unlimited
revision history. Run Lighthouse once, publish the digest, and send a link
instead of four coloured circles.

**[Create your first report →](https://commareports.com/)**