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 as consultas e mutações não são enviadas pelo código do cliente e executadas no servidor.Data Connect 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 os Primeiros passos, 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 seu esquema e trabalhar com consultas e mutações do cliente.

Você pode aprender desenvolvimento de clientes com um repositório de apps de início rápido e criar 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({...});

Gerar o SDK 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 VS Code e a CLI Firebase são ferramentas locais importantes para gerar e gerenciar código do cliente.

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

Inicializar a geração de SDK

No seu 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 deve ser exibido.

package especifica o nome do pacote.

packageJsonDir especifica onde instalar o pacote.

Observação: para geração, adicionamos "firebase": "^10.14.0" como um peerDependency. Dependendo do gerenciador de dependências (por exemplo, pnpm), essas dependências podem não ser instaladas automaticamente.

Nesse caso, instale firebase@latest para garantir que essa dependência de mesmo nível seja atendida.

Inicializar o SDK do JavaScript

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

O objeto ConnectorConfig

O SDK exige 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árias 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 '@myorg/myconnector';

Usar consultas do SDK 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 '@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);
}

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`

Usar mutações do SDK JavaScript

As mutações são acessíveis 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 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 '@myorg/myconnector'; // Replace with your package name

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 anteriormente, as ferramentas do Firebase processam a geração automática de SDKs com base no seu esquema e nas suas operações.

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

Reagir

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

Angular

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

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 '@myorg/myconnector';

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

// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@myorg/connector/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 useListAllMovies com prefixo use para React e o método injectListAllMovies com prefixo inject 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 '@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>
}

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

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

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

Considerações especiais para geração de SDK

Configurar caminhos relativos a node_modules

Para o SDK JavaScript, como o Data Connect usa o npm link para instalar seu SDK, o SDK gerado precisa ser enviado para 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 precisará ser my-app/js-email-generated para que js-email-generated possa importar da pasta pai 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 os módulos estão hospedados na raiz, coloque o diretório de saída em qualquer pasta do 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

Observação: é possível fornecer um caminho absoluto para diretórios se o projeto estiver configurado em uma estrutura de diretório separada.

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

Se você estiver criando protótipos interativamente com a extensão Data Connect do VS Code e o emulador Data Connect, os arquivos de origem do SDK serão gerados e atualizados automaticamente enquanto você modifica os arquivos .gql que definem esquemas, consultas e mutações. Esse pode ser um recurso útil em fluxos de trabalho de recarga (automática) dinâmica.

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 fontes do SDK atualizadas automaticamente.

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

firebase dataconnect:sdk:generate --watch

Gerar SDKs para integração e para versões de produção

Em alguns casos, como ao preparar fontes de projetos para enviar para testes de CI, você pode chamar a CLI Firebase para uma atualização em lote.

Nesses casos, use firebase dataconnect:sdk:generate.