Menggunakan SDK web yang dihasilkan

Dengan SDK klien Firebase Data Connect, Anda dapat memanggil kueri dan mutasi sisi server secara langsung dari aplikasi Firebase. Anda membuat SDK klien kustom secara paralel saat mendesain skema, kueri, dan mutasi yang di-deploy ke layanan Data Connect. Kemudian, Anda akan mengintegrasikan metode dari SDK ini ke dalam logika klien.

Seperti yang telah kami sebutkan di tempat lain, penting untuk diperhatikan bahwa kueri dan mutasi Data Connect tidak dikirim oleh kode klien dan dijalankan di server. Sebagai gantinya, saat di-deploy, operasi Data Connect disimpan di server seperti Cloud Functions. Artinya, Anda perlu men-deploy perubahan sisi klien yang sesuai untuk menghindari kerusakan pada pengguna yang ada (misalnya, pada versi aplikasi lama).

Itulah sebabnya Data Connect menyediakan lingkungan developer dan alat yang memungkinkan Anda membuat prototipe skema, kueri, dan mutasi yang di-deploy server. Alat ini juga membuat SDK sisi klien secara otomatis, saat Anda membuat prototipe.

Setelah Anda melakukan iterasi update pada aplikasi layanan dan klien, update sisi server dan sisi klien siap di-deploy.

Apa alur kerja pengembangan klien?

Jika mengikuti Memulai, Anda telah diberi tahu tentang keseluruhan alur pengembangan untuk Data Connect. Dalam panduan ini, Anda akan menemukan informasi yang lebih mendetail tentang cara membuat Web SDK dari skema dan menggunakan kueri dan mutasi klien.

Untuk meringkas, guna menggunakan Web SDK yang dihasilkan di aplikasi klien, Anda harus mengikuti langkah-langkah prasyarat berikut:

1. Tambahkan Firebase ke aplikasi web Anda.

Kemudian:

1. Kembangkan skema aplikasi Anda.
2. Lakukan inisialisasi kode klien Anda dengan JavaScript SDK, atau library React atau Angular.
3. Untuk React dan Angular, instal paket Kueri Tanstack

4. Siapkan pembuatan SDK:

   • Dengan tombol Tambahkan SDK ke aplikasi di ekstensi VS Code Data Connect kami
   • Dengan mengupdate connector.yaml untuk JavaScript SDK, atau React atau Angular.

5. Mengimpor library dan kode yang dihasilkan dengan JavaScript SDK, atau React atau Angular.

6. Terapkan panggilan ke kueri dan mutasi dengan JavaScript SDK, atau React atau Angular.

7. Uji, dengan menyiapkan emulator Data Connect dengan JavaScript SDK, atau React atau Angular.

Mengimplementasikan kode klien dengan Firebase JavaScript SDK

Bagian ini membahas cara menerapkan klien menggunakan Firebase JavaScript SDK.

Jika Anda menggunakan React atau Angular, lihat petunjuk penyiapan alternatif dan link ke dokumentasi tambahan tentang membuat Data Connect SDK untuk framework.

Inisialisasi aplikasi Anda

Pertama, lakukan inisialisasi aplikasi menggunakan urutan Firebase standar.

initializeApp({...});

Membuat JavaScript SDK

Seperti sebagian besar project Firebase, pekerjaan pada kode klien Firebase Data Connect Anda dilakukan di direktori project lokal. Ekstensi VS Code Data Connect dan CLI Firebase adalah alat lokal penting untuk membuat dan mengelola kode klien.

Opsi pembuatan SDK diberi kunci ke beberapa entri dalam file dataconnect.yaml yang dibuat saat Anda melakukan inisialisasi project.

Melakukan inisialisasi pembuatan SDK

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

outputDir menentukan tempat output SDK yang dihasilkan.

package menentukan nama paket.

packageJsonDir menentukan tempat untuk menginstal paket.

Dalam hal ini, instal firebase@latest untuk memastikan dependensi peer ini terpenuhi.

Melakukan inisialisasi JavaScript SDK

Lakukan inisialisasi instance Data Connect menggunakan informasi yang Anda gunakan untuk menyiapkan Data Connect (semua tersedia di tab Data Connect konsol Firebase).

Objek ConnectorConfig

SDK memerlukan objek konfigurasi konektor.

Objek ini dibuat secara otomatis dari serviceId dan location di dataconnect.yaml, dan connectorId di connector.yaml.

Mengimpor library

Ada dua kumpulan impor yang diperlukan untuk melakukan inisialisasi kode klien: impor Data Connect umum dan impor SDK tertentu yang dihasilkan.

Perhatikan objek ConnectorConfig yang disertakan dalam impor umum.

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

Menggunakan kueri dari JavaScript SDK

Kode yang dihasilkan akan sudah dilengkapi dengan Referensi Kueri yang telah ditentukan. Yang perlu Anda lakukan adalah mengimpor dan memanggil eksekusi pada model tersebut.

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

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

