Next.js CLI란?

Next.js CLI는 Next.js 애플리케이션을 개발하고, 빌드하고, 시작하는 등 다양한 작업을 도와주는 명령어 도구예요. 명령어 한 줄로 손쉽게 앱을 관리할 수 있어서 개발자에게 아주 편리하답니다.

기본 사용법은 아주 간단해요:

npx next [command] [options]

예를 들어, 개발 서버를 실행하고 싶으면:

npx next dev

빌드를 하려면:

npx next build

완성된 앱을 실행하고 싶다면:

npx next start

이렇게 기본적인 명령어만 알아도 Next.js 프로젝트 관리가 훨씬 수월해지죠.

추가로, npx를 사용하지 않고 전역 설치를 통해 바로 next 명령어를 쓰기도 하는데, 개인적으로 프로젝트마다 버전 충돌 없이 쓰려면 npx나 package.json의 스크립트로 실행하는 걸 추천해요.

다음 글에서는 Next.js CLI에서 자주 쓰이는 주요 명령어들을 좀 더 파헤쳐 볼게요!

참고 자료

다음과 같은 옵션들을 사용할 수 있어요:

옵션	설명
`-h` 또는 `--help`	사용 가능한 모든 옵션을 보여줘요
`-v` 또는 `--version`	현재 설치된 Next.js 버전 번호를 출력해줘요

커맨드

여기서 잠깐! 이렇게 옵션과 설명을 표로 정리하면 훨씬 한눈에 보기 쉽죠? 실제 개발할 때도 README 파일이나 문서 작성할 때 Markdown 표를 자주 쓰는데, 꼭 기억해두세요! 옵션을 한눈에 정리해두면 협업할 때도 도움이 많이 된답니다.

다음은 Next.js에서 사용할 수 있는 주요 명령어들입니다:

Command	Description
`dev`	Next.js를 개발 모드로 실행합니다. 핫 모듈 리로딩(HMR), 에러 리포팅 등 개발에 편리한 기능들이 활성화됩니다.
`build`	애플리케이션의 최적화된 프로덕션 빌드를 생성합니다. 각 라우트에 대한 정보도 함께 보여줍니다.
`start`	프로덕션 모드에서 Next.js를 실행합니다. 이 명령어를 사용하려면 먼저 `next build`로 빌드를 완료해야 합니다.
`info`	현재 시스템에 관한 유용한 정보를 출력합니다. Next.js 버그 리포트를 작성할 때 참고할 수 있습니다.
`lint`	`/src`, `/app`, `/pages`, `/components`, `/lib` 디렉토리 내 모든 파일에 대해 ESLint를 실행합니다. ESLint가 설정되어 있지 않으면 가이드에 따라 필요한 의존성을 설치할 수 있게 도와줍니다.
`telemetry`	Next.js의 완전 익명화된 텔레메트리 데이터 수집 기능을 켜거나 끌 수 있습니다.

참고로, next 커맨드만 입력하면 자동으로 next dev 명령어를 실행하는 것과 같습니다.

next dev 옵션

여기서 잠깐!
개발하면서 next dev 명령어를 자주 쓰게 되는데, 이 모드는 개발자 경험을 엄청나게 개선해줘요. HMR 덕분에 코드를 바꿀 때마다 새로 고침을 하지 않아도 되고, 에러도 바로바로 알려주거든요. 또 프로젝트 진행 중에는 lint 명령어로 코드 규칙을 점검하는 것도 잊지 마세요. 깔끔한 코드가 버그를 줄이고 협업에도 좋아요!

추가로 telemetry 기능은 익명으로 사용 데이터를 수집해서 Next.js 개발팀이 더 좋은 기능을 만드는데 도움을 줍니다. 개인정보 침해 걱정 없이 사용 가능한데, 원치 않으면 꺼둘 수도 있으니 마음 편히 설정하세요.

