Next.js 프로젝트에서 AI IDE 글로벌 룰 설정하기: 일관성 있는 코드베이스 만들기

AI 기반 개발 도구가 일상화된 지금, 프로젝트 전반에 걸쳐 일관된 코딩 스타일과 규칙을 유지하는 것이 더욱 중요해졌습니다. 특히 Next.js 프로젝트에서는 페이지, 컴포넌트, API 라우트 등 다양한 영역에서 통일된 패턴을 유지해야 하는데, 이때 글로벌 룰(Global Rule) 설정이 핵심적인 역할을 합니다.

글로벌 룰이란 무엇이며 왜 중요한가?

글로벌 룰은 프로젝트 전체에 적용되는 공통 규칙과 패턴을 의미합니다. AI IDE에서 이러한 룰을 설정하면, 코드 생성 시 자동으로 프로젝트의 컨벤션을 따르도록 할 수 있습니다. 예를 들어, 모든 컴포넌트에서 동일한 props 검증 방식을 사용하거나, API 라우트에서 일관된 에러 핸들링 패턴을 적용하는 것이 가능해집니다.

이러한 글로벌 룰의 핵심 이점은 다음과 같습니다. 팀원들이 서로 다른 스타일로 코드를 작성하더라도 AI가 자동으로 프로젝트 컨벤션에 맞춰 코드를 생성하므로 코드 리뷰 시간이 줄어들고, 새로운 팀원의 온보딩이 빨라집니다. 또한 프로젝트가 커질수록 유지보수성이 크게 향상됩니다.

Next.js 프로젝트 구조와 글로벌 룰 적용 영역

Next.js 프로젝트에서 글로벌 룰이 적용되는 주요 영역을 살펴보겠습니다.

my-nextjs-project/
├── .cursorrules               # Cursor AI IDE 글로벌 룰 파일
├── .anthropic/               # Claude 관련 설정
│   └── project_instructions.md
├── app/                      # App Router (Next.js 13+)
│   ├── layout.tsx           # 글로벌 레이아웃
│   ├── page.tsx
│   ├── globals.css          # 글로벌 스타일
│   └── api/                 # API 라우트
├── components/              # 재사용 컴포넌트
├── lib/                     # 유틸리티 함수
├── hooks/                   # 커스텀 훅
├── types/                   # TypeScript 타입 정의
├── eslint.config.js         # ESLint 설정
├── prettier.config.js       # Prettier 설정
└── tsconfig.json           # TypeScript 설정

글로벌 룰은 이 모든 영역에서 일관된 패턴을 보장합니다. 예를 들어, 컴포넌트 생성 시 항상 TypeScript 인터페이스를 먼저 정의하고, API 라우트에서는 표준화된 응답 형식을 사용하도록 강제할 수 있습니다.

AI IDE별 글로벌 룰 설정 방법

Cursor IDE에서의 설정

Cursor IDE는 .cursorrules 파일을 통해 프로젝트 전체에 적용되는 룰을 설정할 수 있습니다. 프로젝트 루트에 다음과 같은 파일을 생성하세요.

// .cursorrules

You are an expert Next.js developer. Always follow these rules when generating code:

## General Rules
- Use TypeScript for all files
- Use functional components with hooks
- Implement proper error boundaries
- Follow Next.js 14+ App Router conventions
- Use Tailwind CSS for styling

## Component Structure
- Always define TypeScript interfaces before component implementation
- Use named exports for components
- Include proper JSDoc comments
- Implement loading and error states

Example component structure:
```tsx
interface ButtonProps {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary';
  onClick?: () => void;
  disabled?: boolean;
}

/**
 * Reusable button component with variants
 */
export function Button({ 
  children, 
  variant = 'primary', 
  onClick, 
  disabled = false 
}: ButtonProps) {
  return (
    <button
      className={`px-4 py-2 rounded transition-colors ${
        variant === 'primary' 
          ? 'bg-blue-600 hover:bg-blue-700 text-white' 
          : 'bg-gray-200 hover:bg-gray-300 text-gray-800'
      }`}
      onClick={onClick}
      disabled={disabled}
    >
      {children}
    </button>
  );
}

API Routes

• Always use proper HTTP status codes
• Implement consistent error handling
• Use Zod for request validation
• Return standardized response format

API Response format:

{
  success: boolean;
  data?: any;
  error?: {
    message: string;
    code?: string;
  };
}

File Naming

• Use kebab-case for file names (user-profile.tsx)
• Use PascalCase for component names
• Use camelCase for function and variable names

State Management

• Use Zustand for global state
• Use React Query for server state
• Implement optimistic updates where appropriate

Claude (Anthropic)에서의 설정

Claude를 사용하는 경우, .anthropic/project_instructions.md 파일을 생성하여 프로젝트별 지침을 설정할 수 있습니다.

<!-- .anthropic/project_instructions.md -->

# Next.js 프로젝트 개발 가이드라인

## 프로젝트 개요
이 프로젝트는 Next.js 14 App Router를 사용하는 TypeScript 기반 웹 애플리케이션입니다.

## 코딩 컨벤션

### 컴포넌트 작성 규칙
1. 모든 컴포넌트는 TypeScript로 작성
2. Props 인터페이스를 반드시 정의
3. 기본값은 함수 매개변수에서 설정
4. JSDoc 주석 포함

### 폴더 구조
- `/app`: 페이지 및 레이아웃
- `/components`: 재사용 가능한 UI 컴포넌트
- `/lib`: 유틸리티 함수 및 설정
- `/hooks`: 커스텀 React 훅
- `/types`: TypeScript 타입 정의

### 스타일링
- Tailwind CSS 우선 사용
- CSS Modules는 복잡한 애니메이션에만 사용
- styled-components 사용 금지

### 상태 관리
- 로컬 상태: useState, useReducer
- 글로벌 상태: Zustand
- 서버 상태: React Query (TanStack Query)

## 예제 템플릿

### 페이지 컴포넌트
```tsx
import { Metadata } from 'next';

