Lit Query

Purpose and Scope

Lit Query is the TanStack Query framework adapter for Lit applications. TanStack Query itself is described by the project as an async state management library for fetching, caching, synchronizing, and updating server state, with protocol-agnostic fetching, pagination, infinite scroll, mutations, dependent queries, background updates, prefetching, and cancellation. In a Lit application, the adapter’s job is to expose that server-state cache and lifecycle through Lit-native building blocks rather than asking every component to manually coordinate fetch effects, stale data, retries, and cache subscriptions.

Sources: docs/config.json, docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

The public docs navigation treats Lit as a first-class framework section alongside React, Solid, Vue, Svelte, and Angular. The supplied docs configuration registers a lit framework group under Getting Started and includes Lit pages for Overview, Installation, and Quick Start. That placement is important for readers: Lit Query should be approached as an adapter over the same Query core concepts, not as a separate data-fetching library with different cache semantics. Start with the Lit-specific docs entry points, then use the shared guides for query keys, query functions, mutations, invalidation, and cache behavior.

Sources: docs/config.json

Relevant Source Files

• docs/config.json — Defines the documentation navigation and shows that Lit has a framework-specific Getting Started section with Overview, Installation, and Quick Start entries.
• docs/framework/angular/reference/functions/provideTanStackQuery.md — Provides a source-backed example of the shared adapter pattern: an application-level provider receives a QueryClient and optional features, illustrating how framework adapters connect applications to the TanStack Query cache.
• docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md — Explains the promise-based, client-agnostic query function contract that also applies when a Lit app fetches with fetch, GraphQL clients, generated API clients, or other async libraries.
• docs/framework/angular/devtools.md — Shows how framework-specific adapters connect optional devtools features to an application and clarifies development and production loading concerns for devtools integrations.
• docs/framework/angular/guides/background-fetching-indicators.md — Demonstrates adapter-level status consumption for pending, error, success, and background fetching states, which are the same user-facing states Lit components need to render clearly.
• docs/community-resources.md — Lists community learning resources and ecosystem utilities that remain relevant when applying TanStack Query patterns from other frameworks to Lit.

Core Primitives

The central primitive is the QueryClient. A query client owns the query cache and mutation cache and provides methods for fetching, prefetching, reading cached data, invalidating queries, refetching, cancelling, clearing, and resuming paused mutations. Framework adapters make that client available to components through framework-native integration points. The Angular docs show this shape with provideTanStackQuery(new QueryClient()), and while Lit uses its own adapter surface, the architectural idea is the same: create or supply one client for a UI boundary, then let components observe query state through adapter APIs.

Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md

A Lit-oriented mental model is to separate three concerns. First, the Query core owns server-state identity, freshness, retrying, garbage collection, and mutation state. Second, the Lit adapter connects that core to Lit’s reactive rendering model, commonly through adapter primitives such as reactive controllers and a provider element. Third, each component declares the server data it needs by providing a query key and a promise-returning query function. This split keeps network behavior consistent across applications while allowing Lit components to update naturally when the observed query result changes.

Sources: docs/config.json, docs/framework/angular/guides/background-fetching-indicators.md

Query functions are intentionally backend-agnostic. The Angular data-fetching guide states that TanStack Query’s fetching mechanisms are built on Promises and can use the browser fetch API, graphql-request, or other asynchronous clients. That matters for Lit because the adapter should not force a networking stack. A Lit component can use plain fetch, a generated OpenAPI client, a GraphQL client, or a project-specific SDK as long as the query function resolves or rejects a promise. The cache then manages deduplication, status, retries, refetching, and subscribers above that transport layer.

Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

Application Setup Flow

A typical Lit Query setup starts by installing the Lit adapter package and creating a shared QueryClient for the part of the application that should share cached server state. The framework docs navigation confirms that Lit has dedicated Installation and Quick Start pages, so those should be the first stop for exact package names and adapter-specific syntax. Conceptually, the setup mirrors the provider pattern shown in the Angular docs: create the client once, attach it to the application boundary, and then let child components consume query results without creating independent caches for every component.

