Ferry generates immutable data classes for all of your GraphQL Operations and Fragments. This saves time, improves the developer experience, and eliminates potential runtime errors.
How it works
Let's say I've created an
all_pokemon.graphql file with the following query:
When I run the generator, Ferry will create the following classes:
GAllPokemonReq: This class extends
OperationRequestand includes the GraphQL document and variables for this query. It also includes other necessary configuration to adjust how this operation is executed (e.g.
GAllPokemonVars: This class includes any variables used in the query (just "first", in this case)
GAllPokemonData: This class represents the data returned by the query, including the "pokemons" field and all child fields.
In addition, Ferry will generate any necessary supporting classes from your GraphQL schema, including
enums, and custom
Ferry's generated classes are based on the
built_value package, which means they are:
- immutable: once they are created, they cannot be changed.
- equatable: multiple instances with identical values have
- serializable: can be serialized using the
- use the builder pattern: can be deeply copied with modifications using the Builder Pattern.
Check out this post for more information on
built_value classes and how to use them.
As you can see, Ferry prepends
"G" to all class names. This is due to a limitation in the
built_value package and is necessary to ensure classes get generated correctly.
Download Your GraphQL Schema
To generate our classes, we first need to downoad our GraphQL in SDL format to any location within the
lib project directory. You can use the get-graphql-schema tool to download a schema from a GraphQL endpoint:
First, install the tool:
Next, download the schema by running the following command, replacing
[ENDPOINT_URL] with the url of your GraphQL endpoint:
As shown in the example above, we need to save all of our GraphQL operations to files that end with the
The generated files are created as siblings to the
.graphql file. To reduce clutter, we recommend placing your
.graphql files in a
/graphql subdirectory. For example, if I have an
AllPokemon widget that will use the
AllPokemon query from above, I might use the following directory structure:
Make sure that all
.graphql files are located in the
lib directory (or a subdirectory). The generator cannot read files located outside of
See the examples for more detail.
Importing from other
If your operations have dependencies in other
.graphql files, you can import them by adding a comment import statement at the top of your
Build Generated Classes
Now that we've downloaded our GraphQL schema and saved our GraphQL Operations to
.graphql files, we're almost ready to run the generator. The final step is to add a configuration file so that
built_runner knows which generators to run and where to find our schema.
build.yaml file to your project root with the following contents, replacing
your_package_name and the path to your schema file accordingly.
Now you can build your dart generated files by calling:
Or, if you are using flutter
You may need to add the
--delete-conflicting-outputs flag to the build_runner command:
After running the generator, your directory should look something like this:
You may want to configure your IDE to hide the generated files, since it can get unwieldy, even if you're placing your
.graphql files in a subdirectory.
If you use VSCode, you can include the following in your