개발 서버 실행 및 기본 설정

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.js` 파일 살펴보기 및 기본 설정

next.config.js 파일은 Next.js 애플리케이션의 전반적인 동작 방식을 설정하는 중요한 파일입니다. 프로젝트의 루트 디렉터리에 위치하며, create-next-app으로 프로젝트를 생성했다면 기본적으로 다음과 같은 내용으로 생성되어 있을 것입니다.

/** @type {import('next').NextConfig} */
const nextConfig = {};

module.exports = nextConfig;

이 파일은 Node.js의 모듈 시스템을 사용하여 Next.js 설정을 내보냅니다. nextConfig 객체 안에 다양한 설정 옵션을 추가하여 Next.js의 동작을 커스터마이징할 수 있습니다.

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

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

Next.js는 이미지 최적화를 위한 <Image> 컴포넌트를 제공합니다. 이 컴포넌트를 사용하기 위해서는 next.config.js에 이미지 도메인을 명시해 주는 것이 좋습니다. 외부 도메인에서 이미지를 로드할 때 필요합니다.

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    // 이미지를 로드할 외부 도메인들을 여기에 추가합니다.
    // 예시: 'res.cloudinary.com', 'example.com'
    domains: [],
    // 또는 remotePatterns를 사용하여 더 유연한 패턴 매칭 가능
    // remotePatterns: [
    //   {
    //     protocol: 'https',
    //     hostname: 'assets.example.com',
    //     port: '',
    //     pathname: '/my-bucket/**',
    //   },
    // ],
  },
};

module.exports = nextConfig;

`reactStrictMode` 설정: React 엄격 모드

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true, // true 또는 false
};

module.exports = nextConfig;

true로 설정하면 React 컴포넌트의 특정 생명주기 메서드가 두 번 호출되거나, 구식 API 사용 시 경고를 표시하여 잠재적인 버그를 조기에 발견하는 데 도움을 줍니다. 개발 중에는 true를 유지하는 것이 좋지만, 특정 라이브러리와의 호환성 문제 등으로 인해 false로 설정해야 하는 경우도 있습니다.

`env` 설정: 환경 변수 관리

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

/** @type {import('next').NextConfig} */
const nextConfig = {
  env: {
    // 클라이언트 사이드 코드에서도 접근 가능한 환경 변수
    // 'NEXT_PUBLIC_' 접두사가 붙은 환경 변수는 자동으로 클라이언트에서 사용 가능
    CUSTOM_ENV_VARIABLE: 'My Custom Value',
    API_URL: process.env.NODE_ENV === 'production' ? 'https://api.myapp.com' : 'http://localhost:5000',
  },
};

module.exports = nextConfig;

주의: process.env.NEXT_PUBLIC_으로 시작하는 환경 변수만 클라이언트 사이드 코드("use client"가 붙은 컴포넌트 등)에서 접근할 수 있습니다.

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

서버 사이드에서만 사용해야 하는 환경 변수는 접두사 없이 .env 파일에만 정의하고, 클라이언트 번들에 포함되지 않도록 주의해야 합니다.

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

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

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

개발 서버 시작 전 최종 확인

모든 설정이 완료되었다면 프로젝트 디렉터리에서 npm run dev를 다시 실행합니다. 실행 전에는 현재 폴더, 포트 충돌, 설정 파일 변경 여부를 함께 확인합니다.

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

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

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

개발 서버 실행 및 기본 설정

On this page