From 8a40e0a9a88c064e2c3cb109af39f8ab5bab6a3b Mon Sep 17 00:00:00 2001 From: gwansikk Date: Thu, 7 Nov 2024 04:53:53 +0900 Subject: [PATCH 1/2] docs(suspensive.org): add docs for codemods --- .../src/pages/ko/docs/_meta.tsx | 3 +- .../src/pages/ko/docs/codemods/_meta.tsx | 9 ++++ .../src/pages/ko/docs/codemods/motivation.mdx | 46 +++++++++++++++++++ .../ko/docs/codemods/tanstackQueryImport.mdx | 31 +++++++++++++ .../src/pages/ko/docs/codemods/usage.mdx | 24 ++++++++++ 5 files changed, 112 insertions(+), 1 deletion(-) create mode 100644 docs/suspensive.org/src/pages/ko/docs/codemods/_meta.tsx create mode 100644 docs/suspensive.org/src/pages/ko/docs/codemods/motivation.mdx create mode 100644 docs/suspensive.org/src/pages/ko/docs/codemods/tanstackQueryImport.mdx create mode 100644 docs/suspensive.org/src/pages/ko/docs/codemods/usage.mdx diff --git a/docs/suspensive.org/src/pages/ko/docs/_meta.tsx b/docs/suspensive.org/src/pages/ko/docs/_meta.tsx index ba46d9dc1..3ebc40af8 100644 --- a/docs/suspensive.org/src/pages/ko/docs/_meta.tsx +++ b/docs/suspensive.org/src/pages/ko/docs/_meta.tsx @@ -5,7 +5,8 @@ export default { }, react: { title: '@suspensive/react' }, 'react-query': { title: '@suspensive/react-query' }, - jotai: '@suspensive/jotai', + jotai: { title: '@suspensive/jotai' }, + codemods: { title: '@suspensive/codemods' }, '--- More': { type: 'separator', title: '더보기', diff --git a/docs/suspensive.org/src/pages/ko/docs/codemods/_meta.tsx b/docs/suspensive.org/src/pages/ko/docs/codemods/_meta.tsx new file mode 100644 index 000000000..94d4dd367 --- /dev/null +++ b/docs/suspensive.org/src/pages/ko/docs/codemods/_meta.tsx @@ -0,0 +1,9 @@ +export default { + motivation: { title: '어떤 이유로 사용하나요?' }, + usage: { title: '사용하기' }, + '--- Codemods': { + type: 'separator', + title: 'Codemods', + }, + tanstackQueryImport: { title: 'TanStack Query로 import 경로 변경' }, +} diff --git a/docs/suspensive.org/src/pages/ko/docs/codemods/motivation.mdx b/docs/suspensive.org/src/pages/ko/docs/codemods/motivation.mdx new file mode 100644 index 000000000..fb4d9afdb --- /dev/null +++ b/docs/suspensive.org/src/pages/ko/docs/codemods/motivation.mdx @@ -0,0 +1,46 @@ +import { Steps } from 'nextra/components' +import { Callout } from '@/components' + +# 어떤 이유로 사용하나요? + + + +`@suspensive/codemods`는 실험 기능이므로 이 인터페이스는 변경될 수 있습니다. + + + +Codemods는 코드베이스 내에서 반복적이고 대규모로 발생하는 작업을 자동화하여 코드를 효율적으로 업데이트할 수 있는 강력한 도구입니다. 이를 통해 수많은 변경 사항을 수동으로 검토할 필요 없이 빠르고 안전하게 업데이트할 수 있습니다. + +Suspensive는 API 업데이트나 더 이상 사용되지 않는 API를 쉽게 관리할 수 있도록 Codemods를 제공합니다. + + + +### 대규모 API 변경을 쉽고 빠르게 처리할 수 있습니다. + +Suspensive 패키지를 사용하는 프로젝트에서는 패키지가 코드베이스 전역에서 활용되기 마련입니다. 이때 모든 사용처를 수동으로 찾고 수정하는 것은 많은 시간이 소요될 뿐만 아니라 실수할 가능성도 큽니다. + +```ansi +npx @suspensive/codemods +✔ Which transform would you like to apply? > tanstack-query-import +✔ On which files or directory should the codemods be applied? … . +Processing 130 files... +Spawning 10 workers... +Sending 13 files to free worker... +Sending 13 files to free worker... +... +All done. +Results: +0 errors +31 unmodified +0 skipped +99 ok +Time elapsed: 2.980 seconds +``` + +위 로그는 `@suspensive/react-query` & `@tanstack/react-query` v5 환경에서 `@deprecated`된 `@suspensive/react-query` API를 자동으로 전환하기 위해 [`tanstack-query-import`](/ko/docs/codemods/tanstackQueryImport) codemod를 실행한 결과입니다. 총 130개 파일 중 99개 파일이 단 2.980초 만에 변환되었습니다. + +### Suspensive 패키지를 쉽고 안전하게 업데이트할 수 있습니다. + +패키지의 메이저 업데이트에서는 종종 Break Change가 발생해 코드 마이그레이션이 복잡해집니다. Suspensive는 이러한 Break Change를 쉽게 관리할 수 있도록 Codemods를 통해 꼼꼼하게 지원할 예정입니다. Codemods를 사용하면 새로운 버전과 기능으로 빠르고 안전하게 업그레이드할 수 있습니다. + + diff --git a/docs/suspensive.org/src/pages/ko/docs/codemods/tanstackQueryImport.mdx b/docs/suspensive.org/src/pages/ko/docs/codemods/tanstackQueryImport.mdx new file mode 100644 index 000000000..eb1065d98 --- /dev/null +++ b/docs/suspensive.org/src/pages/ko/docs/codemods/tanstackQueryImport.mdx @@ -0,0 +1,31 @@ +import { Callout } from '@/components' + +# TanStack Query로 import 경로 변경 + + + +해당 codemod는 `@suspensive/react-query` & `@tanstack/react-query` v4 환경에서 `@tanstack/react-query`를 v5로 업데이트 하는 경우 추천합니다. + + + +```shell +npx @suspensive/codemods tanstack-query-import . +``` + +`@suspensive/react-query` & `@tanstack/react-query` v5 환경에서는 `@suspensive/react-query`가 제공하는 Suspense Hooks와 queryOptions가 `@deprecated`로 표시됩니다. 이는 `@tanstack/react-query` v5에 동일한 API인 Suspense Hooks와 queryOptions를 `@suspensive/react-query`가 제공하고 있어, 개발자가 `@tanstack/react-query`의 v5 API를 우선적으로 사용하도록 유도하기 위함입니다. + +이 codemod를 통해 `@suspensive/react-query`에서 `@tanstack/react-query` v5로 import 경로를 자동 변환할 수 있습니다. + +예: + +```tsx +import { queryOptions } from '@suspensive/react-query'; +import { useSuspenseQuery } from '@suspensive/react-query-5'; // 버전 패키지도 변환됩니다! +``` + +변환 후: + +```tsx +import { queryOptions } from '@tanstack/react-query'; +import { useSuspenseQuery } from '@tanstack/react-query'; +``` diff --git a/docs/suspensive.org/src/pages/ko/docs/codemods/usage.mdx b/docs/suspensive.org/src/pages/ko/docs/codemods/usage.mdx new file mode 100644 index 000000000..313e535b8 --- /dev/null +++ b/docs/suspensive.org/src/pages/ko/docs/codemods/usage.mdx @@ -0,0 +1,24 @@ +import { Callout } from '@/components' + +# 사용하기 + + + +`@suspensive/codemods`는 실험 기능이므로 이 인터페이스는 변경될 수 있습니다. + + + +단 하나의 명령어로 Suspensive의 Codemods를 실행할 수 있으며, 종속성으로 설치할 필요 없이 npx로 간편하게 사용할 수 있습니다. + +터미널에서 프로젝트 폴더로 이동한 후 다음 명령어를 실행하세요. + +[![npm version](https://img.shields.io/npm/v/@suspensive/codemods?color=000&labelColor=000&logo=npm)](https://www.npmjs.com/package/@suspensive/codemods) + +```shell +npx @suspensive/codemods +``` + +Codemod를 적용하고자 하는 환경에서 맞춰서 ``과 ``를 변경하세요. + +- ``: 실행할 Codemods의 이름 +- ``: 변환할 디렉터리 From 766a674679f6b431afa2de1e329b137399942d27 Mon Sep 17 00:00:00 2001 From: gwansikk Date: Thu, 7 Nov 2024 15:30:18 +0900 Subject: [PATCH 2/2] feat: update docs --- .../src/pages/en/docs/_meta.tsx | 13 ++---- .../src/pages/en/docs/codemods/_meta.tsx | 9 ++++ .../src/pages/en/docs/codemods/motivation.mdx | 46 +++++++++++++++++++ .../en/docs/codemods/tanstackQueryImport.mdx | 31 +++++++++++++ .../src/pages/en/docs/codemods/usage.mdx | 24 ++++++++++ .../src/pages/ko/docs/codemods/motivation.mdx | 4 +- .../ko/docs/codemods/tanstackQueryImport.mdx | 12 ++--- 7 files changed, 122 insertions(+), 17 deletions(-) create mode 100644 docs/suspensive.org/src/pages/en/docs/codemods/_meta.tsx create mode 100644 docs/suspensive.org/src/pages/en/docs/codemods/motivation.mdx create mode 100644 docs/suspensive.org/src/pages/en/docs/codemods/tanstackQueryImport.mdx create mode 100644 docs/suspensive.org/src/pages/en/docs/codemods/usage.mdx diff --git a/docs/suspensive.org/src/pages/en/docs/_meta.tsx b/docs/suspensive.org/src/pages/en/docs/_meta.tsx index cd043ba91..9b5073e38 100644 --- a/docs/suspensive.org/src/pages/en/docs/_meta.tsx +++ b/docs/suspensive.org/src/pages/en/docs/_meta.tsx @@ -3,15 +3,10 @@ export default { type: 'separator', title: 'Packages', }, - react: { - title: '@suspensive/react', - }, - 'react-query': { - title: '@suspensive/react-query', - }, - jotai: { - title: '@suspensive/jotai', - }, + react: { title: '@suspensive/react' }, + 'react-query': { title: '@suspensive/react-query' }, + jotai: { title: '@suspensive/jotai' }, + codemods: { title: '@suspensive/codemods' }, '--- More': { type: 'separator', title: 'More', diff --git a/docs/suspensive.org/src/pages/en/docs/codemods/_meta.tsx b/docs/suspensive.org/src/pages/en/docs/codemods/_meta.tsx new file mode 100644 index 000000000..08480b360 --- /dev/null +++ b/docs/suspensive.org/src/pages/en/docs/codemods/_meta.tsx @@ -0,0 +1,9 @@ +export default { + motivation: { title: 'Why need to use?' }, + usage: { title: 'Usage' }, + '--- Codemods': { + type: 'separator', + title: 'Codemods', + }, + tanstackQueryImport: { title: 'Migrate TanStack Query imports' }, +} diff --git a/docs/suspensive.org/src/pages/en/docs/codemods/motivation.mdx b/docs/suspensive.org/src/pages/en/docs/codemods/motivation.mdx new file mode 100644 index 000000000..592cca29b --- /dev/null +++ b/docs/suspensive.org/src/pages/en/docs/codemods/motivation.mdx @@ -0,0 +1,46 @@ +import { Steps } from 'nextra/components' +import { Callout } from '@/components' + +# Why need to use? + + + +`@suspensive/codemods` is an experimental feature, so this interface may change. + + + +Codemods are powerful tools that automate repetitive and large-scale tasks within a codebase, making code updates more efficient. They allow for fast and safe updates without the need to manually review numerous changes. + +Suspensive provides codemods to help manage API updates and deprecated APIs seamlessly. + + + +### Handle Large-Scale API Changes Quickly and Easily + +Projects using Suspensive packages often have these packages utilized globally across the codebase. Manually locating and modifying all usages is not only time-consuming but also prone to errors. + +```shell +npx @suspensive/codemods +✔ Which transform would you like to apply? > tanstack-query-import +✔ On which files or directory should the codemods be applied? … . +Processing 130 files... +Spawning 10 workers... +Sending 13 files to free worker... +Sending 13 files to free worker... +... +All done. +Results: +0 errors +31 unmodified +0 skipped +99 ok +Time elapsed: 2.980 seconds +``` + +The log above shows the result of running the [`tanstack-query-import`](/docs/codemods/tanstackQueryImport) codemod to automatically migrate the deprecated `@suspensive/react-query` API to `@tanstack/react-query` v5 in a `@suspensive/react-query` & `@tanstack/react-query` environment. Out of 130 files, 99 were transformed in just 2.980 seconds. + +## Update Suspensive Packages Easily and Safely + +Major updates to packages often introduce breaking changes that complicate code migration. Suspensive plans to thoroughly support these breaking changes through codemods, making management simpler. By using codemods, you can upgrade to new versions and features quickly and securely. + + diff --git a/docs/suspensive.org/src/pages/en/docs/codemods/tanstackQueryImport.mdx b/docs/suspensive.org/src/pages/en/docs/codemods/tanstackQueryImport.mdx new file mode 100644 index 000000000..7180b7aac --- /dev/null +++ b/docs/suspensive.org/src/pages/en/docs/codemods/tanstackQueryImport.mdx @@ -0,0 +1,31 @@ +import { Callout } from '@/components' + +# Migrate TanStack Query imports + + + +This codemod is recommended for updating `@suspensive/react-query` & `@tanstack/react-query` from v4 to v5. + + + +In the `@suspensive/react-query` & `@tanstack/react-query` v5 environment, Suspense Hooks and queryOptions provided by `@suspensive/react-query` are marked as deprecated. This is because `@suspensive/react-query` offers the same APIs (Suspense Hooks and queryOptions) that are available in `@tanstack/react-query` v5. The purpose is to encourage developers to use the v5 API from `@tanstack/react-query` directly. + +```shell +npx @suspensive/codemods tanstack-query-import . +``` + +This codemod automatically transforms import paths from `@suspensive/react-query` to `@tanstack/react-query` v5. + +Example: + +```tsx +import { queryOptions } from '@suspensive/react-query' +import { useSuspenseQuery } from '@suspensive/react-query-5' // The versioned package is also transformed! +``` + +After transformation: + +```tsx +import { queryOptions } from '@tanstack/react-query' +import { useSuspenseQuery } from '@tanstack/react-query' +``` diff --git a/docs/suspensive.org/src/pages/en/docs/codemods/usage.mdx b/docs/suspensive.org/src/pages/en/docs/codemods/usage.mdx new file mode 100644 index 000000000..1c305eec7 --- /dev/null +++ b/docs/suspensive.org/src/pages/en/docs/codemods/usage.mdx @@ -0,0 +1,24 @@ +import { Callout } from '@/components' + +# Usage + + + +`@suspensive/codemods` is an experimental feature, so this interface may change. + + + +You can run Suspensive's Codemods with a single command, easily using npx without the need to install it as a dependency. + +Navigate to your project folder in the terminal and run the following command: + +[![npm version](https://img.shields.io/npm/v/@suspensive/codemods?color=000&labelColor=000&logo=npm)](https://www.npmjs.com/package/@suspensive/codemods) + +```shell +npx @suspensive/codemods +``` + +Adjust `` and `` to match the environment where you want to apply the codemod. + +- ``: name of transform +- ``: files or directory to transform diff --git a/docs/suspensive.org/src/pages/ko/docs/codemods/motivation.mdx b/docs/suspensive.org/src/pages/ko/docs/codemods/motivation.mdx index fb4d9afdb..ed278d2db 100644 --- a/docs/suspensive.org/src/pages/ko/docs/codemods/motivation.mdx +++ b/docs/suspensive.org/src/pages/ko/docs/codemods/motivation.mdx @@ -19,7 +19,7 @@ Suspensive는 API 업데이트나 더 이상 사용되지 않는 API를 쉽게 Suspensive 패키지를 사용하는 프로젝트에서는 패키지가 코드베이스 전역에서 활용되기 마련입니다. 이때 모든 사용처를 수동으로 찾고 수정하는 것은 많은 시간이 소요될 뿐만 아니라 실수할 가능성도 큽니다. -```ansi +```shell npx @suspensive/codemods ✔ Which transform would you like to apply? > tanstack-query-import ✔ On which files or directory should the codemods be applied? … . @@ -37,7 +37,7 @@ Results: Time elapsed: 2.980 seconds ``` -위 로그는 `@suspensive/react-query` & `@tanstack/react-query` v5 환경에서 `@deprecated`된 `@suspensive/react-query` API를 자동으로 전환하기 위해 [`tanstack-query-import`](/ko/docs/codemods/tanstackQueryImport) codemod를 실행한 결과입니다. 총 130개 파일 중 99개 파일이 단 2.980초 만에 변환되었습니다. +위 로그는 `@suspensive/react-query` & `@tanstack/react-query` v5 환경에서 deprecated된 `@suspensive/react-query` API를 자동으로 전환하기 위해 [`tanstack-query-import`](/docs/codemods/tanstackQueryImport) codemod를 실행한 결과입니다. 총 130개 파일 중 99개 파일이 단 2.980초 만에 변환되었습니다. ### Suspensive 패키지를 쉽고 안전하게 업데이트할 수 있습니다. diff --git a/docs/suspensive.org/src/pages/ko/docs/codemods/tanstackQueryImport.mdx b/docs/suspensive.org/src/pages/ko/docs/codemods/tanstackQueryImport.mdx index eb1065d98..c4ecf57be 100644 --- a/docs/suspensive.org/src/pages/ko/docs/codemods/tanstackQueryImport.mdx +++ b/docs/suspensive.org/src/pages/ko/docs/codemods/tanstackQueryImport.mdx @@ -8,24 +8,24 @@ import { Callout } from '@/components' +`@suspensive/react-query` & `@tanstack/react-query` v5 환경에서는 `@suspensive/react-query`가 제공하는 Suspense Hooks와 queryOptions가 deprecated로 표시됩니다. 이는 `@tanstack/react-query` v5에 동일한 API인 Suspense Hooks와 queryOptions를 `@suspensive/react-query`가 제공하고 있어, 개발자가 `@tanstack/react-query`의 v5 API를 우선적으로 사용하도록 유도하기 위함입니다. + ```shell npx @suspensive/codemods tanstack-query-import . ``` -`@suspensive/react-query` & `@tanstack/react-query` v5 환경에서는 `@suspensive/react-query`가 제공하는 Suspense Hooks와 queryOptions가 `@deprecated`로 표시됩니다. 이는 `@tanstack/react-query` v5에 동일한 API인 Suspense Hooks와 queryOptions를 `@suspensive/react-query`가 제공하고 있어, 개발자가 `@tanstack/react-query`의 v5 API를 우선적으로 사용하도록 유도하기 위함입니다. - 이 codemod를 통해 `@suspensive/react-query`에서 `@tanstack/react-query` v5로 import 경로를 자동 변환할 수 있습니다. 예: ```tsx -import { queryOptions } from '@suspensive/react-query'; -import { useSuspenseQuery } from '@suspensive/react-query-5'; // 버전 패키지도 변환됩니다! +import { queryOptions } from '@suspensive/react-query' +import { useSuspenseQuery } from '@suspensive/react-query-5' // 버전 패키지도 변환됩니다! ``` 변환 후: ```tsx -import { queryOptions } from '@tanstack/react-query'; -import { useSuspenseQuery } from '@tanstack/react-query'; +import { queryOptions } from '@tanstack/react-query' +import { useSuspenseQuery } from '@tanstack/react-query' ```