생성된 웹 SDK 사용

Firebase Data Connect 클라이언트 SDK를 사용하면 Firebase 앱에서 직접 서버 측 쿼리와 변형을 호출할 수 있습니다. Data Connect 서비스에 배포하는 스키마, 쿼리, 변형을 설계할 때 동시에 맞춤 클라이언트 SDK를 생성합니다. 그런 다음 이 SDK의 메서드를 클라이언트 로직에 통합합니다.

다른 곳에서 언급했듯이 Data Connect 쿼리 및 변형은 클라이언트 코드에서 제출되지 않으며 서버에서 실행됩니다. 대신 배포 시 Data Connect 작업은 Cloud Functions와 같이 서버에 저장됩니다. 즉, 기존 사용자를 손상시키지 않도록 (예: 이전 앱 버전) 상응하는 클라이언트 측 변경사항을 배포해야 합니다.

그렇기 때문에 Data Connect는 서버에 배포된 스키마, 쿼리, 변형의 프로토타입을 만들 수 있는 개발자 환경과 도구를 제공합니다. 또한 프로토타입을 만드는 동안 클라이언트 측 SDK를 자동으로 생성합니다.

서비스 및 클라이언트 앱 업데이트를 반복한 후에는 서버 측 업데이트와 클라이언트 측 업데이트를 모두 배포할 수 있습니다.

클라이언트 개발 워크플로는 무엇인가요?

시작하기를 따랐다면 Data Connect의 전반적인 개발 흐름을 알아봤습니다. 이 가이드에서는 스키마에서 웹 SDK를 생성하고 클라이언트 쿼리 및 변형을 사용하는 방법에 관한 자세한 내용을 확인할 수 있습니다.

빠른 시작 앱 저장소로 클라이언트 개발을 학습하고 웹용 Codelab에 따라 모든 기능을 갖춘 Data Connect 앱을 빌드할 수 있습니다.

요약하자면 클라이언트 앱에서 생성된 웹 SDK를 사용하려면 다음과 같은 기본 단계를 따르세요.

1. 웹 앱에 Firebase를 추가합니다.

그리고 나서 다음 안내를 따르세요.

1. 앱 스키마를 개발합니다.
2. JavaScript SDK, React 또는 Angular 라이브러리로 클라이언트 코드를 초기화합니다.
3. React 및 Angular의 경우 Tanstack 쿼리 패키지를 설치합니다.

4. SDK 생성 설정:

   • Data Connect VS Code 확장 프로그램의 앱에 SDK 추가 버튼을 사용합니다.
   • JavaScript SDK, React 또는 Angular의 connector.yaml를 업데이트합니다.

5. JavaScript SDK, React 또는 Angular를 사용하여 라이브러리와 생성된 코드를 가져옵니다.

6. JavaScript SDK, React 또는 Angular를 사용하여 쿼리 및 변형 호출을 구현합니다.

7. JavaScript SDK, React 또는 Angular로 Data Connect 에뮬레이터를 설정하여 테스트합니다.

Firebase JavaScript SDK로 클라이언트 코드 구현

이 섹션에서는 Firebase JavaScript SDK를 사용하여 클라이언트를 구현하는 방법을 설명합니다.

React 또는 Angular를 사용하는 경우 대체 설정 안내와 프레임워크용 Data Connect SDK 생성에 관한 추가 문서 링크를 참고하세요.

앱 초기화

먼저 표준 Firebase 시퀀스를 사용하여 앱을 초기화합니다.

initializeApp({...});

JavaScript SDK 생성

대부분의 Firebase 프로젝트와 마찬가지로 Firebase Data Connect 클라이언트 코드 작업은 로컬 프로젝트 디렉터리에서 이루어집니다. Data Connect VS Code 확장 프로그램과 Firebase CLI는 모두 클라이언트 코드를 생성하고 관리하는 데 중요한 로컬 도구입니다.

SDK 생성 옵션은 프로젝트를 초기화할 때 생성된 dataconnect.yaml 파일의 여러 항목에 키가 지정됩니다.

SDK 생성 초기화

connector.yaml에서 outputDir, package, 웹 SDK의 경우 packageJsonDir를 추가합니다.

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

