Usar SDKs da Web gerados

Com os SDKs do cliente do Firebase Data Connect, é possível chamar consultas e mutações do lado do servidor diretamente de um app do Firebase. Você gera um SDK do cliente personalizado em paralelo ao projetar os esquemas, consultas e mutações que serão implantados no serviço Data Connect. Em seguida, integre os métodos desse SDK à lógica do cliente.

Como mencionamos em outro lugar, é importante observar que as consultas e mutações Data Connect não são enviadas pelo código do cliente e executadas no servidor. Em vez disso, quando implantadas, as operações Data Connect são armazenadas no servidor, como o Cloud Functions. Isso significa que você precisa implantar as mudanças correspondentes do lado do cliente para evitar problemas com usuários existentes (por exemplo, em versões mais antigas do app).

Por isso, o Data Connect oferece um ambiente de desenvolvimento e ferramentas que permitem criar protótipos de esquemas, consultas e mutações implantados no servidor. Ele também gera SDKs do lado do cliente automaticamente enquanto você cria o protótipo.

Depois de iterar as atualizações nos apps de serviço e cliente, as atualizações do lado do servidor e do cliente estão prontas para implantação.

Implementar o código do cliente com o SDK JavaScript da Firebase

Esta seção aborda como implementar clientes usando o SDK JavaScript Firebase.

Se você estiver usando o React, consulte instruções de configuração alternativas e links para documentação sobre como gerar SDKs do React para Data Connect.

Inicializar o aplicativo

Primeiro, inicialize o app usando a sequência padrão do Firebase.

initializeApp({...});

Gerar o SDK do JavaScript

Como na maioria dos projetos do Firebase, o trabalho no código do cliente Firebase Data Connect acontece em um diretório de projeto local. A extensão do Data Connect para VS Code e a CLI Firebase são ferramentas locais importantes para gerar e gerenciar o código do cliente.

As opções de geração do SDK são vinculadas a várias entradas no arquivo dataconnect.yaml gerado quando você inicializou o projeto.

Inicializar a geração do SDK

No connector.yaml, adicione outputDir, package e (para o SDK da Web) packageJsonDir. 
generate:
  javascriptSdk:
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

outputDir especifica onde o SDK gerado precisa ser gerado.

package especifica o nome do pacote.

packageJsonDir especifica onde instalar o pacote.

Nesse caso, instale firebase@latest para garantir que essa dependência de peer seja atendida.

Inicializar o SDK do JavaScript

Inicialize sua instância do Data Connect usando as informações que você usou para configurar o Data Connect (todas disponíveis na guia "Data Connect" do console do Firebase).

O objeto ConnectorConfig

O SDK requer um objeto de configuração do conector.

Esse objeto é gerado automaticamente de serviceId e location em dataconnect.yaml e connectorId em connector.yaml.

Importar bibliotecas

Há dois conjuntos de importações necessários para inicializar o código do cliente: importações Data Connect gerais e importações específicas e geradas do SDK.

Observe o objeto ConnectorConfig incluído nas importações gerais.

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

Usar consultas do SDK do JavaScript

O código gerado já vem com referências de consulta predefinidas. Basta importar e chamar execute neles.

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

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

Chamar métodos de consulta do SDK

Confira um exemplo usando essas funções de atalho de ação:

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

Receber notificações sobre mudanças

