flutter-retrofit-networking
Build type-safe HTTP networking with Dio and Retrofit including auth interceptors. Use when integrating Dio, Retrofit, or API auth interceptors in Flutter. (triggers: **/data_sources/**, **/api/**, Retrofit, Dio, RestClient, GET, POST, Interceptor, refreshing)
Best use case
flutter-retrofit-networking is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Build type-safe HTTP networking with Dio and Retrofit including auth interceptors. Use when integrating Dio, Retrofit, or API auth interceptors in Flutter. (triggers: **/data_sources/**, **/api/**, Retrofit, Dio, RestClient, GET, POST, Interceptor, refreshing)
Teams using flutter-retrofit-networking should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/flutter-retrofit-networking/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How flutter-retrofit-networking Compares
| Feature / Agent | flutter-retrofit-networking | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Build type-safe HTTP networking with Dio and Retrofit including auth interceptors. Use when integrating Dio, Retrofit, or API auth interceptors in Flutter. (triggers: **/data_sources/**, **/api/**, Retrofit, Dio, RestClient, GET, POST, Interceptor, refreshing)
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Retrofit & Dio Networking
## **Priority: P0 (CRITICAL)**
Type-safe REST API communication using `Dio` and `Retrofit`.
## Structure
```text
infrastructure/
├── data_sources/
│ ├── remote/ # Retrofit abstract classes
│ └── local/ # Cache/Storage
└── network/
├── dio_client.dart # Custom Dio setup
└── interceptors/ # Auth, Logging, Cache
```
## Implementation Workflow
1. **Define Retrofit clients** — Create abstract classes with `@RestApi()` and HTTP annotations (`@GET`, `@POST`). Methods return `Future<DTO>`.
2. **Create DTOs** — Use `@freezed` and `@JsonSerializable` for all request/response bodies.
3. **Map to domain** — Data sources must map DTOs to Domain Entities (e.g., `userDto.toDomain()`).
4. **Guard enums** — Always use `@JsonKey(unknownEnumValue: Status.unknown)` to prevent crashes from new backend values.
5. **Add auth interceptor** — Inject `Authorization: Bearer <token>` in `onRequest`.
6. **Handle token refresh** — On 401, lock Dio, call `refreshToken()`, update stored token, retry via `dio.fetch(err.requestOptions)`.
7. **Map failures** — Convert `DioException` to typed `Failure` objects (ServerFailure, NetworkFailure).
### Retrofit Client & Safe Enum DTO Examples
See [implementation examples](references/implementation.md) for RestClient definitions and safe enum DTO patterns.
## Anti-Patterns
- ❌ `jsonDecode(response.body)` — use Retrofit's generated mappers, never manual JSON parsing
- ❌ Static global `Dio` instance — inject Dio via DI; avoid global singletons
- ❌ `try-catch` inside Retrofit interface methods — let the repository layer handle exceptions
- ❌ Enum fields without `unknownEnumValue` — new backend values will crash the app
## Reference & Examples
For RestClient definitions and Auth Interceptor implementation:
See [references/REFERENCE.md](references/REFERENCE.md).
## Related Topics
feature-based-clean-architecture | error-handlingRelated Skills
ios-networking
Build API clients with URLSession, Alamofire, and Codable. Use when implementing URLSession networking, Alamofire, or API clients in iOS. (triggers: **/*Service.swift, **/*API.swift, **/*Client.swift, URLSession, Alamofire, Moya, URLRequest, URLComponents, Codable)
flutter-widgets
Build maintainable Flutter UI components with composition and theming. Use when building, refactoring, or reviewing Flutter widget implementations for maintainability. (triggers: **_page.dart, **_screen.dart, **/widgets/**, StatelessWidget, const, Theme, ListView)
flutter-testing
Write unit, widget, and integration tests with robots, widget keys, and Patrol in Flutter. Use when writing Flutter unit tests, widget tests, or integration tests with Patrol. (triggers: **/test/**.dart, **/integration_test/**.dart, **/robots/**.dart, lib/core/keys/**.dart, test, patrol, robot, WidgetKeys, patrolTest, blocTest, mocktail)
flutter-security
Enforce OWASP Mobile security standards for Flutter apps. Use when storing data, making network calls, handling tokens/PII, or preparing a release build. (triggers: lib/infrastructure/**, pubspec.yaml, secure_storage, obfuscate, jailbreak, pinning, PII, OWASP)
flutter-riverpod-state-management
Implement reactive state management using Riverpod 2.0 with code generation in Flutter. Use when defining @riverpod providers, building AsyncNotifiers, overriding providers in tests, or enforcing immutable state with Freezed models. (triggers: **_provider.dart, **_notifier.dart, riverpod, ProviderScope, ConsumerWidget, Notifier, AsyncValue, ref.watch, @riverpod)
flutter-performance
Optimization standards for rebuilds and memory. Use when optimizing Flutter widget rebuilds, reducing memory usage, or improving rendering performance. (triggers: lib/presentation/**, pubspec.yaml, const, buildWhen, ListView.builder, Isolate, RepaintBoundary)
flutter-notifications
Integrate push and local notifications using FCM and flutter_local_notifications. Use when adding push or local notifications to Flutter apps. (triggers: **/*notification*.dart, **/main.dart, FirebaseMessaging, FlutterLocalNotificationsPlugin, FCM, notification, push)
flutter-navigation
Implement navigation patterns with go_router, deep linking, and named routes. Use when building navigation, deep linking, or named routes in Flutter. (triggers: **/*_route.dart, **/*_router.dart, **/main.dart, Navigator, GoRouter, routes, deep link, go_router, AutoRoute)
flutter-localization
Add multi-language support using easy_localization with CSV or JSON. Use when implementing localization or multi-language support in Flutter apps. (triggers: **/assets/translations/*.json, **/assets/langs/*.csv, main.dart, localization, multi-language, translation, tr(), easy_localization, sheet_loader)
flutter-layer-based-clean-architecture
Enforce inward dependency flow, pure domain layers, and DTO-to-entity mapping in Flutter DDD architecture. Use when structuring lib/domain/, lib/infrastructure/, lib/application/, or lib/presentation/ layers, defining repository interfaces, or wiring BLoCs with get_it. (triggers: lib/domain/**, lib/infrastructure/**, lib/application/**, dto, mapper, Either, Failure)
flutter-idiomatic-flutter
Compose modern Flutter layouts and widgets idiomatically. Use when composing Flutter widget trees, managing layout constraints, or following idiomatic Flutter patterns. (triggers: lib/presentation/**/*.dart, context.mounted, SizedBox, Gap, composition, shrink)
flutter-go-router-navigation
Typed routes, route state, and redirection using go_router. Use when implementing go_router typed routes, guards, or redirects in Flutter. (triggers: **/router.dart, **/app_router.dart, GoRouter, GoRoute, StatefulShellRoute, redirection, typed-routes)