RFC: @tanstack/query/prefer-query-options

[Newbie012]

Separating queryKey and queryFn can cause unexpected runtime issues when the same query key is accidentally used with more than one queryFn.

Rule Details

Examples of incorrect code for this rule:

/* eslint "@tanstack/query/prefer-query-options": "error" */functionComponent({ id }){constquery=useQuery({queryKey: ["get",id],queryFn: ()=>Api.get(`/foo/${id}`),});// ...}

/* eslint "@tanstack/query/prefer-query-options": "error" */functionuseFooQuery(){returnuseQuery({queryKey: ["get",id],queryFn: ()=>Api.get(`/foo/${id}`),});}

Examples of correct code for this rule:

/* eslint "@tanstack/query/prefer-query-options": "error" */constoptions=queryOptions({queryKey: ["get",id],queryFn: ()=>Api.get(`/foo/${id}`)});functionComponent({ id }){constquery=useQuery(options);// ...}

/* eslint "@tanstack/query/prefer-query-options": "error" */constoptions=queryOptions({queryKey: ["get",id],queryFn: ()=>Api.get(`/foo/${id}`),});functionuseFooQuery(){returnuseQuery({ ...options,select: (data)=>data.foo});}

Options

ignorePatterns

An array of strings used to ignore specific query key patterns:

{
"@tanstack/query/prefer-query-options": [
"error",
{
"ignorePatterns": {
"startsWith": ["ignore-key"],
"endsWith": ["ignore-key"],
"includes": ["ignore-key"],
}
}
]
}

collections

An array of strings used to enforce the use of queryOptions in specific collections of queries:

{
"@tanstack/query/prefer-query-options": [
"error",
{
"collections": ["fooQueries", "deeply.nested.queries"]
}
]
}

When Not To Use It

If you do not want to enforce the use of queryOptions in your codebase, you will not need this rule.

Attributes

• ✅ Recommended
• 🔧 Fixable.

[TkDodo]

love it ❤️ . One question that remains is if we want to add this to the recommended ruleset, and if so, on which level ?

[Newbie012]

While I do advocate for co-locating queryKey and queryFn I feel like this rule is a bit more opinionated than the others. Maybe we could add recommendedStrict config and add it there.

[camjackson]

I would absolutely love for this to exist. I've just spent a bunch of time going through my repo and making sure we are using queryOptions helpers everywhere. Including both:

• functions that take the whole options object like useQuery
• functions that take just the key like getQueryData, as this helps greatly with type inference as per the docs

I really want to lock this down via eslint so that someone can't come and undo my hard work. In lieu of a proper dedicated rule like the one proposed here, I did manage to create a pretty gnarly set of no-restricted-syntax queries to enforce this.

Here's what I came up with:

// Selectors to find relevant react-query function callsconstcallAFunctionThatTakesQueryOptions='CallExpression[callee.name=/^(useQuery|useSuspenseQuery)$/]'constcallAMethodThatTakeQueryOptions='CallExpression[callee.property.name=/^(invalidateQueries|fetchQuery|removeQueries|getQueriesData)$/]'constcallAMethodThatTakesAQueryKey='CallExpression[callee.property.name=/^(getQueryData|setQueryData)$/]'// "Assertions" to enforce that the first argument is either `fooQueryOptions()` or `fooQueryOptions().queryKey`constfirstArgMustBeSomethingQueryOptions='[arguments.0.callee.name!=/.+QueryOptions/]'constfirstArgMustBeSomethingQueryOptionsDotQueryKey=':matches([arguments.0.object.callee.name!=/.+QueryOptions/],[arguments.0.property.name!="queryKey"])'// DRY-ing up the error messagesconstqueryOptionsDocs=`See: https://tanstack.com/query/v5/docs/framework/react/guides/query-options`// Glue it all togetherconstqueryOptionsRules=[{selector: `${callAFunctionThatTakesQueryOptions}${firstArgMustBeSomethingQueryOptions}`,message: `Generate the query options using a helper e.g. \`profileQueryOptions()\` ${queryOptionsDocs}`,},{selector: `${callAMethodThatTakeQueryOptions}${firstArgMustBeSomethingQueryOptions}`,message: `Generate the query options using a helper e.g. \`profileQueryOptions()\` ${queryOptionsDocs}`,},{selector: `${callAMethodThatTakesAQueryKey}${firstArgMustBeSomethingQueryOptionsDotQueryKey}`,message: `Look up the queryKey using a queryOptions helper e.g. \`profileQueryOptions().queryKey\` ${queryOptionsDocs}`,},]

Like I said, it's pretty gnarly, and it has some rough edges. I haven't listed every single function (e.g. use/fetchInfiniteQuery), only the ones that I'm using. And it doesn't allow for spreading and overriding of the query options as in this example from the docs:

// this is not allowed by the above rules :(constquery=useQuery({
...groupOptions(1),select: (data)=>data.groupName,})

It might be technically possible to cover every edge case with no-restricted-syntax but it would be difficult. It would be much better to have a first class rule to check this stuff.

[danielpza]

I created this plugin a few months ago about pretty much this same issue https://github.com/danielpza/eslint-plugin-react-query-options

I'd be happy to send a PR adding the rules as a PoC if you are still planning to add it, or you could also use the code for reference. There's not a lot to it https://github.com/danielpza/eslint-plugin-react-query-options/blob/main/src/rules/use-query-no-inline-query.ts.

---

Referenced from TkDodo/blog-comments#128 (reply in thread)

[Newbie012]

I think it would be great porting both of the rules you've written to the official plugin. I don't remember why I didn't end up implementing this draft. Although I would wait for @TkDodo's approval on this. I can port these rules myself if you prefer 🙂

[TkDodo]

Let's do it 🔥

[danielpza]

#10184

I ended up combining the 2 rules in my plugin into a single one during the process to align with this discussion: prefer-query-options