react-vite-scaffold

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vite React Project Scaffold

Vite React项目脚手架

참고: https://www.heropy.dev/p/6iFzkB

Vite 기반 React(CSR) 프로젝트를 스캐폴딩하거나, 기존 프로젝트의 누락된 설정을 자동 보완하는 스킬.

参考: https://www.heropy.dev/p/6iFzkB

本工具可用于搭建基于Vite的React（CSR）项目脚手架，或自动补全现有项目缺失的配置。

동작 흐름

运行流程

1단계: 프로젝트 상태 감지

第1步：检测项目状态

다음 파일들을 확인하여 현재 프로젝트 상태를 판별한다:

확인 대상	감지 방법
빈 디렉토리 여부	현재 디렉토리에 파일이 없거나 `package.json` 이 없음
Vite 프로젝트	`vite.config.ts` 또는 `vite.config.js` 존재
TypeScript	`tsconfig.json` 또는 `tsconfig.app.json` 존재
TanStack Query	`package.json` 의 dependencies에 `@tanstack/react-query` 존재
React Router	`package.json` 의 dependencies에 `react-router` 존재
Zustand	`package.json` 의 dependencies에 `zustand` 존재
Tailwind CSS	`package.json` 의 dependencies/devDependencies에 `tailwindcss` 존재
ESLint 구성	`eslint.config.js` 또는 `eslint.config.mjs` 존재
Prettier 구성	`.prettierrc` 존재
VSCode 설정	`.vscode/settings.json` 존재
패키지 매니저	`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` / `bun.lock` → bun, `package-lock.json` 또는 없음 → npm

通过检查以下文件判断当前项目状态：

检测对象	检测方式
是否为空目录	当前目录下无文件，或不存在 `package.json`
Vite项目	存在 `vite.config.ts` 或 `vite.config.js`
TypeScript	存在 `tsconfig.json` 或 `tsconfig.app.json`
TanStack Query	`package.json` 的dependencies中存在 `@tanstack/react-query`
React Router	`package.json` 的dependencies中存在 `react-router`
Zustand	`package.json` 的dependencies中存在 `zustand`
Tailwind CSS	`package.json` 的dependencies/devDependencies中存在 `tailwindcss`
ESLint配置	存在 `eslint.config.js` 或 `eslint.config.mjs`
Prettier配置	存在 `.prettierrc`
VSCode设置	存在 `.vscode/settings.json`
包管理器	`pnpm-lock.yaml` → pnpm， `yarn.lock` → yarn， `bun.lockb` / `bun.lock` → bun，存在 `package-lock.json` 或无锁文件 → npm

2단계: 분기 처리

第2步：分支处理

빈 디렉토리인 경우 (스캐폴딩 모드):

프로젝트 생성 명령 실행
아래 설정 전부 자동 적용

기존 Vite 프로젝트인 경우 (보완 모드):

위 감지 기준으로 설치 상태 자동 판별
누락된 설정만 식별하여 자동 생성
이미 존재하는 설정 파일은 건드리지 않음

如果是空目录（脚手架模式）：

执行项目创建命令
自动应用下方所有配置

如果是现有Vite项目（补全模式）：

按照上述检测标准自动判断安装状态
仅识别并自动生成缺失的配置
不修改已经存在的配置文件

3단계: 프로젝트 생성

第3步：创建项目

현재 디렉토리에 Vite 프로젝트 생성:

bash

{pm} create vite@latest .

{pm}
은 패키지 매니저 감지 규칙에 따라 결정된 패키지 매니저로 대체한다. (npm, pnpm, yarn, bun)

대화형 선택지:

Current directory is not empty. Please choose how to proceed: Ignore files and continue (디렉토리에
```
.claude/
```
등 스킬 관련 파일이 있는 경우 표시됨)
Select a framework: React
Select a variant: TypeScript + React Compiler
Use rolldown-vite (Experimental)?: No
Install with npm and start now? Yes

요구사항: Node.js 18+, NPM 8+

在当前目录下创建Vite项目：

bash

{pm} create vite@latest .

{pm}
会替换为根据包管理器检测规则判定的包管理器（npm、pnpm、yarn、bun）。

交互式选项：

Current directory is not empty. Please choose how to proceed: Ignore files and continue（目录下存在
```
.claude/
```
等工具相关文件时会显示该选项）
Select a framework: React
Select a variant: TypeScript + React Compiler
Use rolldown-vite (Experimental)?: No
Install with npm and start now? Yes

环境要求：Node.js 18+，NPM 8+

4단계: Tailwind CSS 설치

第4步：安装Tailwind CSS

bash

{pm} install -D tailwindcss @tailwindcss/vite

vite.config.ts

에 Tailwind 플러그인 추가:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    react(),
    tailwindcss()
  ],
  resolve: {
    alias: [
      { find: '@', replacement: '/src' }
    ]
  }
})

src/index.css

파일 상단에 추가:

css

@import 'tailwindcss';

bash

{pm} install -D tailwindcss @tailwindcss/vite

在

vite.config.ts

