ESLint Plugin Query

Purpose and Scope

Query-specific linting is most useful when it protects the conventions that make TanStack Query predictable: stable cache identity, declarative data dependencies, and framework-native setup. In this repository slice, the strongest source-backed signals come from the documentation that describes Angular Query providers, query functions, devtools wiring, background fetching indicators, and the docs navigation. Those files show the API shapes and usage patterns that linting should preserve in application code, even when the actual rule implementation files are outside this page's supplied source set.

Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md, docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md, docs/framework/angular/guides/background-fetching-indicators.md

TanStack's official ESLint guidance also distinguishes shared TanStack project linting from framework-specific Query APIs. The shared @tanstack/eslint-config package is framework-agnostic and is configured through ESLint v9 flat config. For a Query application, that means a team can start with the common TanStack lint baseline and then layer Query-specific linting where the framework adapter exposes data-fetching primitives. The practical goal is not to lint network requests in the abstract; it is to catch patterns that break Query's cache and observer model before they become runtime bugs.

Recommended Usage

Start with a normal ESLint v9 flat-config setup, then apply Query linting close to the code that calls Query APIs. The official TanStack Config setup installs @tanstack/eslint-config as a development dependency and spreads tanstackConfig into eslint.config.js. That shared configuration covers general JavaScript and TypeScript hygiene, while Query-specific linting should be treated as an additional layer for files that construct query options, providers, mutation flows, or framework adapter calls. Keeping those layers separate helps teams understand whether a warning is about general TypeScript quality or about Query's server-state contract.

pnpm add -D @tanstack/eslint-config

import { tanstackConfig } from '@tanstack/eslint-config'
 
export default [
  ...tanstackConfig,
  {
    // Add Query-specific rules or project overrides here
  },
]

In Angular Query projects, the setup surface starts at provideTanStackQuery(queryClient, ...features), which returns Angular Provider[] and enables TanStack Query for the application. That function accepts either a QueryClient instance or an Angular InjectionToken that provides one, and it can also receive feature functions such as devtools integration. Linting is valuable around this boundary because provider setup tends to be copied into application configuration, lazy-loaded routes, or module providers, where accidental duplication or inconsistent feature flags can create confusing development behavior.

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

The docs also show why query functions should remain promise-oriented and explicit. Angular's HttpClient returns observables, so the Angular guide converts them with lastValueFrom or firstValueFrom before returning from queryFn. That detail matters for linting because a correct Query function is not just any callback; it is the asynchronous contract Query uses for caching, retries, background updates, and status transitions. A rule set or local code review checklist should therefore pay close attention to queryKey, queryFn, and adapter calls such as injectQuery.

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

Relevant Source Files

• docs/framework/angular/reference/functions/provideTanStackQuery.md - Documents the Angular provider entry point, the QueryClient or InjectionToken input, optional feature arguments, devtools usage, and the returned Provider[] contract.
• docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md - Shows the promise-based queryFn contract and the Angular HttpClient conversion pattern that linting should not obscure.
• docs/framework/angular/devtools.md - Documents the withDevtools feature, development-only default loading, production subpath, and loadDevtools options that affect provider configuration.
• docs/framework/angular/guides/background-fetching-indicators.md - Shows adapter-level consumption through injectQuery, query status methods, isFetching, and the global injectIsFetching indicator.
• docs/config.json - Defines the documentation navigation structure and framework sections, confirming that Query documentation is organized by adapter and feature area rather than as a single React-only surface.
• docs/community-resources.md - Lists community utilities and learning resources that teams may use alongside linting when standardizing Query usage patterns.

Source-Backed Rule Targets

Because the provided repository evidence is documentation-focused, the safest way to describe the linting target is by the public code patterns that appear in the docs. A Query lint rule should protect cache identity and declarative execution wherever the adapter exposes it. In the Angular examples, that means the object passed to injectQuery contains a queryKey and a queryFn, with status and fetching state consumed from the returned query object. Those names are the stable surface developers see while building components, so they are the natural places for lints, examples, and team conventions to converge.

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

Devtools configuration is another concrete target. The Angular docs enable devtools by passing withDevtools() as an optional feature to provideTanStackQuery(new QueryClient(), withDevtools()). They also document the production import path @tanstack/angular-query-experimental/devtools/production and the loadDevtools option, whose values include automatic loading, explicit true, and false. Linting cannot decide a team's environment policy, but it can help keep imports and configuration centralized so staging, production, and local development do not drift into different provider shapes by accident.

Sources: docs/framework/angular/devtools.md

The HttpClient guide supplies an important negative boundary: TanStack Query is promise-based, while Angular HttpClient currently returns observables. The documented pattern wraps this.http.get(...) with lastValueFrom(...) inside queryFn. That indicates a rule set should not force teams into a single data client, because Query is described as agnostic over asynchronous clients including browser fetch, graphql-request, and Angular HttpClient. Instead, linting should encourage a valid Query function shape while allowing each project to choose the client that fits testing, interceptors, SSR caching, and dependency-injection needs.

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

Compact Reference

The following names are the source-backed surfaces from this page's evidence that are most relevant when configuring or reviewing Query linting. provideTanStackQuery(queryClient, ...features): Provider[] installs Angular Query providers and accepts a QueryClient or an InjectionToken<QueryClient>. withDevtools() is an optional feature passed to that provider setup, with production loading controlled by the documented production subpath and loadDevtools option. injectQuery(() => ({ queryKey, queryFn })) is the component-level query construction pattern shown in the Angular guides. injectIsFetching() supplies a global background-fetching signal for UI indicators.

provideTanStackQuery(new QueryClient())
provideTanStackQuery(new QueryClient(), withDevtools())
provideTanStackQuery(MY_QUERY_CLIENT)
 
injectQuery(() => ({
  queryKey: ['repoData'],
  queryFn: () => lastValueFrom(this.http.get('https://api.github.com/repos/tanstack/query')),
}))
 
injectIsFetching()

These examples show a useful way to evaluate lint output: a warning should help preserve the relationship between the provider, the cache client, the query key, and the asynchronous query function. If a proposed rule only enforces style without improving that relationship, it belongs in the shared TanStack or project-level ESLint config instead. If it prevents unstable cache identity, accidental provider divergence, incorrect async return types, or confusing devtools loading, it belongs near Query-specific configuration.

Docs and Ecosystem Signals

The documentation config organizes TanStack Query content into framework sections such as React, Solid, Vue, Svelte, Lit, and Angular, with each framework having its own installation, quick start, devtools, TypeScript, or related guide pages where applicable. That structure matters for linting documentation because Query rules should be explained in framework terms. A React team may experience a rule through hooks, while an Angular team sees functions and signals such as injectQuery and injectIsFetching. The cache concepts are shared, but the developer-facing syntax is adapter-specific.

Sources: docs/config.json

Community resources add another signal: Query teams often standardize usage through external utilities, code generators, and educational material. The community resources page lists tools such as GraphQL Code Generator, Orval for OpenAPI-generated TypeScript clients, Query Key Factory for standardized query keys, and React Query Kit for reusable typed hooks. These tools can coexist with linting, but they should not replace it. Generated clients and query-key helpers create conventions; ESLint catches violations of those conventions during everyday edits.

Sources: docs/community-resources.md

Next Steps

For application teams, the next step is to decide which Query surfaces deserve hard lint rules and which belong in examples or code review guidance. Use the framework documentation to identify the adapter entry points in your codebase, then configure ESLint so warnings appear where developers construct query keys, query functions, provider setup, and devtools features. For this repository, pair this page with the Angular adapter, devtools, query functions, and community resources pages to connect linting practice back to concrete Query usage patterns.