flutter_lighthouse 0.1.0

Lighthouse for Flutter — drop in, tap once, and it auto-walks every route, scores performance 0–100, and emits actionable findings.

🛰️ flutter_lighthouse

Lighthouse for Flutter. Drop it in, tap once, and it auto-walks every route, scores your app's performance 0–100 (Chrome-Lighthouse-style), and emits actionable findings — "17 widgets rebuild on /feed", "hero.jpg decoded 16× larger than displayed" — each with a fix and a code example.

---

Why

DevTools is great for manual profiling. flutter_lighthouse is for the other 90% of the time — a one-tap, repeatable audit you can run on every build, paste into a PR, or wire into CI. The scoring math is ported directly from Chrome Lighthouse's log-normal curves (see SCORING_SPEC.md), so a score means the same thing run to run.

Features

• One-call audit — Lighthouse.audit(context) or a floating dev button.
• Auto-walk — visits named routes, dwells, scrolls, collects.
• Real metrics — frame build/raster timing, jank ratio, FPS, route load latency, memory delta, oversized-image detection, widget rebuild storms.
• Chrome-grade scoring — 0–100 overall + Performance / Responsiveness / Memory / Best-Practices sub-scores, per route.
• Actionable findings — severity-ranked, each with a recommendation and a code example. Conservative thresholds keep false positives low.
• Exports — JSON (CI), Markdown (PR), HTML (shareable). Plus an in-app report screen with animated score gauges.

Getting started

dependencies:
  flutter_lighthouse: ^0.1.0

Usage

One-tap overlay (dev builds)

import 'package:flutter_lighthouse/flutter_lighthouse.dart';

void main() {
  runApp(
    LighthouseOverlay(
      config: LighthouseConfig(routes: ['/feed', '/profile', '/settings']),
      child: const MyApp(),
    ),
  );
}

Tap the 🏎️ speed button → it walks your routes → a report screen opens.

Programmatic / headless

final report = await Lighthouse.audit(
  context,
  config: LighthouseConfig(routes: ['/feed', '/profile']),
);

print('Score: ${report.overallScore.round()} (${report.grade})');
for (final f in report.findings) {
  print('${f.severity.label}: ${f.title} → ${f.recommendation}');
}

// Paste into a PR:
print(ReportExporter(report).toMarkdown());

Accurate rebuild counts

Flutter has no global rebuild hook, so wrap the subtrees you care about:

LighthouseProbe(label: 'FeedItem', child: FeedItem(post));

During an audit, every rebuild of that subtree is counted — no guessing, near- zero false positives.

Score thresholds

Range	Grade	Meaning
90–100	Excellent	Ship it.
70–89	OK	Some findings worth addressing.
50–69	Needs work	Real perf debt.
0–49	Poor	Users feel this.

vs. the alternatives

	flutter_lighthouse	DevTools	manual timeline
One-tap repeatable audit	✅	❌	❌
0–100 score	✅	❌	❌
Actionable findings + fixes	✅	partial	❌
PR / CI export	✅	❌	❌
In-app, no desktop needed	✅	❌	❌

Roadmap

v0.2: network + bundle-size collectors, headless CI runner, GitHub Action, fail-on-regression threshold, dwell-weighted overall score.

Contributing

Issues and PRs welcome at github.com/jayu1023/flutter_lighthouse.

License

MIT © Jay Limbani