outputDir는 생성된 SDK를 출력할 위치를 지정합니다.

package은 패키지 이름을 지정합니다.

packageJsonDir은 패키지를 설치할 위치를 지정합니다.

참고: 생성의 경우 "firebase": "^10.14.0"를 peerDependency로 추가합니다. 종속 항목 관리자 (예: pnpm)에 따라 이러한 종속 항목이 자동으로 설치되지 않을 수 있습니다.

이 경우 firebase@latest를 설치하여 이 피어 종속 항목이 충족되도록 합니다.

JavaScript SDK 초기화

Data Connect를 설정하는 데 사용한 정보를 사용하여 Data Connect 인스턴스를 초기화합니다 (Firebase 콘솔의 Data Connect 탭에서 모두 사용 가능).

ConnectorConfig 객체

SDK에는 커넥터 구성 객체가 필요합니다.

이 객체는 dataconnect.yaml의 serviceId 및 location, connector.yaml의 connectorId에서 자동으로 생성됩니다.

라이브러리 가져오기

클라이언트 코드를 초기화하는 데 필요한 두 가지 가져오기 세트가 있습니다. 일반 Data Connect 가져오기와 생성된 특정 SDK 가져오기입니다.

일반 가져오기에 포함된 ConnectorConfig 객체를 확인합니다.

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

JavaScript SDK의 쿼리 사용

생성된 코드에는 사전 정의된 쿼리 참조가 이미 포함되어 있습니다. 가져와서 실행을 호출하기만 하면 됩니다.

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

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

SDK 쿼리 메서드 호출

다음은 이러한 작업 바로가기 함수를 사용하는 예입니다.

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

변경사항 구독