Você pode se inscrever para receber notificações de mudanças, que são atualizadas sempre que você executa uma 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`

Usar mutações do SDK do JavaScript

As mutações podem ser acessadas da mesma forma que as consultas.

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

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

Conectar-se ao emulador do Data Connect

Se quiser, você pode se conectar ao emulador chamando connectDataConnectEmulator e transmitindo a instância Data Connect, assim:

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 alternar para recursos de produção, comente as linhas para se conectar ao emulador.

Implementar o código do cliente para React

O Firebase Data Connect fornece um SDK gerado com hooks para React usando uma biblioteca disponível dos nossos parceiros da Invertase, TanStack Query Firebase.

Essa biblioteca fornece um conjunto de hooks que facilitam muito o processamento de tarefas assimétricas com o Firebase nos seus aplicativos.

Inicializar o aplicativo

Primeiro, como em qualquer app da Web do Firebase, inicialize seu app usando a sequência padrão do Firebase.

initializeApp({...});

Instalar pacotes do Firebase da TanStack Query

Instale pacotes para a consulta TanStack no seu projeto.

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

Gerar o SDK do React

Assim como no SDK da Web padrão, conforme descrito anteriormente, as ferramentas do Firebase processam a geração automática de SDKs com base no esquema e nas operações.

Para gerar um SDK do React para seu projeto, adicione uma chave react ao arquivo de configuração connector.yaml.

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

Importar bibliotecas

Há quatro conjuntos de importações necessários para inicializar o código do cliente do React: importações gerais de Data Connect, importações gerais do TanStack e importações específicas para SDKs gerados por JS e React.

Observe o tipo ConnectorConfig incluído nas importações gerais.

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

Usar consultas e mutações no cliente React

Com a configuração concluída, é possível incorporar métodos do SDK do React gerado.

No snippet a seguir, observe o método useListAllMovies com prefixo use do SDK do React gerado. Todas essas operações use no SDK gerado, tanto consultas quanto mutações, chamam as vinculações de consulta da 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>
}

Conectar-se ao emulador do Data Connect

Se preferir, você pode se conectar ao emulador chamando connectDataConnectEmulator e transmitindo a instância Data Connect para o hook gerado, como este:

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 alternar para recursos de produção, comente as linhas para se conectar ao emulador.

Tipos de dados no SDK

O servidor Data Connect representa tipos de dados comuns do GraphQL. Elas são representadas no SDK da seguinte maneira.

Tipo de conexão de dados TypeScript
Carimbo de data/hora string
Data string
UUID string
Int64 string
Duplo Número
Ponto flutuante Número

Considerações especiais para a geração de SDKs

Configurar caminhos relativos a node_modules

Para o SDK JavaScript, como Data Connect usa npm link para instalar o SDK, o SDK gerado precisa ser gerado em um diretório no mesmo nível do caminho node_modules ou em um diretório filho que possa acessar node_modules.

Em outras palavras, o SDK gerado precisa ter acesso ao módulo de nó firebase para funcionar corretamente.

Por exemplo, se você tiver node_modules em my-app/, o diretório de saída precisa ser my-app/js-email-generated para que js-email-generated possa importar da pasta mãe 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"

Ou, se você tiver um monorepo em que seus módulos são hospedados na raiz, poderá colocar o diretório de saída em qualquer pasta no 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

Atualizar SDKs durante a prototipagem

Se você estiver criando protótipos interativos com a extensão do Data Connect para o VS Code e o emulador Data Connect, os arquivos de origem do SDK serão gerados e atualizados automaticamente enquanto você modifica arquivos .gql que definem esquemas, consultas e mutações. Esse pode ser um recurso útil em fluxos de trabalho de (re)carregamento em tempo real.

Em outros cenários, se você estiver usando o emulador Data Connect da CLI Firebase, poderá definir um monitoramento nas atualizações do .gql e também ter as origens do SDK atualizadas automaticamente.

Como alternativa, use a CLI para regenerar SDKs sempre que os arquivos .gql forem alterados:

firebase dataconnect:sdk:generate --watch

Gerar SDKs para integração e lançamentos de produção

Em alguns casos, como ao preparar fontes de projeto para envio para testes de CI, é possível chamar a CLI Firebase para uma atualização em lote.

Nesses casos, use firebase dataconnect:sdk:generate.

Outras considerações sobre frameworks

Angular

Ao gerar o código, o Angular CLI não vai detectar novas mudanças devido ao código de otimização de dependência. Para corrigir isso, você precisa modificar o angular.json.

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