中添加Tailwind插件：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    react(),
    tailwindcss()
  ],
  resolve: {
    alias: [
      { find: '@', replacement: '/src' }
    ]
  }
})

在

src/index.css

文件顶部添加：

css

@import 'tailwindcss';

5단계: 경로 별칭 구성

第5步：配置路径别名

vite.config.ts

의

resolve.alias

설정 (위 코드에 포함됨):

resolve: {
  alias: [
    { find: '@', replacement: '/src' }
  ]
}

tsconfig.app.json

에 경로 별칭 추가:

json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

vite.config.ts

中的

resolve.alias

配置（已包含在上述代码中）：

resolve: {
  alias: [
    { find: '@', replacement: '/src' }
  ]
}

在

tsconfig.app.json

中添加路径别名：

json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

6단계: ESLint + Prettier 구성

第6步：配置ESLint + Prettier

ESLint 관련 패키지는 Vite 프로젝트 생성 시 이미 포함되어 있음. Prettier 관련 패키지를 추가 설치:

bash

{pm} install -D prettier eslint-config-prettier eslint-plugin-prettier prettier-plugin-tailwindcss

eslint.config.js

에 Prettier 통합 추가:

import prettierRecommended from 'eslint-plugin-prettier/recommended'

export default defineConfig([
  {
    extends: [
      prettierRecommended
    ]
  }
])

TanStack Query가 포함된 경우, 같은

extends

배열에 추가:

import prettierRecommended from 'eslint-plugin-prettier/recommended'
import tanstackQuery from '@tanstack/eslint-plugin-query'

export default defineConfig([
  {
    extends: [
      prettierRecommended,
      tanstackQuery.configs.recommended
    ]
  }
])

ESLint相关包在创建Vite项目时已默认包含。额外安装Prettier相关包：

bash

{pm} install -D prettier eslint-config-prettier eslint-plugin-prettier prettier-plugin-tailwindcss

在

eslint.config.js

中添加Prettier集成：

import prettierRecommended from 'eslint-plugin-prettier/recommended'

export default defineConfig([
  {
    extends: [
      prettierRecommended
    ]
  }
])

如果项目包含TanStack Query，在同一个

extends

数组中添加配置：

import prettierRecommended from 'eslint-plugin-prettier/recommended'
import tanstackQuery from '@tanstack/eslint-plugin-query'

export default defineConfig([
  {
    extends: [
      prettierRecommended,
      tanstackQuery.configs.recommended
    ]
  }
])

패키지 역할 참고

包作用参考

패키지	설명
`eslint`	ESLint 코어 패키지 (Vite에 포함)
`prettier`	Prettier 코어 패키지
`eslint-plugin-react`	React 문법 분석 및 검사 (Vite에 포함)
`eslint-config-prettier`	ESLint와 Prettier의 충돌 방지
`eslint-plugin-prettier`	Prettier 규칙을 ESLint 규칙으로 통합
`eslint-plugin-react-hooks`	React Hooks 규칙 강제 (Vite에 포함)
`eslint-plugin-react-refresh`	React Refresh 규칙 (Vite에 포함)
`prettier-plugin-tailwindcss`	Tailwind CSS 클래스 자동 정렬
`@tanstack/eslint-plugin-query`	TanStack Query 규칙 (TanStack Query 사용 시)

包名	说明
`eslint`	ESLint核心包（Vite已内置）
`prettier`	Prettier核心包
`eslint-plugin-react`	React语法分析与校验（Vite已内置）
`eslint-config-prettier`	避免ESLint与Prettier规则冲突
`eslint-plugin-prettier`	将Prettier规则整合为ESLint规则
`eslint-plugin-react-hooks`	强制React Hooks规则（Vite已内置）
`eslint-plugin-react-refresh`	React Refresh规则（Vite已内置）
`prettier-plugin-tailwindcss`	自动排序Tailwind CSS类名
`@tanstack/eslint-plugin-query`	TanStack Query规则（使用TanStack Query时需要）

7단계: .prettierrc

第7步：生成.prettierrc

.prettierrc

파일이 없으면 프로젝트 루트에 생성:

json

{
  "semi": false,
  "singleQuote": true,
  "singleAttributePerLine": true,
  "bracketSameLine": true,
  "endOfLine": "auto",
  "trailingComma": "none",
  "arrowParens": "avoid",
  "plugins": ["prettier-plugin-tailwindcss"]
}

如果不存在

.prettierrc

文件，在项目根目录创建该文件：

json

{
  "semi": false,
  "singleQuote": true,
  "singleAttributePerLine": true,
  "bracketSameLine": true,
  "endOfLine": "auto",
  "trailingComma": "none",
  "arrowParens": "avoid",
  "plugins": ["prettier-plugin-tailwindcss"]
}

8단계: .vscode/settings.json

第8步：生成.vscode/settings.json

.vscode/settings.json

파일이 없으면 생성:

json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

如果不存在

.vscode/settings.json

文件，创建该文件：

json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

9단계: TanStack Query

第9步：配置TanStack Query

@tanstack/react-query

가

package.json

에 없으면:

