graphql_codegen

Description:

graphql codegen

GraphQL Codegen #
HELP US SURVIVE, BECOME A SPONSOR! #
This is an opinionated code-generation tool from GraphQL to Dart/Flutter.
It'll allow you to generate Dart serializers and client helpers with minimal config.
The framework makes no assumption on how you structure your fragments or queries,
for each operation.graphql the framework will generate a operation.graphql.dart file containing dart classes.
Read more about the tool and motivation at the GraphQL Codegen deep-dive
and on how you can structure your flutter apps with the tool on Structure your Flutter GraphQL apps.
The framework does not fetch your schema for you, so before you run this, you'll need
to add your schema to your project. In Android Studio this can be done with the GraphQL plugin.
Installation #
Dev dependencies #

build_runner generates files from dart code. Read more here

$ flutter pub add --dev graphql_codegen build_runner
copied to clipboard
Dependencies #


graphql (optional) to use generated types with graphql. See options


graphql_flutter (optional) to use generated types with graphql_flutter. See options


flutter_hooks (optional) to use generated operations hooks. Will be inside HookWidgets


$ flutter pub add graphql graphql_flutter flutter_hooks
copied to clipboard
Basic Usage #
To generate dart classes from GraphQL schema, firstly you have to create a schema.graphql file and GraphQL document files.
For instance:
Given schema
# ./lib/schema.graphql

type Query {
fetch_person(id: ID!): Person
}

type Person {
full_name: String!
nickname: String
website: URL
date_of_birth: ISODateTime
parents: [Person!]
siblings: [Person!]
children: [Person!]
}

scalar ISODateTime

scalar URL
copied to clipboard
and a query
# ./lib/person.graphql

query FetchPerson($id: ID!) {
fetch_person(id: $id) {
name: full_name
}
}
copied to clipboard
and then you can generate dart classes with:
$ dart run build_runner build
copied to clipboard
afterwards, you can parse the result with
// person.dart

import 'person.graphql.dart';

main () {
final data = fetchDataFromSomewhereMaybeOuterSpace();
final parsedData = Query$FetchPerson.fromJson(data);
final name = parsedData.fetchPerson?.name;
print(name);
}
copied to clipboard
Using fragments #
Fragments are a great tool to re-use queries throughout your app. These are used to create "interfaces"
which allow you to easily parse your data around. Given the schema above and the query
# parents_and_children.graphql

fragment PersonSummary on Person {
full_name
}

query FetchParentsAndChildren {
fetch_person(id: "1") {
parents {
...PersonSummary
nickname
}

children {
...PersonSummary
}
}
}
copied to clipboard
this will allow you to do the following
// parents_and_children.dart

import 'parents_and_children.graphql.dart';

printPerson(FragmentPersonSummary person) {
print(person.fullName);
}

main () {
final data = fetchDataFromTheVoid();
final parsedData = Query$FetchParentsAndChildren.fromJson(data);
for (final parent in parsedData?.fetchPerson.parents ?? []) {
printPerson(parent);
print(parent.dob);
}
for (final child in parsedData?.fetchPerson.children ?? []) {
printPerson(child);
}
}
copied to clipboard
The Fragment$PersonSummary is a class on the shape of
...
class Fragment$PersonSummary {
String get fullName;
}
...
copied to clipboard
and will be available in the generated .graphql.dart file for the .graphql file
containing the fragment.
Inline fragments #
Inline fragment spreads work just like fragment spreads with the exception that they don't generate any explicit Fragment$YourFragment classes.
So let's have the schema
type Query {
account: Account!
}

union Account = PersonalAccount | BusinessAccount

type PersonalAccount {
personName: String!
}

type BusinessAccount {
businessName: String!
}
copied to clipboard
and the query
query FetchAccount {
account {
... on PersonalAccount {
personName
}
... on BusinessAccount {
businessName
}
}
}
copied to clipboard
the generated classes will allow you to handle the data appropriately with code along the lines of

void printAccount(Query$FetchAccount$account account) {
if (account is Query$FetchAccount$account$$PersonalAccount) print(account.personName);
if (account is Query$FetchAccount$account$$BusinessAccount) print(account.businessName);
}

void printQuery(Query$FetchAccount query) {
printAccount(query.account);
}
copied to clipboard
This works but is a long class name! In these cases I usually opt to using named fragments
fragment PersonalAccount on PersonalAccount {
personName
}

fragment BusinessAccount on BusinessAccount {
businessName
}

