Skip to content

Commit

Permalink
feat: update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
gwansikk committed Nov 7, 2024
1 parent 8a40e0a commit 766a674
Show file tree
Hide file tree
Showing 7 changed files with 122 additions and 17 deletions.
13 changes: 4 additions & 9 deletions docs/suspensive.org/src/pages/en/docs/_meta.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
9 changes: 9 additions & 0 deletions docs/suspensive.org/src/pages/en/docs/codemods/_meta.tsx
Original file line number Diff line number Diff line change
@@ -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' },
}
46 changes: 46 additions & 0 deletions docs/suspensive.org/src/pages/en/docs/codemods/motivation.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
import { Steps } from 'nextra/components'
import { Callout } from '@/components'

# Why need to use?

<Callout type='experimental'>

`@suspensive/codemods` is an experimental feature, so this interface may change.

</Callout>

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.

<Steps>

### 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.

</Steps>
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
import { Callout } from '@/components'

# Migrate TanStack Query imports

<Callout type='info'>

This codemod is recommended for updating `@suspensive/react-query` & `@tanstack/react-query` from v4 to v5.

</Callout>

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'
```
24 changes: 24 additions & 0 deletions docs/suspensive.org/src/pages/en/docs/codemods/usage.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
import { Callout } from '@/components'

# Usage

<Callout type='experimental'>

`@suspensive/codemods` is an experimental feature, so this interface may change.

</Callout>

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 <transform> <path>
```

Adjust `<transform>` and `<path>` to match the environment where you want to apply the codemod.

- `<transform>`: name of transform
- `<path>`: files or directory to transform
4 changes: 2 additions & 2 deletions docs/suspensive.org/src/pages/ko/docs/codemods/motivation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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?.
Expand All @@ -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 패키지를 쉽고 안전하게 업데이트할 수 있습니다.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,24 +8,24 @@ import { Callout } from '@/components'

</Callout>

`@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'
```

0 comments on commit 766a674

Please sign in to comment.