개발 서버 실행 및 기본 설정

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

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

개발 서버 다시 실행하기

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

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

cd my-next-app
npm run dev

또는 yarn을 사용한다면:

cd my-next-app
yarn dev

명령이 성공하면 접속 URL이 출력됩니다. 아래는 로그 형식의 예시이며, Next.js 버전과 실행 환경에 따라 실제 문구가 달라집니다.

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

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

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

개발 서버의 특징

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

개발 서버를 종료할 때는 Windows, macOS, Linux 모두 실행 중인 터미널에서 Ctrl + C를 누릅니다.

기본 포트 변경하기

간혹 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

환경값의 노출 위치와 시점
설정 위치	값을 읽는 방식	노출 범위
일반 환경 변수	서버 코드에서 process.env.DATABASE_URL	브라우저에 자동 제공하지 않음; 응답이나 props에 직접 넣으면 노출됨
NEXT_PUBLIC_	process.env.NEXT_PUBLIC_API_ORIGIN처럼 직접 접근	빌드 시 공개 값으로 치환; 빌드 후 환경값만 바꿔도 기존 번들은 바뀌지 않음
next.config의 env	설정 객체에 값을 포함	접두사와 무관하게 번들에 들어갈 수 있으므로 비밀값을 두지 않음

일반 환경 변수: 값을 읽는 방식: 서버 코드에서 process.env.DATABASE_URL
노출 범위: 브라우저에 자동 제공하지 않음; 응답이나 props에 직접 넣으면 노출됨
NEXT_PUBLIC_: 값을 읽는 방식: process.env.NEXT_PUBLIC_API_ORIGIN처럼 직접 접근
노출 범위: 빌드 시 공개 값으로 치환; 빌드 후 환경값만 바꿔도 기존 번들은 바뀌지 않음
next.config의 env: 값을 읽는 방식: 설정 객체에 값을 포함
노출 범위: 접두사와 무관하게 번들에 들어갈 수 있으므로 비밀값을 두지 않음

NEXT_PUBLIC_라도 process.env[name] 같은 동적 조회는 이 치환 대상이 아닙니다. 공개 여부를 결정한 뒤 변수명을 사용합니다.

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

개발 서버 시작 전 최종 확인

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

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

이 페이지의 목차