OpenParable
Skip to content
← Back to skills

Fjson Dart Bean Generator

Development
fjson-dart-bean-generator

Fjson Dart Bean Generator is an Agent Skill for development published in the K3vinb5/unyo-app repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Generate Dart bean classes from JSON and regenerate serialization helpers using the fjson CLI. Use this skill whenever the user needs to create Dart models from API JSON responses, generate @JsonSerializable entity classes, or regenerate .g.dart helper files. Also use when the user mentions FlutterJsonBeanFactory, fjson, json_to_dart, JSON serialization, @JSONField, @JsonSerializable, or needs to add new API response DTOs to the unyo project.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/K3vinb5/unyo-app/blob/HEAD/.agents/skills/fjson-dart-bean-generator/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/fjson-dart-bean-generator, 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.

fjson CLI — Dart Bean Generator

The fjson CLI generates @JsonSerializable Dart entity classes from JSON responses and regenerates .g.dart serialization helpers, json_field.dart, and json_convert_content.dart. It replaces the FlutterJsonBeanFactory IntelliJ plugin for CLI/agent workflows.

The bundled JAR lives inside this skill directory: fjson-cli.jar. Invoke it as:

java -jar <path-to-skill>/fjson-cli.jar <command> [options]

When running from the unyo project root, the skill is at .agents/skills/fjson-dart-bean-generator/:

java -jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar <command> [options]

If you need to rebuild the JAR (rare — only after modifying fjson-cli source):

cd ../fjson-cli && ./gradlew jar
# Then copy the new JAR into the skill:
cp ../fjson-cli/build/libs/fjson-cli.jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar

Two Commands

CommandPurposeWhen to use
fjson beanCreate a new entity .dart file from JSONUser provides a class name + JSON (string or file)
fjson genRegenerate all .g.dart helpers, json_field.dart, json_convert_content.dartAfter adding/modifying any @JsonSerializable class

Important: fjson bean automatically runs fjson gen when invoked inside a Flutter project (one with a pubspec.yaml). You do NOT need to run gen separately after bean.

fjson bean — Generate a new entity from JSON

Required flags

FlagDescriptionExample
--class <Name>Root class name (use the API response root name)--class MediaResponse
--json <string>Raw JSON string--json '{"id":1,"title":"..."}'
--file <path>Path to a .json file (alternative to --json)--file response.json

Optional flags

FlagDescriptionDefaultWhen to use
--output <path>Directory for the generated .dart file./libDirect entity to correct DTO subfolder
--suffix <text>Suffix appended to generated class namesentityLeave as default for unyo
--nullableMake fields nullable (Type?)offRarely needed in unyo
--set-defaultAssign default values to primitive fieldsoffAlways use this for unyo DTOs
--project <path>Flutter project root.Usually not needed from unyo root

Typical unyo invocation

java -jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar bean \
  --class MediaCollectionResponse \
  --json '<paste JSON here>' \
  --output ./lib/core/services/api/dto/anilist/ \
  --set-default

Or from a file:

java -jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar bean \
  --class AnizipEpisodeInfo \
  --file ./response.json \
  --output ./lib/core/services/api/dto/anizip/ \
  --set-default

What gets generated

The command produces a .dart file containing:

  • A root @JsonSerializable() class with --suffix appended (e.g., MediaCollectionResponse → MediaCollectionResponseEntity)
  • Nested @JsonSerializable() classes for each nested JSON object (e.g., MediaCollectionResponseDtoPage)
  • @JSONField(name: 'original_key') annotations for keys whose Dart naming differs from JSON
  • late fields with default values (if --set-default)
  • fromJson() factory and toJson() method stubs
  • import of json_field.dart and the matching .g.dart
  • export of the matching .g.dart

The generated entity also auto-triggers fjson gen, so the matching .g.dart, json_field.dart, and json_convert_content.dart are all regenerated immediately.

fjson gen — Regenerate all helpers

java -jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar gen --project .

This scans lib/**/*.dart for every @JsonSerializable class and:

  1. Regenerates each <entity>.g.dart file in lib/generated/json/
  2. Rebuilds lib/generated/json/base/json_field.dart (annotation definitions)
  3. Rebuilds lib/generated/json/base/json_convert_content.dart (the JsonConvert runtime and JsonConvertClassCollection registry with all entity imports)
  4. Deletes any stale .g.dart files for entities that no longer exist

Run this after any manual edit to an entity file (adding/removing/renaming fields).

Generated File Layout in unyo

unyo/
├── lib/core/services/api/dto/
│   └── anilist/
│       └── media_response_entity.dart          ← fjson bean output
└── lib/generated/json/
    ├── media_response_entity.g.dart             ← auto-generated helpers
    ├── media_collection_graphql_entity.g.dart   ← existing
    ├── ...                                      ← all other .g.dart
    └── base/
        ├── json_field.dart                     ← annotations
        └── json_convert_content.dart            ← registry + runtime

Entity file naming convention in unyo

  • Snake_case filenames: e.g., media_details_graphql_entity.dart
  • PascalCase class names: e.g., MediaDetailsGraphqlEntity
  • fjson converts PascalCase --class names to snake_case filenames automatically
  • Always place entities in the correct DTO subfolder: lib/core/services/api/dto/<provider>/
    • Providers: anilist/, anizip/, aniskip/, extensions/

Default unyo settings that fjson matches

  • --set-default is always used → all fields get = '', = 0, = false, etc.
  • --suffix entity (default) → class names end with Entity
  • flutter_json.generated_path is generated/json in pubspec.yaml

Workflow: Adding a new API response model

  1. Get the JSON — Either from the user, from a file, or from a GraphQL response
  2. Determine the provider (anilist, anizip, aniskip, extensions)
  3. Run fjson bean with --class, --json/--file, --output, and --set-default:
    java -jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar bean \
      --class NewApiResponse \
      --json '<the JSON>' \
      --output ./lib/core/services/api/dto/anilist/ \
      --set-default
    
  4. Verify the output — Open the generated .dart file and check:
    • Class names and field types are correct
    • Nested objects are properly generated as sub-classes
    • @JSONField(name: ...) mappings are correct for non-matching keys
  5. Update json_convert_content.dart — Already done automatically by fjson gen (triggered by fjson bean). Verify the new entity's import is present.
  6. Run analysis — flutter analyze to ensure no issues
  7. If fields need adjustment — Edit the entity file directly, then re-run fjson gen:
    java -jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar gen --project .
    

Common Pitfalls

  • Wrong --output path: Entity files must go to the correct provider subfolder (lib/core/services/api/dto/<provider>/) for the import in json_convert_content.dart and .g.dart files to resolve correctly.
  • Forgetting --set-default: Without it, fields use late without defaults. In unyo, all DTO fields have defaults (except dynamic).
  • Running in wrong directory: Commands assume the current working directory is the unyo project root (where pubspec.yaml lives). The --project flag overrides this.
  • Class name collision: If a class name already exists in another entity file, the generated .g.dart will have duplicate function names, causing compile errors. Check for existing names before running.
  • JSON with empty arrays: fjson handles this but cannot infer the element type of an empty List. The field will be typed List<dynamic> and must be corrected manually.
  • After running bean in a non-Flutter directory: fjson gen is skipped. You must manually run it from the project root.

Cross-references

  • unyo project structure and entity patterns: See unyo-domain-data-layer skill
  • DTO conventions and GraphQL response mapping: See unyo-domain-data-layer skill
  • Rebuilding fjson-cli from source: See ../fjson-cli/README.md