Usa SDKs web generados

Los SDKs cliente de Firebase Data Connect te permiten llamar a tus consultas y mutaciones del servidor directamente desde una app de Firebase. Generas un SDK cliente personalizado en paralelo a medida que diseñas los esquemas, las consultas y las mutaciones que implementas en tu servicio de Data Connect. Luego, integra los métodos de este SDK en la lógica de tu cliente.

Como ya mencionamos en otro lugar, es importante tener en cuenta que el código del cliente no envía las consultas ni las mutaciones, sino que se ejecutan en el servidor.Data Connect En cambio, cuando se implementan, las operaciones Data Connect se almacenan en el servidor, como Cloud Functions. Esto significa que debes implementar los cambios correspondientes del cliente para evitar que se interrumpa la experiencia de los usuarios existentes (por ejemplo, en versiones anteriores de la app).

Por eso, Data Connect te proporciona un entorno de desarrollo y herramientas que te permiten crear prototipos de tus esquemas, consultas y mutaciones implementados en el servidor. También genera automáticamente SDKs del cliente mientras creas prototipos.

Cuando hayas iterado las actualizaciones de tus apps de servicio y cliente, las actualizaciones del servidor y del cliente estarán listas para implementarse.

¿Cuál es el flujo de trabajo de desarrollo del cliente?

Si seguiste la sección Comienza ahora, se te presentó el flujo de desarrollo general de Data Connect. En esta guía, encontrarás información más detallada para generar SDKs web a partir de tu esquema y trabajar con consultas y mutaciones del cliente.

En resumen, para usar los SDK web generados en tus apps cliente, deberás seguir estos pasos previos:

1. Agrega Firebase a tu app web.

Luego, haz lo siguiente:

1. Desarrolla el esquema de tu app.
2. Inicializa tu código de cliente con el SDK de JavaScript o las bibliotecas de React o Angular.
3. Para React y Angular, instala los paquetes de Tanstack Query

4. Configura la generación del SDK:

   • Con el botón Add SDK to app en nuestra extensión Data Connect de VS Code
   • Actualiza tu connector.yaml para el SDK de JavaScript, React o Angular.

5. Importa bibliotecas y código generado con el SDK de JavaScript, o bien React o Angular.

6. Implementa llamadas a consultas y mutaciones con el SDK de JavaScript, React o Angular.

7. Configura el emulador de Data Connect con el SDK de JavaScript, React o Angular para realizar pruebas.

Implementa código de cliente con el SDK de Firebase JavaScript

En esta sección, se explica cómo puedes implementar clientes con el SDK de Firebase JavaScript.

Si usas React o Angular, consulta las instrucciones de configuración alternativas y los vínculos a documentación adicional sobre la generación de SDKs de Data Connect para frameworks.

Inicializa tu app

Primero, inicializa tu app con la secuencia estándar de Firebase.

initializeApp({...});

Genera tu SDK de JavaScript

Al igual que con la mayoría de los proyectos de Firebase, el trabajo en el código del cliente de Firebase Data Connect se realiza en un directorio del proyecto local. Tanto la extensión Data Connect de VS Code como la CLI de Firebase son herramientas locales importantes para generar y administrar código de cliente.

Las opciones de generación del SDK se basan en varias entradas del archivo dataconnect.yaml que se generó cuando inicializaste tu proyecto.

Inicializa la generación del SDK

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

outputDir especifica dónde se debe generar el SDK.

package especifica el nombre del paquete.

packageJsonDir especifica dónde instalar el paquete.

En este caso, instala firebase@latest para asegurarte de que se cumpla esta dependencia de elementos del mismo nivel.

Inicializa el SDK de JavaScript

Inicializa tu instancia de Data Connect con la información que usaste para configurar Data Connect (toda la información está disponible en la pestaña Data Connect de la consola de Firebase).

El objeto ConnectorConfig

El SDK requiere un objeto de configuración del conector.

Este objeto se genera automáticamente a partir de serviceId y location en dataconnect.yaml, y connectorId en connector.yaml.

Importa las bibliotecas

Se necesitan dos conjuntos de importaciones para inicializar tu código de cliente: importaciones generales de Data Connect e importaciones específicas del SDK generado.

Observa el objeto ConnectorConfig incluido en las importaciones generales.

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

Usa consultas desde el SDK de JavaScript

El código generado ya incluirá referencias de consulta predefinidas. Lo único que debes hacer es importarlos y llamar a execute en ellos.

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

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

