개발 서버 실행 및 기본 설정

Next.js 프로젝트의 구조를 이해하셨다면, 이제 개발의 핵심적인 부분인 개발 서버(Development Server) 를 좀 더 자세히 살펴보고, 기본적인 설정을 통해 개발 환경을 최적화하는 방법을 알아보겠습니다. 개발 서버는 여러분이 작성하는 코드를 실시간으로 브라우저에 반영하여, 빠르게 결과를 확인하며 개발할 수 있도록 돕는 매우 중요한 도구입니다.

개발 서버 다시 실행하기

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

프로젝트 디렉터리(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=4000 && npm run dev

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

# macOS/Linux
PORT=4000 npm run dev

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

`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에 이미지 도메인을 명시해 주는 것이 좋습니다. 외부 도메인에서 이미지를 로드할 때 필요합니다.

/** @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는 개발 중에 잠재적인 문제를 감지하고 경고를 표시하는 StrictMode를 제공합니다. 기본적으로 활성화되어 있으며, 개발 중에만 적용됩니다.

/** @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 명령어를 다시 실행해 보세요. 이제 여러분은 Next.js 개발 서버를 완벽하게 제어할 수 있게 되었습니다.

개발 서버 실행 및 기본 설정

On this page