flutter-debugging

name	flutter-debugging
description	Debug and profile Flutter applications using DevTools, structured logging, and memory analysis. Use when diagnosing layout issues, tracking performance bottlenecks, or setting up centralized error reporting with Crashlytics. Use when this capability is needed.
metadata	{"author":"dhruvanbhalara"}

Logging

• Use a centralized AppLogger class for all logging — NEVER use print() or raw debugPrint()
• Define log levels: verbose, debug, info, warning, error, fatal
• In dev flavor: log everything (verbose and above)
• In staging: log info and above
• In production: log warning and above only, route to Crashlytics
• Include context in logs: AppLogger.error('Failed to fetch user', error: e, stackTrace: st)
• NEVER log sensitive data (passwords, tokens, PII) at any level

Flutter DevTools

• Use Widget Inspector to debug layout issues and identify unnecessary rebuilds
• Use Performance Overlay (showPerformanceOverlay: true) to monitor frame rates
• Use Timeline View to identify jank — target 16ms per frame (60fps)
• Use Memory View to detect memory leaks and monitor allocation patterns
• Use Network Profiler to inspect Dio requests/responses during development

Debugging Strategies

• Layout Issues: Use debugPaintSizeEnabled = true to visualize widget boundaries
• Overflow Errors: Check RenderFlex overflowed — use Expanded, Flexible, or constrain dimensions
• Unbounded Height: Wrap ListView in SizedBox or use shrinkWrap: true with NeverScrollableScrollPhysics
• Rebuild Tracking: Add debugPrint('$runtimeType rebuild') temporarily to identify excessive rebuilds — remove before commit
• Async Errors: Always catch and log errors in try-catch blocks with stack traces
• Use assert() for development-time invariant checks that are stripped in release builds

Memory Management

• Dispose ALL controllers, subscriptions, Timer, and AnimationController in dispose()
• Use late initialization in initState() — never inline-initialize disposable objects
• Use WeakReference for caches that should not prevent garbage collection
• Profile memory with DevTools Memory tab — watch for monotonically increasing allocations
• Watch for common leaks: undisposed listeners, closures capturing BuildContext, global streams without cancellation

Performance Profiling

• Always profile with --profile mode (not debug): flutter run --profile --flavor dev -t lib/main_dev.dart
• Use Timeline.startSync / Timeline.finishSync for custom performance tracing of critical paths
• Monitor shader compilation jank on first run — use --cache-sksl for warmup:

  flutter run --profile --cache-sksl --purge-persistent-cache
  

• Target metrics: < 16ms frame build time, < 100ms screen transition, < 2s cold start

Error Boundaries

• Route errors to Crashlytics in staging/prod (FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError)
• Set FlutterError.onError and PlatformDispatcher.instance.onError to catch framework and async errors
• Wrap critical widget subtrees in custom error boundary widgets that show fallback UI instead of red screens
• In release mode: NEVER show stack traces to users — show user-friendly error messages only

---

Source: dhruvanbhalara/skills — distributed by TomeVault.