Utiliser les SDK Web générés

Les SDK client Firebase Data Connect vous permettent d'appeler vos requêtes et mutations côté serveur directement depuis une application Firebase. Vous générez un SDK client personnalisé en parallèle de la conception des schémas, des requêtes et des mutations que vous déployez sur votre service Firebase Data Connect.Data Connect Ensuite, vous intégrez les méthodes de ce SDK dans votre logique client.

Comme nous l'avons mentionné ailleurs, il est important de noter que les requêtes et les mutations Data Connect ne sont pas envoyées par le code client et ne sont pas exécutées sur le serveur. En revanche, une fois déployées, les opérations Data Connect sont stockées sur le serveur, comme Cloud Functions. Cela signifie que vous devez déployer les modifications côté client correspondantes pour éviter de perturber les utilisateurs existants (par exemple, sur les anciennes versions de l'application).

C'est pourquoi Data Connect vous fournit un environnement de développement et des outils qui vous permettent de prototyper vos schémas, requêtes et mutations déployés sur le serveur. Il génère également automatiquement des SDK côté client pendant que vous créez votre prototype.

Une fois que vous avez effectué des mises à jour itératives de vos applications de service et client, les mises à jour côté serveur et côté client sont prêtes à être déployées.

Qu'est-ce que le workflow de développement client ?

Si vous avez suivi la section Premiers pas, vous avez découvert le flux de développement global pour Data Connect. Ce guide fournit des informations plus détaillées sur la génération de SDK Web à partir de votre schéma, ainsi que sur l'utilisation des requêtes et mutations client.

Vous pouvez apprendre à développer des clients avec un dépôt d'application de démarrage rapide et créer une application Data Connect complète en suivant notre atelier de programmation pour le Web.

En résumé, pour utiliser les SDK Web générés dans vos applications clientes, vous devez suivre les étapes préalables suivantes :

1. Ajoutez Firebase à votre application Web.

Puis :

1. Développez le schéma de votre application.
2. Initialisez votre code client avec le SDK JavaScript ou les bibliothèques React ou Angular.
3. Pour React et Angular, installez les packages Tanstack Query.

4. Configurez la génération du SDK :

   • Avec le bouton Ajouter le SDK à l'application de notre extension VS Code Data Connect
   • En mettant à jour votre connector.yaml pour le SDK JavaScript, ou React ou Angular.

5. Importez des bibliothèques et du code généré avec le SDK JavaScript, React ou Angular.

6. Implémentez des appels aux requêtes et aux mutations avec le SDK JavaScript, React ou Angular.

7. Testez en configurant l'émulateur Data Connect avec le SDK JavaScript, ou React ou Angular.

Implémenter le code client avec le SDK Firebase JavaScript

Cette section explique comment implémenter des clients à l'aide du SDK Firebase JavaScript.

Si vous utilisez React ou Angular, consultez les autres instructions de configuration et les liens vers la documentation supplémentaire sur la génération de SDK Data Connect pour les frameworks.

Initialiser votre application

Commencez par initialiser votre application à l'aide de la séquence Firebase standard.

initializeApp({...});

Générer votre SDK JavaScript

Comme pour la plupart des projets Firebase, le code client Firebase Data Connect est développé dans un répertoire de projet local. L'extension VS Code Data Connect et la CLI Firebase sont des outils locaux importants pour générer et gérer le code client.

Les options de génération du SDK sont associées à plusieurs entrées du fichier dataconnect.yaml généré lors de l'initialisation de votre projet.

Initialiser la génération du SDK

Dans votre connector.yaml, ajoutez vos outputDir, package et (pour le SDK Web) packageJsonDir.

generate:
  javascriptSdk:
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

outputDir indique l'emplacement où le SDK généré doit être placé.

package spécifie le nom du package.

packageJsonDir indique où installer le package.

Remarque : Pour la génération, nous ajoutons "firebase": "^10.14.0" en tant que peerDependency. Selon votre gestionnaire de dépendances (par exemple, pnpm), il est possible que ces dépendances ne soient pas installées automatiquement.

Dans ce cas, installez firebase@latest pour vous assurer que cette dépendance de pair est satisfaite.

Initialiser le SDK JavaScript

Initialisez votre instance Data Connect à l'aide des informations que vous avez utilisées pour configurer Data Connect (toutes disponibles dans l'onglet "Data Connect" de la console Firebase).

Objet ConnectorConfig

Le SDK nécessite un objet de configuration du connecteur.

Cet objet est généré automatiquement à partir de serviceId et location dans dataconnect.yaml, et de connectorId dans connector.yaml.

Importer des bibliothèques

Deux ensembles d'importations sont nécessaires pour initialiser votre code client : les importations générales Data Connect et les importations spécifiques du SDK généré.

Notez l'objet ConnectorConfig inclus dans les importations générales.

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// generated queries and mutations from SDK
import { listMovies, ListMoviesResponse, createMovie, connectorConfig } from '@myorg/myconnector';