변경사항을 구독할 수 있으며, 변경사항은 쿼리를 실행할 때마다 업데이트됩니다.

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`

JavaScript SDK의 변형 사용

변형은 쿼리와 동일한 방식으로 액세스할 수 있습니다.

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

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

Data Connect 에뮬레이터에 연결

원하는 경우 다음과 같이 connectDataConnectEmulator를 호출한 다음 Data Connect 인스턴스를 전달하여 에뮬레이터에 연결할 수 있습니다.

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

프로덕션 리소스로 전환하려면 에뮬레이터에 연결하는 선을 주석 처리합니다.

참고: getDataConnect를 호출하는 것은 Data Connect 에뮬레이터에 연결하려는 경우에만 필요합니다. 그러지 않으면 생성된 SDK가 DataConnect 객체의 인스턴스를 자동으로 만듭니다.

React 및 Angular용 클라이언트 코드 구현

Firebase Data Connect는 Google의 파트너인 Invertase의 라이브러리인 TanStack Query Firebase를 사용하여 React 및 Angular용 후크가 있는 생성된 SDK를 제공합니다.

이 라이브러리는 애플리케이션에서 Firebase를 사용하여 비동기 작업을 훨씬 쉽게 처리할 수 있는 일련의 후크를 제공합니다.

앱 초기화

먼저 다른 Firebase 웹 앱과 마찬가지로 표준 Firebase 시퀀스를 사용하여 앱을 초기화합니다.

initializeApp({...});

TanStack Query Firebase 패키지 설치

프로젝트에 TanStack 쿼리용 패키지를 설치합니다.

ReactAngular

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

React 또는 Angular SDK 생성

앞서 설명한 것처럼 표준 웹 SDK와 마찬가지로 Firebase 도구는 스키마 및 작업을 기반으로 SDK 자동 생성을 처리합니다.

프로젝트의 React SDK를 생성하려면 connector.yaml 구성 파일에 react 키를 추가합니다.

ReactAngular

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

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

라이브러리 가져오기

React 또는 Angular 클라이언트 코드를 초기화하는 데 필요한 가져오기 세트는 네 가지입니다. 일반 Data Connect 가져오기, 일반 TanStack 가져오기, JS 및 React 생성 SDK의 특정 가져오기입니다.

일반 가져오기에 포함된 ConnectorConfig 유형을 참고하세요.

ReactAngular

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

React 또는 Angular 클라이언트에서 쿼리 및 변형 사용

설정이 완료되면 생성된 SDK의 메서드를 통합할 수 있습니다.

다음 스니펫에서 생성된 SDK의 React용 use 접두사 메서드 useListAllMovies와 Angular용 inject 접두사 메서드 injectListAllMovies를 확인할 수 있습니다.

ReactAngular

생성된 SDK의 이러한 모든 작업(쿼리 및 변형 모두)은 TanStackQuery 바인딩을 호출합니다.

• 쿼리가 TanStack useDataConnectQuery 후크를 호출하고 반환합니다.
• 변형이 TanStack useDataConnectMutation 후크를 호출하고 반환합니다.

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

참고: ng add @angular/fire가 자동으로 이 작업을 실행하지만 수동으로 설정하려면 다음 코드를 사용하면 됩니다.

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

React 및 Angular에서 자동 새로고침 쿼리 사용

데이터가 변경될 때 자동으로 새로고침되도록 쿼리를 구성할 수 있습니다.

ReactAngular

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

Data Connect 에뮬레이터에 연결

원하는 경우 connectDataConnectEmulator를 호출한 다음 생성된 후크에 Data Connect 인스턴스를 전달하여 에뮬레이터에 연결할 수 있습니다.

React Angular

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

프로덕션 리소스로 전환하려면 에뮬레이터에 연결하는 선을 주석 처리합니다.

참고: getDataConnect를 호출하는 것은 Data Connect 에뮬레이터에 연결하려는 경우에만 필요합니다. 그러지 않으면 생성된 SDK가 DataConnect 객체의 인스턴스를 자동으로 만듭니다.

SDK의 데이터 유형

Data Connect 서버는 일반적인 GraphQL 데이터 유형을 나타냅니다. 이는 SDK에서 다음과 같이 표현됩니다.

데이터 연결 유형	TypeScript
타임스탬프	문자열
날짜	문자열
UUID	문자열
Int64	문자열
Double	숫자
부동 소수점 수	숫자

SDK 생성에 관한 특별 고려사항

node_modules를 기준으로 경로 구성

JavaScript SDK의 경우 Data Connect가 npm link를 사용하여 SDK를 설치하므로 생성된 SDK는 node_modules 경로와 동일한 수준의 디렉터리 또는 node_modules에 액세스할 수 있는 하위 디렉터리에 출력되어야 합니다.

즉, 생성된 SDK가 제대로 작동하려면 firebase 노드 모듈에 액세스할 수 있어야 합니다.

예를 들어 my-app/에 node_modules가 있는 경우 js-email-generated가 상위 node_modules 폴더에서 가져올 수 있도록 출력 디렉터리는 my-app/js-email-generated여야 합니다.

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"

또는 모듈이 루트에 호스팅되는 모노레포가 있는 경우 모노레포의 폴더에 출력 디렉터리를 배치할 수 있습니다.

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

참고: 프로젝트가 별도의 디렉터리 구조로 설정된 경우 디렉터리의 절대 경로를 제공할 수 있습니다.

프로토타입 제작 중에 SDK 업데이트

Data Connect VS Code 확장 프로그램 및 Data Connect 에뮬레이터로 대화형으로 프로토타입을 제작하는 경우 스키마, 쿼리, 변형을 정의하는 .gql 파일을 수정하는 동안 SDK 소스 파일이 자동으로 생성되고 업데이트됩니다. 이 기능은 핫 (재)로드 워크플로에 유용할 수 있습니다.

다른 시나리오에서는 Firebase CLI에서 Data Connect 에뮬레이터를 사용하는 경우 .gql 업데이트에 워치를 설정하고 SDK 소스를 자동으로 업데이트할 수 있습니다.

또는 .gql 파일이 변경될 때마다 CLI를 사용하여 SDK를 다시 생성할 수 있습니다.

firebase dataconnect:sdk:generate --watch

통합 및 프로덕션 출시용 SDK 생성

CI 테스트를 위해 제출할 프로젝트 소스를 준비하는 등의 시나리오에서는 Firebase CLI를 호출하여 일괄 업데이트할 수 있습니다.

이러한 경우에는 firebase dataconnect:sdk:generate를 사용합니다.