query FetchAccount {
account {
...BusinessAccount
...PersonalAccount
}
}
copied to clipboard
which allows you to do the following

void printAccount(Query$FetchAccount$account account) {
if (account is Fragment$PersonalAccount) print(account.personName);
if (account is Fragment$BusinessAccount) print(account.businessName);
}

void printQuery(Query$FetchAccount query) {
printAccount(query.account);
}
copied to clipboard
Additionally, you can use the when and maybeWhen methods to avoid is type tests. NOTE This also works the same without the inline fragments.

void printAccount(Query$FetchAccount$account account) {
// specify all the cases (and an else in case there's a new type in the response that wasn't previously known)
account.when(
personalAccount: (personalAccount) => print(personalAccount.personName),
businessAccount: (businessAccount) => print(businessAccount.businessName),
orElse: () => print('Some other unexpected type'),
)

// specify only the cases you want to handle (and an else)
account.maybeWhen(
personalAccount: (personalAccount) => print(personalAccount.personName),
orElse: () => print('Anything else, including BusinessAccount'),
)
}

void printQuery(Query$FetchAccount query) {
printAccount(query.account);
}
copied to clipboard
Options #
# build.yaml

targets:
$default:
builders:
graphql_codegen:
options:
# all options go here
copied to clipboard



Option
Default
Description
More info




clients
{}
Graphql clients to generate helper functions for. Supported types are graphql and graphql_flutter
Clients


scalars
{}
Allows custom JSON-Dart transformations. Builder will warn if scalars are not recognized. Unless using primitive types, you will need fromJsonFunctionName, toJsonFunctionName, type, and import
Custom scalars


enums
{}
Allows custom enum implementation. You can define fromJsonFunctionName, toJsonFunctionName, type, and import
Custom enums


addTypename
true
Whether to automatically insert the __typename field in requests
Add typename


addTypenameExcludedPaths
[]
When addTypename is true, the paths to exclude
Excluding typenames


outputDirectory
"."
Location where to output generated types relative to each .graphql file
Change output directory


assetsPath
"lib/**.graphql"
Path to .graphql files
see above


generatedFileHeader
""
A string to add at the beginning of all graphql.dart files
Generated file headers


scopes
["**.graphql"]
For multiple schemas, the globs for each schema
Multiple Schemas


namingSeparator
"$"
The separator to use for generated names
Change naming separator


extraKeywords
[]
A way to specify fields that are also keywords
Extra keywords


disableCopyWithGeneration
false
Allow you to disable generation of copy-with classes and methods





Clients #
Parsing data is all fine and well, but practically not extremely useful. Therefore, we can generate
clients to call your API.
Clients can be enabled in the build.yaml file with:
# build.yaml

targets:
$default:
builders:
graphql_codegen:
options:
clients:
- graphql
- graphql_flutter
copied to clipboard
Currently, we support two clients:
Client graphql #
Once you've set up your graphql client (see pub.dev/packages/graphql), you can use
GraphQL Codegen to generate new queries or mutators on the client.
With the query from above:
# person.graphql

query FetchPerson($id: ID!) {
fetch_person(id: $id) {
name: full_name
}
}
copied to clipboard
we can now access the client:
import 'person.graphql.dart';


main () async {
final client = GraphQLClient();
final result = await client.query$FetchPerson(
Options$Query$FetchPerson(
variables: Variables$Query$FetchPerson(id: "1"),
),
);
final parsedData = result.parsedData;
print(parsedData?.fetchPerson?.name);
}

copied to clipboard
Cache access
You can also manipulate the cache directly using the generated readFragmentX, writeFragmentX, readQueryX, and writeQueryX methods.
Given the fragment:
fragment PersonSummary on Person {
name
}
copied to clipboard
you can update the fragment with

main () {
// ...
final person = client.readFragment$PersonSummary(
idFields: {'__typename': 'Person', 'id': '1'},
);
assert(person != null);
client.writeFragment$PersonSummary(
idFields: {'__typename': 'Person', 'id': '1'},
data: person.copyWith(name: 'Kurt'),
);
}
copied to clipboard
the query methods work similarly.
Client graphql_flutter #
Once you've set up your graphql_flutter client (see pub.dev/packages/graphql_flutter),
you can use GraphQL Codegen to generate new Query or Mutation widgets.
With the query from above:
# person.graphql

query FetchPerson($id: ID!) {
fetch_person(id: $id) {
name: full_name
}
}
copied to clipboard
we can query with the widget
import 'person.graphql.dart';
import 'package:flutter/widgets.dart';

