@basketry/react-query

React Query

Basketry generator for generating React Query (TanStack Query) hooks and query/mutation options. This generator can be coupled with any Basketry parser to automatically generate type-safe React Query integration from your API definitions.

Features

• Generates type-safe query and mutation options following React Query v5 patterns
• Type-safe query key builder for cache operations with IntelliSense support
• Support for infinite queries with Relay-style pagination
• Full TypeScript support with proper type inference
• Backwards compatibility with deprecated hook wrappers for smooth migration

Migration Guide (v0.1.x to v0.2.x)

Starting with v0.2.0, this generator adopts the React Query v5 queryOptions pattern. The old hook wrappers are deprecated but still available for backwards compatibility.

Query Hooks

// Old pattern (deprecated)
import { useGetWidgets } from './hooks/widgets';
const result = useGetWidgets(params);

// New pattern
import { useQuery } from '@tanstack/react-query';
import { getWidgetsQueryOptions } from './hooks/widgets';
const result = useQuery(getWidgetsQueryOptions(params));

Mutation Hooks

// Old pattern (deprecated)
import { useCreateWidget } from './hooks/widgets';
const mutation = useCreateWidget();

// New pattern
import { useMutation } from '@tanstack/react-query';
import { createWidgetMutationOptions } from './hooks/widgets';
const mutation = useMutation(createWidgetMutationOptions());

Infinite Query Hooks

// Old pattern (deprecated)
import { useGetWidgetsInfinite } from './hooks/widgets';
const result = useGetWidgetsInfinite(params);

// New pattern
import { useInfiniteQuery } from '@tanstack/react-query';
import { getWidgetsInfiniteQueryOptions } from './hooks/widgets';
const result = useInfiniteQuery(getWidgetsInfiniteQueryOptions(params));

Query Key Builder

The new version includes a type-safe query key builder for cache operations:

import { matchQueryKey } from './hooks/query-key-builder';

// Invalidate all queries for a service
queryClient.invalidateQueries({ queryKey: matchQueryKey('widgets') });

// Invalidate specific operation
queryClient.invalidateQueries({
  queryKey: matchQueryKey('widgets', 'getWidgets'),
});

// Invalidate with specific parameters
queryClient.invalidateQueries({
  queryKey: matchQueryKey('widgets', 'getWidgets', { status: 'active' }),
});

Benefits of the New Pattern

• Better tree-shaking - only import what you use
• More flexible - compose with any React Query hook
• Better TypeScript inference
• Easier testing - options can be tested without React context
• Consistent with React Query v5 best practices

Automated Migration

We provide a jscodeshift codemod to automatically migrate your codebase:

# Using the provided script
./node_modules/@basketry/react-query/codemod/run-migration.sh        # Preview (dry run)
./node_modules/@basketry/react-query/codemod/run-migration.sh --apply # Apply changes

# Or using jscodeshift directly
npx jscodeshift -t ./node_modules/@basketry/react-query/codemod/react-query-v0.2-migration.js \
  src/ --extensions=ts,tsx --parser=tsx --dry  # Preview (dry run)

npx jscodeshift -t ./node_modules/@basketry/react-query/codemod/react-query-v0.2-migration.js \
  src/ --extensions=ts,tsx --parser=tsx        # Apply changes

See codemod documentation for more details.

For contributors:

Run this project

• Install packages: npm ci
• Build the code: npm run build
• Run it! npm start

Note that the lint script is run prior to build. Auto-fixable linting or formatting errors may be fixed by running npm run fix.

Create and run tests

• Add tests by creating files with the .test.ts suffix
• Run the tests: npm t
• Test coverage can be viewed at /coverage/lcov-report/index.html

Publish a new package version

• Create new version
  • Navigate to the version workflow from the Actions tab.
  • Manually dispatch the action with the appropriate inputs
  • This will create a PR with the new version
• Publish to NPM
  • Review and merge the PR
  • The publish workflow will create a git tag and publish the package on NPM

Generated with generator-ts-console