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 à partir d'une application Firebase. Vous générez un SDK client personnalisé en parallèle lorsque vous concevez les schémas, les requêtes et les mutations que vous déployez sur votre service Data Connect. Vous devez ensuite intégrer les méthodes de ce SDK à votre logique client.

Comme nous l'avons indiqué 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 exécutées sur le serveur. Au lieu de cela, lors du déploiement, 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 créer des prototypes de 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 le prototypage.

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

Quel est le workflow de développement du client ?

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

Pour résumer, pour utiliser les SDK Web générés dans vos applications clientes, procédez comme suit:

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 de requêtes Tanstack.

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, React ou Angular.

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

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

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

Implémenter le code client avec le SDK JavaScript Firebase

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

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

Initialiser votre application

Tout d'abord, initialisez 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 travail sur le code client Firebase Data Connect se déroule dans un répertoire de projet local. L'extension VS Code Data Connect et la CLI Firebase sont tous deux des outils locaux importants pour générer et gérer le code client.

Les options de génération de SDK sont associées à plusieurs entrées dans le fichier dataconnect.yaml généré lorsque vous avez initialisé votre projet.

Initialiser la génération du SDK

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

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

package spécifie le nom du package.

packageJsonDir spécifie l'emplacement où installer le package.

Dans ce cas, installez firebase@latest pour vous assurer que cette dépendance d'appairage 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 de SDK générées spécifiques.

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 du SDK JavaScript

Le code généré est déjà fourni avec des références de requête prédéfinies. Il vous suffit d'importer et d'appeler l'exécution.

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 utilisant 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, commentez les lignes permettant de se connecter à l'émulateur.

Implémenter du code client pour React et Angular

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

Cette bibliothèque fournit un ensemble de crochets 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 Firebase de la requête TanStack

Installez les packages pour la requête TanStack dans votre projet.

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

ng add @angular/fire

Générer votre SDK React ou Angular

Comme pour le SDK Web standard, comme décrit plus tôt, les outils Firebase gèrent la génération automatique de 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.

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

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: importations générales Data Connect, importations générales TanStack et importations spécifiques pour vos SDK générés en JS et React.

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

// 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";

// 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 les méthodes du SDK généré.

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

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>
}

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 de rechargement automatique avec React et Angular

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

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 });
  }
}

// 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:

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);
  ...
}

// 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, commentez les lignes permettant de se connecter à l'émulateur.

Types de données dans le SDK

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

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

Configurer des chemins d'accès relatifs à node_modules

Pour le SDK JavaScript, comme Data Connect utilise npm link pour installer votre SDK, votre SDK généré doit être généré dans 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, votre 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 monorépertoire dans lequel vos modules sont hébergés à la racine, vous pouvez placer votre répertoire de sortie dans n'importe quel dossier de votre monorépertoire.

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

Mettre à jour les SDK lors du prototypage

Si vous effectuez un prototypage interactif avec l'extension Data Connect pour VS Code 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 qui définissent les schémas, les requêtes et les mutations. Cette fonctionnalité peut s'avérer utile dans les workflows de (re)chargement à chaud.

Vous pouvez également utiliser la CLI pour regénérer les SDK chaque fois que des fichiers .gql sont modifiés:

firebase dataconnect:sdk:generate --watch

Générer des SDK pour l'intégration et 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 la CLI Firebase pour une mise à jour par lot.

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