class PersonWidget extends StatelessWidget {

@override
Widget build(BuildContext context) {
return Query$FetchPerson$Widget(
options: Options$Query$FetchPerson(
variables: Variables$Query$FetchPerson(id: 'id'),
),
builder: (result, {fetchMore, refetch}) {
return Text(
result.parsedData?.fetchPerson?.name ?? '...loading'
);
}
);
}
}
copied to clipboard
or the hook
import 'person.graphql.dart';
import 'package:flutter/widgets.dart';
import 'flutter_hooks/flutter_hooks.dart';

class PersonWidget extends HookWidget {

@override
Widget build(BuildContext context) {
final result = useQuery$FetchPerson(
Options$Query$FetchPerson(
variables: Variables$Query$FetchPerson(id: 'id'),
),
);
return Text(result.parsedData?.fetchPerson?.name ?? '...loading');
}
}
copied to clipboard
Custom scalars #
Out of the box, the standard scalars are supported and mapped to relevant dart types. You can add
new mappings for your custom scalars or overwrite existing configurations.
In the schema above, you can see that we have defined the ISODateTime scalar. In this example, it contains
a string with an ISO formatted date-time string. We would like to map this to a String type by
adding the following configuration to the build.yaml file:
# build.yaml

targets:
$default:
builders:
graphql_codegen:
options:
scalars:
ISODateTime:
type: String
JSON:
type: Map<String, dynamic>
copied to clipboard
The library supports converting to and from DateTime automatically. So, we can write our config as
# build.yaml

targets:
$default:
builders:
graphql_codegen:
options:
scalars:
ISODateTime:
type: DateTime
JSON:
type: Map<String, dynamic>
copied to clipboard
and it'll work as expected.
Assume we want to use a CustomDateTime class instead, we can add
# build.yaml

targets:
$default:
builders:
graphql_codegen:
options:
scalars:
ISODateTime:
type: CustomDateTime
fromJsonFunctionName: customDateTimeFromJson
toJsonFunctionName: customDateTimeToJson
import: package:my_app/scalar.dart
copied to clipboard
and create a scalar.dart file with your converters
// scalar.dart

class CustomDateTime {
final DateTime dt;
CustomDateTime(this.dt);
}

CustomDateTime customDateTimeFromJson(dynamic data) => CustomDateTime(DateTime(data as String));
dynamic customDateTimeToJson(CustomDateTime time) => time.dt.toIso8601String();
copied to clipboard
and now all fields using ISODateTime will be a CustomDateTime instance.
Custom Enums #
Per default, the library will build enum serializers. If you want to provide your own implementation of an Enum, you can follow a similar pattern as Custom scalars.
Given the enum
enum GraphQLEnum {
FOO
BAR
BAZ
}
copied to clipboard
the config
# build.yaml

targets:
$default:
builders:
graphql_codegen:
options:
enums:
GraphQLEnum:
type: DartEnum
fromJsonFunctionName: fromJson
toJsonFunctionName: toJson
import: package:my_app/enum.dart
copied to clipboard
and the implementation
// enum.dart

enum DartEnum {
foo, bar, baz
}

DartEnum fromJson(String v) {
switch(v) {
case 'FOO': return DartEnum.foo;
case 'BAR': return DartEnum.bar;
default: return DartEnum.baz;
}
}

String toJson(DartEnum v) {
switch(v) {
case DartEnum.foo: return 'FOO';
case DartEnum.bar: return 'BAR';
case DartEnum.baz: return 'BAZ';
}
}

copied to clipboard
the generator will work as expected.
Use a custom fallback value #
Per default, the code-generator provides a default fallback value called $unknown. This is used to handle any
new enum values when parsing the enum. Without a fallback value, your app would break when you add a new enum value.
You can select an existing enum value to be the fallback enum value. This is done by specifying the fallbackEnumValue option on the enum. So given the GraphQL:
enum MyEnum {
FIRST
LAST
OTHER
}
copied to clipboard
and the configuration
# build.yaml

