docs(suspensive.org): add docs for cli (#1032)

# 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]>
toss · Jul 4, 2024 · 51671ca · 51671ca
1 parent 451ec67
commit 51671ca
Show file tree

Hide file tree

Showing 4 changed files with 265 additions and 0 deletions.
diff --git a/docs/suspensive.org/src/pages/docs/react-query/_meta.en.json b/docs/suspensive.org/src/pages/docs/react-query/_meta.en.json
@@ -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",

diff --git a/docs/suspensive.org/src/pages/docs/react-query/_meta.ko.json b/docs/suspensive.org/src/pages/docs/react-query/_meta.ko.json
@@ -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",

diff --git a/docs/suspensive.org/src/pages/docs/react-query/tanstack-query-compatibility.en.mdx b/docs/suspensive.org/src/pages/docs/react-query/tanstack-query-compatibility.en.mdx
@@ -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"
+  }
+}
+```
diff --git a/docs/suspensive.org/src/pages/docs/react-query/tanstack-query-compatibility.ko.mdx b/docs/suspensive.org/src/pages/docs/react-query/tanstack-query-compatibility.ko.mdx
@@ -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"
+  }
+}
+```