Next.js React Project Scaffold

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

동작 흐름

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

package.json

next.config.ts

next.config.js

next.config.mjs

tsconfig.json

package.json

@tanstack/react-query

package.json

tailwindcss

eslint.config.js

eslint.config.mjs

.prettierrc

.vscode/settings.json

pnpm-lock.yaml

yarn.lock

bun.lockb

bun.lock

package-lock.json

2단계: 분기 처리

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

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

3단계: 프로젝트 생성

{pm}

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

{pmx}

는 해당 패키지 매니저의 실행 명령어로 대체한다. (npx, pnpm dlx, yarn dlx, bunx)

참고:

npx skills add

로 스킬을 설치하면

.agents/

,

skills-lock.json

등의 파일이 이미 존재할 수 있다.

create-next-app

은 디렉토리에 파일이 있으면 충돌로 판단하고 종료되므로, 스캐폴딩 모드에서는 다음 절차를 따른다:

1. 현재 디렉토리의 기존 파일/폴더 목록을 기억해 둔다
2. 기존 파일/폴더를 모두 삭제한다

3. {pmx} create-next-app@latest .

   명령으로 프로젝트를 생성한다
4. 기억해 둔 파일/폴더 중 프로젝트 생성으로 만들어지지 않은 것들(

   .agents/

   ,

   skills-lock.json

   등)을 다시 생성한다

{pmx} create-next-app@latest .

• Would you like to use the recommended Next.js defaults?: No, customize settings
• Would you like to use TypeScript?: Yes
• Which linter would you like to use?: ESLint
• Would you like to use React Compiler?: Yes
• Would you like to use Tailwind CSS?: Yes
• Would you like your code inside a

  src/

  directory?: Yes
• Would you like to use App Router? (recommended): Yes
• Would you like to customize the import alias (

  @/*

  by default)?: No

4단계: 경로 별칭

@/*

create-next-app

5단계: ESLint + Prettier 구성

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

eslint.config.js

eslint.config.mjs

import prettierRecommended from 'eslint-config-prettier'

const eslintConfig = defineConfig([
  {
    extends: [prettierRecommended]
  }
])

export default eslintConfig

extends

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

const eslintConfig = defineConfig([
  {
    extends: [
      prettierRecommended,
      tanstackQuery.configs.recommended
    ]
  }
])

export default eslintConfig

패키지 역할 참고

prettier

eslint-config-prettier

eslint-plugin-prettier

prettier-plugin-tailwindcss

@tanstack/eslint-plugin-query

6단계: .prettierrc

.prettierrc

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

7단계: .vscode/settings.json

.vscode/settings.json

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

8단계: TanStack Query

참고: https://www.heropy.dev/p/HZaKIE#h2_with_Nextjs

@tanstack/react-query

package.json

@tanstack/react-query-next-experimental

1. 패키지 설치:
   bash

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

2. ESLint Flat Config(

   eslint.config.js

   )에 TanStack Query 플러그인 추가 (5단계 참조)

3. src/providers/query.tsx

   생성:
   tsx

   'use client'
   import {
     QueryClient,
     QueryClientProvider,
     isServer,
   } from '@tanstack/react-query'
   import { ReactQueryStreamedHydration } from '@tanstack/react-query-next-experimental'
   
   function makeQueryClient() {
     return new QueryClient({
       defaultOptions: {
         queries: {
           // 클라이언트의 즉시 다시 요청에 대응하도록, 기본 캐싱 시간(min)을 지정
           staleTime: 60 * 1000
         }
       }
     })
   }
   
   let browserQueryClient: QueryClient | undefined = undefined
   
   function getQueryClient() {
     if (isServer) {
       return makeQueryClient()
     } else {
       if (!browserQueryClient) browserQueryClient = makeQueryClient()
       return browserQueryClient
     }
   }
   
   export function QueryProvider({ children }: { children: React.ReactNode }) {
     const queryClient = getQueryClient()
     return (
       <QueryClientProvider client={queryClient}>
         <ReactQueryStreamedHydration>
           {children}
         </ReactQueryStreamedHydration>
       </QueryClientProvider>
     )
   }

4. src/app/layout.tsx

   에서

   QueryProvider

   로

   children

   을 래핑:
   tsx

   import { QueryProvider } from '@/providers/query'
   
   export default function RootLayout({
     children
   }: Readonly<{
     children: React.ReactNode
   }>) {
     return (
       <html lang="ko">
         <body>
           <QueryProvider>{children}</QueryProvider>
         </body>
       </html>
     )
   }

주의사항

• 이미 존재하는 설정 파일은 덮어쓰지 않는다
• 기존 프로젝트 보완 모드에서는 질문 없이 자동으로 진행한다
• 패키지 매니저는 기존 프로젝트의 lock 파일로 판별한다:

  • pnpm-lock.yaml

    →

    pnpm

  • yarn.lock

    →

    yarn

  • bun.lockb

    또는

    bun.lock

    →

    bun

  • package-lock.json

    또는 lock 파일 없음 →

    npm

• 빈 디렉토리(스캐폴딩 모드)에서는

  npm

  을 사용한다