export const metadata: Metadata = {
  title: '페이지 제목',
  description: '페이지 설명',
};

interface PageProps {
  params: { id: string };
  searchParams: { [key: string]: string | string[] | undefined };
}

export default function Page({ params, searchParams }: PageProps) {
  return (
    <div className="container mx-auto p-4">
      <h1 className="text-2xl font-bold mb-4">페이지 제목</h1>
      {/* 페이지 내용 */}
    </div>
  );
}

## 공통 패턴별 글로벌 룰 예시

### 인증 관련 패턴

인증이 필요한 모든 페이지와 컴포넌트에서 일관된 패턴을 사용하도록 설정할 수 있습니다.

```typescript
// lib/auth-patterns.ts

// 글로벌 룰: 모든 보호된 페이지는 이 패턴을 따라야 함
export const protectedPageTemplate = `
import { redirect } from 'next/navigation';
import { getServerSession } from 'next-auth';
import { authOptions } from '@/lib/auth';

export default async function ProtectedPage() {
  const session = await getServerSession(authOptions);

  if (!session) {
    redirect('/login');
  }

  return (
    <div className="min-h-screen bg-gray-50">
      {/* 보호된 페이지 내용 */}
    </div>
  );
}
`;

// 글로벌 룰: 클라이언트 컴포넌트에서 인증 확인
export const useAuthRedirect = `
'use client';

import { useSession } from 'next-auth/react';
import { useRouter } from 'next/navigation';
import { useEffect } from 'react';

export function useAuthRedirect(redirectTo: string = '/login') {
  const { data: session, status } = useSession();
  const router = useRouter();

  useEffect(() => {
    if (status === 'loading') return;
    if (!session) {
      router.push(redirectTo);
    }
  }, [session, status, router, redirectTo]);

  return { session, isLoading: status === 'loading' };
}
`;

데이터 페칭 패턴

모든 데이터 페칭에서 일관된 로딩 상태와 에러 처리를 보장하는 패턴입니다.

// hooks/use-api.ts

// 글로벌 룰: 모든 API 호출은 이 훅을 사용
export const useApiTemplate = `
import { useQuery, useMutation } from '@tanstack/react-query';
import { toast } from 'sonner';

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    message: string;
    code?: string;
  };
}