앞으로 Next.js로 프로젝트 하면서 이 명령어들 잘 활용해보시면 개발 속도가 훨씬 빨라질 거예요! 필요한 부분 있으면 언제든지 질문하거나 검색해서 도움받으세요~

next dev는 개발 모드에서 애플리케이션을 시작할 때 사용하는 명령어로, 핫 모듈 리로딩(HMR), 에러 리포팅 등 개발에 도움 되는 기능들이 자동으로 활성화돼요. 이 때 사용할 수 있는 옵션들이 몇 가지 있는데, 아래 표로 정리해봤어요.

옵션	설명
`-h, --help`	사용 가능한 모든 옵션을 보여줍니다.
`[directory]`	애플리케이션을 빌드할 디렉토리를 지정합니다. 지정하지 않으면 현재 디렉토리를 사용해요.
`--turbopack`	Turbopack을 사용해 개발 모드를 시작합니다.
`-p` 또는 `--port <port>`	애플리케이션을 시작할 포트 번호를 지정합니다. 기본값은 3000번이며, 환경 변수 PORT도 지원해요.
`-H` 또는 `--hostname <hostname>`	애플리케이션을 시작할 호스트네임(주소)를 지정합니다. 네트워크에 연결된 다른 기기에서 접속할 수 있게 할 때 유용합니다. 기본값은 0.0.0.0입니다.
`--experimental-https`	HTTPS 서버를 시작하며, 자체 서명된 인증서를 생성합니다.
`--experimental-https-key <path>`	HTTPS 키 파일의 경로를 지정합니다.
`--experimental-https-cert <path>`	HTTPS 인증서 파일 경로를 지정합니다.
`--experimental-https-ca <path>`	HTTPS 인증서 권한(CA) 파일 경로를 지정합니다.
`--experimental-upload-trace <traceUrl>`	디버깅 트레이스의 일부 정보를 원격 HTTP URL로 전송해 리포팅합니다.

next build 옵션

next build는 프로덕션에 최적화된 빌드를 만들어 줘요. 빌드가 끝나면 각 라우트(route)에 대한 정보들을 출력해줍니다.

예를 들어, 페이지마다 빌드 결과 크기와 성능 정보를 확인할 수 있는데, 이걸 참고해서 용량 최적화나 로딩 속도 향상을 고민할 수 있죠. 실제로 빌드 명령어에 옵션을 더 붙여서 좀 더 디테일하게 빌드 과정이나 성능을 분석하는 방법도 있어요.

추가로, next build 명령어는 프로덕션 모드 빌드이기 때문에 개발 모드(next dev)와 달리 HMR 같은 즉각적인 반영 기능은 없어요. 따라서 수정 → 빌드 → 배포 과정을 반복하게 되니 점진적 배포에 유의하세요!

혹시 HMR이나 Turbopack에 대해 잘 모른다면 간단히 설명해볼게요.

핫 모듈 리로딩(HMR): 코드를 수정하면 전체 페이지를 새로고침하지 않고도 그 부분만 즉시 반영해주는 기능이에요. 덕분에 개발할 때 훨씬 빠르게 결과를 확인할 수 있죠.
Turbopack: Next.js가 공식적으로 지원하는 새로운 초고속 번들러(bundler)인데, Webpack보다 훨씬 빠르다고 알려져 있어요. 아직 실험적 기능이긴 하지만, 향후 Next.js 개발 방식에 큰 변화를 불러올 주목할 만한 기술이에요.

Next.js를 사용하는 개발자라면 next dev와 next build 명령어의 옵션들을 잘 이해하고 활용하는 게 개발 효율을 크게 올리는 지름길이니, 꼭 익혀두길 추천합니다!

Route (app)	Size	First Load JS
○ /_not-found	0 B	0 kB
└ ƒ /products/[id]	0 B	0 kB

