Usa SDKs web generados

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

Como mencionamos en otro lugar, es importante tener en cuenta que el código de cliente no envía las Data Connect consultas y mutaciones, y que estas no se ejecutan en el servidor. 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 interrumpir a 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 SDKs de cliente automáticamente mientras creas prototipos.

Cuando hayas iterado las actualizaciones de tu servicio y tus apps de 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 guía de inicio, se te presentó el flujo de desarrollo general de Data Connect. En esta guía, encontrarás información más detallada sobre la generación de SDKs web a partir de tu esquema y el trabajo con consultas y mutaciones del cliente.

Puedes aprender el desarrollo del cliente con un repositorio de apps de inicio rápido y compilar una app con todas las funciones Data Connect siguiendo nuestro codelab para la Web.

En resumen, para usar los SDKs web generados en tus apps de cliente, debes seguir estos pasos previos:

1. Agrega Firebase a tu app web.

Luego:

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 de Data Connect VS Code
   • Actualizando tu connector.yaml para el SDK de JavaScript, o React o Angular.

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

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

7. Prueba configurando el Data Connect emulador con el SDK de JavaScript o React o Angular.

Implementa código de cliente con el Firebase JavaScript SDK

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

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

Inicializa tu app

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

initializeApp({...});

Instala el SDK de JavaScript generado

Usa el Firebase CLI para configurar los Data Connect generados SDKs en tus apps. El comando init debería detectar todas las apps en la carpeta actual y, luego, instalar los SDKs generados automáticamente.

firebase init dataconnect:sdk

Conecta tu app al servicio de Data Connect.

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
// [Optionally] Configure the SDK to use Data Connect local emulator.
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

Actualiza los SDKs mientras creas prototipos

Si tienes instalada la extensión de Data Connect VS Code, siempre mantendrá actualizados los SDKs generados.

Si no usas la extensión de Data Connect VS Code, puedes usar Firebase CLI para mantener actualizados los SDKs generados.

firebase dataconnect:sdk:generate --watch

Genera SDKs en canalizaciones de compilación

Puedes usar Firebase CLI para generar Data Connect SDKs en procesos de compilación de CI/CD.

firebase dataconnect:sdk:generate

Importa las bibliotecas

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

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 '@dataconnect/generated';

Nota: Los SDKs de cliente de JavaScript generados usan los mismos nombres para las interfaces y operaciones que los SDKs de administrador de Node.js generados. Asegúrate de importar la biblioteca correcta para tu plataforma. Si necesitas usar ambas bibliotecas en el mismo archivo, usa un alias de importación o una importación con espacio de nombres para una o ambas bibliotecas.

import { listMovies as adminListMovies } from '@dataconnect/admin-generated';
Or:
import * as Admin from '@dataconnect/admin-generated';

Usa consultas del SDK de JavaScript

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

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@dataconnect/generated';

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 la acción:

import { listMovies } from '@dataconnect/generated';
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 consulta).

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`

Controla los cambios en los campos de enumeración

El esquema de una app puede contener enumeraciones, a las que pueden acceder tus consultas de GraphQL.

A medida que cambia el diseño de una app, puedes agregar nuevos valores admitidos de enum. Por ejemplo, imagina que, más adelante en el ciclo de vida de tu aplicación, decides agregar un valor FULLSCREEN a la enumeración AspectRatio.

En el flujo de trabajo Data Connect, puedes usar herramientas de desarrollo local para actualizar tus consultas y SDKs.

Sin embargo, antes de lanzar una versión actualizada de tus clientes, es posible que los clientes implementados más antiguos se interrumpan.

Ejemplo de implementación resistente

Siempre agrega una rama default a una instrucción switch sobre los valores de enum o una rama else a un bloque if/else if que se compare con los valores de enum. El lenguaje JavaScript/TypeScript no aplica esto, pero es la forma de hacer que el código de cliente sea sólido en caso de que se agreguen valores de enum nuevos.

const queryResult = await getOldestMovie();

if (queryResult.data) {
  // we can use a switch statement's "default" case to check for unexpected values
  const oldestMovieAspectRatio = queryResult.data.originalAspectRatio;
  switch (oldestMovieAspectRatio) {
      case AspectRatio.ACADEMY:
      case AspectRatio.WIDESCREEN:
      case AspectRatio.ANAMORPHIC:
        console.log('This movie was filmed in Academy, widescreen or anamorphic aspect ratio!');
        break;
      default:
        // the default case will catch FULLSCREEN, UNAVAILABLE or _UNKNOWN
        // it will also catch unexpected values the SDK isn't aware of, such as CINEMASCOPE
        console.log('This movie was was NOT filmed in Academy, widescreen or anamorphic.');
        break;
  }

  // alternatively, we can check to see if the returned enum value is a known value
  if (!Object.values(AspectRatio).includes(oldestMovieAspectRatio)) {
    console.log(`Unrecognized aspect ratio: ${oldestAspectRatio}`);
  }
} else {
  console.log("no movies found!");
}

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 '@dataconnect/generated';

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

Conéctate al emulador 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 '@dataconnect/generated';

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.

Nota: Solo se requiere llamar a getDataConnect si deseas conectarte al Data Connect emulador. De lo contrario, el SDK generado creará automáticamente una instancia del objeto DataConnect por ti.

Implementa código de cliente para React y Angular

Firebase Data Connect proporciona un SDK generado con hooks para React y Angular con bibliotecas disponibles de nuestros socios en 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 paquetes para TanStack Query en tu proyecto.

Reaccionar

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

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 en función de tu esquema y tus operaciones.

Si acabas de agregar React o Angular a tu proyecto, vuelve a ejecutar firebase init dataconnect:sdk para volver a configurar los SDKs generados de modo que incluyan las vinculaciones de framework adicionales.

Importa las bibliotecas

Se necesitan cuatro conjuntos de importaciones para inicializar tu código de cliente de React o Angular: importaciones generales de Data Connect, importaciones generales de TanStack, e importaciones específicas para tus SDKs generados de JS y React.

Observa el tipo ConnectorConfig incluido en las importaciones generales.

Reaccionar

// 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 '@dataconnect/generated';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@dataconnect/generated/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 '@dataconnect/generated';

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

Usa consultas y mutaciones en tu cliente de React o Angular

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

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

Reaccionar

Todas estas operaciones en el SDK generado, tanto las consultas como las mutaciones, llaman a las vinculaciones de TanStackQuery:

• Las consultas llaman y muestran elhook useDataConnectQueryde TanStack
• Las mutaciones llaman y muestran el hook useDataConnectMutation deTanStack.

import { useListAllMovies } from '@dataconnect/generated/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

Nota: ng add @angular/fire lo hará automáticamente por ti, pero si decides configurarlo de forma manual, puedes hacerlo con el siguiente código:

import { injectAllMovies, connectorConfig } from '@dataconnect/generated/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.

Reaccionar

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

Conéctate al emulador Data Connect

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

Reaccionar

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';
import { useListAllMovies } from '@dataconnect/generated/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;
}),

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

Nota: Solo se requiere llamar a getDataConnect si deseas conectarte al Data Connect emulador. De lo contrario, el SDK generado creará automáticamente una instancia del objeto DataConnect por ti.

Habilita el almacenamiento en caché del cliente

Data Connect tiene una función opcional de almacenamiento en caché del cliente, que puedes habilitar editando el archivo connector.yaml. Cuando esta función está habilitada, los SDKs de cliente generados almacenan en caché de forma local las respuestas de las consultas, lo que puede reducir la cantidad de solicitudes de base de datos que realiza tu app y permite que las partes de la app que dependen de la base de datos funcionen cuando se interrumpe la disponibilidad de la red.

Desarrolladores de React, Next.js y Angular: Los SDKs de React y Angular de Data Connect controlan el almacenamiento en caché con las bibliotecas de TanStack, que no son compatibles con la función de almacenamiento en caché nativa de Data Connect. Si usas React o Angular, te recomendamos que no habilites el almacenamiento en caché como se describe en esta sección y, en su lugar, sigas usando la capacidad que proporciona TanStack.

Para habilitar el almacenamiento en caché del cliente, agrega una configuración de almacenamiento en caché del cliente a la configuración de tu conector:

generate:
  javascriptSdk:
    outputDir: ../web/
    package: "@dataconnect/generated"
    clientCache:
      maxAge: 5s
      storage: memory

Esta configuración tiene dos parámetros, ambos opcionales:

• maxAge: Es la antigüedad máxima que puede tener una respuesta almacenada en caché antes de que el SDK de cliente recupere valores nuevos. Ejemplos: "0", "30s", "1h30m".

  El valor predeterminado de maxAge es 0, lo que significa que las respuestas se almacenan en caché, pero el SDK de cliente siempre recuperará valores nuevos. Los valores almacenados en caché solo se usarán cuando se especifique CACHE_ONLY en executeQuery() y el resultado inicial que se muestra de subscribe().

• storage: El SDK de cliente se puede configurar para almacenar en caché las respuestas en el almacenamiento persistent o en la memory. Los resultados almacenados en caché en el almacenamiento persistent se conservarán entre los reinicios de la app. En los SDKs web, solo se admite el almacenamiento memory.

Después de actualizar la configuración de almacenamiento en caché de tu conector, vuelve a generar tus SDKs de cliente y vuelve a compilar tu app. Una vez que lo hagas, executeQuery() y subscribe() almacenarán en caché las respuestas y usarán los valores almacenados en caché según la política que configuraste. Por lo general, esto sucede automáticamente, sin que tengas que realizar ningún paso adicional. Sin embargo, ten en cuenta lo siguiente:

• El comportamiento predeterminado de executeQuery() es el que se describió anteriormente: si se almacena en caché un resultado para una consulta y el valor almacenado en caché no es más antiguo que maxAge, usa el valor almacenado en caché. Este comportamiento predeterminado se denomina política PREFER_CACHE.

  También puedes especificar invocaciones individuales de executeQuery() para que solo entreguen valores almacenados en caché (CACHE_ONLY) o para recuperar de forma incondicional valores nuevos del servidor (SERVER_ONLY).

  await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
  

  await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
  

• Cuando llamas a subscribe(), siempre mostrará de inmediato el contenido almacenado en caché si existe, independientemente de la configuración de maxAge. Las llamadas posteriores a executeQuery() notificarán a los objetos de escucha según el maxAge configurado.

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.

Data Connect Tipo	TypeScript
Marca de tiempo	string
Fecha	string
UUID	string
Int64	string
Doble	Número
Número de punto flotante	Número

Actualiza los SDKs mientras creas prototipos

Si tienes instalada la extensión de Data Connect VS Code, siempre mantendrá actualizados los SDKs generados.

Si no usas la extensión de Data Connect VS Code, puedes usar Firebase CLI para mantener actualizados los SDKs generados.

firebase dataconnect:sdk:generate --watch

Genera SDKs en canalizaciones de compilación

Puedes usar Firebase CLI para generar Data Connect SDKs en procesos de compilación de CI/CD.

firebase dataconnect:sdk:generate