패키지 설치:

bash

{pm} install @tanstack/react-query
{pm} install -D @tanstack/eslint-plugin-query

ESLint Flat Config(
```
eslint.config.js
```
)에 TanStack Query 플러그인 추가 (6단계 참조)

src/App.tsx

에서 QueryClientProvider 래핑:

tsx

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* 기존 컴포넌트 */}
    </QueryClientProvider>
  )
}

如果

package.json

中没有

@tanstack/react-query

：

安装包：

bash

{pm} install @tanstack/react-query
{pm} install -D @tanstack/eslint-plugin-query

在ESLint Flat Config（
```
eslint.config.js
```
）中添加TanStack Query插件（参考第6步）

在

src/App.tsx

中用QueryClientProvider包裹组件：

tsx

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* 原有组件 */}
    </QueryClientProvider>
  )
}

10단계: React Router

第10步：配置React Router

참고: https://www.heropy.dev/p/9tesDt

react-router

가

package.json

에 없으면:

패키지 설치:
bash
```
{pm} install react-router
```

src/routes/index.tsx

생성:

tsx

import { createBrowserRouter, RouterProvider } from 'react-router'
import Home from './pages/Home'
import About from './pages/About'

const router = createBrowserRouter([
  {
    path: '/',
    element: <Home />
  },
  {
    path: '/about',
    element: <About />
  }
])

export default function Router() {
  return <RouterProvider router={router} />
}

src/routes/pages/Home.tsx

생성:

tsx

export default function Home() {
  return <h1>Home</h1>
}

src/routes/pages/About.tsx

생성:

tsx

export default function About() {
  return <h1>About</h1>
}

src/main.tsx

에서

Router

를 사용하도록 수정:

tsx

import { createRoot } from 'react-dom/client'
import Router from './routes'

createRoot(document.getElementById('root')!).render(<Router />)

参考: https://www.heropy.dev/p/9tesDt

如果

package.json

中没有

react-router

：

安装包：
bash
```
{pm} install react-router
```

生成

src/routes/index.tsx

：

tsx

import { createBrowserRouter, RouterProvider } from 'react-router'
import Home from './pages/Home'
import About from './pages/About'

const router = createBrowserRouter([
  {
    path: '/',
    element: <Home />
  },
  {
    path: '/about',
    element: <About />
  }
])

export default function Router() {
  return <RouterProvider router={router} />
}

生成

src/routes/pages/Home.tsx

：

tsx

export default function Home() {
  return <h1>Home</h1>
}

生成

src/routes/pages/About.tsx

：

tsx

export default function About() {
  return <h1>About</h1>
}

修改

src/main.tsx

使用

Router

：

tsx

import { createRoot } from 'react-dom/client'
import Router from './routes'

createRoot(document.getElementById('root')!).render(<Router />)

11단계: Zustand

第11步：配置Zustand

참고: https://www.heropy.dev/p/n74Tgc

zustand

가

package.json

에 없으면:

패키지 설치:
bash
```
{pm} install zustand
```

src/store/example.ts

생성:

import { create } from 'zustand'

interface ExampleStore {
  count: number
  increase: () => void
  decrease: () => void
}

export const useExampleStore = create<ExampleStore>(set => ({
  count: 0,
  increase: () => set(state => ({ count: state.count + 1 })),
  decrease: () => set(state => ({ count: state.count - 1 }))
}))

参考: https://www.heropy.dev/p/n74Tgc

如果

package.json

中没有

zustand

：

安装包：
bash
```
{pm} install zustand
```

生成

src/store/example.ts

：

import { create } from 'zustand'

interface ExampleStore {
  count: number
  increase: () => void
  decrease: () => void
}

export const useExampleStore = create<ExampleStore>(set => ({
  count: 0,
  increase: () => set(state => ({ count: state.count + 1 })),
  decrease: () => set(state => ({ count: state.count - 1 }))
}))

주의사항

注意事项

이미 존재하는 설정 파일은 덮어쓰지 않는다
기존 프로젝트 보완 모드에서는 질문 없이 자동으로 진행한다
패키지 매니저는 기존 프로젝트의 lock 파일로 판별한다:
- ```
pnpm-lock.yaml
```
  →
```
pnpm
```
- ```
yarn.lock
```
  →
```
yarn
```
- ```
bun.lockb
```
  또는
```
bun.lock
```
  →
```
bun
```
- ```
package-lock.json
```
  또는 lock 파일 없음 →
```
npm
```
빈 디렉토리(스캐폴딩 모드)에서는
```
npm
```
을 사용한다

不会覆盖已经存在的配置文件
现有项目补全模式下无需人工确认，自动执行
根据现有项目的锁文件判定包管理器：
- ```
pnpm-lock.yaml
```
  →
```
pnpm
```
- ```
yarn.lock
```
  →
```
yarn
```
- ```
bun.lockb
```
  或
```
bun.lock
```
  →
```
bun
```
- 存在
```
package-lock.json
```
  或无锁文件 →
```
npm
```
空目录（脚手架模式）下默认使用
```
npm
```