Size: 클라이언트 사이드에서 해당 페이지로 이동할 때 다운로드되는 자산 크기입니다. 각 라우트의 크기는 해당 라우트가 필요로 하는 의존성만 포함합니다.
First Load JS: 서버에서 페이지를 처음 방문할 때 다운로드되는 자바스크립트 크기입니다. 모든 페이지가 공유하는 JS 크기는 별도로 표시됩니다.

여기서 두 값 모두 gzip 압축된 크기이고, 첫 로드 시 크기는 초록, 노랑, 빨강 색상으로 퍼포먼스를 간단하게 표현해줘요. 초록색일수록 빠르고 최적화된 상태라고 보면 됩니다.

이런 정보를 통해 우리가 직접 개발할 때 페이지별 리소스 최적화가 얼마나 잘 되어있는지 쉽게 파악할 수 있죠. 나중에 프로젝트 빌드할 때 next build 명령어에 다양한 옵션들도 줄 수 있으니 필요하면 그 부분도 한번 살펴보시면 좋아요.

위 내용을 보시면서, 다음과 같은 팁도 같이 공유할게요.

개발 시 참고할 점

**프리렌더링(Static Generation)**을 적극 활용하면, 성능 향상에 큰 도움이 됩니다. 위 예시에서 ○ (Static) 표시가 있는 페이지가 바로 그런 경우에 해당해요.
반대로, ƒ (Dynamic)는 필요할 때마다 서버에서 데이터를 받아 렌더링하는 방식이라 처음 로딩 시 시간이 좀 더 걸릴 수 있답니다.
gzip 압축은 기본이기 때문에 이걸 해제하거나 신경 쓸 필요 없지만, 만약 페이지 로딩 속도가 느리다면 번들 크기를 분석해서 꼭 줄일 방법을 찾아보세요.
네트워크 환경이 좋지 않은 사용자도 많으니, 가능한 한 First Load JS 크기를 작게 유지하는 게 중요합니다.

이렇게 최적화를 의식하며 작업하면 사용자 경험이 훨씬 좋아질 거예요!

다음은 next build 명령어에 사용할 수 있는 여러 가지 옵션들입니다. 개발할 때 빌드 설정을 세밀하게 조절할 수 있어서 상황에 맞게 활용하면 좋아요.

옵션	설명
`-h, --help`	사용 가능한 모든 옵션을 보여줍니다.
`[directory]`	앱을 빌드할 디렉터리를 지정해요. 만약 생략하면 현재 디렉터리가 기본으로 사용됩니다.
`-d` 또는 `--debug`	빌드 과정에 대한 자세한 로그를 보고 싶을 때 사용해요. 이 옵션을 켜면 리다이렉션, 헤더 설정, 리라이트 같은 추가 정보들이 출력됩니다.
`--profile`	React 프로파일링을 활성화해요. 프로덕션 환경에서 React 컴포넌트 성능을 자세히 분석할 수 있습니다. (React Profiler에 대해 더 알고 싶다면 React 공식 문서를 참고!)
`--no-lint`	린팅(linting)을 비활성화합니다. 린트 검사 없이 빠르게 빌드할 때 유용하지만, 코드 품질은 직접 신경 써야 해요.
`--no-mangling`	네이밍 맹글링(Name Mangling)을 비활성화합니다. 맹글링은 코드 압축 성능을 높이는데, 해제하면 디버깅이 편해지지만 수행 속도에는 영향이 있을 수 있습니다.
`--experimental-app-only`	App Router 경로만 빌드합니다. Next.js의 실험적 기능을 사용하고 싶을 때 쓰여요.
`--experimental-build-mode [mode]`	실험적 빌드 모드를 사용합니다. 선택지는 `"compile"`, `"generate"`, 기본값은 `"default"`입니다. 새 기능을 시험해보고 싶을 때 도움이 됩니다.

next start 옵션

next start 명령어는 빌드가 완료된 애플리케이션을 프로덕션 모드로 실행할 때 사용합니다. 빌드(next build)가 먼저 되어 있어야 하죠.

next start에 사용할 수 있는 옵션들도 있는데, 필요하면 알려드릴게요!

