Taeeun Kim
Next.js

Next.js 프로젝트 셋팅

Taeeun Kim
2025년 5월 29일
목차

모든 프로젝트는 올바른 셋팅에서 시작된다. 이번 과제를 통해 Next.js 프로젝트의 셋팅 과정과 주요 설정 방법을 정리해보자.

Next.js 프로젝트 시작하기

우선 설치하기 전에 사용자 시스템이 이 두가지 조건을 만족해야한다

  • MacOs, Windows, 아니면 Linux

  • Node.js 18.18 이상

    node -v          ## 버전 확인 커맨드 
-> v22.13.1      ## 현재 node 버전

설치 방법:

  1. create-next-app 을 사용해 자동으로 프로젝트를 셋업 해준다
npx create-next-app@latest
  • 이때 latest 는 최신 버전을 뜻하며 블로그 작성 시점의 최신 버전은 15.3.2 이다.

❗ Next.js 11~15 버전 일부에서 심각한 보안 취약점이 발견되었는데, 인증 없이 보호된 리소스에 접근 가능한 위험이 있어 패치된 버전(15.2.3 이상) 으로 업데이트가 필요하다. 꼭 버전 확인할 것.
자세히 보기 → https://github.com/vercel/next.js/security/advisories/GHSA-f82v-jwr5-mffw

  1. 설치 시 여러 프롬프트가 표시된다:
What is your project named? my-app
Would you like to use TypeScript? No / 
Yes 
 
Would you like to use ESLint? No / 
Yes
 
Would you like to use Tailwind CSS? No / 
Yes
 
Would you like your code inside a `src/` directory? 
No
 / 
Yes
 
Would you like to use App Router? (recommended) No / 
Yes
 
Would you like to use Turbopack for `next dev`?  No / 
Yes
 
Would you like to customize the import alias (`@/*` by default)? 
No
 / Yes
