Getting Started

Creating a new project

npm이나 Yarn보다 더 빠르고 효율적이므로 pnpm을 패키지 관리자로 사용하는 것이 좋습니다. pnpm이 설치되어 있지 않은 경우 다음을 실행하여 전역적으로 설치할 수 있습니다.

npm install -g pnpm

Next.js 앱을 만들려면 프로젝트를 보관하려는 폴더에 있는 터미널 ’cd’를 열고 다음 명령어를 실행하세요.

npx create-next-app@latest nextjs-dashboard --example "https://github.com/vercel/next-learn/tree/main/dashboard/starter-example" --use-pnpm

이 명령은 Next.js 애플리케이션을 설정하는 CLI(명령줄 인터페이스) 도구인 create-next-app을 사용합니다. 위 명령에서는 이 과정의 시작 예제와 함께 –example 플래그도 사용하고 있습니다. command의 각 부분의 설명은 아래와 같습니다.

command 설명
npx create-next-app@latest

  • npx: Node.js 버전 5.2.0 이상에서 사용할 수 있는 명령어로, 패키지를 설치하지 않고 실행할 수 있도록 도와줍니다.

  • create-next-app@latest: Next.js 애플리케이션을 생성하기 위한 공식 CLI 도구입니다. @latest는 최신 버전을 사용하겠다는 뜻입니다.
nextjs-dashboard
  • 프로젝트 이름입니다. 명령어 실행 후, nextjs-dashboard라는 이름의 폴더가 생성되고 그 안에 Next.js 프로젝트가 초기화됩니다.