추가 팁을 하나 더 드리자면, --debug 옵션은 빌드 문제를 찾을 때 정말 유용해요. 예를 들어, 설정한 리다이렉션이 제대로 적용되는지, 특정 헤더가 붙는지 등을 확인할 때 말이죠. 빌드 시간이 조금 더 걸리긴 하지만 디버깅 시간이 훨씬 단축됩니다!

React 프로파일링도 성능 최적화할 때 꼭 써보세요. 사용자 경험에 큰 영향을 주는 렌더링 병목을 쉽게 찾아낼 수 있답니다.

필요하면 좀 더 자세히 알려드릴게요!

Option	Description
`-h` or `--help`	사용 가능한 모든 옵션을 보여줍니다.
`[directory]`	애플리케이션을 시작할 디렉토리입니다. 지정하지 않으면 현재 디렉토리가 사용됩니다.
`-p` or `--port <port>`	애플리케이션을 시작할 포트 번호를 지정합니다. 기본값은 3000이며 환경 변수 PORT가 우선 적용됩니다.
`-H` or `--hostname <hostname>`	애플리케이션을 시작할 호스트 이름을 지정합니다. 기본값은 `0.0.0.0` 입니다.
`--keepAliveTimeout <keepAliveTimeout>`	비활성 연결을 닫기 전 대기할 최대 시간을 밀리초 단위로 지정합니다.

next info 옵션 설명

next info 명령어는 현재 시스템에 관한 다양한 정보를 출력해줍니다. 이 정보들은 Next.js 관련 버그를 GitHub에 리포트할 때 아주 유용합니다. 출력되는 내용에는 운영체제 플랫폼/아키텍처/버전 정보부터, Node.js, npm, Yarn, pnpm 같은 바이너리 버전, 그리고 Next.js, React, React DOM 등 주요 패키지들의 버전 정보가 포함됩니다.

예를 들어, 이런 식으로 보이게 되죠:

System: OS: macOS 13.4 CPU: Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz Memory: 16 GB

Binaries: Node: v18.15.0 npm: 9.5.1 Yarn: 1.22.19

Dependencies: next: 13.4.4 react: 18.2.0 react-dom: 18.2.0

제가 개인적으로 느낄 때, 이런 시스템 정보를 미리 확인하는 습관은 문제 해결과 협업에 큰 도움이 돼요. 특히 버전 차이에서 발생하는 문제를 빠르게 파악할 수 있거든요. 그래서 next info 같은 명령어를 모르셨다면 꼭 한번 써보시길 추천합니다!

운영 체제(OS):
  플랫폼: darwin (맥OS)
  아키텍처: arm64 (애플 실리콘 M1/M2 등)
  버전: Darwin Kernel Version 23.6.0
  사용 가능한 메모리(MB): 65536 (64GB)
  사용 가능한 CPU 코어 수: 10

바이너리 정보:
  Node.js: 20.12.0
  npm: 10.5.0
  Yarn: 1.22.19
  pnpm: 9.6.0

주요 패키지:
  next: 15.0.0-canary.115 (최신 베타 버전)
  eslint-config-next: 14.2.5
  react: 19.0.0-rc (릴리즈 후보)
  react-dom: 19.0.0
  typescript: 5.5.4

Next.js 설정:
  output: N/A

여기서 살펴본 정보들은 next info 명령어를 실행했을 때 나오는 시스템 정보와 설정값들이에요. 이 명령어는 Next.js 프로젝트를 디버깅할 때 굉장히 유용하답니다.

추가로, next info 명령어에는 몇 가지 옵션이 있어요:

옵션	설명
`-h` 또는 `--help`	사용 가능한 모든 옵션을 확인할 수 있어요.
`--verbose`	디버깅에 필요한 추가 정보를 수집해요.

예를 들어, 문제가 생겨서 더 자세한 정보를 보고 싶다면 다음과 같이 명령어를 쓰면 되죠.

next info --verbose

