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, integras los 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 cliente no envía las consultas ni las mutaciones de Data Connect, y que estas se ejecutan en el servidor. En cambio, cuando se implementan, las operaciones de Data Connect se almacenan en el servidor como Cloud Functions. Esto significa que debes implementar los cambios correspondientes del cliente para evitar que se produzcan errores en los usuarios existentes (por ejemplo, en versiones anteriores de la app).

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

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

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

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

Si usas React, consulta las instrucciones de configuración alternativas y los vínculos a documentación adicional sobre cómo generar SDKs de React para Data Connect.

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 cliente de Firebase Data Connect se realiza en un directorio de proyecto local. Tanto la extensión de VS Code de Data Connect como la CLI de Firebase son herramientas locales importantes para generar y administrar código de cliente.

Las opciones de generación de SDKs se vinculan a varias entradas del archivo dataconnect.yaml generado cuando inicializaste tu proyecto.

Inicializa la generación de SDK

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

outputDir especifica dónde se debe generar el SDK generado.

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 pares.

Inicializa el SDK de JavaScript

Inicializa tu instancia de Data Connect con la información que usaste para configurar Data Connect (todo 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

Hay dos conjuntos de importaciones necesarias para inicializar tu código cliente: las importaciones generales de Data Connect y las importaciones específicas y generadas del SDK.

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 del SDK de JavaScript

El código generado ya vendrá con referencias de consulta predefinidas. Solo debes importar y llamar a la ejecución 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

Este es un ejemplo en el que se usan estas funciones de acceso directo a la acción:

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

Usa mutaciones desde el 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' }));

Cómo conectarse 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 el código del cliente para React

Firebase Data Connect proporciona un SDK generado con hooks para React mediante una biblioteca disponible de nuestros socios de Invertase, TanStack Query Firebase.

Esta biblioteca proporciona un conjunto de hooks que facilitan enormemente el manejo de tareas asincrónicas 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 Firebase de TanStack Query

Instala 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

Genera tu SDK de React

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

Importa las bibliotecas

Existen cuatro conjuntos de importaciones necesarias para inicializar tu código cliente de React: importaciones generales de Data Connect, importaciones generales de TanStack y específicas importaciones para tus SDKs generados por 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";

Usa consultas y mutaciones en tu cliente de React

Cuando se complete la configuración, podrás incorporar métodos del SDK de React generado.

En el siguiente fragmento, observa el método useListAllMovies con el prefijo use del SDK de React generado. Todas esas operaciones use en el SDK generado, tanto las consultas como las mutaciones, llaman a las vinculaciones de consulta de TanStack:

• Consulta la llamada y muestra el hook useDataConnectQuery de TanStack.
• Las mutaciones llaman y devuelven el hook useDataConnectMutation de TanStack.

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

Cómo conectarse al emulador de Data Connect

De manera opcional, puedes conectarte al emulador llamando a connectDataConnectEmulator y, luego, pasando la instancia de Data Connect a tu 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);

function App() {
  ...
  const { isLoading, data, error } = useListAllMovies(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 de SDK

Configura rutas de acceso en relación con node_modules

En el caso del SDK de JavaScript, como Data Connect usa npm link para instalar tu SDK, el SDK generado debe generarse en un directorio al 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 nodos 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 superior 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 se alojan en la raíz, puedes colocar el directorio de salida en cualquier carpeta de tu 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 estás creando prototipos de forma interactiva con la extensión de VS Code de Data Connect 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 (re)carga 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 las fuentes de un proyecto 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.

Otras consideraciones sobre los frameworks

Angular

Cuando se genera código, Angular CLI no detectará cambios nuevos debido a su código de optimización de dependencias. Para solucionar este problema, deberás modificar tu angular.json.

  "projects": {
    "myproject": {
      "architect": {
        "serve:": {
          "prebundle": {
            "exclude": ["@movie-app/movies"]
          }
        }
      }
    }
  }