0
Fork 0
mirror of https://github.com/TanStack/query.git synced 2026-11-16 22:50:20 +00:00
query/docs/framework/lit/overview.md
Gaurav 4082894509
feat: lit query adapter
* feat lit-query: add initial lit-query package

* remove internal docs from initial PR

* fix review issues

* align scripts with monorepo Nx targets and use workspace:* for query-core

* feat(lit-query): fix type inference and monorepo integration

  - Fix createQueriesController tuple type inference with recursive types
  - Add DataTag support to queryOptions
  - Fix build config and vitest custom-condition resolution
  - Fix example install scripts for standalone bootstrap

* fix(lit-query): polish package validation and examples

* ci: apply automated fixes

* lit-query: preserve provider handshake ordering in BaseController

* Update .changeset/lemon-memes-divide.md

Co-authored-by: Dominik Dorfmeister 🔮 <office@dorfmeister.cc>

* removing prettier config from adapter, so that global config from the monorepo is used

* removed the package local format scripts so formatting stays centralized at the monorepo root

* removing like other adapters keep build and test:build as separate targets

* Compared against the other adapters and removed the lit-query-only aliases/gates, keeping the standard Nx target names so root CI can pick them up consistently

* package:check has been removed. The CJS smoke check is still needed because lit-query publishes custom CJS output/types

* fix(lit-query): align lit examples and integration with monorepo conventions

* chore(lit-query): clean up stale package checks

* fix(lit-query): address review feedback for lit examples and lifecycle tests

* chore: fix lockfile

* fix: add customCondition

* docs(lit-query): add Lit docs and generated reference

* docs(lit-query): fix Lit docs review comment and align examples

---------

Co-authored-by: gauravchugh <gauravchugh@servicenow.com>
Co-authored-by: Dominik Dorfmeister 🔮 <office@dorfmeister.cc>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-05-08 15:18:50 +02:00

3.7 KiB

id title
overview Overview

IMPORTANT: The @tanstack/lit-query package is currently experimental and v0.1. Expect the Lit adapter API and docs to keep evolving. If you use it in production while it is early, pin the package to a patch version and upgrade deliberately.

The @tanstack/lit-query package is the Lit adapter for TanStack Query. It gives Lit applications reactive controller APIs for fetching, caching, synchronizing, and updating server state.

TanStack Query manages server state: data that is owned by a remote system, fetched asynchronously, shared across screens, and potentially changed by someone else at any time. It handles caching, request deduplication, stale data, background refetching, mutations, invalidation, pagination, and garbage collection.

Lit Query exposes those features through Lit reactive controllers. A Lit reactive controller is attached to a ReactiveControllerHost, usually a LitElement. Lit Query controllers subscribe to the QueryClient, request host updates when results change, and are cleaned up with the host lifecycle.

Core APIs

Most Lit applications use these APIs:

The adapter also re-exports TanStack Query Core APIs from @tanstack/lit-query, so examples in the Lit docs use @tanstack/lit-query as the user-facing import path.

A First Query

import { LitElement, html } from 'lit'
import {
  QueryClient,
  QueryClientProvider,
  createQueryController,
} from '@tanstack/lit-query'

const queryClient = new QueryClient()

class AppQueryProvider extends QueryClientProvider {
  constructor() {
    super()
    this.client = queryClient
  }
}

customElements.define('app-query-provider', AppQueryProvider)

class RepoStats extends LitElement {
  private readonly repo = createQueryController(this, {
    queryKey: ['repoData'],
    queryFn: async () => {
      const response = await fetch(
        'https://api.github.com/repos/TanStack/query',
      )
      if (!response.ok) throw new Error('Failed to fetch repo data')
      return response.json() as Promise<{
        name: string
        description: string
        stargazers_count: number
      }>
    },
  })

  render() {
    const query = this.repo()

    if (query.isPending) return html`Loading...`
    if (query.isError) return html`Error: ${query.error.message}`

    return html`
      <h1>${query.data.name}</h1>
      <p>${query.data.description}</p>
      <strong>${query.data.stargazers_count} stars</strong>
    `
  }
}

customElements.define('repo-stats', RepoStats)

Render the provider above your query consumers:

<app-query-provider>
  <repo-stats></repo-stats>
</app-query-provider>

Status Notes

Lit Devtools are not available yet. Use the cache APIs and the generated API reference while the adapter matures.

Start with Installation, then Quick Start, and use the Reactive Controllers vs Hooks guide if you are coming from React Query.