next lint 옵션

사실 Next.js는lint(코드 품질 검사)도 아주 중요한 부분에요. next lint 명령어를 통해 프로젝트 내 코드를 검사할 수 있는데, 여기서도 여러가지 옵션이 있답니다. 예를 들어, 특정 파일만 검사하거나, 자동으로 고치기도 가능하죠.

다음 포스팅에서는 next lint 명령어와 그 옵션들을 상세히 다뤄볼게요! 코드 퀄리티 올리는 데 큰 도움이 될 거예요.

참고로, 현재 Next.js 버전 is canary(미리보기/베타 버전)이어서 안정된 버전과는 차이가 있을 수 있어요. 실무에서 쓸 땐 조금 주의하셔야 합니다!

next lint 명령어는 pages/, app/, components/, lib/, 그리고 src/ 디렉터리에 있는 모든 파일에 대해 ESLint를 실행해주는 도구에요. ESLint 설정이 아직 안 되어 있다면, 필요한 의존성 설치를 위한 가이드도 함께 제공해준답니다.

그럼 next lint 명령어에서 사용할 수 있는 옵션들을 살펴볼게요!

옵션	설명
`[directory]`	lint를 실행할 기본 디렉터리를 지정해요. 지정하지 않으면 현재 디렉터리가 기본값이에요.
`-d, --dir, <dirs...>`	ESLint를 실행할 디렉터리를 하나 이상 지정할 수 있어요.
`--file, <files...>`	ESLint를 실행할 파일을 직접 지정할 수 있어요.
`--ext, [exts...]`	검사할 JavaScript 파일 확장자를 지정해요. 기본값은 [".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx"] 입니다.
`-c, --config, <config>`	이 옵션을 사용하면 다른 모든 설정을 무시하고 지정한 ESLint 설정 파일만 사용해요.
`--resolve-plugins-relative-to, <rprt>`	플러그인을 어디서부터 찾을지 디렉터리를 지정할 수 있어요.
`--strict`	Next.js 권장 strict 설정으로 `.eslintrc.json` 파일을 생성해줘요.
`--rulesdir, <rulesdir...>`	추가적으로 사용할 ESLint 규칙들이 있는 디렉터리를 지정할 수 있어요.
`--fix`	자동으로 수정 가능한 lint 문제들을 고쳐줘요.
`--fix-type <fixType>`	적용할 fix 타입을 지정할 수 있어요 (예: problem, suggestion, layout).
`--ignore-path <path>`	lint 검사에서 제외할 파일이나 디렉터리 패턴을 지정하는 파일 경로를 지정해요.
`--no-ignore <path>`	`--ignore-path` 옵션을 비활성화해요.
`--quiet`	경고 메시지를 숨기고 에러만 보고해요.
`--max-warnings [maxWarnings]`	지정한 경고 수 이상이면 non-zero 종료 코드를 반환해요. 기본값은 -1(제한 없음)입니다.
`-o, --output-file, <outputFile>`	ESLint 결과를 저장할 파일을 지정해요.
`-f, --format, <format>`	결과 출력 형식을 지정할 수 있어요.
`--no-inline-config`	코드 내에 주석으로 ESLint 설정 변경을 막아요.
`--report-unused-disable-directives-severity <level>`	사용하지 않는 `eslint-disable` 지시어에 대한 심각도 수준 지정 (error, off, warn)
`--no-cache`	캐시를 사용하지 않도록 해요.
`--cache-location, <cacheLocation>`	캐시 위치를 지정할 수 있어요.
`--cache-strategy, [cacheStrategy]`	변경 파일을 감지하는 캐시 전략을 지정할 수 있어요. 기본값은 `metadata`입니다.
`--error-on-unmatched-pattern`	지정한 패턴에 맞는 파일이 없으면 에러로 처리해요.
`-h, --help`	도움말 메시지를 보여줘요.

조금 더 팁!

