---
description: "Flutter Web conventions for TaskFlow — Pillar 4"
alwaysApply: true
---

# Flutter Web Standards — TaskFlow

## Critical: No dart:io on web
- **NEVER** import `dart:io` in shared code — it crashes on web
- Use `dart:html` or `universal_io` for platform-specific I/O
- Use `path_provider` alternatives: `universal_html` for web file access
- Check: `kIsWeb` constant before any platform-specific code

```dart
// ✅ Platform-safe
import 'package:universal_io/io.dart';

// ❌ Crashes on web
import 'dart:io';
```

## Web rendering
- Choose renderer carefully:
  - `canvaskit` — pixel-perfect, larger initial load, better for graphics
  - `html` — smaller load, uses DOM elements, inconsistent rendering
- Set in `index.html`: `flutterWebRenderer: "canvaskit"`

## PWA requirements
- Update `web/manifest.json`: name, icons (192×192, 512×512), theme_color
- Service worker: configure for offline caching of app shell
- Test with Chrome DevTools → Lighthouse → PWA audit

## Web-specific rendering caveats
- `BackdropFilter` has limited support on `html` renderer
- `Canvas` operations differ between renderers — test both
- Text selection differs — use `SelectableText` not `Text` where appropriate
- Scrollbars appear automatically on web — style or hide with `ScrollbarTheme`

## URL strategy
- Use `usePathUrlStrategy()` in `main.dart` for clean URLs (no `#`)
- Configure server to redirect all paths to `index.html` (SPA routing)

## Performance
- Lazy-load routes — use `GoRouter` deferred loading
- Initial load budget: < 3MB (canvaskit) or < 1MB (html renderer)
