Firebase Data Connect client SDKs let you call your server-side queries andmutations directly from a Firebase app. You generate a custom client SDK inparallel as you design the schemas, queries and mutations you deploy to yourData Connect service. Then, you integrate methods from this SDK intoyour client logic.

As we've mentioned elsewhere, it's important to note thatData Connectqueries and mutations are not submitted by client code and executed on theserver. Instead, when deployed,Data Connect operations are stored onthe server like Cloud Functions. This means you need to deploy correspondingclient-side changes to avoid breaking existing users (for example, on older appversions).

That's whyData Connect provides you with a developer environment andtooling that lets you prototype your server-deployed schemas, queries and mutations.It also generates client-side SDKs automatically, while you prototype.

When you've iterated updates to your service and client apps, both server- andclient-side updates are ready to deploy.

What is the client development workflow?

If you followed theGet started, you wereintroduced to the overall development flow forData Connect. In thisguide, you'll find more detailed information about generating Flutter SDKs fromyour schema and working with client queries and mutations.

To summarize, to use generated Flutter SDKs in your client apps, you'll followthese prerequisite steps:

1. Add Firebase to yourFlutter app.
2. Install the flutterfire CLIdart pub global activate flutterfire_cli.
3. Runflutterfire configure.

Then:

1. Develop your app schema.

2. Set up SDK generation:

   • With theAdd SDK to app button in our Data Connect VS Code extension
   • Byupdating yourconnector.yaml.

3. Initialize your client code and import libraries.

4. Implement calls to queries andmutations.

5. Set up and use theData Connect emulator anditerate.

Generate your Flutter SDK

Use theFirebase CLI to set upData Connect generated SDKs in your apps.Theinit command should detect all apps in the current folder and installgenerated SDKs automatically.

firebase init dataconnect:sdk

Update SDKs while prototyping

If you have Data Connect VS Code extension installed, it will always keep generatedSDKs up to date.

If you don't use Data Connect VS Code extension, you can use Firebase CLIto keep generated SDKs up to date.

firebasedataconnect:sdk:generate--watch

Generate SDKs in build pipelines

You can use the Firebase CLI to generate Data Connect SDKs in CI/CD build processes.

firebasedataconnect:sdk:generate

Set up client code

Initialize yourData Connect app

First, initialize your app using thestandard Firebase setup instructions.

Then, install theData Connect plugin:

flutterpubaddfirebase_data_connect

Initialize theData Connect Flutter SDK

Initialize yourData Connect instance using the information youused to set up Data Connect (all available in theFirebase consoleData Connect tab).

Import libraries

There are two sets of imports needed to initialize your client code, generalData Connect imports and specific, generated SDK imports.

// general importsimport'package:firebase_data_connect/firebase_data_connect.dart';// generated queries and mutations from SDKimport'generated/movies.dart';

Use queries on the client side

The generated code will already come with predefined Query Refs. All you needto do is import and callexecute on them.

import'generated/movies.dart';awaitMoviesConnector.instance.listMovies().execute();

Call SDK query methods

Here's an example using these action shortcut functions:

import'generated/movies.dart';functiononBtnClick(){// This will call the generated Dart from the CLI and then make an HTTP request to the server.MoviesConnector.instance.listMovies().execute().then(data=>showInUI(data));// == MoviesConnector.instance.listMovies().ref().execute();}

Optional fields

Some queries may have optional fields. In these cases, the Flutter SDK exposesa builder method, and will have to be set separately.

For example, the fieldrating is optional when callingcreateMovie, so youneed to provide it in the builder function.

awaitMoviesConnector.instance.createMovie({title:'Empire Strikes Back',releaseYear:1980,genre:"Sci-Fi"}).rating(5).execute();

Subscribe to changes

You can subscribe to changes (which will update any time you execute a query).

QueryRef<ListMoviesData,void>listRef=MoviesConnector.instance.listMovies().ref();// subscribe will immediately invoke the query if no execute was called on it previously.listRef.subscribe().listen((data){updateUIWithMovies(data.movies);});awaitMoviesConnector.instance.createMovie({title:'Empire Strikes Back',releaseYear:1980,genre:"Sci-Fi"}).rating(5).execute();awaitlistRef.execute();// will update the subscription above`

Handle changes to enumeration fields

An app's schema cancontain enumerations,which can be accessed by yourGraphQL queries.

As an app's design changes, you may add new enum supported values. For example,imagine that later in your application’s lifecycle you decide to add aFULLSCREEN value to theAspectRatio enum.

In theData Connect workflow, you can use local development tooling toupdate your queries and SDKs.

However, before you release an updated version of your clients, older deployedclients may break.

Example resilient implementation

The generated SDK forces handling of unknown values. That is, client code mustunwrap theEnumValue object into eitherKnown orUnknown.

finalresult=awaitMoviesConnector.instance.listMovies().execute();if(result.data!=null &&result.data!.isNotEmpty){handleEnumValue(result.data![0].aspectratio);}voidhandleEnumValue(EnumValue<AspectRatio>aspectValue){if(aspectValue.value!=null){switch(aspectValue.value!){caseAspectRatio.ACADEMY:print("This movie is in Academy aspect");break;caseAspectRatio.WIDESCREEN:print("This movie is in Widescreen aspect");break;caseAspectRatio.ANAMORPHIC:print("This movie is in Anamorphic aspect");break;caseAspectRatio.IMAX:print("This movie is in IMAX aspect");}}else{print("Unknown aspect ratio detected:${aspectValue.stringValue}");}}

Use mutations on the client side

Mutations are accessible in the same way as queries.

awaitMoviesConnector.instance.createMovie({title:'Empire Strikes Back',releaseYear:1980,genre:"Sci-Fi"}).rating(5).execute();

Prototype and test your Flutter apps

Instrument clients to use a local emulator

You can use theData Connect emulator, whether from theData Connect VS Code extension or from the CLI.

Instrumenting the app to connect to the emulator is the same for both scenarios.

import'package:firebase_data_connect/firebase_data_connect.dart';import'generated/movies.dart';MoviesConnector.instance.dataConnect.useDataConnectEmulator('127.0.0.1',9399);// Make calls from your appQueryRef<ListMoviesData,void>ref=MoviesConnector.instance.listMovies.ref();

To switch to production resources, comment out lines for connecting to theemulator.

Data types in the Dart SDK

TheData Connect server represents common GraphQL data types. Theseare represented in the SDK as follows.