Usar SDKs da Web gerados

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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.

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ê vai encontrar informações mais detalhadas sobre como gerar SDKs da Web a partir do seu esquema e trabalhar com consultas e mutações do cliente.

Para resumir, siga estas etapas de pré-requisito para usar os SDKs da Web gerados nos seus apps clientes:

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 do JavaScript ou as bibliotecas React ou Angular.
3. Para React e Angular, instale os pacotes de consulta da Tanstack

4. Configurar a geração de SDK:

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

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

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

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

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

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

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

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

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

ng add @angular/fire

Gerar seu SDK do React ou do 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 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: "../../"

generate:
  javascriptSdk:
    angular: 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 React ou Angular: importações gerais de Data Connect, importações gerais do TanStack e importações específicas para os SDKs gerados pelo JS e pelo 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";

// 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, é possível 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.

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

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 recarga automática com React e Angular

É possível configurar consultas para que sejam recarregadas automaticamente quando os dados mudarem.

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

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

class AppComponent() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

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

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 de forma interativa 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.

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.