개발 서버 실행 및 기본 설정

Next.js 프로젝트의 구조를 이해하셨다면, 이제 개발의 핵심적인 부분인 개발 서버(Development Server)를 좀 더 자세히 살펴보고, 기본적인 설정을 통해 개발 환경을 최적화하는 방법을 알아보겠습니다.

개발 서버는 여러분이 작성하는 코드를 실시간으로 브라우저에 반영하여, 빠르게 결과를 확인하며 개발할 수 있도록 돕는 매우 중요한 도구입니다.

먼저 개발 서버가 맡는 역할을 코드 감시, 즉시 반영, 오류 표시, 로컬 주소 제공으로 나눠 봅니다.

개발 서버 다시 실행하기

개발 서버 재실행은 프로젝트 폴더, 실행 명령, localhost 주소, 종료 방법을 순서대로 확인하는 과정입니다.

이전 절에서 이미 개발 서버를 한 번 실행해 보셨겠지만, 다시 한번 그 과정을 상기하고 몇 가지 유의할 점을 짚어보겠습니다.

프로젝트 디렉터리(my-next-app 또는 여러분이 지정한 프로젝트 이름)로 이동한 후, 다음 명령어를 터미널에 입력합니다.

cd my-next-app
npm run dev

또는 yarn을 사용한다면:

cd my-next-app
yarn dev

명령어가 성공적으로 실행되면, 다음과 유사한 메시지가 나타날 것입니다.

ready - started server on 0.0.0.0:3000, url: http://localhost:3000

이 메시지는 Next.js 개발 서버가 http://localhost:3000 주소에서 실행 중임을 의미합니다.

웹 브라우저를 열고 해당 주소로 접속하면, Next.js의 기본 환영 페이지를 볼 수 있습니다.

개발 서버의 특징

자동 새로 고침 (Hot Module Replacement, HMR): 개발 서버가 실행 중인 상태에서 코드를 수정하고 저장하면, 브라우저가 자동으로 새로 고침 되거나 변경된 모듈만 교체되어 화면에 즉시 반영됩니다. 이는 개발 효율성을 크게 높여주는 기능입니다.
에러 오버레이: 개발 중에 문법 오류나 런타임 오류가 발생하면, 브라우저 화면에 에러 메시지 오버레이가 나타나 문제를 쉽게 파악하고 해결할 수 있도록 돕습니다.
성능 최적화 미적용: 개발 서버는 빠른 피드백을 위해 성능 최적화가 최소화되어 있습니다. 따라서 실제 프로덕션 환경에서의 성능과는 차이가 있을 수 있습니다.

개발 서버를 종료하고 싶을 때는 터미널에서 Ctrl + C (Windows/Linux) 또는 Cmd + C (macOS)를 누르면 됩니다.

기본 포트 변경하기

간혹 3000번 포트가 다른 애플리케이션에 의해 사용 중이거나, 다른 포트에서 개발하고 싶은 경우가 있을 수 있습니다.

이럴 때는 npm run dev 명령어를 실행할 때 PORT 환경 변수를 지정하여 포트를 변경할 수 있습니다.

# Windows (명령 프롬프트)
set PORT=3001 && npm run dev

# Windows (PowerShell)
$env:PORT=3001; npm run dev

# macOS/Linux
PORT=3001 npm run dev

위 명령어를 실행하면 http://localhost:3001으로 개발 서버가 시작되는 것을 확인할 수 있습니다.

`next.config.ts` 파일 살펴보기 및 기본 설정

next.config.ts 파일은 Next.js 애플리케이션의 전반적인 동작 방식을 설정하는 중요한 파일입니다.

프로젝트의 루트 디렉터리에 위치하며, create-next-app으로 프로젝트를 생성했다면 기본적으로 다음과 같은 내용으로 생성되어 있을 것입니다.

next.config.ts

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {};

export default nextConfig;

이 파일은 타입 검사를 받는 설정 객체를 기본 export합니다.

nextConfig 객체 안에 다양한 설정 옵션을 추가하여 Next.js의 동작을 커스터마이징할 수 있습니다.

몇 가지 유용한 기본 설정 옵션을 살펴보겠습니다.

`images` 설정: 이미지 최적화

Next.js는 이미지 최적화를 위한 <Image> 컴포넌트를 제공합니다.

로컬 이미지는 별도 설정 없이 사용할 수 있고, 외부 이미지는 next.config.ts의 remotePatterns로 허용 범위를 명시합니다.

외부 도메인에서 이미지를 로드할 때 필요합니다.

next.config.ts

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.example.com',
        pathname: '/my-bucket/**',
      },
    ],
  },
};

export default nextConfig;

`reactStrictMode` 설정: React 엄격 모드

next.config.ts

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  reactStrictMode: true, // true 또는 false
};

export default nextConfig;

App Router는 기본적으로 Strict Mode를 사용하므로 보통 이 옵션을 직접 적을 필요가 없습니다.

개발 중 일부 로직이 두 번 실행되는 것처럼 보인다면 Strict Mode를 끄기보다, effect 정리 함수와 부수 효과가 안전하게 반복되는지 먼저 확인합니다.

`.env.local`: 환경 변수 관리

애플리케이션에서 민감한 정보(API 키 등)나 환경별로 달라지는 값(백엔드 API 주소)을 관리할 때 환경 변수를 사용합니다.

프로젝트 루트의 .env.local에 서버 전용 값과 브라우저 공개 값을 구분해 작성합니다.

.env.local

# 서버 컴포넌트와 Route Handler에서만 읽습니다.
DATABASE_URL=postgresql://user:password@localhost:5432/app

# 브라우저 번들에 공개해도 되는 값에만 접두사를 붙입니다.
NEXT_PUBLIC_API_ORIGIN=https://api.example.com

NEXT_PUBLIC_ 접두사가 없는 값은 서버에서만 읽고, 접두사가 있는 값은 빌드할 때 클라이언트 번들에 포함됩니다.

민감한 정보는 절대로 NEXT_PUBLIC_ 접두사를 붙이면 안 됩니다.

또한 next.config.ts의 env 옵션에 넣은 값은 이름과 관계없이 번들에 인라인될 수 있으므로 비밀값 저장소로 사용하지 않습니다.

환경 변수 관리에 대해서는 추후 더 자세히 다룰 예정입니다.

개발 환경을 정리할 때는 실행 명령, 포트, 설정 파일, 환경 변수를 한 번에 점검하면 실수를 줄일 수 있습니다.

아래 다이어그램은 개발 서버를 실행할 때 함께 점검할 명령, 포트, 설정 파일의 관계를 정리한 것입니다.

개발 서버 시작 전 최종 확인

모든 설정이 완료되었다면 프로젝트 디렉터리에서 npm run dev를 다시 실행합니다.

실행 전에는 현재 폴더, 포트 충돌, 설정 파일 변경 여부를 함께 확인합니다.

다음 다이어그램은 Windows에서 Next.js 프로젝트를 실행할 때 셸, 경로, 패키지 관리자, 환경 변수를 확인하는 순서입니다.

설정 파일을 바꿀 때는 개발 서버 재시작 필요 여부와 브라우저 확인 위치를 함께 보아야 합니다.

마지막으로 개발 서버 실행과 next.config.ts 기본 설정을 실제 점검 순서로 정리합니다.

개발 서버 실행 및 기본 설정

이 페이지의 목차