Support both TanStack Query v4 and 5

@suspensive/react-query is composed of @suspensive/react-query-4 and @suspensive/react-query-5, which provide interfaces corresponding to the version of @tanstack/react-query. It detects the installed version of @tanstack/react-query in the user’s environment and automatically provides the compatible interface.

Command-Line Interface (CLI)

The Command-Line Interface (CLI) of @suspensive/react-query is a tool to match compatibility with @tanstack/react-query. It allows you to check the compatibility with the installed version of @tanstack/react-query and switch the interface of @suspensive/react-query to a compatible one via commands.

However, in most cases, the CLI is rarely needed as @suspensive/react-query automatically provides a compatible interface based on the installed version of @tanstack/react-query upon installation.

Getting Started

The CLI is included with the @suspensive/react-query package. No additional installation is required. You can use it directly with the following command.

npx suspensive-react-query

Or simply use srq.

npx srq

Commands

The CLI currently offers 5 commands. Here are the descriptions of each command.

version

Displays the installed version of @suspensive/react-query. This reflects the package version specified in package.json and does not indicate the version of @suspensive/react-query-4 or @suspensive/react-query-5 internally configured for compatibility with @tanstack/react-query.

npx suspensive-react-query -v

Or

npx suspensive-react-query --version

help

Provides usage information for commands in the console. For example, to learn more about the fix command, use.

npx suspensive-react-query fix -h

Or

npx suspensive-react-query --help

status

You can check the compatibility status between the installed versions of @tanstack/react-query and @suspensive/react-query in your current environment. Additionally, you can see which interfaces are available for use in the current environment from the list of available interfaces.

npx suspensive-react-query status

For example, using @suspensive/react-query@2.12.1 and @tanstack/react-query@5.51.21, the result might be.

┌─────────────────────────────────────────┬──────────┬────────────────────────────────────┐
│ @suspensive/react-query@2.12.1          │ status   │ available interfaces               │
├──────────┬──────────────────────────────┼──────────┼────────────────────────────────────┤
│ exports  │ @suspensive/react-query-5    │ 🟢       │ SuspenseQuery SuspenseQueries      │
│ from     │ @2.12.1                      │          │ SuspenseInfiniteQuery              │
│          │                              │          │ QueryErrorBoundary Mutation        │
│          ├──────────────────────────────┼──────────┼────────────────────────────────────┤
│          │ @tanstack/react-query        │ 🟢       │ useSuspenseQuery                   │
│          │ @5.51.21                     │          │ useSuspenseQueries                 │
│          │                              │          │ useSuspenseInfiniteQuery           │
│          │                              │          │ queryOptions infiniteQueryOptions  │
└──────────┴──────────────────────────────┴──────────┴────────────────────────────────────┘

switch

Switches the exports of @suspensive/react-query to use the interface compatible with the installed version of @tanstack/react-query. This updates the entry file (dist/index.js) of @suspensive/react-query.

// dist/index.js of @suspensive/react-query
 
// When you use "npx suspensive-react-query switch 4"
// @suspensive/react-query's dist/index.js
export * from '@suspensive/react-query-4' // Suspensive interfaces for @tanstack/react-query@4
// When you use "npx suspensive-react-query switch 5"
// @suspensive/react-query's dist/index.js
export * from '@suspensive/react-query-5' // Suspensive interfaces for @tanstack/react-query@5

If you are using @tanstack/react-query v5 and encounter errors, you can update the entry file (dist/index.js) and switch to the compatible interface by using the following command.

npx suspensive-react-query switch 5

fix

The fix command is a convenient way to match versions in an environment where @suspensive/react-query and @tanstack/react-query are incompatible. It automatically switches the exports of @suspensive/react-query to use the interface compatible with the installed version of @tanstack/react-query.

npx suspensive-react-query fix

Troubleshooting

If you encounter errors related to @suspensive/react-query during build, it is likely due to compatibility issues with the installed @tanstack/react-query version.

You can specify the version in package.json to ensure the correct version is used during build. For example, to automatically use the correct version, you can use the following script.

{
  "scripts": {
    "build": "suspensive-react-query fix && next build"
  }
}

Or to fix the version, set it up as follows,

{
  "scripts": {
    "build": "suspensive-react-query switch 5 && next build"
  }
}