flutter-startup-network-blocking

name	flutter-startup-network-blocking
description	Fix slow Flutter app startup caused by blocking network operations during initialization. Use when: (1) App takes several seconds to show first frame, (2) Startup logs show sequential network operations (WebSocket connections, API calls), (3) Services initialize during startup that aren't needed until user authenticates. Covers: converting sequential network ops to parallel with Future.wait(), deferring service initialization until actually needed (lazy init), and identifying blocking operations in Riverpod/provider initialization chains.
author	Claude Code
version	1.0.0
date	"2026-02-01T00:00:00.000Z"

Flutter Startup Network Blocking

Problem

Flutter app startup is slow because network operations (WebSocket connections, API calls, service initialization) run sequentially during the initialization phase, blocking the first frame from rendering. With multiple relay/server connections, worst-case startup time becomes O(n × timeout) instead of O(max timeout).

Context / Trigger Conditions

• App takes 3+ seconds to show first frame on fresh launch
• Startup logs show sequential "connecting to relay X... connecting to relay Y..."
• Services that require authentication initialize even for unauthenticated users
• _initializeCoreServices() or similar contains multiple awaited network operations
• Riverpod providers eagerly initialize network-dependent services in their build() method

Solution

1. Identify Blocking Operations

Look for sequential awaits in startup code:

// BAD: Sequential - each connection blocks the next
for (final url in relays) {
  await connectToRelay(url);  // Blocks startup!
}

2. Convert Sequential to Parallel

Use Future.wait() to run all connections simultaneously:

// GOOD: Parallel - all connections run at once
final results = await Future.wait(
  relays.map((url) async {
    final success = await connectToRelay(url);
    return MapEntry(url, success);
  }),
);

3. Defer Non-Critical Service Initialization

Move network-dependent services out of the critical startup path:

Before (blocking startup):

Future<void> _initializeCoreServices(ProviderContainer container) async {
  await container.read(authServiceProvider).initialize();
  await container.read(nostrServiceProvider).initialize();  // BLOCKS for relay connections!
  await container.read(otherServiceProvider).initialize();
}

After (lazy initialization):

Future<void> _initializeCoreServices(ProviderContainer container) async {
  // NOTE: NostrService initializes lazily when user authenticates
  await container.read(authServiceProvider).initialize();
  await container.read(seenVideosServiceProvider).initialize();
  // NostrService NOT initialized here - happens when auth state changes
}

4. Use Provider Dependencies for Lazy Init

Let Riverpod handle lazy initialization through provider dependencies:

@riverpod
NostrClient nostrClient(NostrClientRef ref) {
  final authService = ref.watch(authServiceProvider);

  // Only creates client when auth state is ready
  if (!authService.isAuthenticated) {
    return NostrClient.disconnected();
  }

  // Initialize lazily when actually needed
  final client = NostrClient(relays: authService.userRelays);
  Future.microtask(() => client.initialize());
  return client;
}

Verification

1. Check startup logs for "First frame rendered in Xms" - should be < 2000ms
2. Verify network operations happen AFTER first frame timestamp in logs
3. For unauthenticated users, relay connections should NOT appear in startup logs

Example

Startup improvement achieved:

• Before: First frame at 3500ms+ (waiting for 5 relays × ~700ms each)
• After: First frame at 1426ms (parallel connections happen post-frame)

Log pattern showing fix working:

[18:15:17.538] First frame rendered in 1426ms
[18:15:17.556] Creating NostrClient...  // AFTER first frame!

Notes

• This pattern applies to any async initialization, not just WebSockets
• Consider timeout handling when parallelizing - use Future.wait with error handling
• For critical services, use a loading screen rather than blocking the main thread
• Profile with Flutter DevTools Timeline to identify other startup bottlenecks
• Remember that Future.wait() fails fast by default - use try/catch inside the map if you want partial success

Related Patterns

• Splash screen with async initialization
• Riverpod AsyncNotifier for lazy-loaded state
• Background service initialization after first frame

References

• Flutter Performance Best Practices
• Dart Future.wait documentation
• Riverpod lazy initialization