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, as consultas e as mutações que implanta no seu serviço Data Connect. Em seguida, integre métodos desse SDK à lógica do cliente.

Como mencionamos em outro lugar, é importante observar que Data Connect consultas e mutações 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 falhas nos usuários atuais (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 protótipos.

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

Qual é o fluxo de trabalho de desenvolvimento do cliente?

Se você seguiu a seção Começar, conheceu o fluxo geral de desenvolvimento do Data Connect. Neste guia, você encontra informações mais detalhadas sobre como gerar SDKs da Web com base no esquema e trabalhar com consultas e mutações do cliente.

Aprenda desenvolvimento de clientes com um repositório de apps de início rápido e crie um app Data Connect completo seguindo nosso codelab para a Web.

Em resumo, para usar os SDKs da Web gerados nos apps cliente, siga estas etapas de pré-requisito:

1. Adicione o Firebase ao seu app da Web.

Depois, siga estas instruções:

1. Desenvolva o esquema do app.
2. Inicialize o código do cliente com o SDK JavaScript ou as bibliotecas React ou Angular.
3. Para React e Angular, instale os pacotes Tanstack Query.

4. Configure a geração de SDKs:

   • Com o botão Adicionar SDK ao app na extensão Data Connect do VS Code
   • Atualizando o connector.yaml para o SDK para JavaScript ou React ou Angular.

5. Importe bibliotecas e código gerado com o SDK JavaScript ou React ou Angular.

6. Implemente chamadas para consultas e mutações com o SDK JavaScript, ou React ou Angular.

7. Teste configurando o emulador Data Connect com o SDK JavaScript ou React ou Angular.

Implementar código do cliente com o SDK Firebase JavaScript

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

Se você estiver usando React ou Angular, consulte instruções de configuração alternativas e links para documentação adicional sobre geração de SDKs Data Connect para frameworks.

Inicializar o aplicativo

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

initializeApp({...});

Instalar o SDK JavaScript gerado

Use a CLI Firebase para configurar os SDKs gerados pelo Data Connect nos seus apps. O comando init detecta todos os apps na pasta atual e instala os SDKs gerados automaticamente.

firebase init dataconnect:sdk

Conecte o app ao serviço 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);

Atualizar SDKs durante a criação de protótipos

Se você tiver a extensão do Data Connect VS Code instalada, ela sempre manterá os SDKs gerados atualizados.

Se você não usa a extensão Data Connect do VS Code, pode usar a CLI do Firebase para manter os SDKs gerados atualizados.

firebase dataconnect:sdk:generate --watch

Gerar SDKs em pipelines de build

É possível usar a CLI do Firebase para gerar SDKs do Data Connect em processos de build de CI/CD.

firebase dataconnect:sdk:generate

Importar bibliotecas

Há dois conjuntos de importações necessários para inicializar o código do cliente: importações gerais de Data Connect 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 '@dataconnect/generated';

Usar consultas do SDK do JavaScript

O código gerado já vem com referências de consulta predefinidas. Basta importar e chamar a execução neles.

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

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

Inscrever-se para receber notificações sobre mudanças

Você pode se inscrever para receber atualizações (que serão enviadas sempre que você executar 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`

Processar mudanças em campos de enumeração

O esquema de um app pode conter enumerações, que podem ser acessadas pelas suas consultas GraphQL.

À medida que o design de um app muda, você pode adicionar novos valores compatíveis com enumeração. Por exemplo, imagine que, mais tarde no ciclo de vida do aplicativo, você decida adicionar um valor FULLSCREEN à enumeração AspectRatio.

No fluxo de trabalho do Data Connect, você pode usar ferramentas de desenvolvimento local para atualizar suas consultas e SDKs.

No entanto, antes de lançar uma versão atualizada dos clientes, os clientes implantados mais antigos podem falhar.

Exemplo de implementação resiliente

Sempre adicione uma ramificação default a uma instrução switch nos valores de enumeração ou uma ramificação else a um bloco if/else if comparando com os valores de enumeração. Isso não é aplicado pela linguagem JavaScript/TypeScript, mas é a maneira de tornar o código do cliente robusto caso novos valores de enumeração sejam adicionados.

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

Usar mutações do SDK do JavaScript

As mutações são acessíveis da mesma forma que as consultas.

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@dataconnect/generated';

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

Conectar-se ao emulador Data Connect

Se quiser, conecte-se ao emulador chamando connectDataConnectEmulator e transmitindo a instância Data Connect desta forma:

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 mudar para recursos de produção, comente as linhas de conexão com o emulador.

Observação: chamar getDataConnect só é necessário se você quiser se conectar ao emulador Data Connect. Caso contrário, o SDK gerado vai criar automaticamente uma instância do objeto DataConnect para você.

Implementar código do cliente para React e Angular

O Firebase Data Connect fornece um SDK gerado com hooks para React e Angular usando bibliotecas disponíveis dos nossos parceiros da Invertase, TanStack Query Firebase.

Essa biblioteca oferece um conjunto de hooks que facilitam muito o processamento de tarefas assíncronas com o Firebase nos seus aplicativos.

Inicializar o aplicativo

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

initializeApp({...});

Instalar pacotes do Firebase do TanStack Query

instale pacotes para TanStack Query no seu projeto.

Reagir

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

Gerar seu SDK do React ou Angular

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

Se você acabou de adicionar o React ou o Angular ao seu projeto, execute firebase init dataconnect:sdk novamente para reconfigurar os SDKs gerados e incluir as vinculações extras do framework.

Importar bibliotecas

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

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

Reagir

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

Usar consultas e mutações no cliente React ou Angular

Com a configuração concluída, você pode incorporar métodos do SDK gerado.

No snippet a seguir, observe o método com prefixo use useListAllMovies para React e o método com prefixo inject injectListAllMovies para Angular, ambos do SDK gerado.

Reagir

Todas essas operações no SDK gerado, consultas e mutações, chamam vinculações do TanStackQuery:

• As consultas chamam e retornam o hook useDataConnectQuery do TanStack.
• As mutações chamam e retornam o hook useDataConnectMutation do TanStack.

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

Observação: o ng add @angular/fire faz isso automaticamente, mas se você preferir configurar manualmente, use o seguinte 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;
  })
]

Usar consultas de recarregamento automático com React e Angular

É possível configurar as consultas para serem recarregadas automaticamente quando os dados mudarem.

Reagir

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

Conectar-se ao emulador Data Connect

Se quiser, conecte-se ao emulador chamando connectDataConnectEmulator e transmitindo a instância Data Connect ao hook gerado, assim:

Reagir

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 mudar para recursos de produção, comente as linhas de conexão com o emulador.

Observação: chamar getDataConnect só é necessário se você quiser se conectar ao emulador Data Connect. Caso contrário, o SDK gerado vai criar automaticamente uma instância do objeto DataConnect para você.

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

Atualizar SDKs durante a criação de protótipos

Se você tiver a extensão do Data Connect VS Code instalada, ela sempre manterá os SDKs gerados atualizados.

Se você não usa a extensão Data Connect do VS Code, pode usar a CLI do Firebase para manter os SDKs gerados atualizados.

firebase dataconnect:sdk:generate --watch

Gerar SDKs em pipelines de build

É possível usar a CLI do Firebase para gerar SDKs do Data Connect em processos de build de CI/CD.

firebase dataconnect:sdk:generate