--fix 옵션을 잘 활용하면 코드 스타일을 자동으로 맞춰줘서 개발 속도를 올릴 수 있어요.
--quiet 모드는 CI 환경에서 에러만 보고 싶을 때 매우 유용해요.
여러 디렉터리나 파일을 지정해 특정 부분만 검사하는 것도 가능하니, 프로젝트 상황에 맞게 유연하게 사용해보세요.

next lint 옵션을 잘 익히면 코드 품질 관리가 훨씬 편해진답니다! 도움이 되었길 바라요 :)

Next.js는 완전히 익명으로 일반 사용 패턴에 관한 텔레메트리(사용 데이터)를 수집해요. 이 프로그램 참여는 선택사항이고, 원하지 않으면 언제든지 옵트아웃(참여 중지) 할 수 있답니다.

텔레메트리 관련 명령어(next telemetry)에서 사용할 수 있는 옵션들은 다음과 같아요:

옵션	설명
`-h`, `--help`	사용 가능한 모든 옵션을 보여줍니다.
`--enable`	Next.js 텔레메트리 수집을 활성화합니다.
`--disable`	Next.js 텔레메트리 수집을 비활성화합니다.

참고로, 텔레메트리를 통해 수집되는 데이터는 프로젝트가 얼마나 잘 동작하는지, 어떤 기능이 자주 사용되는지 같은 정보들이에요. 이를 통해 Next.js 팀은 더 나은 기능을 만들고 버그를 빠르게 잡을 수 있답니다.

텔레메트리에 관해 더 자세히 알고 싶다면 공식 문서를 참고해보세요!

예제들

기본 포트 바꾸기

Next.js는 기본적으로 개발할 때나 next start 명령어를 사용할 때 http://localhost:3000 포트를 씁니다. 근데 가끔 3000번 포트가 이미 다른 프로그램에서 사용 중일 수도 있고, 다른 포트를 쓰고 싶을 때가 있죠? 그럴 땐 -p 옵션을 써서 쉽게 바꿀 수 있어요. 예를 들어, 4000번 포트로 바꾸려면 이렇게 하면 됩니다:

next dev -p 4000

위 명령어에서 next dev는 개발 모드로 서버를 실행하는 거고, -p 4000이 4000번 포트로 바꾸는 옵션이에요.

참고로, 실제 운영 모드에서 사용하는 next start 명령에도 동일하게 -p 옵션을 쓸 수 있어요. 예를 들어:

next start -p 5000

이렇게 하면 운영 서버가 5000번 포트에서 실행되겠죠.

또 한 가지 팁을 드리자면, package.json 스크립트에 이 옵션을 추가해서 명령어를 짧게 관리하는 것도 좋아요. 예를 들어:

"scripts": {
  "dev": "next dev -p 4000",
  "start": "next start -p 4000"
}

이렇게 해두면 터미널에 npm run dev 혹은 npm run start만 쳐서 원하는 포트에 서버를 띄울 수 있으니, 기억해두면 편리합니다!

PORT 환경 변수로 설정하는 방법도 있어요:

PORT=4000 next dev

참고할 점: .env 파일에서 PORT를 설정해도 효과가 없어요. HTTP 서버가 가장 먼저 실행되기 때문에, 다른 코드들이 초기화되기 전에 이미 포트가 정해져 버리거든요.

개발 환경에서 HTTPS 사용하기

개발할 때도 HTTPS를 쓰면 진짜 서비스 환경과 비슷하게 테스트할 수 있어서 좋아요. 다만, 로컬 개발 환경이라 SSL 인증서를 직접 만들어 써야 하죠. 이를 위해 mkcert 같은 툴을 사용하면 쉽게 로컬용 신뢰할 수 있는 인증서를 만들 수 있어요.

예를 들어, next.js 애플리케이션에 HTTPS를 적용하려면 커스텀 서버를 한번 설정해줘야 하는데, https 모듈을 사용하거나 next-https 같은 라이브러리를 활용할 수도 있어요.