What import alias would you like configured? @/*
  • Typescript는 코드 안전성을 위해, ESLint는 코드 품질과 스타일 유지를 위해, Tailwind CSS 는 개발 속도와 간편함을 위해 yes 로 하겠다.
  • src 디렉토리 설정은 개인의 취향에 따라 다를 수 있을 것 같다.
  • App Router 와 Page Router 의 차이는 나중에 따로 다룰 것 같지만 Next 에서는 현재 App Router 를 추천한다.
  • turbopack 은 기존의 webpack 보다 훨씬 빠르게 코드 수정을 반영해주는 유용한 도구이다.
  • import를 할 때 사용할 얼라이어스를 설정하는데 대부분 default 를 사용한다.

질문이 끝나면 create-next-app 이 알아서 프로젝트 폴더를 만들고 필요한 의존성 패키지를 설치한다.

package.json 을 보면 미리 지정된 스크립트가 보일 것이다.

"scripts": {
    "dev": "next dev --turbopack", // 개발 모드 실행. 실시간 변경 반영 및 디버깅 용이
    "build": "next build", // 프로덕션 빌드. 코드 최적화 및 정적 파일 생성
    "start": "next start", // 빌드된 결과물로 앱 실행. 실제 배포 환경과 동일
    "lint": "next lint", // ESLint 실행. 규칙에 따라 코드 품질 검사
  },

Typescript 설정

이미 Next.js 를 설치할때 적당한 Typescript 설정이 되어있으며 tsconfig.json 과 package.json 을 보면 확인할 수 있다. 확장자 하나만 간단히 소개하고 넘어가겠다.

Screenshot_2025-05-28_at_8.18.07_PM.png

Always-on Next.js TypeScript Plugin

  • Next.js 프로젝트에서 TypeScript를 쓸 때 TS 지원을 자동으로 해주는 확장 프로그램
  • 적용방법:
    1. Ctrl/⌘ + Shift + P 로 명령 팔레트 열기
    2. "TypeScript: Select TypeScript Version" 입력
    3. "Use Workspace Version" 선택
  • 이 설정은 팀 전체가 동일한 TypeScript 버전을 사용하며 Next.js에서 요구하는 TS 기능도 안전하게 사용할 수 있게 도와준다.

Screenshot_2025-05-28_at_8.26.51_PM.png

설치 후 Metadata 위에 커서를 올려보면 위의 이미지처럼 해당 스펙 설명이 나온다.

ESLint, Prettier 설정

Next.js 프로젝트에서 코드 품질과 일관성을 유지하기 위해 ESLint 와 Prettier 를 설정해준다. Next 에서는 이미 ES Lint 가 설치되어 있으며 Lint 검사를 npm run lint 로 할 수 있다.

  • eslint: 코드 품질 검사
  • prettier: 코드 스타일 포매터

Prettier 설치 방법:

  1. Prettier 설치
npm install --save-dev prettier eslint-config-prettier
  1. .prettierrc 루트에 만들고 설정
// 설정 예시
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100,
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "auto",
  "plugins": ["prettier-plugin-tailwindcss"]
}
  1. eslintConfigPrettier 를 eslint.config.mjs 에 꼭 import 해서 eslintConfig 안에 명시한다.

편의성을 위해 package.json 에 관련 스크립트를 추가한다.

{
  "scripts": {
    "lint": "next lint",
    "lint:fix": "next lint --fix", // Lint 검사 후 자동으로 코드를 고친다
    "format": "prettier --write",  // 자동으로 prettier 규칙을 따르게 변경한다
  }
}

추천 플러그인:

TailwindCSS v4 설치 및 최적화

최근에 TailwindCSS 가 버전 업데이트를 거쳤는데 현 시점에는 Next 에서 버전 업그레이드를 반영해 의존성 패키지를 올바르게 설치한 걸 볼 수 있다.

만약 나중에 Next 에서 TailwindCSS 를 최신 버전으로 업그레이드 시켜야 하는 경우가 있다면:

  • 자동 마이그레이션 도구를 사용하거나

    $ npx @tailwindcss/upgrade

Screenshot_2025-05-28_at_8.42.43_PM.png

설치할 확장 프로그램들

  1. Tailwind CSS IntelliSense

    Screenshot_2025-05-28_at_8.52.35_PM.png

  • Linting
  1. Prettier 클래스 정렬 플러그인

    • 설치 방법

      # 터미널에 밑의 커맨드 실행
npm install -D prettier prettier-plugin-tailwindcss
# .prettierrc 파일에 플러그인 추가 
{
  "plugins": ["prettier-plugin-tailwindcss"]
}

    • 정렬 전/후 비교

      ## 정렬 전
<main className="flex flex-col gap-[32px] row-start-2 items-center sm:items-start">
## 정렬 후 
<main className="row-start-2 flex flex-col items-center gap-[32px] sm:items-start">

      CMD+S 나 파일을 저장할때마다 자동으로 Prettier 규칙을 따라 클래스 정렬을 해준다.

❗ 만약 Hover Preview 같이 확장 프로그램 기능들이 잘 표시되지 않는다면 Shift+Cmd+P 로 팔레트를 열고 Developer: Reload Window 를 검색해서 현재 윈도우를 다시 돌리면 잘 적용될 것이다!

Shadcn/ui 컴포넌트 라이브러리 설치 및 활용

Shadcn/ui 는 Tailwind CSS 를 기반으로 한 컴포넌트 라이브러리로, Next.js 에 적용하기에 적합한 오픈소스 UI 이다. 미니멀리스틱 하고 consistent 한 디자인 시스템 덕분에 프론트엔드 작업을 할 때 편리하고 개발 효율이 금방 올라간다.

설치 가이드 :

  1. Next.js 프로젝트 안에 새로운 shadcn 프로젝트 생성

    npx shadcn@latest init ## TailwindCSS 버전 주의. Lastest 는 Tailwind v4 와 호환

    Screenshot_2025-05-29_at_1.18.14_AM.png

    • Base color 를 선택할 수 있으며 원하는 디자인 형식에 따라 설정하면 된다.
    • Use --force 로 의존성 패키지들을 설치해야 문제없이 잘 셋팅된다.
    • 이때 다양한 dependency 가 설치되는데 이 중 clsx 와 tailwind-merge 가 병합되어 만들어진 cn() 유틸리티 함수를 짚고 넘어가자.
    // @/lib/utils.ts
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"
 
// 기존 컴포넌트 CSS 와 외부에서 컴포넌트를 clsx로 결합한 후 tailwind-merge 로 클래스 충돌을 해결하고 최적화. 커스텀 스타일이 기본 스타일을 오버라이드 한다. 
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))  
}

  2. 필요한 컴포넌트 추가

    npx shadcn@latest add card // @/components/ui/card.tsx 가 생김

    @/app/page.tsx

    import {
  Card,
  CardHeader,
  CardDescription,
  CardTitle,
} from "@/components/ui/card";
 
export default function Home() {
  return (
    <div>
      <Card>
        <CardHeader>
          <CardTitle>블로그 제목</CardTitle>
          <CardDescription>간단한 더미 블로그 설명입니다. </CardDescription>
        </CardHeader>
      </Card>
    </div>
  );
}

    이렇게 손쉽게 완성된 UI를 구현할 수 있다.

    Screenshot_2025-05-29_at_1.53.55_AM.png

참고