Memanggil metode kueri SDK

Berikut adalah contoh penggunaan fungsi pintasan tindakan ini:

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

Berlangganan perubahan

Anda dapat berlangganan perubahan (yang akan diperbarui setiap kali Anda menjalankan kueri).

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`

Menggunakan mutasi dari JavaScript SDK

Mutasi dapat diakses dengan cara yang sama seperti kueri.

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

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

Menghubungkan ke emulator Data Connect

Atau, Anda dapat terhubung ke emulator dengan memanggil connectDataConnectEmulator, lalu meneruskan instance Data Connect, seperti ini:

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

Untuk beralih ke resource produksi, komentari baris untuk terhubung ke emulator.

Mengimplementasikan kode klien untuk React dan Angular

Firebase Data Connect menyediakan SDK yang dihasilkan dengan hook untuk React dan Angular menggunakan library yang tersedia dari partner kami di Invertase, TanStack Query Firebase.

Library ini menyediakan serangkaian hook yang sangat memudahkan penanganan tugas asinkron dengan Firebase di aplikasi Anda.

Inisialisasi aplikasi Anda

Pertama, seperti aplikasi web Firebase lainnya, lakukan inisialisasi aplikasi menggunakan urutan Firebase standar.

initializeApp({...});

Menginstal paket Firebase Kueri TanStack

instal paket untuk Kueri TanStack di project Anda.

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

Membuat SDK React atau Angular

Seperti halnya SDK web standar, seperti yang dijelaskan sebelumnya, alat Firebase menangani pembuatan SDK secara otomatis berdasarkan skema dan operasi Anda.

Untuk membuat React SDK untuk project Anda, tambahkan kunci react ke file konfigurasi 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: "../../"

Mengimpor library

Ada empat kumpulan impor yang diperlukan untuk melakukan inisialisasi kode klien React atau Angular: impor Data Connect umum, impor TanStack umum, dan impor khusus untuk SDK yang dihasilkan JS dan React.

Perhatikan jenis ConnectorConfig yang disertakan dalam impor umum.

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

Menggunakan kueri dan mutasi di klien React atau Angular

Setelah penyiapan selesai, Anda dapat menggabungkan metode dari SDK yang dihasilkan.

Dalam cuplikan berikut, perhatikan metode useListAllMovies dengan awalan use untuk React dan metode injectListAllMovies dengan awalan inject untuk Angular, keduanya dari SDK yang dihasilkan.

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

Menggunakan kueri muat ulang otomatis dengan React dan Angular

Anda dapat mengonfigurasi kueri agar otomatis dimuat ulang saat data berubah.

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

Menghubungkan ke emulator Data Connect

Secara opsional, Anda dapat terhubung ke emulator dengan memanggil connectDataConnectEmulator, lalu meneruskan instance Data Connect ke hook yang dihasilkan, seperti ini:

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

Untuk beralih ke resource produksi, komentari baris untuk terhubung ke emulator.

Jenis data di SDK

Server Data Connect mewakili jenis data GraphQL umum. Hal ini diwakili dalam SDK sebagai berikut.

Pertimbangan khusus untuk pembuatan SDK

Mengonfigurasi jalur yang relatif terhadap node_modules

Untuk JavaScript SDK, karena Data Connect menggunakan npm link untuk menginstal SDK, SDK yang dihasilkan harus menghasilkan output ke direktori pada level yang sama dengan jalur node_modules atau di direktori turunan yang dapat mengakses node_modules.

Dengan kata lain, SDK yang dihasilkan harus memiliki akses ke modul node firebase agar dapat berfungsi dengan benar.

Misalnya, jika Anda memiliki node_modules di my-app/, direktori output Anda harus my-app/js-email-generated sehingga js-email-generated dapat mengimpor dari folder node_modules induknya.

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"

Atau, jika Anda memiliki monorepo tempat modul dihosting di root, Anda dapat menempatkan direktori output di folder mana pun di 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

Mengupdate SDK saat membuat prototipe

Jika Anda membuat prototipe secara interaktif dengan ekstensi Data Connect VS Code dan emulator Data Connect-nya, file sumber SDK akan otomatis dibuat dan diperbarui saat Anda mengubah file .gql yang menentukan skema, kueri, dan mutasi. Hal ini dapat menjadi fitur yang berguna dalam alur kerja pemuatan ulang (hot reload).

Atau, Anda dapat menggunakan CLI untuk membuat ulang SDK setiap kali file .gql diubah:

firebase dataconnect:sdk:generate --watch

Membuat SDK untuk integrasi dan untuk rilis produksi

Dalam beberapa skenario, seperti menyiapkan sumber project untuk dikirimkan ke pengujian CI, Anda dapat memanggil Firebase CLI untuk update batch.

Dalam kasus ini, gunakan firebase dataconnect:sdk:generate.