Chopper
DevelopmentchopperChopper is an Agent Skill for development published in the lejard-h/chopper repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use this skill whenever a user wants to install, configure, write, generate, debug, or choose options for Chopper HTTP clients in Dart or Flutter, including @ChopperApi services, ChopperClient setup, build_runner/chopper_generator, converters, interceptors, response handling, query parameters, or chopper_built_value integration.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/lejard-h/chopper/blob/HEAD/skills/chopper/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/chopper, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Chopper Usage Assistant
Help users build Dart and Flutter HTTP clients with Chopper. Focus on application code, generated service setup, and interoperability outcomes, not repository maintenance.
Start With Inputs
Before producing a final snippet, collect only details that change the code:
- Runtime: Dart package, Dart server/CLI, Flutter app, or test.
- API shape: base URL, service base path, endpoint paths, methods, headers, path/query parameters, request bodies, and expected status handling.
- Response handling: raw
Response, nullable/no-content endpoint, typed body, JSON map/list, custom model converter, stream, file, or error body. - Serialization approach: built-in
JsonConverter, custom converter,json_serializable,built_value, form URL encoding, multipart, or raw body. - Generation issue details: file name,
partdirective, service declaration, build command, and relevantbuild_runnererror output.
Do not over-ask when the intent is clear. State assumptions and give concrete snippets users can paste.
When To Read References
- Read core.md for service/client setup, annotations, responses, converters, interceptors, query parameters, forms, and multipart.
- Read generator.md for
chopper_generator,build_runner, generated files, and generation troubleshooting. - Read built-value.md for
chopper_built_value, serializer setup, built_value enum query parameters, and error conversion.
Installation
For a Dart package or CLI:
dart pub add chopper
dart pub add --dev build_runner chopper_generator
For Flutter:
flutter pub add chopper
flutter pub add --dev build_runner chopper_generator
Use the public import:
import 'package:chopper/chopper.dart';
Generate services after adding or changing @ChopperApi declarations:
dart run build_runner build --delete-conflicting-outputs
Use flutter pub run build_runner ... only when the user's project explicitly requires old Flutter tooling. Prefer the current dart run build_runner ... form in new snippets.
Base Pattern
Use uppercase annotation classes in examples.
import 'package:chopper/chopper.dart';
part 'todos_service.chopper.dart';
@ChopperApi(baseUrl: '/todos')
abstract class TodosService extends ChopperService {
static TodosService create([ChopperClient? client]) => _$TodosService(client);
@GET()
Future<Response<List<dynamic>>> listTodos();
@GET(path: '/{id}')
Future<Response<Map<String, dynamic>>> getTodo(@Path('id') String id);
@POST()
Future<Response<Map<String, dynamic>>> createTodo(
@Body() Map<String, dynamic> body,
);
}
Bind generated services to a client:
final chopper = ChopperClient(
baseUrl: Uri.parse('https://api.example.com'),
services: [TodosService.create()],
converter: const JsonConverter(),
errorConverter: const JsonConverter(),
);
final todosService = chopper.getService<TodosService>();
Core Rules
- Use
ChopperClient(baseUrl: Uri.parse('https://api.example.com')); avoid old examples that pass a stringbaseUrl. - Every generated service file needs a matching
part '*.chopper.dart';. - Generated service classes use the private
_$ServiceNameconstructor helper. JsonConverterJSON-encodes maps/lists and decodes JSON text into Dart maps/lists. It does not automatically turn JSON into user model classes.- Use
Future<Response<T>>when callers need status code, headers, error body, nullable success bodies, or HTTP 204/no-content handling. - Use
Future<T>only when a non-null converted body is enough. Chopper returnsresponse.bodyOrThrow; unsuccessful responses and successfulnullbodies throw. @FactoryConverterwith a non-null request or response factory replaces the client-level converter for that endpoint direction. It is not chained after the client converter.- Query parameter conversion currently applies to query values only, not keys. Chopper preserves a nested map/list shape and converts leaf values before URL encoding.
Troubleshooting Checklist
Check these before proposing unusual fixes:
- Missing or wrong
partdirective: it must match the current Dart file name. - Missing
chopper_generatororbuild_runnerdev dependency. - Stale generated files: rerun
dart run build_runner build --delete-conflicting-outputs. - Service is not abstract, does not extend
ChopperService, or lacks@ChopperApi. - Client uses a string
baseUrlinstead ofUri.parse(...). - Typed model responses are requested without a converter that maps JSON to the model type.
- A
@FactoryConverterendpoint unexpectedly skipped the client converter. - A built_value query enum uses the enum name because
BuiltValueConverterwas not passed asconverterorparameterConverter.
Response Shape
For code-generation or troubleshooting requests, answer with:
- Assumptions that affect code, especially runtime, base URL, body format, converter choice, response shape, and generation command.
- One complete service/client snippet or the smallest patchable snippet.
- The command to generate code when generated files are involved.
- A brief explanation of only the annotations/options/converters used.
- A focused troubleshooting or verification step.