Sources: docs/config.json, docs/framework/angular/reference/functions/provideTanStackQuery.md

After the client is available, individual Lit components should model each remote resource with a stable query key and a query function. A query key is the cache contract: it identifies the resource and its inputs so reads, background refetches, invalidations, prefetches, and devtools all speak the same language. In Lit, this is especially useful because components can remain focused on rendering while TanStack Query coordinates whether data is fresh, stale, pending, refetching, or errored. The component should render those states deliberately rather than hiding background work from users.

Sources: docs/framework/angular/guides/background-fetching-indicators.md

Status, Background Fetching, and UX

The Angular background-fetching guide provides a useful state vocabulary that transfers to Lit: a query can be pending, error, success, and separately fetching in the background. That distinction is central to TanStack Query UX. A first load can show a blocking loading state, an error can show an actionable message, and a successful query can continue displaying cached data while a background refetch is in progress. In Lit components, reactive controllers or equivalent adapter primitives should be used to trigger re-rendering from those state transitions instead of manually wiring imperative fetch flags.

Sources: docs/framework/angular/guides/background-fetching-indicators.md

Global fetching indicators are also part of the adapter story. The Angular guide demonstrates a framework-level injectIsFetching helper for a global loading indicator; the exact Lit API should be taken from the Lit docs, but the behavior to look for is the same: observe the query client for any active background fetches and render an application-level indicator. This is different from a per-component spinner because it reflects cache-wide network activity and can make route transitions, refresh buttons, and optimistic flows feel predictable without duplicating request tracking state.

Sources: docs/framework/angular/guides/background-fetching-indicators.md

Devtools and Ecosystem Notes

Devtools make the TanStack Query cache visible. The Angular devtools documentation explains the framework pattern: a devtools feature can be attached during application setup, loaded automatically in development, excluded from production bundles by default, or imported from a production subpath when an application wants controlled production loading. Lit users should look for the Lit adapter’s devtools story in the Lit docs or use browser extensions where appropriate, but the operational questions are the same: who can inspect cache state, when is the panel loaded, and how does that affect production bundles?

Sources: docs/framework/angular/devtools.md

The community resources page is useful for Lit teams because many TanStack Query practices are framework-independent. Blog posts and talks explain cache design, query keys, invalidation, and the difference between server state and client state. Utilities such as OpenAPI client generators, GraphQL code generation, query key factories, batching tools, and normalization helpers can complement Lit Query when the application needs typed endpoints, consistent keys, or specialized request orchestration. Treat these resources as ecosystem additions around the core Query contract rather than replacements for the Lit adapter setup.

Sources: docs/community-resources.md

Compact Reference

Area	What to use or verify	Source-backed note
Docs entry points	framework/lit/overview, framework/lit/installation, framework/lit/quick-start	Lit is registered as a framework section in the docs navigation.
Cache owner	QueryClient	Framework adapters connect applications to a query client; Angular documents this with provideTanStackQuery(new QueryClient()).
Fetching contract	Promise-returning queryFn	TanStack Query fetching is promise-based and can use fetch, graphql-request, or other async clients.
UI state	pending, error, success, fetching	Adapter examples distinguish first-load state from background fetching state.
Devtools	Framework devtools or browser extensions	Devtools inspect queries and mutations and may be development-only or deliberately lazy loaded.

Next Steps

Read the Lit Overview, Installation, and Quick Start pages from the official docs navigation first, then return to the shared TanStack Query concepts for query keys, query functions, mutations, invalidation, and caching defaults. When implementing a real Lit component, create a single query client for the application boundary, connect it through the Lit adapter’s provider mechanism, use adapter primitives such as reactive controllers to observe query results, and keep fetch logic promise-based. Add devtools early during development so query identity, freshness, observers, retries, and errors are visible while building the UI.

Sources: docs/config.json, docs/framework/angular/reference/functions/provideTanStackQuery.md, docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md, docs/framework/angular/devtools.md