Ultimate toolchain to work with GraphQL in FlutterIntro
Hi! Recent times I’m investigating Flutter to suit our production needs. One of technologies that we use is GraphQL for fetching data from our API. To have a deep understanding of the whole range of flutter pros and cons I’m writing the same app using Flutter as my teammate on ReactNative. I’ve already tested Flutter capabilities in markup, navigation and animation — the results are very promising. As far as I’m experimenting in my free time I was able to achieve the same results as ReactNative counterpart in 1/3 of the time. And now it’s time to test GraphQL.
Intro
Nearly 6 month ago when I started experimenting with GraphQL in the Flutter ecosystem there was no suitable toolset for my purposes. The main available library, graphql_flutter
, was only 1 year old. There were some features missing like, fetchMore
and some others. The counterpart package for type generation was even younger — 3 month old. There was also a lack of documentation and examples.
Recently I returned back to the GraphQL field and I succeeded to find a pretty good set of tools to work with GraphQL in Flutter. I decided to share my solution because there is still a lack of docs.
This article is mainly based on Android Studio (all JetBrains products also work pretty well). Actually, there is only one plugin that does not work for VSCode, but I think you’ll be able to find a proper replacement for it.
Let’s start from the beginning — if you are not familiar with Flutter or GraphQL here is a little list of links:
- official docs Flutter — https://flutter.dev/docs
- Flutter benefits — https://medium.com/hackernoon/whats-revolutionary-about-flutter-946915b09514
- GraphQL docs — https://graphql.org/
Prerequisites
Let’s start from what we want to achieve:
- generate dart types and classes which covers GraphQL API queries
- local schema update in one click
- autocomplete and validation of GraphQL queries
- have an ability to work with API without waiting of backend implementation
Here what we will need for this:
- Android Studio (or any other suitable IDE from JetBrains) — https://developer.android.com/studio or https://www.jetbrains.com/
- install Flutter https://flutter.dev/docs/get-started/install
- properly setup IDE https://flutter.dev/docs/get-started/editor?tab=androidstudio
- install JS Graphql for Android Studio https://jimkyndemeyer.github.io/js-graphql-intellij-plugin/docs/getting-started
- install NodeJs https://nodejs.org/en/
Practice
Create new Flutter project
File -> New -> New Flutter Project
In opened window select — Flutter Application
Press “Next” several times until the end and then press “Finish”
More extended version of creating the initial project can be found in the “Test Drive” section in official docs — https://flutter.dev/docs/get-started/test-drive?tab=androidstudio
Now we have a dummy app for our experiments.
Install graphql_faker
npm install -g graphql-faker
oryarn global add graphql-faker
Let’s start it from terminalgraphql-faker ./fake.schema — open
This will launch a GraphQL server for you and open a web console for editing API.
./fake.schema param sets the file name which will be taken as a base for API mocking. As far as we do not have this file in our project root there will be a default schema mock shipped with graphql_faker
Let’s try to add something — after line 20 add the following
id: ID! @fake(type: uuid)
and press a “Save” button.
If you return to the project structure you will see the new file fake.schema
with the initial schema itself including all your changes. It will be useful to start server later or share between team mates.
graphql_faker
will be useful if you want to make quick experiments with API, to play around with schema design, or to implement most of the UI features without being blocked by backend implementation. You can even extend an existing API with custom queries. More cases could be found in readme
— https://github.com/APIs-guru/graphql-faker
JSGraphQL plugin
Let’s create .graphqlconfig
in project root with the next contents:
Save your changes and move to the “GraphQL” tab, double click on “Default” and select “Get Graph schema from Endpoint”
This will create new file in project root — my.schema.json
and fetch you API schema into.
JS GraphQL Plugin helps control errors and typos in queries. Also provides excellent code competition. It’s easy to check — create graphql folder inside the project root with an employee_data.graphql file inside. Try to type the next query by yourself to see the code completion in action.
Move back to the graphql_faker
editor(http://localhost:9002/editor/) and change the employee’s
field first_name
to first_name1
, press save and refresh the local schema — you’ll see the highlighted errors inside the file.
Flutter part
We will need two main packages — graphql_flutter
for working with GraphQL endpoints and artemis
for type generation.
Add next lines to your pubspec.yaml
file
Run `flutter packages get` in the terminal.
Artemis
We will start from artemis
setup (full manual available here — https://github.com/comigor/artemis)
Create file build.yaml in project root:
Launch type generation from terminal
pub run build_runner build
orflutter pub run build_runner build
After 10–20 seconds there will be 2 files generated:
- graphql_api.dart
- graphql_api.g.dart
graphql_flutter
Get back to the graphql_faker
editor(http://localhost:9002/editor/) on line 31 we have predefined query allCompanies
let’s try to display them in Listview
In the editor after line 14 add id: ID! @fake(type: uuid)
we will need this for correct caching.
Refresh local scheme.
Create file ./graphql/companies_data.graphql
Launch type generation one more time.
Create file /lib/graphql_provide.dart
In lib/main.dart
add host
function to substitute proper localhost
address depending on the platform
In the same file as before wrap the MaterialApp
widget with GraphqlProvider
Replace all body
contents in MaterialApp
with
Restart the app and you’ll see something similar
A few more details:
The Query
widget passes the operation specified in the documentNode
parameter as a request to the GraphQL endpoint.
builder
function has 3 standard parts
Error display
Loading indicator
Response data in ListView
Summary
After finishing my experiments, I’m happy to find that there are a lot of positive changes in the GraphQL ecosystem for flutter. As a result we get a fully functioning and pretty stable approach to work with GraphQL using full power of types and autocompletion.
All code as a single project available here — https://github.com/artflutter/graphql_toolchain
Support projects mentioned in this article with a star, detailed bug report or PR.
- https://github.com/flutter/flutter
- https://github.com/zino-app/graphql-flutter
- https://github.com/comigor/artemis
- https://github.com/jimkyndemeyer/js-graphql-intellij-plugin
Leave your favourite Dart libraries to work with GraphQL.
We are developing a local Flutter community in Ukraine «Art Flutter» — feel free to join.