📑 프로젝트 기초 세팅 가이드

블로그

1. 프로젝트 기본 환경 세팅

🧩 Git 초기 세팅

# README 생성
echo "# 제목" >> README.md

# Git 초기화
git init

# 파일 Git 등록
git add README.md

# 첫 커밋
git commit -m "first commit"

# 기본 브랜치를 main으로 변경
git branch -M main

# 원격 저장소 연결
git remote add origin <레포지토리 주소>

# 원격 저장소에 첫 push
git push -u origin main

⚙️ Next.js 프로젝트 생성

npx create-next-app@latest .

# 실행 중 선택 추천:
# TypeScript: Yes → 타입 안정성 확보
# ESLint: Yes → 코드 컨벤션 유지
# Tailwind CSS: 선택/Yes → 빠른 UI 스타일링
# src/ directory: Yes → 구조 깔끔
# App Router: 선택/Yes → 최신 구조 사용
# Import alias: Yes → @/*
# Turbopack: No → 안정성 우선

2. 코드 품질 & 개발 생산성 도구

🚂 ESLint

# 1. ESLint 설치
npm install -D eslint
# JS/TS 코드 문법과 스타일 검사

# 2. TypeScript ESLint Parser 설치
npm install -D @typescript-eslint/parser
# ESLint가 TypeScript 코드를 이해하도록 함

# 3. TypeScript ESLint Plugin 설치
npm install -D @typescript-eslint/eslint-plugin
# TypeScript 전용 규칙 제공

# ESLint 설정 파일 생성
npx eslint --init
# 자동으로 .eslintrc.js 또는 eslint.config.mjs 생성

// eslint.config.mjs
import tsPlugin from '@typescript-eslint/eslint-plugin';
import parser from '@typescript-eslint/parser';
import pluginImport from 'eslint-plugin-import';
import perfectionist from 'eslint-plugin-perfectionist';
import simpleImportSort from 'eslint-plugin-simple-import-sort';

export default [
  {
    files: ['**/*.{js,jsx,ts,tsx}'],
    ignores: ['node_modules', '.next', 'dist'],
    languageOptions: {
      parser,
      parserOptions: {
        ecmaVersion: 'latest',
        sourceType: 'module',
        ecmaFeatures: { jsx: true },
        project: './tsconfig.json',
      },
    },
    plugins: {
      import: pluginImport,
      'simple-import-sort': simpleImportSort,
      '@typescript-eslint': tsPlugin,
      perfectionist,
    },
    rules: {
      'simple-import-sort/imports': 'error',
      'simple-import-sort/exports': 'error',
      'perfectionist/sort-jsx-props': [
        'error',
        {
          type: 'natural',
          order: 'asc',
          groups: ['multiline', 'unknown', 'shorthand'],
        },
      ],
      'perfectionist/sort-objects': [
        'error',
        { type: 'natural', order: 'asc' },
      ],
      'perfectionist/sort-array-includes': 'off',
      'no-unused-vars': 'warn',
      '@typescript-eslint/no-unused-vars': [
        'warn',
        { argsIgnorePattern: '^_' },
      ],
    },
  },
];

✨ Prettier

# Prettier 설치
npm install -D prettier

# ESLint + Prettier 충돌 방지 설정
npm install -D eslint-config-prettier

# Tailwind Prettier 플러그인 설치
npm install -D prettier-plugin-tailwindcss

// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "tabWidth": 2,
  "useTabs": false,
  "printWidth": 80,
  "arrowParens": "always",
  "endOfLine": "lf",
  "plugins": ["prettier-plugin-tailwindcss"]
}

🪁 ESLint + Prettier

# 설정 통합 : 한 번에 설치 가능
npm install -D eslint prettier eslint-config-prettier @typescript-eslint/parser @typescript-eslint/eslint-plugin prettier-plugin-tailwindcss eslint-plugin-simple-import-sort eslint-plugin-perfectionist

🐶 Husky

# Husky 설치
npm install -D husky

# Husky 초기화
npx husky install

// package.json 스크립트 추가, Git Hook 관리 도구
"scripts": {
  "prepare": "husky install"
}

📝 lint-staged

# lint-staged 설치
npm install -D lint-staged

# pre-commit 훅 생성
mkdir -p .husky
echo "npx lint-staged" > .husky/pre-commit
chmod +x .husky/pre-commit

// package.json에 lint-staged 설정
// 커밋 대상 파일만 자동으로 ESLint + Prettier 적용
// Husky pre-commit 훅과 함께 사용
"lint-staged": {
  "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{json,css,md}": ["prettier --write"]
}

⚙️ VSCode settings.json

// 저장할 때 ESLint + Prettier 자동 실행
// import 정렬과 코드 포맷 적용
{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "explicit"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "eslint.useFlatConfig": true
}

3. UI & 스타일 시스템

🌹 Tailwind CSS (v4)

# Tailwind CSS 설치
npm install tailwindcss

# globals.css 파일 상단에 Tailwind import 추가
@import "tailwindcss";

# layout.tsx 또는 앱 entry 파일에 globals.css import
import './globals.css';

🌷 shadcn/ui

# shadcn/ui 설치
npx shadcn@latest init

🩹 clsx + cva

# className 조건부 합치기 라이브러리
npm install clsx

# Tailwind + Variants 쉽게 관리 (cva)
npm install class-variance-authority

🌟 SVGR

# SVGR 설치
npm install @svgr/webpack --save-dev

// next.config.ts 설정
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  webpack(config) {
    config.module.rules.push({
      test: /\.svg$/i,
      issuer: /\.[jt]sx?$/,
      use: ['@svgr/webpack'],
    });
    return config;
  },
};

export default nextConfig;

// svg.d.ts 생성
declare module '*.svg' {
  import React from 'react';
  export const ReactComponent: React.FC<React.SVGProps<SVGSVGElement>>;
  const src: string;
  export default src;
}

4. 상태 관리 & 서버 상태

🧸 Zustand

# Zustand 설치
npm install zustand

🛹 React Query + QueryProvider

# React Query 설치
npm install @tanstack/react-query
npm install @tanstack/react-query-devtools

// src/components/QueryProvider.tsx
'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { ReactNode, useState } from 'react';

export default function QueryProvider({ children }: { children: ReactNode }) {
  const [queryClient] = useState(() => new QueryClient());

  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

5. 폼 / 검증 / 애니메이션 / 아이콘 / 유틸

🔩 Zod

# Zod 설치
npm install zod

🔧 React Hook Form + @hookform/resolvers

# React Hook Form 설치
npm install react-hook-form

# Resolvers 설치 (Zod 등 연동용)
npm install @hookform/resolvers

🧭 Axios

# Axios 설치
npm install axios

🖍️ Framer Motion

# Framer Motion 설치
npm install framer-motion

🤹🏻‍♂️ Lucide React

# Lucide React 설치
npm install lucide-react