Utiliser des requêtes à partir du SDK JavaScript

Le code généré inclura déjà des références de requête prédéfinies. Il vous suffit de les importer et d'appeler "execute" sur eux.

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@movie-app/movies';

const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);

Appeler les méthodes de requête du SDK

Voici un exemple d'utilisation de ces fonctions de raccourci d'action :

import { listMovies } from '@movie-app/movies';
function onBtnClick() {
// This will call the generated JS from the CLI and then make an HTTP request out
// to the server.
  listMovies().then(data => showInUI(data)); // == executeQuery(listMoviesRef);
}

S'abonner aux modifications

Vous pouvez vous abonner aux modifications (qui seront mises à jour chaque fois que vous exécuterez une requête).

const listRef = listAllMoviesRef();

// subscribe will immediately invoke the query if no execute was called on it previously.
subscribe(listRef, ({ data }) => {
 updateUIWithMovies(data.movies);
});

await createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi", rating: 5 });\
await listMovies(); // will update the subscription above`

Utiliser des mutations à partir du SDK JavaScript

Les mutations sont accessibles de la même manière que les requêtes.

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@movie-app/movies';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

Se connecter à l'émulateur Data Connect

Vous pouvez éventuellement vous connecter à l'émulateur en appelant connectDataConnectEmulator, puis en transmettant l'instance Data Connect, comme suit :

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@myorg/myconnector'; // Replace with your package name

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);`

// Make calls from your app

Pour passer aux ressources de production, mettez en commentaire les lignes de connexion à l'émulateur.

Remarque : L'appel de getDataConnect n'est requis que si vous souhaitez vous connecter à l'émulateur Data Connect. Sinon, le SDK généré créera automatiquement une instance de l'objet DataConnect pour vous.

Implémenter le code client pour React et Angular

Firebase Data Connect fournit un SDK généré avec des hooks pour React et Angular à l'aide des bibliothèques disponibles auprès de nos partenaires chez Invertase, TanStack Query Firebase.

Cette bibliothèque fournit un ensemble de hooks qui facilitent grandement la gestion des tâches asynchrones avec Firebase dans vos applications.

Initialiser votre application

Tout d'abord, comme pour toute application Web Firebase, initialisez votre application à l'aide de la séquence Firebase standard.

initializeApp({...});

Installer les packages TanStack Query Firebase

Installez les packages pour TanStack Query dans votre projet.

React

npm i --save @tanstack/react-query @tanstack-query-firebase/react
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0

Angular

ng add @angular/fire

Générer votre SDK React ou Angular

Comme pour le SDK Web standard décrit plus haut, les outils Firebase gèrent la génération automatique des SDK en fonction de votre schéma et de vos opérations.

Pour générer un SDK React pour votre projet, ajoutez une clé react à votre fichier de configuration connector.yaml.

React

generate:
  javascriptSdk:
    react: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

Angular

generate:
  javascriptSdk:
    angular: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

Importer des bibliothèques

Quatre ensembles d'importations sont nécessaires pour initialiser votre code client React ou Angular : les importations générales Data Connect, les importations TanStack générales et les importations spécifiques pour vos SDK JS et React générés.

Notez le type ConnectorConfig inclus dans les importations générales.

React

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@myorg/myconnector';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@myorg/connector/react";

Angular

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@myorg/myconnector';

// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@myorg/connector/angular";

Utiliser des requêtes et des mutations dans votre client React ou Angular

Une fois la configuration terminée, vous pouvez intégrer des méthodes à partir du SDK généré.

Dans l'extrait suivant, notez la méthode préfixée par use, useListAllMovies, pour React et la méthode préfixée par inject, injectListAllMovies, pour Angular, toutes deux issues du SDK généré.

React

Toutes les opérations de ce type dans le SDK généré, qu'il s'agisse de requêtes ou de mutations, appellent les liaisons TanStackQuery :

• Les requêtes appellent et renvoient lehook useDataConnectQuery TanStack.
• Les mutations appellent et renvoient le hook TanStack useDataConnectMutation.

import { useListAllMovies } from '@movies-app/movies/react';

function MyComponent() {
  const { isLoading, data, error } = useListAllMovies();
  if(isLoading) {
    return <div>Loading...</div>
  }
  if(error) {
    return <div> An Error Occurred: {error} </div>
  }
}

// App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import MyComponent from './my-component';

function App() {
  const queryClient = new QueryClient();
  return <QueryClientProvider client={queryClient}>
    <MyComponent />
  </QueryClientProvider>
}

Angular

Remarque : ng add @angular/fire le fera automatiquement pour vous, mais si vous choisissez de le configurer manuellement, vous pouvez le faire avec le code suivant :

import { injectAllMovies, connectorConfig } from '@movies-app/movies/angular';
import { provideDataConnect, getDataConnect } from '@angular/fire/data-connect';
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";
const queryClient = new QueryClient();
...
providers: [
  ...
  provideTanStackQuery(queryClient),
  provideDataConnect(() => {
    const dc = getDataConnect(connectorConfig);
    return dc;
  })
]

Utiliser des requêtes d'actualisation automatique avec React et Angular

Vous pouvez configurer les requêtes pour qu'elles se rechargent automatiquement lorsque les données changent.

React

export class MovieListComponent {
  movies = useListAllMovies();
}

export class AddPostComponent {
  const mutation = useCreateMovie({ invalidate: [listAllMoviesRef()] });
  addMovie() {
    // The following will automatically cause Tanstack to reload its listAllMovies query
    mutation.mutate({ title: 'The Matrix });
  }
}

Angular

// class
export class MovieListComponent {
  movies = injectListAllMovies();
}

// template
@if (movies.isPending()) {
    Loading...
}
@if (movies.error()) {
    An error has occurred: {{  movies.error() }}
}
@if (movies.data(); as data) {
    @for (movie of data.movies; track movie.id) {
    <mat-card appearance="outlined">
        <mat-card-content>{{movie.description}}</mat-card-content>
    </mat-card>
    } @empty {
        <h2>No items!</h2>
    }
}

Se connecter à l'émulateur Data Connect

Vous pouvez éventuellement vous connecter à l'émulateur en appelant connectDataConnectEmulator, puis en transmettant l'instance Data Connect à votre hook généré, comme suit :

React

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@movies-app/movies';
import { useListAllMovies } from '@movies-app/movies/react';

const dc = getDataConnect(connectorConfig);
connectDataConnectEmulator(dc, 'localhost', 9399);

class AppComponent() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

Angular

// app.config.ts
import { provideDataConnect } from '@angular/fire/data-connect';
import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
provideDataConnect(() => {
  const dc = getDataConnect(connectorConfig);
  connectDataConnectEmulator(dc, 'localhost', 9399);
  return dc;
}),

Pour passer aux ressources de production, mettez en commentaire les lignes de connexion à l'émulateur.

Remarque : L'appel de getDataConnect n'est requis que si vous souhaitez vous connecter à l'émulateur Data Connect. Sinon, le SDK généré créera automatiquement une instance de l'objet DataConnect pour vous.

Types de données dans le SDK

Le serveur Data Connect représente les types de données GraphQL courants. Elles sont représentées dans le SDK comme suit.

Type de connexion de données	TypeScript
Horodatage	chaîne
Date	chaîne
UUID	chaîne
Int64	chaîne
Double	Nombre
Float	Nombre

Considérations particulières pour la génération de SDK

Configurer des chemins d'accès relatifs à node_modules

Pour le SDK JavaScript, étant donné que Data Connect utilise npm link pour installer votre SDK, votre SDK généré doit être envoyé vers un répertoire au même niveau que votre chemin d'accès node_modules ou dans un répertoire enfant pouvant accéder à node_modules.

En d'autres termes, le SDK généré doit avoir accès au module de nœud firebase pour fonctionner correctement.

Par exemple, si votre node_modules se trouve dans my-app/, votre répertoire de sortie doit être my-app/js-email-generated afin que js-email-generated puisse importer à partir de son dossier parent node_modules.

my-app/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  js-email-generated/

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@myapp/my-connector"

Si vous disposez d'un monorepo où vos modules sont hébergés à la racine, vous pouvez placer votre répertoire de sortie dans n'importe quel dossier de votre monorepo.

my-monorepo/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  my-app/
    js-email-generated/
  package.json

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../my-app/js-email-generated" # You can also output to ../../js-email-generated

Remarque : Vous pouvez fournir un chemin d'accès absolu aux répertoires si votre projet est configuré dans une structure de répertoire distincte.

Mettre à jour les SDK lors du prototypage

Si vous créez des prototypes de manière interactive avec l'extension VS Code Data Connect et son émulateur Data Connect, les fichiers sources du SDK sont automatiquement générés et mis à jour lorsque vous modifiez les fichiers .gql définissant les schémas, les requêtes et les mutations. Cette fonctionnalité peut être utile dans les workflows de rechargement à chaud.

Dans d'autres scénarios, si vous utilisez l'émulateur Data Connect à partir de l'interface de ligne de commande Firebase, vous pouvez définir une surveillance des mises à jour .gql et faire en sorte que les sources du SDK soient également mises à jour automatiquement.

Vous pouvez également utiliser l'interface de ligne de commande pour régénérer les SDK chaque fois que des fichiers .gql sont modifiés :

firebase dataconnect:sdk:generate --watch

Générez des SDK pour l'intégration et pour les versions de production.

Dans certains cas, par exemple lorsque vous préparez des sources de projet à envoyer pour des tests CI, vous pouvez appeler l'interface de ligne de commande Firebase pour une mise à jour par lot.

Dans ce cas, utilisez firebase dataconnect:sdk:generate.