직접 HTTPS 개발 환경을 구성하는 게 번거롭다면, 최근에 Next.js 관련 도구들이 HTTPS 옵션을 좀 더 쉽게 지원하는 방향으로 업데이트되고 있으니 공식 문서나 깃허브 이슈를 참고하는 것도 추천해요.

혹시 HTTPS 개발 환경에서 겪는 문제나 궁금한 점 있으면 편하게 알려주세요!

로컬 개발 환경에서 웹후크(webhooks)나 인증(authentication) 같은 보안이 필요한 작업을 할 때, HTTPS를 사용하는 게 좋아요. Next.js에서는 --experimental-https 플래그를 사용해서 간단하게 자체 서명된(self-signed) 인증서를 생성하고 HTTPS 환경을 띄울 수 있답니다.

next dev --experimental-https

이렇게 하면 Next.js 개발 서버가 https://localhost:3000 에서 실행되는데요, 기본 포트인 3000번이 사용되고, 만약 다른 포트를 쓰고 싶다면 -p, --port 옵션이나 환경변수 PORT를 통해 지정할 수 있어요.

더 나아가서, 자신만의 인증서나 키를 직접 넣고 싶다면 아래 옵션을 활용하면 됩니다.

옵션	설명
`--experimental-https-key`	커스텀 HTTPS 키 파일 경로 지정
`--experimental-https-cert`	커스텀 인증서 파일 경로 지정
`--experimental-https-ca`	커스텀 CA 인증서 파일 경로 지정

예를 들어, 회사 내부에서 자체 인증서를 관리하고 있다면 이 옵션들을 사용해서 그대로 적용할 수 있겠죠.

참고로!
로컬에서 HTTPS를 사용할 때 브라우저가 '안전하지 않다'고 경고하는 경우가 있어요. 이유는 자체 서명된 인증서이기 때문이죠. 실제 서비스용으로 사용하려면 공인된 인증서를 발급받아야 하지만, 개발할 때는 그냥 이 경고 무시하고 진행해도 크게 문제없어요. 그래도 개발 중에도 HTTPS 환경을 미리 만들어 테스트해보면 많은 문제가 사전에 걸러져서 좋아요!

이렇게 Next.js가 HTTPS 환경 구축을 좀 더 쉽게 도와주니, 보안이 필요한 기능 개발 시 꼭 활용해 보세요.

next dev --experimental-https --experimental-https-key ./certificates/localhost-key.pem --experimental-https-cert ./certificates/localhost.pem

next dev --experimental-https 옵션은 오직 개발 환경에서만 사용하도록 설계되어 있습니다. 이 옵션을 쓰면 mkcert를 통해 로컬에서 신뢰할 수 있는 인증서를 자동으로 만들어주는데, 편리하긴 하지만 진짜 운영 환경에선 신뢰할 수 있는 인증 기관에서 발급받은 정식 인증서를 써야 합니다.

참고로, Vercel에 배포할 경우에는 HTTPS 설정이 자동으로 처리되니 별도로 신경 쓰지 않아도 됩니다.

아래 방향 프록시(downstream proxy)에서 타임아웃 설정하기

여기서 잠깐! 개발 중에 프록시 서버를 쓰다가 요청 지연 때문에 문제가 생긴 경험 있으신가요? 프록시 설정 시 타임아웃 시간을 적절하게 조절해주면 네트워크 안정성을 높이는 데 도움이 됩니다.

예를 들어, Next.js 프로젝트에서 프록시를 설정할 때 http-proxy-middleware 같은 라이브러리를 사용한다면, 아래처럼 타임아웃 옵션을 넣을 수 있어요:

const { createProxyMiddleware } = require('http-proxy-middleware');

module.exports = function(app) {
  app.use('/api', createProxyMiddleware({
    target: 'http://backend.server',
    changeOrigin: true,
    timeout: 5000, // 5초 대기 후 타임아웃 처리
    proxyTimeout: 5000,
  }));
};

