Skip to content
Build dart types from GraphQL schemas and queries
Dart
Branch: master
Clone or download
Latest commit fca47fd Sep 18, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Add GH actions badge Sep 7, 2019
example Upgrade `gql` to version `0.2.0` Sep 11, 2019
lib Run linter Sep 18, 2019
test
tool disable implicit-casts Sep 18, 2019
.gitignore only ignore root pubspec Sep 5, 2019
CHANGELOG.md
FUNDING.yml
LICENSE Transform it into a dart library May 30, 2019
README.md Add GH actions badge Sep 7, 2019
analysis_options.yaml disable implicit-casts Sep 18, 2019
build.yaml Make builder $lib$, outputting to defined output file Sep 7, 2019
pubspec.yaml 1.0.4 Sep 18, 2019

README.md

Artemis

Build dart types from GraphQL schemas and queries

Pub Package GitHub Actions

Artemis is a code generator that looks for *.schema.json (GraphQL Introspection Query response data) and *.graphql files and builds .dart files typing that query, based on the schema. That's similar to what Apollo does (Artemis is his sister anyway).


Installation

Add the following to your pubspec.yaml file:

dependencies:
  artemis: <1.0.0

dev_dependencies:
  build_runner: ^1.5.0
  json_serializable: ^3.0.0

ℹ️ Note that build_runner and json_serializable are required on dev_dependencies!

ℹ️ If you're not using ArtemisClient, the lib can be included on dev_dependencies instead.

Then run:

pub packages get

or

flutter packages get

Now Artemis will generate the API files for you by running:

pub run build_runner build

or

flutter pub run build_runner build

Configuration

Artemis offers some configuration options to generate code. All options should be included on build.yaml file on the root of the project:

targets:
  $default:
    builders:
      artemis:
        options:
          # custom configuration options!
Option Default value Description
generate_helpers true If Artemis should generate query/mutation helper GraphQLQuery subclasses.
custom_parser_import null Import path to the file implementing coercer functions for custom scalars. See Custom scalars.
scalar_mapping [] Mapping of GraphQL and Dart types. See Custom scalars.
schema_mapping [] Mapping of queries and which schemas they will use for code generation. See Schema mapping.

It's important to remember that, by default, build will follow Dart's package layout conventions, meaning that only some folders will be considered to parse the input files. So, if you want to reference files from a folder other than lib/, make sure you've included it on sources:

targets:
  $default:
    sources:
      - lib/**
      - graphql/**
      - data/**
      - schema.json

Schema mapping

By default, Artemis won't generate anything. That's because your queries/mutations should be linked to GraphQL schemas. To configure it, you need to point a schema_mapping to the path of those queries and schemas:

targets:
  $default:
    builders:
      artemis:
        options:
          schema_mapping:
            - output: 'lib/graphql_api.dart'
              schema: lib/my_graphql.schema.json
              queries_glob: lib/**.query.graphql

Each SchemaMap is configured this way:

Option Default value Description
output Relative path to output the generated code.
schema Relative path to the GraphQL schema.
queries_glob Glob that selects all query files to be used with this schema. Their extension must be .query.graphql.
resolve_type_field __resolveType The name of the field used to differentiatiate interfaces and union types (commonly __resolveType or __typename). Note that __resolveType field are not added automatically to the query. If you want interface/union type resolution, you need to manually add it to the query.
add_query_prefix false Wheter to add the name of the query as a prefix for each dependent object of this query input or response.

See examples for more information and configuration options.

Custom scalars

If your schema uses custom scalars, they must be defined on build.yaml. If it needs a custom parser (to decode from/to json), the custom_parser_import path must be set and the file must implement both fromGraphQL___ToDart___ and fromDart___toGraphQL___ constant functions.

targets:
  $default:
    builders:
      artemis:
        options:
          custom_parser_import: 'package:graphbrainz_example/coercers.dart'
          scalar_mapping:
            - graphql_type: Date
              dart_type: DateTime

If your custom scalar needs to import Dart libraries, you can provide it in the config as well:

targets:
  $default:
    builders:
      artemis:
        options:
          custom_parser_import: 'package:graphbrainz_example/coercers.dart'
          scalar_mapping:
            - graphql_type: BigDecimal
              dart_type:
                name: Decimal
                imports:
                  - 'package:decimal/decimal.dart'

Each ScalarMap is configured this way:

Option Default value Description
graphql_type The GraphQL custom scalar name on schema.
dart_type The Dart type this custom scalar should be converted from/to.
use_custom_parser false Wheter custom_parser_import should be imported on the beginning of the file.

See examples for more information and configuration options.

ArtemisClient

If you have generate_helpers then, Artemis will create a subclass of GraphQLQuery for you, this class can be used in conjunction with ArtemisClient.

final client = ArtemisClient();
final gitHubReposQuery = MyGitHubReposQuery();
final response = await client.query(gitHubReposQuery);

Check the examples to see how to use it in details.

You can’t perform that action at this time.