Support both TanStack Query v4 and 5

From version 2.2.0 onwards, @tanstack/react-query supports both v4 and v5. To support older browser versions, use @suspensive/react-query with @tanstack/react-query v4.

@suspensive/react-query internally uses @suspensive/react-query-4 and @suspensive/react-query-5, depending on the version of @tanstack/react-query detected in your environment. It automatically provides a compatible interface.

Command-Line Interface (CLI)

The Command-Line Interface (CLI) of @suspensive/react-query is a tool to handle compatibility issues with @tanstack/react-query. You can use commands to check compatibility and switch to the compatible interface of @suspensive/react-query.

However, using the CLI is rarely necessary as @suspensive/react-query automatically provides the appropriate interface 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.

Command	Description
version	Displays the currently installed version of @suspensive/react-query.
help	Shows usage information for the commands.
status	Checks compatibility with the currently used version of @tanstack/react-query.
switch	Switches to the specified version of @suspensive/react-query interface.
fix	Automatically switches to the compatible interface for @tanstack/react-query.

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

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

npx suspensive-react-query --help

status

Checks and displays the interface compatibility of @suspensive/react-query with the currently used version of @tanstack/react-query. It also lists the available APIs based on the version.

npx suspensive-react-query status

For instance, if using @suspensive/react-query@2.9.0 and @tanstack/react-query@5, the result might look like this:

┌─────────────────────────┬─────────────────────────────────┬────────┬────────────────────────────────────────────────────────┐
│ @suspensive/react-query │ result                          │ status │ advice                                                 │
├─────────────────────────┼─────────────────────────────────┼────────┼────────────────────────────────────────────────────────┤
│ version                 │ 2.9.0                           │ 🟢     │                                                        │
├─────────────────────────┼─────────────────────────────────┼────────┼────────────────────────────────────────────────────────┤
│ export                  │ @suspensive/react-query-5@2.9.0 │ 🟢     │                                                        │
├─────────────────────────┼─────────────────────────────────┼────────┼────────────────────────────────────────────────────────┤
│ peerDependency          │ @tanstack/react-query@5         │ 🟢     │ The versions are compatible.                           │
├─────────────────────────┼─────────────────────────────────┼────────┼────────────────────────────────────────────────────────┤
│ You can use             │ SuspenseQuery                   │ 🟢     │ For more detailed information about the provided APIs, │
│                         │ SuspenseQueries                 │        │ please visit the official documentation:               │
│                         │ SuspenseInfiniteQuery           │        │ https://suspensive.org/docs/react-query/motivation     │
│                         │ Mutation                        │        │                                                        │
│                         │ QueryErrorBoundary              │        │                                                        │
└─────────────────────────┴─────────────────────────────────┴────────┴────────────────────────────────────────────────────────┘

switch

Updating the entry file (dist/index.js) of @suspensive/react-query. This will switch to the specified version of the @suspensive/react-query interface.

// 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 the @suspensive/react-query interface with the @tanstack/react-query version in your environment. It detects the installed @tanstack/react-query version and switches to the compatible @suspensive/react-query interface automatically.

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"
  }
}

Installation Migrating to v2