Skip to content

Commit

Permalink
docs(suspensive.org): add docs for cli (#1032)
Browse files Browse the repository at this point in the history
# Overview

I am adding a document introducing the Command-Line Interface (CLI).

| support-both-tanstack-query-v4-and-5.en.mdx |
support-both-tanstack-query-v4-and-5.ko.mdx |
| --- | --- |

|![image](https://github.com/toss/suspensive/assets/39869096/fb03b973-0c8f-4f9c-9e9c-cf8395216e2d)|![image](https://github.com/toss/suspensive/assets/39869096/cb86da0d-a16d-418b-89e3-7c82fbab722f)|

Additionally, there are some parts we need to discuss together. Please
make sure to check the comments below.


## PR Checklist

- [x] I did below actions if need

1. I read the [Contributing
Guide](https://github.com/toss/suspensive/blob/main/CONTRIBUTING.md)
2. I added documents and tests.

---------

Co-authored-by: Jonghyeon Ko <[email protected]>
  • Loading branch information
gwansikk and manudeli authored Jul 4, 2024
1 parent 9935212 commit c648a17
Show file tree
Hide file tree
Showing 4 changed files with 265 additions and 0 deletions.
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
{
"motivation": { "title": "Why need to use?" },
"installation": { "title": "Installation" },
"tanstack-query-compatibility": { "title": "Support both TanStack Query v4 and 5" },
"migrate-to-v2": { "title": "Migrating to v2" },
"--- API Reference": {
"type": "separator",
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
{
"motivation": { "title": "어떤 이유로 사용하나요?" },
"installation": { "title": "설치하기" },
"tanstack-query-compatibility": { "title": "TanStack Query v4, 5를 모두 지원" },
"migrate-to-v2": { "title": "v2로 마이그레이션하기" },
"--- API Reference": {
"type": "separator",
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
import { Callout } from '@/components'

# Support both TanStack Query v4 and 5

As of version 2.2.0, @suspensive/react-query supports both v4 and v5 of @tanstack/react-query.

Internally, it is composed of @suspensive/react-query-4 and @suspensive/react-query-5, corresponding to the respective versions of @tanstack/react-query. It automatically detects the version of @tanstack/react-query installed in the user's environment and provides a compatible interface from @suspensive/react-query.

## Command-Line Interface (CLI)

The Command-Line Interface (CLI) of @suspensive/react-query is a tool designed to resolve compatibility issues with @tanstack/react-query. Through commands, it verifies compatibility with @tanstack/react-query and switches to a compatible interface of @suspensive/react-query.

If an error occurs due to incompatibility with @tanstack/react-query for any special reason, the CLI can be used to resolve the issue. However, the actual use of the CLI is rare, as the appropriate interface is automatically used upon installing @suspensive/react-query.

<Callout type="info">The CLI is still experimental and may not function as intended.</Callout>

## Getting Started

The CLI is included in the @suspensive/react-query package. No additional installation is needed, and it can be used immediately with the following command.

```bash
npx suspensive-react-query
```

Or simply use `srq`.

```bash
npx srq
```

## Commands

Currently, the CLI provides a total of 5 commands, each described below,

| Command | Description |
| ------- | ------------------------------------------------------------------------------ |
| version | Displays the installed version of @suspensive/react-query. |
| help | Provides usage information for the commands in the console. |
| status | Checks compatibility with the currently used @tanstack/react-query. |
| switch | Switches to the specified version of the @suspensive/react-query interface. |
| fix | Automatically switches to the interface compatible with @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.

```bash
npx suspensive-react-query -v
```

Or

```bash
npx suspensive-react-query --version
```

### help

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

```bash
npx suspensive-react-query fix -h
```

Or

```bash
npx suspensive-react-query --help
```

### status

Checks the interface of @suspensive/react-query being used to match @tanstack/react-query and verifies compatibility. It also lists the available APIs based on the version.

```bash
npx suspensive-react-query status
```

For instance, if using @suspensive/react-query@2.4.0 and @tanstack/react-query@5.49.2, you might see,

```
Suspensive React Query status:
@suspensive/[email protected] exports @suspensive/react-query-5's interfaces
- SuspenseQuery
- SuspenseQueries
- SuspenseInfiniteQuery
- QueryErrorBoundary
@tanstack/[email protected]
The versions are compatible.
```

### switch

Switches to the @suspensive/react-query interface compatible with @tanstack/react-query. For example, if using @tanstack/react-query v5 and encountering issues, you can switch to a compatible interface with,

```bash
npx suspensive-react-query switch 5
```

### fix

The `fix` command provides an easy way to match versions. It detects the @tanstack/react-query version in the user's environment and automatically switches to the compatible @suspensive/react-query interface.

```bash
npx suspensive-react-query fix
```

## Troubleshooting

If version errors occur during the build, you can specify the version to use in `package.json` as follows. To automatically use the correct version during build, use the script below,

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

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

```json
{
"scripts": {
"build": "suspensive-react-query switch 5 && next build"
}
}
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
import { Callout } from '@/components'

# TanStack Query v4, 5를 모두 지원

@suspensive/react-query는 v2.2.0 버전 이후로 @tanstack/react-query의 v4와 v5를 모두 지원합니다.

내부적으로 @tanstack/react-query 버전에 대응하는 @suspensive/react-query-4@suspensive/react-query-5로 구성되어 있습니다. 사용자 환경에 설치된 @tanstack/react-query 버전을 감지하여 자동으로 @suspensive/react-query의 호환되는 인터페이스를 제공합니다.

## Command-Line Interface (CLI)

@suspensive/react-query의 Command-Line Interface (CLI)는 @tanstack/react-query와의 호환성 문제를 해결하기 위한 도구입니다. 명령어를 통해 @tanstack/react-query와의 호환 여부를 확인하고, @suspensive/react-query의 호환되는 인터페이스로 전환할 수 있습니다.

특수한 이유로 @tanstack/react-query와 호환되지 않아 에러가 발생하면, CLI를 통해 문제를 해결할 수 있습니다. 하지만 실제로 CLI를 사용할 일은 드물며, @suspensive/react-query 설치 시 자동으로 알맞은 인터페이스를 사용합니다.

<Callout type="info">CLI는 아직 실험적인 기능이며, 의도대로 동작하지 않을 수 있습니다.</Callout>

## 시작하기

CLI는 @suspensive/react-query 패키지에 포함되어 있습니다. 추가적인 설치는 필요 없으며, 아래 명령어를 통해 바로 사용할 수 있습니다.

```bash
npx suspensive-react-query
```

또는 간단히 `srq`로도 사용할 수 있습니다.

```bash
npx srq
```

## 명령어

현재 CLI가 제공하는 명령어는 총 5개로, 각 명령어의 설명은 다음과 같습니다.

| 명령어 | 설명 |
| ------- | ------------------------------------------------------------------ |
| version | 현재 설치된 @suspensive/react-query의 버전을 표시합니다. |
| help | 명령어의 사용 방법을 콘솔에서 확인할 수 있습니다. |
| status | 현재 사용 중인 @tanstack/react-query와의 호환성 여부를 확인합니다. |
| switch | 지정한 버전의 @suspensive/react-query 인터페이스로 전환합니다. |
| fix | @tanstack/react-query와 호환되는 인터페이스로 자동 전환합니다. |

### version

현재 설치된 @suspensive/react-query의 버전을 표시합니다. 이는 패키지의 버전으로 `package.json`에 명시된 버전을 표시하며, @tanstack/react-query와 호환되도록 내부적으로 구성하는 @suspensive/react-query-4 또는 @suspensive/react-query-5의 버전을 의미하지는 않습니다.

```bash
npx suspensive-react-query -v
```

또는

```bash
npx suspensive-react-query --version
```

### help

명령어의 사용 방법을 콘솔에서 확인할 수 있습니다. 예를 들어 `fix` 명령어에 대해 자세히 알고 싶다면, 다음과 같이 명령어를 사용하여 확인할 수 있습니다.

```bash
npx suspensive-react-query fix -h
```

또는

```bash
npx suspensive-react-query --help
```

### status

현재 사용 중인 @tanstack/react-query와 대응되고 있는 @suspensive/react-query의 인터페이스를 확인하고, 호환성 여부를 확인할 수 있습니다. 또한 버전에 따라 사용 가능한 API를 확인할 수 있습니다.

```bash
npx suspensive-react-query status
```

예를 들어, @suspensive/react-query@2.4.0 버전과 @tanstack/react-query@5.49.2 버전을 사용 중인 경우, 다음과 같은 결과를 확인할 수 있습니다.

```
Suspensive React Query status:
@suspensive/[email protected] exports @suspensive/react-query-5's interfaces
- SuspenseQuery
- SuspenseQueries
- SuspenseInfiniteQuery
- QueryErrorBoundary
@tanstack/[email protected]
The versions are compatible.
```

### switch

@tanstack/react-query에 대응하고 있는 @suspensive/react-query 인터페이스로 변경할 수 있습니다. 예를 들어, @tanstack/react-query v5를 사용하고 있는데 오류가 발생하면, 다음 명령어를 사용하여 호환되는 인터페이스로 변경할 수 있습니다.

```bash
npx suspensive-react-query switch 5
```

### fix

`fix` 명령어는 손쉽게 버전을 맞추는 간편한 방법입니다. 사용자 환경에서 @tanstack/react-query 버전을 감지하여, 호환되는 @suspensive/react-query의 인터페이스를 자동으로 변경합니다.

```bash
npx suspensive-react-query fix
```

## 문제 해결

빌드 도중 버전에 대한 오류가 발생하면, 다음과 같은 방법으로 `package.json`에 사용하고자 하는 버전을 지정할 수 있습니다.
빌드 시 자동으로 올바른 버전을 사용하게 하려면 다음과 같이 스크립트를 사용할 수 있습니다.

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

또는 버전을 고정하려면 다음과 같이 설정할 수 있습니다.

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

0 comments on commit c648a17

Please sign in to comment.