타임아웃 설정을 해주면, 백엔드 API가 응답하지 않을 때 프론트엔드가 무한 대기 상태에 빠지지 않도록 방지할 수 있으니 꼭 활용해 보세요!

개발할 때 HTTPS 설정, 프록시 타임아웃 등 이런 작은 디테일 하나하나가 전체 앱의 안정성과 개발 경험을 훨씬 더 좋게 만들어요. 앞으로도 이런 팁들 계속 공유할게요!

Next.js를 AWS ELB나 ALB 같은 다운스트림 프록시(Load Balancer 등) 뒤에 배포할 때, Next.js가 내부적으로 사용하는 HTTP 서버의 keep-alive 타임아웃 설정을 프록시의 타임아웃보다 크게 해주는 게 정말 중요해요.
이걸 안 하게 되면, keep-alive 타임아웃이 도달한 순간 Node.js가 아무런 알림 없이 TCP 연결을 끊어버리는데, 프록시는 여전히 그 연결을 재사용하려고 시도하거든요. 그래서 결국 프록시 에러가 발생해요.

해결 방법

Next.js 프로덕션 서버를 실행할 때는 --keepAliveTimeout 옵션을 밀리초 단위로 넘겨주면 됩니다. 예를 들어 70초(70000ms)로 설정하려면 이렇게 해요:

next start --keepAliveTimeout 70000

Node.js 인자 추가 전달하기

만약 직접 Node.js 인자를 주고 싶다면 NODE_OPTIONS 환경변수를 활용할 수도 있는데요, 예를 들어 메모리 제한을 늘리거나 디버깅 옵션을 넣고 싶을 때 유용해요.

NODE_OPTIONS="--max-old-space-size=4096" next start --keepAliveTimeout 70000

추가 팁

ALB, ELB 같은 프록시는 기본적으로 60초 전후로 타임아웃이 설정되어 있어요. 그래서 Node.js 서버의 keepAliveTimeout은 그보다 약간 더 길게 세팅하는 게 좋습니다.
만약 타임아웃이 너무 짧게 설정되어 있으면 “502 Bad Gateway” 같은 프록시 에러가 발생하는 걸 보실 수 있어요.
이 외에도, 내부 네트워크 상태나 트래픽 특성에 맞춰서 적절히 값을 튜닝해주는 걸 추천합니다.

이렇게만 설정해줘도 Next.js 앱 안정성이 한층 높아지니 꼭 기억해두세요!

Node.js에서 NODE_OPTIONS 환경변수를 활용하면, 다음에 실행할 명령어에 다양한 옵션들을 간편하게 넘길 수 있어요. 특히 Next.js 같은 프레임워크를 실행할 때 유용하죠.

예를 들어 이렇게 쓸 수 있어요:

NODE_OPTIONS='--throw-deprecation' next

이 옵션은 deprecated(사용 중단 예정)된 기능을 사용할 때 경고 대신 에러를 던져서 문제를 더 빨리 발견하게 도와줘요.

NODE_OPTIONS='-r esm' next

-r esm 옵션은 실행 전에 esm 모듈을 리퀴어해서 ES 모듈을 사용할 수 있도록 환경을 세팅해줘요. 물론 Node.js 최신 버전은 기본 지원하지만, 호환성 이슈가 있을 때 유용하답니다.

NODE_OPTIONS='--inspect' next

이 옵션은 디버깅 모드를 켜서 크롬 개발자도구나 VSCode 같은 툴로 디버깅할 수 있게 해줘요.

실제로 NODE_OPTIONS는 Node.js가 실행될 때 항상 참조하기 때문에, 여러 설정을 한 번에 전달 가능해 작업 효율을 올려주죠. 단, 옵션이 복잡해지면 환경변수 길이가 길어질 수 있으니 주의하세요!

필요한 옵션을 적절히 활용해서 Next.js 개발환경을 좀 더 편리하게 만들어보세요~

Next.js 15 CLI 사용하는 방법