targets:
$default:
builders:
graphql_codegen:
options:
enums:
MyEnum:
fallbackEnumValue: OTHER
copied to clipboard
no $unknown value will be added to your enum and all new values will be mapped to MyEnum.OTHER.
Add typename #
By default, the addTypename option is enabled. This'll add the __typename introspection field to every selection set. E.g.,
query Foo {
bar {
baz
}
}
copied to clipboard
becomes
query Foo {
bar {
baz
__typename
}
__typename
}
copied to clipboard
This ensures the best conditions for caching.
Excluding some selections from adding typename #
Any query, mutation, subscription, or fragment can be excluded from adding the __typename introspection by the addTypenameExcludedPaths option:
Setting
addTypenameExcludedPaths:
- subscription
copied to clipboard
or
addTypenameExcludedPaths:
- Foo
copied to clipboard
will both transform
subscription Foo {
bar {
baz
}
}
copied to clipboard
to
subscription Foo {
bar {
baz
__typename
}
}
copied to clipboard
where
addTypenameExcludedPaths:
- subscription.bar
copied to clipboard
or
addTypenameExcludedPaths:
- subscription.*
copied to clipboard
or
addTypenameExcludedPaths:
- **.bar
copied to clipboard
will transform to
subscription Foo {
bar {
baz
}
__typename
}
copied to clipboard
Change output directory #
By default, the dart files are generated relative to the *.graphql file.
You can change this by specifying the outputDirectory folder.
# build.yaml

targets:
$default:
builders:
graphql_codegen:
options:
outputDirectory: __generated
copied to clipboard
which place the files in the __generated folder relative to the .graphql file. E.g.,
/lib/document.graphql -> /lib/__generated/document.graphql
copied to clipboard
You may also specify an absolute path, e.g,
# build.yaml

targets:
$default:
builders:
graphql_codegen:
options:
outputDirectory: /lib/__generated
assetsPath: graphql/**
copied to clipboard
this in combination with an asset path will place the folders in
/graphql/document.graphql -> /lib/__generated/document.graphql
/graphql/fragments/document.graphql -> /lib/__generated/fragments/document.graphql
copied to clipboard
NOTICE: For build_runner to consider files outside of the "default package layout" you'll need to add the graphql/** to the source options.
Generated file headers #
Generated .graphql.dart files can have any string inserted at the beginning of the file with the generatedFileHeader option.
# build.yaml

targets:
$default:
builders:
graphql_codegen:
options:
generatedFileHeader: "// GENERATED FILE\n// DO NOT MODIFY\n"
copied to clipboard
One way to use this might be to ignore lint warnings with
generatedFileHeader: "// ignore_for_file: type=lint\n"
copied to clipboard
But since the .graphql.g.dart files also might have warnings it might be easier to ignore the generated file directories from analysis_options.yaml
analyzer:
exclude:
- lib/**/__generated__/*
copied to clipboard
Multiple schemas #
To support multiple schemas, the code generator has a concept of scopes. Consider the following configuration:
targets:
$default:
builders:
graphql_codegen:
options:
scopes:
- lib/schema1/**
- lib/schema2/**
copied to clipboard
here the generator will perform independent analysis for the GraphQL files matching the relevant scope. E.g., any GraphQL file in
the lib/schema1 folder will be built relative to the schema in this folder, ignoring all other files completely.
Change naming separator #
The library will generate a lot of serializers and other classes. The class names are a combination of operation, field, and
type names. To avoid name collisions, the library will separate each of these names with $.
E.g.,
query Q {
name
}
copied to clipboard
might yield the class
class Query$Q$name { ... }
copied to clipboard
This should work for most, but some other libraries might not support $. Therefore, you can configure the naming separator with the namingSeparator option. E.g., the configuration:
# build.yaml

targets:
$default:
builders:
graphql_codegen:
options:
namingSeparator: "___"
copied to clipboard
will change the above-yielded code to

class Query___Q___name { ... }
copied to clipboard
Null and input serializers #
Per default, when you construct an input any null field provided in the constructor will be omitted. E.g., given the input
input I {
s: String
b: Boolean
}
copied to clipboard
the following holds
Input$I(s: "Foo").toJson(); // {"s": "Foo"}
Input$I(s: "Foo", b: null).toJson(); // {"s": "Foo"}
Input$I(s: "Foo", b: false).toJson(); // {"s": "Foo", "b": false}
Input$I(s: "Foo").copyWith(b: null).toJson(); // {"s": "Foo", "b": null}
copied to clipboard
So to explicitly set a (nullable) field to null, you'll need to use the copyWith function.
Extra keywords #
Some APIs will generate fields that are in some way keywords and will break code generation. These might be fields
with type names.
You may specify extra keywords with the option
# build.yaml

targets:
$default:
builders:
graphql_codegen:
options:
extraKeywords:
- String
copied to clipboard