export function useApiQuery<T>(
  key: string[],
  fetcher: () => Promise<ApiResponse<T>>,
  options?: {
    enabled?: boolean;
    onSuccess?: (data: T) => void;
    onError?: (error: Error) => void;
  }
) {
  return useQuery({
    queryKey: key,
    queryFn: async () => {
      const response = await fetcher();
      if (!response.success) {
        throw new Error(response.error?.message || 'API 요청에 실패했습니다.');
      }
      return response.data;
    },
    enabled: options?.enabled,
    onSuccess: options?.onSuccess,
    onError: (error: Error) => {
      toast.error(error.message);
      options?.onError?.(error);
    },
  });
}
`;

에러 핸들링 패턴

프로젝트 전체에서 일관된 에러 처리 방식을 적용하는 패턴입니다.

// app/error.tsx

// 글로벌 룰: 모든 에러 페이지는 이 구조를 따름
'use client';

import { useEffect } from 'react';
import { Button } from '@/components/ui/button';

interface ErrorProps {
  error: Error & { digest?: string };
  reset: () => void;
}

export default function Error({ error, reset }: ErrorProps) {
  useEffect(() => {
    // 에러 로깅 서비스에 전송
    console.error('Error boundary caught:', error);
  }, [error]);

  return (
    <div className="min-h-screen flex items-center justify-center bg-gray-50">
      <div className="max-w-md w-full bg-white rounded-lg shadow-lg p-6 text-center">
        <h2 className="text-xl font-semibold text-gray-900 mb-2">
          문제가 발생했습니다
        </h2>
        <p className="text-gray-600 mb-4">
          페이지를 불러오는 중 오류가 발생했습니다. 잠시 후 다시 시도해주세요.
        </p>
        <Button onClick={reset} className="w-full">
          다시 시도
        </Button>
      </div>
    </div>
  );
}

ESLint, Prettier와의 통합 설정

글로벌 룰이 다른 개발 도구와 충돌하지 않도록 통합 설정을 구성하는 것이 중요합니다.

// eslint.config.js
import { fixupConfigRules } from '@eslint/compat';
import nextConfig from 'eslint-config-next';

export default [
  ...fixupConfigRules(nextConfig),
  {
    rules: {
      // AI IDE 글로벌 룰과 일치하는 ESLint 규칙
      '@typescript-eslint/consistent-type-definitions': ['error', 'interface'],
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      'react/function-component-definition': [
        'error',
        { namedComponents: 'function-declaration' }
      ],
      'import/order': [
        'error',
        {
          groups: [
            'builtin',
            'external',
            'internal',
            'parent',
            'sibling',
            'index'
          ],
          'newlines-between': 'always',
          alphabetize: { order: 'asc', caseInsensitive: true }
        }
      ]
    }
  }
];

// prettier.config.js
export default {
  // AI IDE 글로벌 룰과 일치하는 Prettier 설정
  semi: true,
  singleQuote: true,
  tabWidth: 2,
  trailingComma: 'es5',
  printWidth: 80,
  bracketSpacing: true,
  arrowParens: 'avoid',
  endOfLine: 'lf',
  // Next.js 특화 설정
  plugins: ['prettier-plugin-tailwindcss'],
  tailwindConfig: './tailwind.config.js',
};

실무에서 자주 발생하는 실수와 해결책

실수 1: 글로벌 룰이 특정 파일에서 무시되는 경우

문제상황: AI IDE가 일부 파일에서 글로벌 룰을 적용하지 않는 경우가 있습니다.

해결책: 파일별로 명시적인 주석을 추가하여 AI가 룰을 인식하도록 합니다.

// components/special-component.tsx

/**
 * @ai-instruction 이 컴포넌트는 프로젝트 글로벌 룰을 따라야 합니다.
 * - TypeScript 인터페이스 정의 필수
 * - Tailwind CSS 사용
 * - 에러 바운더리 포함
 */

interface SpecialComponentProps {
  // props 정의
}

export function SpecialComponent(props: SpecialComponentProps) {
  // 구현
}

실수 2: 글로벌 룰과 기존 코드 스타일 충돌

문제상황: 기존 프로젝트에 글로벌 룰을 적용할 때 일관성이 깨지는 경우입니다.

해결책: 점진적 마이그레이션 전략을 사용합니다.

// migration-guide.md

## 단계별 글로벌 룰 적용 계획

### 1단계: 새로운 파일만 글로벌 룰 적용
- 새로 생성되는 컴포넌트와 페이지에만 적용
- 기존 파일은 수정 시에만 룰 적용

### 2단계: 핵심 컴포넌트 마이그레이션
- 자주 사용되는 공통 컴포넌트부터 변경
- 한 번에 하나의 컴포넌트씩 마이그레이션

### 3단계: 전체 프로젝트 일관성 확보
- 모든 파일에 글로벌 룰 적용
- 자동화 스크립트로 일괄 변경

실수 3: 너무 엄격한 글로벌 룰 설정

문제상황: 지나치게 세부적인 룰로 인해 개발 속도가 저하되는 경우입니다.

해결책: 핵심 패턴에만 집중하고 점진적으로 룰을 추가합니다.

// .cursorrules (권장하지 않는 예시)

// ❌ 너무 세부적인 룰
- Every variable must have exactly 3 characters minimum
- All functions must have try-catch blocks
- Every component must have exactly 5 props

// ✅ 적절한 수준의 룰
- Use TypeScript interfaces for component props
- Implement consistent error handling patterns
- Follow Next.js App Router conventions

글로벌 룰 유지보수 가이드

프로젝트가 성장함에 따라 글로벌 룰도 함께 발전해야 합니다. 다음과 같은 주기적인 점검과 업데이트 프로세스를 권장합니다.

월간 룰 리뷰: 팀원들의 피드백을 수집하여 불편한 룰이나 개선이 필요한 부분을 파악합니다. 새로운 Next.js 기능이나 라이브러리 업데이트에 맞춰 룰을 조정합니다.

분기별 대규모 업데이트: 프로젝트 구조 변경이나 새로운 아키텍처 도입 시 글로벌 룰을 전면 재검토합니다. 팀의 개발 패턴 변화를 반영하여 룰을 개선합니다.

버전 관리: 글로벌 룰 파일도 Git으로 버전 관리하여 변경 사항을 추적하고, 필요시 이전 버전으로 롤백할 수 있도록 합니다.

마무리 및 정리 작업

글로벌 룰 설정이 완료되면 다음과 같은 정리 작업을 수행하세요.

테스트 설정 제거: 글로벌 룰 테스트 중 생성된 임시 파일이나 실험적인 설정을 삭제합니다. 프로덕션에서 사용하지 않는 개발용 규칙은 주석 처리하거나 제거합니다.

문서 업데이트: 팀원들이 참고할 수 있도록 글로벌 룰 설정 방법과 주요 패턴을 README.md에 문서화합니다. 새로운 팀원을 위한 온보딩 가이드에 글로벌 룰 활용법을 포함시킵니다.

지속적인 개선: 글로벌 룰은 한 번 설정하고 끝나는 것이 아닙니다. 프로젝트의 발전과 팀의 성장에 맞춰 지속적으로 개선해 나가는 것이 중요합니다. 정기적인 리뷰를 통해 더 나은 개발 경험을 만들어가시기 바랍니다.

AI IDE의 글로벌 룰을 통해 Next.js 프로젝트의 일관성과 품질을 크게 향상시킬 수 있습니다. 이러한 설정은 초기 투자 시간 대비 장기적으로 엄청난 생산성 향상을 가져다줄 것입니다.

React 성능 최적화: useMemo vs React.memo 완벽 가이드

React 애플리케이션이 커지면서 성능 이슈를 마주하게 되었나요? 컴포넌트가 불필요하게 다시 렌더링되거나, 무거운 계산이 반복되어 앱이 느려지는 경험을 해보셨을 것입니다. 오늘은 이런 문제를 해결하는 두 가지 핵심 도구인 useMemo와 React.memo의 차이점과 올바른 사용법을 알아보겠습니다.

🎯 한 줄 요약부터 시작하기

useMemo: "계산 결과를 메모장에 적어두기" - 비싼 계산을 반복하지 않기 위해
React.memo: "똑같은 정보로 문서를 다시 인쇄하지 않기" - 동일한 props로 컴포넌트를 다시 렌더링하지 않기 위해

💡 왜 이 두 도구가 필요한가요?

React는 기본적으로 부모 컴포넌트가 리렌더링되면 모든 자식 컴포넌트도 함께 리렌더링됩니다. 대부분의 경우 이는 문제가 되지 않지만, 복잡한 계산이나 많은 데이터를 다루는 컴포넌트에서는 성능 병목이 될 수 있습니다.

📝 useMemo: 계산 결과 메모이제이션

언제 사용하나요?

useMemo는 무거운 계산의 결과값을 메모이제이션할 때 사용합니다. 의존성이 변하지 않는 한 이전에 계산한 결과를 재사용합니다.

실제 코드로 살펴보기

import React, { useState, useMemo } from 'react';

function ProductList({ products, searchTerm }) {
  const [sortBy, setSortBy] = useState('name');

  // ❌ 잘못된 예: 매번 계산이 실행됨
  const badFilteredProducts = products
    .filter(product => product.name.includes(searchTerm))
    .sort((a, b) => a[sortBy] > b[sortBy] ? 1 : -1);

  // ✅ 올바른 예: searchTerm이나 sortBy가 바뀔 때만 계산
  const filteredProducts = useMemo(() => {
    console.log('필터링 및 정렬 실행!'); // 언제 실행되는지 확인용
    return products
      .filter(product => product.name.includes(searchTerm))
      .sort((a, b) => a[sortBy] > b[sortBy] ? 1 : -1);
  }, [products, searchTerm, sortBy]);

  return (
    <div>
      <select onChange={e => setSortBy(e.target.value)}>
        <option value="name">이름순</option>
        <option value="price">가격순</option>
      </select>
      {filteredProducts.map(product => (
        <div key={product.id}>{product.name} - {product.price}원</div>
      ))}
    </div>
  );
}

🤔 이 코드는 어떤 조건에서 다시 실행될까요?
useMemo 안의 계산은 products, searchTerm, sortBy 중 하나라도 변경될 때만 실행됩니다. 다른 state가 변경되어 컴포넌트가 리렌더링되어도 이 계산은 건너뛰게 됩니다.

⚠️ 주의사항
간단한 계산에는 useMemo를 사용하지 마세요. 메모이제이션 자체에도 비용이 들기 때문에 오히려 성능이 나빠질 수 있습니다.

🎭 React.memo: 컴포넌트 렌더링 메모이제이션

언제 사용하나요?

React.memo는 컴포넌트 전체의 렌더링을 메모이제이션할 때 사용합니다. props가 변하지 않는 한 이전 렌더링 결과를 재사용합니다.

실제 코드로 살펴보기

import React, { useState, memo } from 'react';

// ❌ 메모이제이션되지 않은 컴포넌트
function ExpensiveComponent({ data, onUpdate }) {
  console.log('ExpensiveComponent 렌더링!'); // 매번 실행됨

  // 복잡한 렌더링 로직이라고 가정
  const processedData = data.map(item => ({
    ...item,
    formatted: `${item.name} (${item.category})`
  }));

  return (
    <div>
      {processedData.map(item => (
        <div key={item.id} onClick={() => onUpdate(item.id)}>
          {item.formatted}
        </div>
      ))}
    </div>
  );
}

// ✅ 메모이제이션된 컴포넌트
const MemoizedExpensiveComponent = memo(function ExpensiveComponent({ data, onUpdate }) {
  console.log('MemoizedExpensiveComponent 렌더링!'); // props가 바뀔 때만 실행

  const processedData = data.map(item => ({
    ...item,
    formatted: `${item.name} (${item.category})`
  }));

  return (
    <div>
      {processedData.map(item => (
        <div key={item.id} onClick={() => onUpdate(item.id)}>
          {item.formatted}
        </div>
      ))}
    </div>
  );
});

// 부모 컴포넌트
function ParentComponent() {
  const [count, setCount] = useState(0);
  const [data] = useState([
    { id: 1, name: '상품A', category: '전자기기' },
    { id: 2, name: '상품B', category: '의류' }
  ]);

  const handleUpdate = (id) => {
    console.log('상품 업데이트:', id);
  };

  return (
    <div>
      <button onClick={() => setCount(count + 1)}>
        카운트: {count}
      </button>

      {/* count가 변경되어도 MemoizedExpensiveComponent는 리렌더링되지 않음 */}
      <MemoizedExpensiveComponent data={data} onUpdate={handleUpdate} />
    </div>
  );
}

🤔 이 컴포넌트는 언제 다시 렌더링될까요?
React.memo로 감싼 컴포넌트는 data나 onUpdate props가 실제로 변경될 때만 리렌더링됩니다. 부모의 count state가 변경되어도 렌더링되지 않습니다.

커스텀 비교 함수 사용하기

const MemoizedComponent = memo(MyComponent, (prevProps, nextProps) => {
  // true를 반환하면 리렌더링하지 않음
  // false를 반환하면 리렌더링함
  return prevProps.data.length === nextProps.data.length &&
         prevProps.isVisible === nextProps.isVisible;
});

📊 한눈에 보는 차이점

🎯 두 기법을 함께 사용하기: TodoList 예제

실제 프로젝트에서는 두 기법을 함께 사용하는 경우가 많습니다. TodoList 앱을 예로 살펴보겠습니다.

import React, { useState, useMemo, memo, useCallback } from 'react';

// 개별 할 일 아이템 컴포넌트 (React.memo로 최적화)
const TodoItem = memo(function TodoItem({ todo, onToggle, onDelete }) {
  console.log(`TodoItem ${todo.id} 렌더링`);

  return (
    <div className={`todo-item ${todo.completed ? 'completed' : ''}`}>
      <input
        type="checkbox"
        checked={todo.completed}
        onChange={() => onToggle(todo.id)}
      />
      <span>{todo.text}</span>
      <button onClick={() => onDelete(todo.id)}>삭제</button>
    </div>
  );
});

function TodoApp() {
  const [todos, setTodos] = useState([
    { id: 1, text: 'React 공부하기', completed: false },
    { id: 2, text: '운동하기', completed: true },
    { id: 3, text: '블로그 글쓰기', completed: false }
  ]);
  const [filter, setFilter] = useState('all'); // all, active, completed
  const [newTodo, setNewTodo] = useState('');

  // useMemo로 필터링된 할 일 목록 최적화
  const filteredTodos = useMemo(() => {
    console.log('할 일 목록 필터링 실행');
    switch (filter) {
      case 'active':
        return todos.filter(todo => !todo.completed);
      case 'completed':
        return todos.filter(todo => todo.completed);
      default:
        return todos;
    }
  }, [todos, filter]);

  // useMemo로 통계 계산 최적화
  const stats = useMemo(() => {
    const total = todos.length;
    const completed = todos.filter(todo => todo.completed).length;
    const active = total - completed;
    return { total, completed, active };
  }, [todos]);

  // useCallback으로 함수 최적화 (React.memo와 함께 사용)
  const handleToggle = useCallback((id) => {
    setTodos(todos => todos.map(todo =>
      todo.id === id ? { ...todo, completed: !todo.completed } : todo
    ));
  }, []);

  const handleDelete = useCallback((id) => {
    setTodos(todos => todos.filter(todo => todo.id !== id));
  }, []);

  const addTodo = () => {
    if (newTodo.trim()) {
      setTodos(todos => [...todos, {
        id: Date.now(),
        text: newTodo,
        completed: false
      }]);
      setNewTodo('');
    }
  };

  return (
    <div className="todo-app">
      <h1>할 일 관리</h1>

      {/* 통계 정보 */}
      <div className="stats">
        전체: {stats.total} | 완료: {stats.completed} | 미완료: {stats.active}
      </div>

      {/* 새 할 일 추가 */}
      <div className="add-todo">
        <input
          value={newTodo}
          onChange={e => setNewTodo(e.target.value)}
          placeholder="새 할 일을 입력하세요"
          onKeyPress={e => e.key === 'Enter' && addTodo()}
        />
        <button onClick={addTodo}>추가</button>
      </div>

      {/* 필터 버튼 */}
      <div className="filters">
        {['all', 'active', 'completed'].map(filterType => (
          <button
            key={filterType}
            className={filter === filterType ? 'active' : ''}
            onClick={() => setFilter(filterType)}
          >
            {filterType === 'all' ? '전체' : 
             filterType === 'active' ? '미완료' : '완료'}
          </button>
        ))}
      </div>

      {/* 할 일 목록 */}
      <div className="todo-list">
        {filteredTodos.map(todo => (
          <TodoItem
            key={todo.id}
            todo={todo}
            onToggle={handleToggle}
            onDelete={handleDelete}
          />
        ))}
      </div>
    </div>
  );
}

export default TodoApp;

💡 이 예제에서 최적화 포인트

• useMemo: 필터링된 할 일 목록과 통계 계산을 캐싱
• React.memo: 각 TodoItem 컴포넌트의 불필요한 리렌더링 방지
• useCallback: 콜백 함수를 메모이제이션하여 React.memo와 시너지 효과

⚠️ 주의사항과 모범 사례

언제 사용하지 말아야 할까요?

// ❌ 나쁜 예시들
function BadExamples() {
  // 간단한 계산에 useMemo 사용 (오버엔지니어링)
  const simpleSum = useMemo(() => a + b, [a, b]);

  // 의존성 배열을 빈 배열로 설정 (버그 유발 가능)
  const buggyCalculation = useMemo(() => 
    expensiveFunction(data), []
  ); // data 변경을 감지하지 못함

  // 매번 새로운 객체/함수를 props로 전달 (React.memo 무력화)
  return (
    <MemoizedComponent 
      data={{ value: 1 }} // 매번 새 객체
      onUpdate={() => {}} // 매번 새 함수
    />
  );
}

✅ 좋은 사용법

function GoodExamples({ items, searchTerm }) {
  // 복잡한 계산에만 useMemo 사용
  const expensiveCalculation = useMemo(() => {
    return items
      .filter(item => item.name.toLowerCase().includes(searchTerm.toLowerCase()))
      .sort((a, b) => a.score - b.score)
      .slice(0, 100);
  }, [items, searchTerm]);

  // 객체/함수는 별도로 메모이제이션
  const config = useMemo(() => ({ 
    theme: 'dark', 
    pageSize: 10 
  }), []);

  const handleUpdate = useCallback((id) => {
    // 업데이트 로직
  }, []);

  return (
    <MemoizedComponent 
      data={expensiveCalculation}
      config={config}
      onUpdate={handleUpdate}
    />
  );
}

💡 팁: Next.js에서의 활용
Next.js의 Server Components와 Client Components를 구분할 때도 이런 최적화 기법들이 중요합니다. 특히 하이드레이션 과정에서 불필요한 계산을 줄이는 데 도움이 됩니다.

🔍 내 프로젝트에 적용해보기: 자가 진단 체크리스트

useMemo 적용 체크리스트

• 복잡한 계산이나 데이터 변환 로직이 있나요?
• 그 계산이 렌더링마다 실행되고 있나요?
• 계산에 사용되는 값들을 의존성 배열로 정확히 지정했나요?
• 정말로 성능 개선이 필요한 부분인가요? (측정해보셨나요?)

React.memo 적용 체크리스트

• 컴포넌트가 자주 리렌더링되나요?
• props가 자주 변경되지 않나요?
• 부모 컴포넌트의 다른 state 변경 시에도 리렌더링되나요?
• 콜백 함수들을 useCallback으로 메모이제이션했나요?

함께 사용할 때 체크리스트

• 컴포넌트에 전달하는 객체나 배열을 useMemo로 안정화했나요?
• 이벤트 핸들러를 useCallback으로 메모이제이션했나요?
• 과도한 최적화로 코드가 복잡해지지 않았나요?

🎉 마무리

useMemo와 React.memo는 각각 다른 영역의 성능을 최적화하는 도구입니다. 핵심을 다시 정리하면:

• useMemo: 비싼 계산의 결과를 캐싱
• React.memo: 동일한 props일 때 컴포넌트 렌더링을 스킵

하지만 가장 중요한 것은 측정 후 최적화입니다. React DevTools Profiler를 사용해서 실제 성능 병목을 찾아낸 후, 그 부분에만 선택적으로 적용하는 것이 좋습니다. 무분별한 최적화는 오히려 코드를 복잡하게 만들고 버그를 유발할 수 있으니까요.

Next.js 프로젝트에서 이런 최적화 기법들을 적절히 활용하면 사용자 경험을 크게 개선할 수 있습니다. 여러분의 프로젝트에도 한번 적용해보세요!

🚀 다음 단계
이제 useCallback과 함께 사용하는 방법, 그리고 React 18의 concurrent features와의 조합에 대해서도 알아보시면 더욱 깊이 있는 최적화가 가능합니다.

Next.js RSC(React Server Components)란? 초보자도 쉽게 이해하는 가이드

웹 개발을 하다 보면 "페이지가 빨리 로드되었으면 좋겠다"는 생각을 자주 하게 됩니다. Next.js의 RSC(React Server Components)는 바로 이런 고민을 해결해주는 새로운 기술입니다.

🤔 RSC가 뭐길래?

RSC를 한 줄로 설명하면 "서버에서 미리 만들어서 보내주는 React 컴포넌트"입니다.

기존에는 이런 식으로 작동했어요:

1. 사용자가 웹사이트 접속
2. 빈 HTML + JavaScript 파일 다운로드
3. JavaScript가 실행되면서 화면을 그림

RSC는 이렇게 바뀝니다:

1. 사용자가 웹사이트 접속
2. 서버에서 이미 완성된 HTML을 받음
3. 훨씬 빠르게 화면이 나타남!

🏠 집 짓기로 비유해보자

기존 방식(CSR)은 건축 자재만 배송받고 현장에서 집을 짓는 것 같아요. 시간이 오래 걸리죠.

RSC는 공장에서 미리 조립한 프리팹 하우스를 배송받는 것과 비슷합니다. 현장에 도착하자마자 바로 살 수 있어요!

📊 기존 방식과 뭐가 다른가요?

전통적인 CSR (Client-Side Rendering)

// 브라우저에서 실행
function UserProfile() {
  const [user, setUser] = useState(null);

  useEffect(() => {
    // 페이지 로드 후 API 호출
    fetch('/api/user').then(setUser);
  }, []);

  if (!user) return <div>로딩중...</div>;
  return <div>안녕하세요, {user.name}님!</div>;
}

문제점: 페이지 → JavaScript 로드 → API 호출 → 화면 그리기 (느려요! 😵‍💫)

Next.js RSC 방식

// 서버에서 실행
async function UserProfile() {
  // 서버에서 미리 데이터 가져오기
  const user = await fetch('https://api.example.com/user').then(r => r.json());

  // 완성된 HTML을 클라이언트에 전송
  return <div>안녕하세요, {user.name}님!</div>;
}

장점: 사용자가 접속하자마자 완성된 화면을 볼 수 있어요! ⚡

🎯 RSC의 핵심 장점

1. 빠른 초기 로딩

• 서버에서 미리 HTML을 만들어서 보내주니까 화면이 빨리 나타나요
• 사용자는 "로딩중..." 화면을 덜 보게 됩니다

2. SEO 친화적

• 검색엔진이 페이지 내용을 쉽게 읽을 수 있어요
• 완성된 HTML이 있으니까 크롤링이 수월합니다

3. 더 작은 JavaScript 번들

• 서버 컴포넌트는 클라이언트로 전송되지 않아요
• 브라우저에서 다운로드할 파일이 줄어듭니다

💻 실제로 어떻게 사용하나요?

Next.js 13+ 버전에서는 기본적으로 모든 컴포넌트가 서버 컴포넌트입니다.

서버 컴포넌트 예시

// app/page.js - 기본적으로 서버 컴포넌트
async function HomePage() {
  // 서버에서 데이터 가져오기
  const posts = await fetch('https://api.blog.com/posts').then(r => r.json());

  return (
    <div>
      <h1>블로그 포스트</h1>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.summary}</p>
        </article>
      ))}
    </div>
  );
}

export default HomePage;

클라이언트 컴포넌트가 필요한 경우

'use client' // 이 지시어로 클라이언트 컴포넌트 만들기

import { useState } from 'react';

function LikeButton() {
  const [likes, setLikes] = useState(0);

  return (
    <button onClick={() => setLikes(likes + 1)}>
      👍 {likes}
    </button>
  );
}

🤷‍♂️ 언제 뭘 써야 하나요?

서버 컴포넌트를 쓰세요:

• 데이터를 가져와서 보여주기만 하는 경우
• 블로그 글, 상품 목록, 사용자 프로필 등
• SEO가 중요한 페이지

클라이언트 컴포넌트를 쓰세요:

• 사용자와 상호작용이 필요한 경우
• 버튼 클릭, 폼 입력, 애니메이션 등
• useState, useEffect 같은 React Hook을 사용할 때

🔄 둘이 함께 사용하기

// 서버 컴포넌트
async function ProductPage({ id }) {
  const product = await fetch(`/api/products/${id}`).then(r => r.json());

  return (
    <div>
      {/* 서버에서 렌더링된 정적 내용 */}
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <img src={product.image} alt={product.name} />

      {/* 인터랙티브한 클라이언트 컴포넌트 */}
      <AddToCartButton productId={id} />
      <ReviewForm productId={id} />
    </div>
  );
}

🎉 정리하면

RSC는 웹사이트를 더 빠르고 효율적으로 만들어주는 Next.js의 신기술입니다.

핵심 포인트:

• 서버에서 미리 HTML을 만들어서 보내줘요
• 초기 로딩이 빨라지고 SEO에 좋아요
• 상호작용이 필요한 부분만 클라이언트 컴포넌트로 만들면 돼요
• Next.js 13+에서는 기본값이라 특별히 설정할 것도 없어요

처음에는 "어떤 걸 서버에서, 어떤 걸 클라이언트에서 처리할지" 고민될 수 있지만, 실제로 써보면 생각보다 직관적이에요. 데이터만 보여주면 서버, 클릭이나 입력이 있으면 클라이언트라고 생각하시면 됩니다!

🔗 함께 보면 좋은 링크

• Next.js 공식 문서 - Server Components
• React 공식 문서 - Server Components
• Vercel - Understanding React Server Components

Next.js Link의 prefetch={false}: 언제 그리고 왜 사용해야 할까?

Next.js의 <Link> 컴포넌트는 기본적으로 링크된 페이지를 미리 가져오는 프리패치(prefetch) 기능을 제공합니다. 하지만 때로는 이 기능을 비활성화해야 하는 경우가 있습니다. 마치 여행 전에 모든 짐을 미리 싸두는 것이 때로는 불필요할 수 있는 것처럼 말이죠.

기본 개념: Next.js의 프리패치란?

Next.js에서 <Link> 컴포넌트는 기본적으로 prefetch={true}로 설정되어 있습니다. 이는 사용자가 링크를 클릭하기 전에 해당 페이지의 JavaScript 번들을 미리 다운로드한다는 의미입니다.

// 기본 동작 - 프리패치가 활성화됨
<Link href="/about">
  소개 페이지로 이동
</Link>

// 명시적으로 프리패치 비활성화
<Link href="/dashboard" prefetch={false}>
  대시보드로 이동
</Link>

기본 프리패치는 뷰포트에 링크가 나타날 때 자동으로 트리거됩니다. 이로 인해 사용자가 실제로 클릭할 때 페이지가 즉시 로드되어 더 빠른 사용자 경험을 제공합니다.

프리패치를 비활성화해야 하는 경우

1. 거의 사용되지 않는 링크

모든 사용자가 클릭하지 않을 링크들은 불필요한 네트워크 트래픽을 발생시킵니다.

function Footer() {
  return (
    <footer>
      <Link href="/privacy-policy" prefetch={false}>
        개인정보처리방침
      </Link>
      <Link href="/terms-of-service" prefetch={false}>
        이용약관
      </Link>
      {/* 대부분의 사용자가 클릭하지 않는 링크들 */}
    </footer>
  );
}

2. 조건부로 표시되는 링크

특정 조건에서만 나타나는 링크는 프리패치할 필요가 없습니다.

function UserProfile({ user, isAdmin }) {
  return (
    <div>
      <h1>{user.name}</h1>
      {isAdmin && (
        <Link href="/admin-panel" prefetch={false}>
          관리자 패널
        </Link>
      )}
    </div>
  );
}

3. 큰 번들 크기를 가진 페이지

대용량 페이지나 많은 의존성을 가진 페이지는 선택적으로 로드하는 것이 좋습니다.

function NavigationMenu() {
  return (
    <nav>
      <Link href="/">홈</Link>
      <Link href="/products">제품</Link>
      {/* 차트 라이브러리 등 큰 번들을 가진 페이지 */}
      <Link href="/analytics" prefetch={false}>
        분석 대시보드
      </Link>
    </nav>
  );
}

성능 측면에서의 고려사항

장점

• 네트워크 대역폭 절약: 불필요한 리소스 다운로드를 방지합니다
• 초기 로딩 성능 향상: 현재 페이지의 로딩에 집중할 수 있습니다
• 모바일 친화적: 제한된 데이터 환경에서 특히 유용합니다

단점

• 클릭 후 지연: 사용자가 링크를 클릭할 때 추가 로딩 시간이 발생합니다
• 사용자 경험 저하: 즉시 페이지 전환을 기대하는 사용자에게는 아쉬울 수 있습니다

개발자 도구로 프리패치 확인하기

브라우저의 개발자 도구 Network 탭에서 프리패치 동작을 확인할 수 있습니다:

// 이 컴포넌트로 테스트해보세요
function TestPrefetch() {
  return (
    <div>
      <Link href="/page1">프리패치 있음</Link>
      <Link href="/page2" prefetch={false}>프리패치 없음</Link>
    </div>
  );
}

Network 탭에서 "page1"에 대한 요청이 링크가 뷰포트에 나타날 때 자동으로 발생하는 것을 확인할 수 있습니다.

실용적인 가이드라인

프리패치를 유지해야 하는 경우

• 메인 네비게이션 링크
• 사용자가 자주 방문하는 페이지
• 작은 번들 크기를 가진 페이지

프리패치를 비활성화해야 하는 경우

• 푸터의 법적 문서 링크
• 관리자 전용 페이지
• 외부 리소스가 많은 페이지
• 조건부로 표시되는 링크

핵심 정리

prefetch={false}는 성능 최적화를 위한 강력한 도구입니다. 모든 링크에 적용할 필요는 없지만, 사용자 경험과 성능 사이의 균형을 맞추는 데 도움이 됩니다.

기억할 점:

• 기본값은 prefetch={true}입니다
• 거의 사용되지 않는 링크에는 prefetch={false}를 사용하세요
• 개발자 도구로 실제 동작을 확인해보세요
• Lighthouse를 통해 번들 분석을 진행하세요

더 자세한 정보는 Next.js 공식 문서를 참고하시기 바랍니다.