2. Create app

이 문서는 Next.js를 사용하여 프로젝트를 시작하는 방법을 안내합니다. 프로젝트를 시작하기 위해 필요한 설정 내용과 방법을 단계별로 설명하며, 최종적으로 Next.js 앱을 로컬 환경에서 실행합니다.

---

Prerequisites

node: 현재 기준 최신 Next.js 16.2.3은 Node.js 20 이상만 지원하므로 버전 24 이상 설치를 추천합니다.

(현재 LTS 최신 버전은 24.16.0)

Set up

1

프로젝트 폴더 생성 및 IDE 열기

예: app 이름 : x2bee-fo-dev

$ mkdir x2bee-fo
$ cd x2bee-fo
$ code .  # 자신이 쓰는 IDE 열기

2

package.json 생성

프로젝트 루트에 package.json 파일을 생성하고 다음 내용을 작성합니다.

{
  "name": "x2bee-fo",
  "private": true
}

3

의존성 설치

Next.js, React, React DOM을 설치합니다.

( 만약 npm이나 yarn을 쓰는 경우 install, bun을 쓰는 경우 bun add 하면 됩니다. )

$ yarn add next react react-dom

설치가 완료되면 node_modules 폴더가 생성되고 해당 경로에 패키지들이 설치됩니다.

git 설정

Git을 사용하여 프로젝트를 관리할 때 무시해야 할 파일 및 디렉토리를 설정하는 .gitignore 파일을 생성합니다.

.gitignore 파일 내용:

# next.js
/.next/

# dependencies
/node_modules
pnpm-lock.yaml
package-lock.json
yarn.lock

이러한 항목을 .gitignore에 추가하면 Git 저장소에 불필요한 파일이나 의존성 패키지들이 포함되지 않도록 할 수 있습니다.

Scripts 및 초기 실행

package.json에 scripts를 추가합니다. 예시:

{
  "name": "x2bee-fo",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
"next": "^16.2.3",
"react": "^19.2.3",
"react-dom": "^19.2.3"
  }
}

이제 개발 서버를 실행합니다:

$ npm run dev

(또는 yarn: yarn dev, pnpm: pnpm dev)

실행 시 .next 폴더가 자동으로 생성되며 다음과 같은 메시지를 볼 수 있습니다:

• Local: http://localhost:3000

• Ready in Xs

(아직 page.jsx 파일이 없으므로 브라우저에서는 404 에러가 뜰 수 있습니다.)

프로젝트 초기화 및 원격 저장소 연결

다음 명령으로 Git 저장소를 초기화하고 원격 저장소를 연결합니다.

$ git init
$ git remote add origin https:// git 주소
$ git remote -v  # 확인용

변경사항을 커밋하고 푸시:

$ git add .
$ git commit -m 'x2bee storefront with Next14'
$ git push origin main

기본 레이아웃 생성

프로젝트 루트에 src 폴더를 만들고, 그 안에 app 폴더를 만든 후 layout.jsx 파일을 생성하고 다음 코드를 복사하여 붙여넣습니다.

import React from 'react'

const RootLayout = ({ children }) => {
  return (
    <html lang="ko">
      <body>{children}</body>
    </html>
  );
};

export default RootLayout;

수행이 완료되면 기본 루트 레이아웃 정의가 완료됩니다.

참고

$ ls node_modules/.bin  # next 등이 있는지 확인
# next

npx로 next를 실행하면 위 경로가 사용됩니다.

$ npx next --help
# Available commands build, start, export, dev, lint, telemetry, info, experimental-compile, experimental-generate

위 명령들을 활용하여 package.json의 scripts를 구성할 수 있습니다.

---