TanStack DB Svelte 어댑터

설치

npm install @tanstack/svelte-db

Svelte 유틸리티

Svelte 어댑터에서 사용할 수 있는 전체 유틸리티 목록은 Svelte 함수 참조를 확인합니다.

쿼리 작성(필터링, 조인, 집계 등)에 관한 종합적인 문서는 Live Queries Guide를 참조할 수 있습니다.

기본 사용법

DbProvider

브라우저 앱마다 하나의 DbClient를 사용하고, 서버 요청마다 하나씩 사용합니다. DbProvider 쿼리가 해당 클라이언트에 대해 컬렉션 설명자를 확인하도록 합니다:

<script lang="ts">
  import { DbClient, DbProvider } from '@tanstack/svelte-db'
  import App from './App.svelte'

  const client = new DbClient()
</script>

<DbProvider {client}>
  <App />
</DbProvider>

서버 사전 로드, 탈수화 및 스냅샷 전달에 대해서는 SSR 및 하이드레이션을 확인합니다.

useLiveQuery

useLiveQuery 유틸리티는 데이터가 변경될 때 컴포넌트를 자동으로 업데이트하는 라이브 쿼리를 생성합니다. Svelte 5 룬으로 구동되는 반응형 값을 반환합니다:

<script>
  import { useLiveQuery } from '@tanstack/svelte-db'
  import { eq } from '@tanstack/db'

  const query = useLiveQuery({
    query: (q) =>
      q.from({ todos: todosCollection })
       .where(({ todos }) => eq(todos.completed, false))
       .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  })
</script>

{#if query.isLoading}
  <div>Loading...</div>
{:else}
  <ul>
    {#each query.data as todo (todo.id)}
      <li>{todo.text}</li>
    {/each}
  </ul>
{/if}

참고: Svelte 5에서 useLiveQuery는 getter를 통해 반응형 값을 반환합니다. query.data 및 query.isLoading에 직접 액세스합니다(더 이상 $ 접두사가 필요하지 않음).

useLiveInfiniteQuery

라이브 업데이트가 포함된 정렬 및 페이지 매김 데이터를 사용하려면 useLiveInfiniteQuery을 사용합니다:

<script>
  import { useLiveInfiniteQuery } from '@tanstack/svelte-db'
  import { eq } from '@tanstack/db'

  let category = $state('news')
  const query = useLiveInfiniteQuery(
    (q) =>
      q
        .from({ posts: postsCollection })
        .where(({ posts }) => eq(posts.category, category))
        .orderBy(({ posts }) => posts.createdAt, 'desc'),
    { pageSize: 20 },
    [() => category],
  )
</script>

{#each query.data as post (post.id)}
  <article>{post.title}</article>
{/each}

{#if query.hasNextPage}
  <button
    disabled={query.isFetchingNextPage}
    onclick={() => query.fetchNextPage()}
  >
    Load more
  </button>
{/if}

fetchNextPage()는 페이지 요청이 완료된 후 해결되는 프로미스를 반환합니다. 오류는 query.error을 통해 노출되며 프로미스를 거부하지 않습니다.

쿼리에는 orderBy가 포함되어야 합니다. 종속성 배열은 쿼리 함수 형식에서만 사용할 수 있습니다. 정렬된 사전 생성 라이브 쿼리 컬렉션을 직접 전달할 수도 있습니다.

쿼리 식별성

useLiveQuery는 구조화된 쿼리 IR에서 ID를 파생합니다. 또한 Svelte는 쿼리를 작성하는 동안 읽은 반응형 값을 추적하므로 일반 빌더 쿼리에는 종속성 배열이나 queryKey가 필요하지 않습니다.

캡처된 props와 상태는 파생된 ID의 일부가 됩니다:

<script>
  import { useLiveQuery } from '@tanstack/svelte-db'
  import { gt } from '@tanstack/db'

  let { minPriority } = $props()

  const query = useLiveQuery({
    query: (q) =>
      q.from({ todos: todosCollection })
       .where(({ todos }) => gt(todos.priority, minPriority))
  })
</script>

<div>{query.data.length} high-priority todos</div>

파생된 ID가 변경되면:

이전 라이브 쿼리 컬렉션이 정리됩니다
업데이트된 값으로 새 쿼리가 생성됩니다
컴포넌트가 새 데이터로 다시 렌더링됩니다
유틸리티가 로딩 상태를 다시 표시합니다

queryKey는 .fn.where와 같은 불투명한 함수형 변형에 사용합니다. DB는 해당 함수가 클로저로 캡처한 값을 검사할 수 없기 때문입니다. 반응형 키 값은 getter를 통해 전달합니다:

<script>
  import { useLiveQuery } from '@tanstack/svelte-db'

  let search = $state('ship')

  const query = useLiveQuery({
    queryKey: () => [todosCollection.id, 'search', search],
    query: (q) =>
      q.from({ todos: todosCollection })
       .fn.where(({ todos }) => todos.title.includes(search))
  })
</script>

기존 종속성 배열도 계속 지원됩니다. 구조화된 쿼리에는 파생된 ID를 사용하고 불투명한 쿼리에는 queryKey을 사용하는 것이 좋습니다.

여러 속성에 액세스하기

쿼리 결과에서 모든 상태 속성에 직접 액세스할 수 있습니다:

<script>
  import { useLiveQuery } from '@tanstack/svelte-db'
  import { eq } from '@tanstack/db'

  const query = useLiveQuery((q) =>
    q.from({ todos: todosCollection })
     .where(({ todos }) => eq(todos.active, true))
  )
</script>

<div>
  <div>Status: {query.status}</div>
  <div>Loading: {query.isLoading}</div>
  <div>Ready: {query.isReady}</div>
  <div>Total: {query.data.length}</div>
</div>

설치​

Svelte 유틸리티​

기본 사용법​

DbProvider​

useLiveQuery​

useLiveInfiniteQuery​

쿼리 식별성​

여러 속성에 액세스하기​

설치