riverpod_timeline

Debug and inspect Riverpod state with zero app logic changes. Records every provider update, tracks dependencies, visualizes state changes, and supports time-travel debugging.

Features: Observer · Timeline Viewer · Dependency Graph · Performance Dashboard · Time Travel · Export/Import · Floating Overlay

---

Install

dependencies:
  flutter_riverpod: ^3.0.0
  riverpod_timeline: ^1.0.0

Quick Start

final _navigatorKey = GlobalKey<NavigatorState>();

void main() {
  RiverpodTimeline.initialize();

  runApp(
    RiverpodTimelineScope(
      navigatorKey: _navigatorKey,
      child: MaterialApp(
        navigatorKey: _navigatorKey,
        home: const MyApp(),
      ),
    ),
  );
}

A floating debug button appears. Tap it to open the full debug panel.

Without RiverpodTimelineScope

RiverpodTimeline.initialize(enableOverlay: false);

runApp(
  ProviderScope(
    observers: [RiverpodTimeline.instance.observer],
    child: MaterialApp(
      navigatorKey: _navigatorKey,
      home: const MyApp(),
    ),
  ),
);

// Navigate to timeline viewer:
Navigator.of(context).push(
  MaterialPageRoute(
    builder: (_) => ProviderTimelineView(controller: tl.controller),
  ),
);

Configuration

RiverpodTimeline.initialize(
  maxEvents: 10000,                    // Max events in memory
  enablePerformanceTracking: true,     // Track rebuild counts & durations
  enableDependencyTracking: true,      // Track provider relationships
  enableReleaseMode: false,            // Enable in release builds
  captureStackTraces: false,           // Capture stack traces (expensive)
  enableLogging: false,                // Print events to debug console
  enableOverlay: true,                 // Show floating debug button
);

API

Method	Description
tl.observer	Pass to ProviderScope
tl.controller	Query/filter timeline events
tl.graphController	Dependency graph inspection
tl.timeTravelController	Time travel controls
tl.metricsCollector	Performance data
tl.replay() / tl.pause() / tl.resumeReplay()	Time travel shortcuts
tl.stepForward() / tl.stepBackward()	Step through events
tl.exportJson() / tl.importJson()	Session export/import

Screenshots

---

MIT License