* 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>
3.1 KiB
| id | title |
|---|---|
| installation | Installation |
IMPORTANT: The Lit adapter is currently experimental and v0.1. Pin exact versions if you need extra release stability while the API is early.
Install Lit Query with Lit and TanStack Query Core:
npm i @tanstack/lit-query @tanstack/query-core lit
or
pnpm add @tanstack/lit-query @tanstack/query-core lit
or
yarn add @tanstack/lit-query @tanstack/query-core lit
or
bun add @tanstack/lit-query @tanstack/query-core lit
@tanstack/query-core is a peer dependency of @tanstack/lit-query. Even though the Lit docs import user-facing APIs from @tanstack/lit-query, your app should install @tanstack/query-core explicitly.
Requirements
Lit Query is intended for Lit 2.8 and newer, including Lit 3. It uses Lit reactive controllers and Lit context, so query consumers should be ReactiveControllerHost instances such as LitElement.
TanStack Query is optimized for modern browsers:
Chrome >= 91
Firefox >= 90
Edge >= 91
Safari >= 15
iOS >= 15
Opera >= 77
Provider Setup
Create a QueryClient, provide it with QueryClientProvider, and register your custom element. The package exports the provider class but does not call customElements.define for you.
Subclass Pattern
import { QueryClient, QueryClientProvider } from '@tanstack/lit-query'
const queryClient = new QueryClient()
class AppQueryProvider extends QueryClientProvider {
constructor() {
super()
this.client = queryClient
}
}
customElements.define('app-query-provider', AppQueryProvider)
<app-query-provider>
<todos-view></todos-view>
</app-query-provider>
Direct Provider Element
You can register the provider class directly and bind its client property from a Lit template. The dot is important: .client=${queryClient} is a property binding, not an HTML attribute.
import { LitElement, html } from 'lit'
import { QueryClient, QueryClientProvider } from '@tanstack/lit-query'
const queryClient = new QueryClient()
customElements.define('query-client-provider', QueryClientProvider)
class AppRoot extends LitElement {
render() {
return html`
<query-client-provider .client=${queryClient}>
<todos-view></todos-view>
</query-client-provider>
`
}
}
If a connected provider has no client, it throws. See the generated QueryClientProvider reference for the full contract.
Render Roots
The snippets in these docs use Lit's default shadow DOM. Lit Query controllers and QueryClientProvider work with shadow DOM and light DOM because they use the host lifecycle and Lit context, not global selectors.
Some runnable examples override createRenderRoot() and return this so their demo markup stays in light DOM for shared page styles and test selectors. That override is not required for Lit Query. Use light DOM only when your app has a separate reason to expose a component's internal markup to global CSS, tests, or non-shadow-DOM integration code.
Devtools Status
Lit Devtools are not available yet. This is a current adapter limitation, not an installation step.