–example

  • Next.js의 예제 코드를 사용하여 프로젝트를 시작하기 위한 옵션입니다.

  • 뒤에 이어지는 URL(https://github.com/vercel/next-learn/tree/main/dashboard/starter-example)은 사용할 예제 코드가 있는 GitHub 저장소를 가리킵니다.

  • 여기서는 Vercel에서 제공하는 Dashboard Starter Example을 사용합니다.
–use-pnpm
  • 프로젝트 설치 시 패키지 매니저로 pnpm을 사용하겠다는 뜻입니다

Exploring the project

처음부터 코드를 작성하는 튜토리얼과 달리 이 과정의 코드 대부분은 이미 작성되어 있습니다. 이는 기존 코드베이스를 사용하여 작업하게 될 실제 개발을 더 잘 반영합니다.

우리의 목표는 모든 애플리케이션 코드를 작성하지 않고도 Next.js의 주요 기능을 배우는 데 집중할 수 있도록 돕는 것입니다.

설치 후 코드 편집기에서 프로젝트를 열고 nextjs-dashboard로 이동합니다.

cd nextjs-dashboard

이제 프로젝트를 살펴보겠습니다.

Folder structure

프로젝트의 폴더 구조는 다음과 같습니다.

  • /app: 애플리케이션에 대한 모든 경로, 구성 요소 및 논리가 포함되어 있으며 여기서 주로 작업하게 됩니다.

  • /app/lib: 재사용 가능한 유틸리티 함수, 데이터 가져오기 함수 등 애플리케이션에서 사용되는 함수가 포함되어 있습니다.

  • /app/ui: 카드, 테이블, 양식 등 애플리케이션의 모든 UI 구성 요소가 포함되어 있습니다. 시간을 절약하기 위해 이러한 구성 요소의 스타일이 미리 지정되어 있습니다.

  • /public: 이미지와 같은 애플리케이션의 모든 정적 자산을 포함합니다.

  • 구성 파일: 애플리케이션 루트에 next.config.ts와 같은 구성 파일도 있습니다. 이러한 파일의 대부분은 create-next-app을 사용하여 새 프로젝트를 시작할 때 생성되고 사전 구성됩니다. 이 과정에서는 수정할 필요가 없습니다.

폴더를 자유롭게 탐색해 보세요. 코드가 수행하는 모든 작업을 아직 이해하지 못하더라도 걱정하지 마세요.

Placeholder data

사용자 인터페이스를 구축할 때 일부 Placeholder 데이터가 있으면 도움이 됩니다. 데이터베이스나 API를 아직 사용할 수 없는 경우 다음을 수행할 수 있습니다.

  • JSON 형식 또는 JavaScript 개체로 자리 표시자 데이터를 사용합니다.

  • mockAPI와 같은 타사 서비스를 사용하세요.

이 프로젝트에서는 app/lib/placeholder-data.ts에 일부 placeholder 데이터를 제공했습니다. 파일의 각 JavaScript 개체는 데이터베이스의 테이블을 나타냅니다.

const invoices = [
  {
    customer_id: customers[0].id,
    amount: 15795,
    status: 'pending',
    date: '2022-12-06',
  },
  {
    customer_id: customers[1].id,
    amount: 20348,
    status: 'pending',
    date: '2022-11-14',
  },
  // ...
];

데이터베이스 설정 장에서는 이 데이터를 사용하여 데이터베이스를 시드합니다. (일부 초기 데이터로 채움).

TypeScript

또한 대부분의 파일에는 .ts 또는 .tsx 접미사가 있음을 알 수 있습니다. 이는 프로젝트가 TypeScript로 작성되었기 때문입니다. 우리는 현대 웹 환경을 반영하는 강좌를 만들고 싶었습니다. TypeScript를 모르더라도 괜찮습니다. 필요한 경우 TypeScript 코드 조각을 제공할 것입니다.

지금은 /app/lib/definitions.ts 파일을 살펴보세요. 여기서는 데이터베이스에서 반환될 유형을 수동으로 정의합니다. 예를 들어 송장 테이블에는 다음과 같은 유형이 있습니다.

export type Invoice = {
  id: string;
  customer_id: string;
  amount: number;
  date: string;
  // In TypeScript, this is called a string union type.
  // It means that the "status" property can only be one of the two strings: 'pending' or 'paid'.
  status: 'pending' | 'paid';
};

TypeScript를 사용하면 송장 금액에 숫자 대신 문자열을 전달하는 것과 같이 실수로 구성 요소나 데이터베이스에 잘못된 데이터 형식을 전달하지 않도록 할 수 있습니다.

Running the development server

pnpm i를 실행하여 프로젝트 패키지를 설치합니다.

pnpm i

개발 서버를 시작하려면 pnpm dev가 따라옵니다.

pnpm dev
Note

버전이 맞지 않는 경우 아래와 같이 error가 발생합니다. Node.js를 버전에 맞게 다시 설치하세요.

You are using Node.js 18.17.1. For Next.js, Node.js version "^18.18.0 || ^19.8.0 || >= 20.0.0" is required.

pnpm dev는 포트 3000에서 Next.js 개발 서버를 시작합니다. 작동하는지 확인해 보겠습니다. 브라우저에서 http://localhost:3000을 엽니다. 홈 페이지는 의도적으로 스타일이 지정되지 않은 다음과 같아야 합니다.

npm 설치가 필요하다면?

Window

npm은 Node.js 설치 시 자동으로 포함됩니다.

  1. Node.js 공식 웹사이트에 접속합니다.

  2. LTS(Long Term Support) 버전을 다운로드합니다. LTS 버전은 안정적이며 대부분의 사용자에게 권장됩니다.

  3. 설치 파일을 실행하고 안내에 따라 설치를 완료합니다.

  4. 설치 완료 후, 터미널이나 명령 프롬프트를 열고 다음 명령어로 Node.js와 npm이 설치되었는지 확인합니다. Node.js 버전과 npm 버전이 출력되면 정상적으로 설치된 것입니다.

    `node -v npm -v`

Ubuntu

  1. 필요 패키지 설치
sudo apt update
sudo apt install -y curl software-properties-common
  1. NodeSource 스크립트 실행
// LTS 버전 설치 18.20.6 (LTS)
# nvm 다운로드 및 설치:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Node.js 다운로드 및 설치:
nvm install 18

# Node.js 버전 확인:
node -v # "v18.20.6"가 출력되어야 합니다.
nvm current # "v18.20.6"가 출력되어야 합니다.

# pnpm 다운로드 및 설치:
corepack enable pnpm

# pnpm 버전 확인:
pnpm -v