Llama a los métodos de consulta del SDK

A continuación, se muestra un ejemplo en el que se usan estas funciones de acceso directo a acciones:

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

Suscríbete a los cambios

Puedes suscribirte a los cambios (que se actualizarán cada vez que ejecutes una búsqueda).

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`

Usa mutaciones del SDK de JavaScript

Se puede acceder a las mutaciones de la misma manera que a las consultas.

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

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

Conéctate al emulador de Data Connect

De manera opcional, puedes conectarte al emulador llamando a connectDataConnectEmulator y, luego, pasando la instancia de Data Connect, de la siguiente manera:

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

Para cambiar a los recursos de producción, comenta las líneas para conectarte al emulador.

Implementa código del cliente para React y Angular

Firebase Data Connect proporciona un SDK generado con hooks para React y Angular que usa bibliotecas disponibles de nuestros socios de Invertase, TanStack Query Firebase.

Esta biblioteca proporciona un conjunto de hooks que facilitan en gran medida el manejo de tareas asíncronas con Firebase en tus aplicaciones.

Inicializa tu app

Primero, como con cualquier app web de Firebase, inicializa tu app con la secuencia estándar de Firebase.

initializeApp({...});

Instala los paquetes de TanStack Query Firebase

Instala los paquetes para TanStack Query en tu proyecto.

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

Genera tu SDK de React o Angular

Al igual que con el SDK web estándar, como se describió anteriormente, las herramientas de Firebase controlan la generación automática de SDKs según tu esquema y tus operaciones.

Para generar un SDK de React para tu proyecto, agrega una clave react a tu archivo de configuración 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: "../../"

Importa las bibliotecas

Hay cuatro conjuntos de importaciones necesarios para inicializar el código del cliente de React o Angular: importaciones generales de Data Connect, importaciones generales de TanStack y las importaciones específicas para tus SDKs generados en JS y React.

Observa el tipo ConnectorConfig incluido en las importaciones generales.

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

Usa consultas y mutaciones en tu cliente de React o Angular

Una vez que se complete la configuración, podrás incorporar métodos del SDK generado.

En el siguiente fragmento, observa el método useListAllMovies con el prefijo use para React y el método injectListAllMovies con el prefijo inject para Angular, ambos del SDK generado.

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

Usa consultas de recarga automática con React y Angular

Puedes configurar las consultas para que se vuelvan a cargar automáticamente cuando cambien los datos.

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

Conéctate al emulador de Data Connect

De manera opcional, puedes conectarte al emulador llamando a connectDataConnectEmulator y, luego, pasando la instancia de Data Connect al hook generado, de la siguiente manera:

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

Para cambiar a los recursos de producción, comenta las líneas para conectarte al emulador.

Tipos de datos en el SDK

El servidor Data Connect representa tipos de datos comunes de GraphQL. Estos se representan en el SDK de la siguiente manera.

Consideraciones especiales para la generación del SDK

Configura rutas de acceso relativas a node_modules

En el caso del SDK de JavaScript, como Data Connect usa npm link para instalar tu SDK, el SDK generado debe enviarse a un directorio en el mismo nivel que tu ruta de acceso node_modules o en un directorio secundario que pueda acceder a node_modules.

En otras palabras, el SDK generado debe tener acceso al módulo de nodo firebase para funcionar correctamente.

Por ejemplo, si tienes tu node_modules en my-app/, tu directorio de salida debe ser my-app/js-email-generated para que js-email-generated pueda importar desde su carpeta principal 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"

O bien, si tienes un monorepo en el que tus módulos están alojados en la raíz, puedes colocar tu directorio de salida en cualquier carpeta del 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

Actualiza los SDKs mientras creas prototipos

Si prototipas de forma interactiva con la extensión Data Connect de VS Code y su emulador Data Connect, los archivos fuente del SDK se generan y actualizan automáticamente mientras modificas los archivos .gql que definen esquemas, consultas y mutaciones. Esta puede ser una función útil en los flujos de trabajo de recarga (en caliente).

Como alternativa, puedes usar la CLI para volver a generar los SDKs cada vez que se cambien los archivos .gql:

firebase dataconnect:sdk:generate --watch

Genera SDKs para la integración y para las versiones de producción

En algunos casos, como cuando preparas fuentes de proyectos para enviarlas a pruebas de CI, puedes llamar a la CLI de Firebase para realizar una actualización por lotes.

En estos casos, usa firebase dataconnect:sdk:generate.