이롭게 현명하게

[Next.js] Next.js 무중단 배포, AWS Amplify로 구축하기

dev_y.h — Wed, 20 May 2026 18:07:36 +0900

Next.js Amplify로 배포하기

[들어가며]

멘토링을 진행하면서 배포에 대한 고민을 하게 되었다.

처음에는 기능 구현에 집중했지만 서비스를 운영하는 관점에서 바라보게 되었다.

이전에 진행했던 프로젝트에서는 Vercel을 사용해 배포를 해본 경험이 있다.

Vercel은 설정이 간단하고 Git과 연동하여 자동으로 배포할 수 있다는 장점을 가지고 있어 편리했다.

[Next.js] Next.js를 Vercel에 배포하기

목차 Vercel이란?Next.js 프로젝트 Vercel에 배포하기환경변수 설정커밋부터 배포까지 : 자동 빌드 확인하기 [Vercel이란?]Next.js는 이미 많은 프론트엔드 개발자들이 선택하는 대표적인 React 프레임워크

devyihyun.tistory.com

결과물을 빠르게 확인하는 프로젝트에서 좋은 선택이었다고 생각한다.

그래서 이번 프로젝트에서도 Vercel을 고려했었다.

하지만 프로젝트 주제가 사진 중심이라는 점에서 고민이 생겼다.

지금은 간단하게 사진 촬영 기능만 있지만 앞으로의 확장성을 생각해야 했다.

기능이 추가되더라도 사용자가 불편함을 느끼지 않게 서비스가 중단되지 않는 무중단 배포 환경이 필요했다.

이러한 요구사항을 생각하다 보니 배포만으로는 부족하다고 느껴 인프라 구조까지 함께 고민하게 되었다.

이번 프로젝트에서는 배포만 하는 것이 아닌 이미지 업로드 처리와 데이터 흐름까지 함께 설계해야 했기 때문에 유연한 인프라를 구성할 수 있는 환경이 필요했다.

AWS는 서버를 거치지 않고 파일을 업로드할 수 있다는 장점이 있다.

그래서 이미지 처리를 위해 S3를 활용하는 방법과 Pre-signed URL 방식도 필요하지 않을까라는 생각이 들었다.

그래서 확장성과 유연성을 고려해 AWS를 선택하게 되었다.

AWS는 말로만 들어봤지 복잡하지 않을까?라는 걱정이 앞섰다.

그래서 간단하게 시작할 수 있는 AWS Amplify를 사용해 보기로 했다.

이번 프로젝트에서는 배포를 넘어서 실제 서비스를 운영하며 확장 가능한 구조를 만들어 가는 것을 목표로 하고 있다.

AWS에 대한 자세한 내용은 다음 포스팅에서 작성할 계획이다.

[AWS Amplify 배포 과정]

깃 레포지터리를 만든다.

next.js 프로젝트를 배포할 것이기 때문에 Next.js로 구현했다.

깃 레포지터리

AWS에 로그인을 해준다. [바로가기]

이때 콘솔로그인 또는 계정 생성으로 로그인을 해주어야 한다.

~~뭣도 모르고 프로필 이미지 페이지에서 로그인했다가 엄청 헤매었었다... 여러분들의 시간은 소중하니까~~~

AWS 랜딩 페이지

계정 플랜을 선택해 준다.

6개월은 무료로 사용할 수 있다.

계정 플랜 선택

AWS 콘솔에 접속한다.

AWS 콘솔 화면

콘솔 화면 검색창에서 amplify를 검색한다.

amplify 검색

Amplify 화면에서 앱 배포, 템플릿으로 시작하기 버튼이 보인다.

두 버튼의 결과는 같기 때문에 아무거나 클릭하면 된다.

저는 앱 배포를 클릭했습니다.

앱 배포 클릭

새 앱을 생성하여 설정하는 화면이 나타납니다.

저는 깃 허브의 리포지터리에 있는 내용을 배포해 보겠습니다.

깃 허브 클릭 > 다음 클릭

새 앱 생성 화면

Git에 권한을 허가하는 화면이 나타납니다.

Authorize 클릭

권한 허용

특정 레포지토리만 배포할 수 있도록 선택합니다.

레포지터리를 선택 후 Install & Authorize 클릭

레포지터리 선택

리포지토리 및 브랜치 추가 화면이 나타난다.

리포지토리 및 브랜치 선택 화면

목록에서 선택을 클릭하면 연동했던 리포지터리가 나타난다.

연결한 리포지터리 클릭

리포지터리를 선택하면 브랜치가 선택됩니다.

이때 브랜치는 production 할 브랜치입니다.

브랜치 선택

내 앱은 모노 리포지터리임 : 리포지터리에 백엔드와 함께 있는 리포지터리를 말합니다.

앱 설정 화면이 나타납니다.

빌드 설정에서는 사용하고 있는 패키지 매니저의 명령어를 입력합니다.

저는 npm을 사용한 프로젝트이므로 npm으로 설정해 주었습니다.

고급 설정 화면입니다.

지금 당장 필요한 부분이 없어 설정하지 않았습니다.

설정을 완료하면 검토 화면이 나옵니다.

편집 버튼이 보이는데 편집 버튼을 클릭하면 아무런 동작이 없습니다.

아마 AWS에서 아직 구현 중인 걸로 예상됩니다.(26년 5월 8일 기준)

다음을 클릭하면 배포가 진행됩니다.

앱 배포 진행 중

앱 배포 상태를 확인할 수 있습니다.

앱 배포가 성공하였습니다.

앱 배포 중

배포 완료

[번외 : 배포 삭제]

앱 삭제를 원한다면 앱 삭제를 클릭한 후 진행하면 된다.

https://devyihyun.tistory.com/271

[IT 노트] CI/CD란 무엇인가? 개념부터 파이프라인 이해하기

목차 CI/CD란 무엇인가?CI/CD 파이프라인 구조환경별 배포 전략 [CI/CD란?]CI/CD는 애플리케이션 개발에서 배포까지의 모든 단계를 자동화를 통해서 조금 더 효율적이고 빠르게 사용자에게 배포할 수

devyihyun.tistory.com

잘못된 정보는 댓글에 남겨주시면 감사하겠습니다!

댓글과 좋아요는 큰 힘이 됩니다!

[ 참고자료 ]

[Next.js] Next.js 시작하기 : 프로젝트 생성

dev_y.h — Mon, 18 May 2026 18:10:52 +0900

Next.js

[개발 환경 준비]

Next.js16 버전을 사용하려면 Node.js가 필요하다.

최소 Node.js 버전 : 20.9
운영체제 : macOS, Windows(WSL포함), Linux

https://devyihyun.tistory.com/168

[React] 리액트 시작하기 / 리액트 설치 / 개발환경

목차 작업환경 준비하기Node.js 설치하기yarn 설치하기vscode 설치하기git for windows 설치하기리액트 환경설정 리액트 환경을 설치하는 CRA가 2025년 2월 14일에 종료되었습니다.npx create-react-app 대신 vite

devyihyun.tistory.com

https://devyihyun.tistory.com/15

[VSCODE] VSCODE 설치 / Visual Studio Code 설치하기

목차 VSCODE 설치 VSCODE 환경설정 (한글설정) 번외 [ VSCODE 설치 ] 1. 홈페이지 접속 2. 본인의 운영체제에 맞는 설치 파일 클릭 저는 window운영체제로 설치하였습니다. 2. 설치 파일 클릭 후 동의합니다

devyihyun.tistory.com

https://devyihyun.tistory.com/166

[Node.js] Node.js 설치하기 / 노드js 설치하기

[Node.js 설치하기] ※ 본 포스팅은 윈도우 11의 환경에서 진행되었습니다. Node.js 공식 홈페이지 접속 Node.js Node.js® is a JavaScript runtime built on Chrome's V8 JavaScript engine. nodejs.org LTS와 Current 버전 중 원하

devyihyun.tistory.com

https://devyihyun.tistory.com/167

[yarn] yarn 설치하기

[Node.js 설치] yarn을 설치하기 위해서는 node.js를 설치해야한다. 단축키 윈도우 + Q를 눌려 cmd를 실행한다. node -v 명령어를 입력하고 Enter키를 누른다. 결과가 다음과 같이 버전이 나온다면 설치가

devyihyun.tistory.com

[Next.js 프로젝트 생성하기]

프로젝트를 생성하기 위해 명령어를 입력합니다.

// npm
npx create-next-app

// pnpm
pnpm create-next-app

// yarn
yarn create next-app

[E-LOG] yarn create next-app@latest 오류

목차오류 내용원인해결방법 [오류 내용]사이드 프로젝트가 next.js 15에서 진행하고 있다.라이브러리 사용법이 이해가 가지 않아 라이브러리를 익히기 위해 동일한 환경에서 학습해 보려고 했다.

devyihyun.tistory.com

명령어를 입력하면 다음과 같은 메시지가 표시됩니다.

What is your project named? my-app
Would you like to use the recommended Next.js defaults?
    Yes, use recommended defaults - TypeScript, ESLint, Tailwind CSS, App Router, AGENTS.md
    No, reuse previous settings
    No, customize settings - Choose your own preferences

설치 과정에서 메시지가 표시됩니다.

what is your project named? : 생성할 프로젝트 폴더 이름을 입력하는 단계입니다. 입력한 이름으로 폴더가 생성됩니다.
Would you like to use the recommended Next.js defaults? : Next.js의 기본 설정을 사용할지 묻는 질문입니다. 3가지의 선택지가 있습니다.
- Yes, use recommended defaults : (추천) Next.js에서 권장하는 최신 개발 환경을 자동으로 설정해 줍니다.
  - TypeScript : 타입 안정성을 위한 언어
  - ESLint : 코드 스타일 및 오류 검사
  - Tailwind CSS : 유틸 기반 CSS 프레임워크
  - App Router : 최신 Next.js 라우팅 방식
  - AGENTS.md : 프로젝트 설정 및 안내 파일
- No, reuse previous settings : 이전에 사용했던 설정을 그대로 사용
  - 한 번 설정한 옵션이 있다면 그대로 적용된다.
  - 반복 프로젝트 생성할 때 편리
- No, customize settings : 직접 하나씩 설정을 선택하는 옵션입니다.

<Yes, use recommended defaults 선택 결과>

추천된 기본 설정 결과 화면

<No, customize settings 선택 결과>

설정을 직접 하나씩 선택하는 옵션이다.

<선택 가능한 항목들>

Would you like to use TypeScript? No / Yes
Which linter would you like to use? ESLint / Biome / None
Would you like to use React Compiler? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like your code inside a `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to customize the import alias (`@/*` by default)? No / Yes
What import alias would you like configured? @/*
Would you like to include AGENTS.md to guide coding agents to write up-to-date Next.js code? No / Yes

Would you like to use TypeScript? No / Yes
- TypeScript를 사용할지 결정하는 옵션
- Yes : 타입 안정성, 자동완성, 유지보수성 높음
- No : JavaScript로 간단하게 시작
- → 요즘 Next.js 프로젝트는 거의 기본적으로 TypeScript를 사용해서 Yes를 추천드립니다.
Which linter would you like to use? ESLint / Biome / None
- 코드 스타일과 오류를 검사하는 도구를 선택하는 옵션
- ESLint : 가장 많이 사용하고 되는 표준 도구
- Biome : 빠르고 최신 도구(Rome 후속)
- None : 사용 안 함
- → 안정성을 위해 ESLint를 사용하는 것을 추천드립니다.
Would you like to use React Compiler? No / Yes
- React 성능 최적화를 자동으로 해주는 기능을 사용할지 결정하는 옵션
- 최근에 추가된 옵션으로 아직은 실험적인 부분이 있습니다.
- 자동으로 불필요한 렌더링을 최적화하는 용도
- → 학습용이나 테스트용이라면 Yes, 안정성을 우선시하신다면 No를 추천드립니다.
Would you like to use Tailwind CSS? No / Yes
- Tailwind CSS를 사용할지 결정하는 옵션
- Yes : 빠른 UI 개발 가능
- No : 일반 CSS/SCSS 사용
- → 생산성을 높이기 위해 Yes를 추천드립니다.
Would you like your code inside a `src/` directory? No / Yes
- 소스코드를 src 폴더 안에 넣을지 결정하는 옵션
- Yes : (추천) 폴더 구조 깔끔
- No : 루트에 바로 파일 생성
- → 프로젝트가 커질수록 폴더 구조가 중요해집니다. 그래서 Yes를 추천드립니다.
- 예시

src/
  app/
  components/

Would you like to use App Router? (recommended) No / Yes
- App Router를 사용할지에 대한 여부를 선택합니다.
- Next.js에서는 페이지를 만드는 방법으로 App Router와 Page Router 두 가지가 있습니다.
- Yes : App Router 방식으로 /app폴더 기반입니다. 최신방식으로 서버 컴포넌트 기본지원, 레이아웃, 로딩, 에러처리 구조가 깔끔합니다.
- No : Page Router 방식으로 /pages 폴더 기반입니다. 예전부터 쓰던 방식으로 단순하고 익숙합니다.
- → 공식문서에서도 App Router 방식을 선호하고 있습니다. 그래서 Yes를 추천드립니다.
Would you like to customize the import alias (`@/*` by default)? No / Yes
- 경로 별칭(alias)을 바꿀지 선택하는 부분입니다.
- Yes : 폴더 경로를 [import Button from "@/components/ui/Button"]으로 표현
- No : 폴더 경로를 [import Button from "../../.../../components/ui/Button]으로 표현
- → 저는 Yes를 추천드립니다.
What import alias would you like configured? @/*
- alias를 입력하는 단계입니다.
- @/* , ~/* , src/* 등으로 사용하기도 합니다.
- 일반적으로는 @/*을 많이 사용합니다.
- → 엔터를 누르면 기본 설정인 '@/*'로 설정됩니다.
Would you like to include AGENTS.md to guide coding agents to write up-to-date Next.js code? No / Yes
- AI 코드 도구를 위한 가이드 파일 생성 여부를 선택하는 옵션입니다.
- 필요에 따라 선택하면 되는 설정입니다.

커스텀 설정 한 후 결과 화면

[Next.js 실행]

명령어를 입력해 실행해 줍니다.

npm run dev

성공!

https://devyihyun.tistory.com/270

[Next.js] Next.js + Firebase(Firestore) 연동하기 + API 구조 설계

목차 Firebase란?Firebase 프로젝트 생성하기Firestore 데이터 생성하기Next.js에서 Firebase 연동하기Firestore 데이터 가져오기API Route 구성하기(/api/board)클라이언트에서 데이터 호출하기전체 구조 흐름 정

devyihyun.tistory.com

https://devyihyun.tistory.com/272

[Next.js] Next.js를 Vercel에 배포하기

devyihyun.tistory.com

https://devyihyun.tistory.com/274

[Next.js] Next.js 무중단 배포, AWS Amplify로 구축하기

목차 들어가며AWS Amplify 배포 과정 [들어가며]멘토링을 진행하면서 배포에 대한 고민을 하게 되었다.처음에는 기능 구현에 집중했지만 서비스를 운영하는 관점에서 바라보게 되었다.이전에 진행

devyihyun.tistory.com

잘못된 정보는 댓글에 남겨주시면 감사하겠습니다!

댓글과 좋아요는 큰 힘이 됩니다!

[ 참고자료 ]

https://nextjs.org/docs

[Next.js] Next.js를 Vercel에 배포하기

dev_y.h — Fri, 15 May 2026 18:10:06 +0900

Next.js와 Vercel

[Vercel이란?]

https://vercel.com/products/previews

Next.js는 이미 많은 프론트엔드 개발자들이 선택하는 대표적인 React 프레임워크다.

서버 사이드 렌더링 (SSR), 정적 사이트 생성(SSG) 같은 기능을 쉽게 구현할 수 있어 성능과 SEO 측면에서도 강력한 장점을 제공한다.

하지만 애플리케이션을 개발했다고 해서 끝이 아니다.

실제로 사용자가 접근할 수 있도록 배포하고 이후에도 안정적으로 서비스를 운영하려면 배포 환경과 자동화된 배포 파이프라인(CI/CD)이 필요하다.

이때 Vercel은 Next.js를 만든 팀에서 직접 제공하는 호스팅 플랫폼이다.

별도의 서버 설정이나 복잡한 빌드 과정 없이도 손쉽게 프로젝트를 배포할 수 있다.

특히 GitHub, Git Lab, BitBuckey 같은 Git 저장소와 연결만 하면, 코드 변경 사항이 자동으로 배포되는 CI/CD 환경얼 자연스럽게 제공하기 때문에 생산성을 크게 높여준다.

이 글에서는 Next.js 프로젝트를 준비하고, Vercel을 통해 간단히 배포하는 방법을 살펴본 뒤 Git 저장소와 연동한 자동 배포 CI/CD 과정까지 작성해보려 한다.

이 과정을 따라가다 보면 코드 작성 → git push → 자동배포라는 개발 워크플로우를 경험할 수 있다.

Vercel은 Git 저장소와 연동하면 기본적으로 자동 CI/CD 환경을 제공한다.

추가 설정 없이도 기본 CI/CD가 작동하므로 Next.js + Vercel조합은 초보자에게 매우 편리하다.

<Vercel배포 자동화 과정>

Vercel로 자동 배포하는 과정이다.

https://vercel.com/products/previews

Vercel's toolkit for fueling iteration. – Vercel

Vercel's DX Platform gives your team everything to develop, preview, and ship the best web experiences to the world.

vercel.com

GitHub, GitLab, BitBucket에 코드를 푸시하면 Vercel이 자동으로 빌드한다.
브랜치별로 Preview Deployment를 생성하여 배포 전에 테스트할 수 있다.
main 혹은 production 브랜치로 푸시하면 자동으로 프로덕션 배포가 진행된다.

[Next.js 프로젝트 Vercel에 배포하기]

먼저 Vercel에 배포할 Next.js 프로젝트와 Git이 있어야 하고 Vercel 계정이 있어야 한다.

// [Next.js 프로젝트 생성 추후 추가 예정]

<Vercel 배포 과정>

Next.js 프로젝트 생성
Vercel 계정 생성
Github에 코드 올리기
Vercel에 프로젝트 연결
환경 변수 설정
배포

Github 리포지토리를 Vercel과 연결한다.

깃허브에서 오른쪽 상단 프로필에서 Settings 클릭

깃허브 Settings

https://github.com/settings/profile 화면에 왼쪽 메뉴에서 applications 클릭

application 클릭

Applications에서 Vercel을 찾아 설치한 후 Vercel의 configure 클릭

Configure 클릭

permission은 리퍼지터리에 읽고 쓸 수 있는 것까지 알려준다.

permission

스크롤을 내리면 Repository access를 볼 수 있다.

Repository access

All repositories : 모든 리포지터리에 vercel을 설치
Only select repositories : 원하는 리포지터리에 vercel 설치

저는 원하는 리퍼지터리만 원해 Only select repositories를 선택하였습니다.

리포지터리 선택 후 Save 클릭

깃 리포지터리에서 Production Brach : 현재 설정된 배포 브랜치 설정

Vercel에 로그인 후 오른쪽 상단에 Dashboard 클릭

Vercel 홈페이지

Add New Project 클릭

Add New > Project 클릭

Import git repository에 추가된 것을 확인할 수 있다.

Import 클릭

Vercel과 연결할 프로젝트 정보가 나타난다.

vercel과 연결할 프로젝트 정보

Root Directory
- 루트 디렉터리
Build and output settings
- 빌드할 때 사용 할 명령어다.
- 기본적인 것을 사용하려면 그대로 두면 된다.
- 만약 내가 정한 명령어를 사용하려면 명령어를 작성하면 된다.
Environment Variables
- 환경변수 설정
- .env 파일에 api키라던지 환경 변수라던지 다양한 키들을 설저할 수 있는데 그 키와 value를 설정한다.

필요한 거 다 설정 후 Deploy 클릭

환경변수 설정은 밑에서 다루도록 하겠다.

building > running check > assign domains

building : 빌드를 먼저 한다.
running check : 코드에 문제가 없는지 다양한 체크를 한다.
assign domains : 도메인 할당

배포 완료

Continue to DashBoard 클릭

Continue to Dashboard 클릭

Continue to Dashboard 클릭한 후 화면

어떻게 배포되었는지 상태 확인이 가능하다.

홈페이지 첫 화면
Deployment : 배포된 url
Domain
Status : 현재 상태
Created : 언제 만들어졌는지
Source 브랜치는 무엇인지에 대한 내용

배포 상태를 확인할 수 있는 화면

[환경변수 설정]

.env 파일에 api키라던지 환경변수라던지 다양한 키들을 설정할 수 있다.

그 키와 value를 설정할 수 있다.

환경변수

.env 파일

Vercel에서 환경변수 설정하기

환경변수 설정은 다음과 같이 입력하면 된다.

환경변수 설정

[커밋부터 배포까지 : 자동 빌드 확인하기]

프로젝트에서 변경사항이 발생하면 먼저 Github에 커밋 후 푸시를 한다.

개발자 A가 feat/devA 브랜치에서 사용자 프로필 수정하기 기능을 만들었다.

개발자 A 커밋 푸시

Vercel은 Github 리포지토리와 연동되어 있기 때문에 푸시가 감지되면 자동으로 빌드가 시작된다.

빌드가 완료되면 브라우저에서 배포된 애플리케이션을 확인할 수 있다.

<Domains>

첫 번째 URL
- 공통적으로 사용하는 메인 URL
- 실제 사용자가 보는 URL
두 번째 URL
- 브랜치 별로 만들어진 url이다.
- main 브랜치에 커밋이 발생하면 최신 것들이 반영이 된 현재 main 브랜치에 코드 내용을 반영하고 있는 웹앱 url
세 번째 URL
- 방금 커밋 한 커밋의 변경사항을 반영하고 있는 url

Domains

푸시를 한 후 깃허브에서 빌드/테스트 상태를 확인할 수 있다.

푸시를 한 직후에는 브라운색 표시가 된 것을 볼 수 있다.

클릭해서 확인해 보면 vercel에서 자동으로 감지해서 빌드를 시작하는 것을 확인할 수 있다.

깃허브에서 빌드 상태 확인

<빌드 및 배포 상태 확인 표시>

초록색 체크(✅) → 성공(Successful) : Github Actions나 연결된 CI/CD(예:Vercel)에서 빌드와 테스트가 정상적으로 통과됐음을 의미한다.
빨간색 X(❌) → 실패(Failed)
노란색 점( ) → 진행 중(In progress)

개발자 A가 feat/devA 브랜치를 develop 브랜치에 pull request와 merge를 진행하면 vercel의 Domains에서 Preview URL(두 번째 URL)을 사용할 수 있다.

develop 브랜치로 pr mrege

<주의할 점>

단, Vercel 프로젝트 설정에서 Production Branch가 main이라면 develop은 Production URL에 반영되지 않고 Preview URL로만 확인됩니다.
만약 develop을 Production Branch로 설정해 둔 경우라면 머지 시 첫 번째 URL(Production domain)에 반영됩니다.

Vercel을 사용하면 CI/CD를 경험할 수 있다.

커밋을 하자마자 터미널에서 따로 빌드를 하고 배포하는 과정을 복잡하게 거치는 것이 아닌 코드를 올려둔 깃허브를 Vercel을 연동해 두면 Vercel이 우리 프로젝트를 감지하고 있으면서 새로운 커밋이 발생하는 순간 커밋 별로 url을 만들어주고 브랜치 별로 url을 만들어 즉각적으로 확인이 가능하다.

https://devyihyun.tistory.com/271

[IT 노트] CI/CD란 무엇인가? 개념부터 파이프라인 이해하기

devyihyun.tistory.com

잘못된 정보는 댓글에 남겨주시면 감사하겠습니다!

댓글과 좋아요는 큰 힘이 됩니다!

[ 참고자료 ]

https://vercel.com/geist/brands#vercel

Geist

Vercel's design system called Geist. Made for building consistent and delightful web experiences.

vercel.com

[IT 노트] CI/CD란 무엇인가? 개념부터 파이프라인 이해하기

dev_y.h — Wed, 13 May 2026 18:10:55 +0900

CI/CD란?

[CI/CD란?]

CI/CD

CI/CD는 애플리케이션 개발에서 배포까지의 모든 단계를 자동화를 통해서 조금 더 효율적이고 빠르게 사용자에게 배포할 수 있도록 하는 것을 말한다.

기업에서는 시장과 고객의 요구를 빠르게 분석하고 반응해야 하기 때문에 제품을 출시, 업데이트할 것인지가 가장 큰 과제이다.

프로젝트 규모가 커질수록 단순히 코드를 작성하는 것보다 코드가 안정적으로 동작하고 빠르게 배포되는 것이 중요해진다.

그래서 많은 기업들이 CI/CD 프로세스를 사용하고 있다.

<CI(Continuous Integration)>

지속적인 통합
개발자가 작업한 코드를 저장소에 Merge 하고 자동으로 빌드 및 테스트를 실행해 코드 품질을 보장하는 과정이다.
기본 과정
- 개발자가 코드 커밋 → 버전 관리 시스템(Git 등)
- 자동 빌드(Build) → 코드가 정상적으로 합쳐지는지 확인
- 자동 테스트 (Test) → 기존 기능이 깨지지 않는지 검증

CI를 통해 코드가 전체 프로젝트에 문제를 일으키는지 여부를 빠르게 알 수 있다.

<CD(Continuous Deployment)>

지속적인 배포
통합된 코드가 자동으로 배포 환경까지 전달되는 과정
코드가 저장소에 Merge 되면 별도의 수동 배포 과정 없이 자동으로 배포되는 것이 핵심
Continuous Delivery
- 배포 준비 상태까지 자동화
- 사람이 승인하면 배포 진행
Continuous Deployment
- 승인 없이 자동으로 운영 환경까지 배포
- 빠른 피드백과 릴리즈 속도 장점

Delivery = 배포 준비, Deployment = 배포 완료

CI/CD를 통해 테스트와 빌드 및 배포 과정을 자동화할 수 있다.

<CI/CD 전체 흐름>

일반적인 CI/CD 단계다.

CI/CD 과정

코드 커밋 푸시 (Commit / Push)
- 개발자가 새로운 기능이나 수정 사항을 저장소에 올린다.
빌드 (Build)
- 소스 코드를 실행 가능한 애플리케이션 형태로 변환하는 과정이다.
- 코드가 정상적으로 컴파일되고 패키징 되는지를 확인
테스트 (Test)
- 자동화된 테스트를 통해 코드가 정상 동작하는지 확인한다.
- 이 단계에서 문제가 발생하면 배포 전에 개발자에게 즉시 피드백이 전달된다.
통합 (Merge)
- 검증된 코드가 메인 브랜치에 합쳐진다.
- 여러 명의 개발자가 동시에 작업해도 코드 품질을 일정하게 유지할 수 있다.
배포 (Deploy)
- 최종적으로 운영환경에 반영되어 사용자들이 새로운 기능을 이용할 수 있다.

이 과정까지 자동화되면 새로운 기능을 사용자에게 빠르게 제공할 수 있다.

<CI/CD가 필요한 이유>

자동화된 품질 보장 : 빌드와 테스트가 자동으로 실행되어 코드 오류를 조기에 발견할 수 있다.
빠른 배포 주기 : 코드가 Merge 되면 바로 배포되어 개발 - 테스트 - 운영 사이클이 단축된다.
안정성 확보 : 브랜치 전략과 결합해 Staging/Production 환경을 분리할 수 있어 안정적인 운영이 가능하다.

<CI/CD 장단점>

빠른 피드백 : 버그를 초기에 발견
협업 효율 향상 : 여러 개발자가 동시에 작업해도 안정적
배포 안정성 : 자동 테스트와 단계별 검증으로 오류 감소

[CI/CD 파이프라인 구조]

CI/CD의 구체적인 파이프라인은 단순히 빌드와 배포로 끝나지 않는다.

일반적으로 아래와 같은 과정을 거친다.

출처 : https://blog.bytebytego.com/p/a-crash-course-in-cicd

계획(plan)
- 개발해야 할 기능이나 수정사항을 정의
코드(code)
- 실제 기능 개발과 버전 관리가 이루어지는 단계
빌드(build)
- 소스 코드를 실행 가능한 애플리케이션으로 변환
테스트(test)
- 자동화된 테스트를 통해 코드의 품질을 보장
릴리즈(release)
- 배포 가능한 형태로 패키징하고 승인 프로세스를 거친다.
배포(deploy)
- 준비된 애플리케이션을 실제 환에 배포
운영(operate)
- 서비스가 정상적으로 동작하는지 운영 단계에서 관리
모니터링(monitor)
- 서비스 상태를 지속적으로 관찰하고, 장애나 성능 문제를 빠르게 파악

[환경별 배포 전략]

CI/CD에서 중요한 포인트는 개발 환경별로 배포 전략을 나누는 것이다.

크게 3가지 환경(브랜치)으로 나눈다.

main 브랜치
develop 브랜치
feat 브랜치

환경별 브랜치

1. feat 브랜치

새로운 기능이나 버그 수정 작업을 하는 개발 브랜치다.

만약 버그를 수정한다면 브랜치는 fix/devA 형식이 된다.

feat 브랜치

2. develop 브랜치

feat 브랜치에서 코드를 push 하여 모아두는 브랜치다.

앱을 출시하기 전에 테스트를 할 수 있다.

develop 브랜치

3. main 브랜치

Production 환경으로 실제 사용자가 서비스를 이용하는 브랜치다.

항상 안정적인 코드만 존재한다.

main 브랜치

이제 CI/CD 개념을 이해했다면 실제로 자동 배포가 어떻게 이루어지는지 알아 보록 합시다.

Next.js와 Vercel을 이용해 코드 push 자동 배포 방법 보러가기

잘못된 정보는 댓글에 남겨주시면 감사하겠습니다!

댓글과 좋아요는 큰 힘이 됩니다!

[ 참고자료 ]

https://testrigor.com/blog/what-is-cicd/

What Is CI/CD? Expedite The Software Development Life Cycle - testRigor

CI/CD is a DevOps best practice that consists of continuous integration, delivery, and deployment. It expedites the software development life cycle. Read more!

testrigor.com

https://blog.bytebytego.com/p/a-crash-course-in-cicd

A Crash Course in CI/CD

Introduction

blog.bytebytego.com

https://www.blackduck.com/glossary/what-is-cicd.html

What Is CI/CD and How Does It Work? | Black Duck

Continuous integration (CI) is practice that involves developers making small changes and checks to their code. Due to the scale of requirements and the number of steps involved, this process is automated to ensure that teams can build, test, and package t

www.blackduck.com

[Next.js] Next.js + Firebase(Firestore) 연동하기 + API 구조 설계

dev_y.h — Mon, 11 May 2026 18:10:08 +0900

Next.js와 Firebase

[Firebase란?]

Firebase

Firebase는 구글이 운영하는 백엔드 서비스로 애플리케이션에서 공통적으로 사용하는 백엔드 기능을 모아놓은 플랫폼이다.

웹, 앱 프로토타입이나 MVP 제품을 만들어야 하는 상황이라면 좋은 서비스다.

Firebase에는 Authentication이라는 서비스가 있다.

사용자 인증에 대한 서비스로 로그인, 회원가입, 비밀번호 찾기와 같은 인증과 관련된 서비스를 간단하게 개발할 수 있다.

사용자의 데이터를 저장하거나 조회할 수 있는 Firestore나 Realtime database 서비스가 있다.

이 서비스들은 NoSQL 기반으로 사용자의 데이터를 빠르게 저장할 수 있도록 지원한다.

Firebase의 큰 핵심은 빠르게 애플리케이션을 만들면서 출시하고 모니터링이 가능하다.

빠르게 시장 반응을 봐야 하는 스타트업에서 앱을 만들 때 앱에는 회원가입 기능이 있고 스타트업이 제공하는 핵심 기능이 있다.

사용자로서는 회원가입, 로그인, 계정 찾기 기능은 특별한 기능은 아니다.

하지만 백엔드 입장에서는 회원가입, 로그인, 계정 찾기와 같은 인증에 관한 서비스를 신규로 구축하고 유지보수하는 것은 까다로운 일이다.

프로젝트 스펙에 따라서 굉장한 비용이 소모되기 때문이다.

스타트업에서는 핵심 비즈니스 로직을 빨리 개발해서 프로토타입을 출시해야 하는데 이런 공통적인 기능만 만들다가 끝나버릴 수 있다.

이럴 때 파이어베이스 Authentication을 활용하면 간단히 해결할 수 있다.

처음에 Firebase를 접했을 때는 RDBMS와 같은 형태라고 생각했다.

하지만 실제로는 NoSQL 문서 중심 구조로 데이터를 조인해서 조회하는 방식이 지원되지 않아 많이 당황스러웠다.

그래서 UI/UX 흐름에 맞춰 데이터를 설계하는 데이터 모델링 과정이 매우 중요하다는 것을 알게 되었다.

[Firebase 프로젝트 생성하기]

Firebase에 로그인 후 Go to Console을 클릭한다.

로그인 후 Go to Console 클릭

Firebase 프로젝트 시작하기 클릭

프로젝트 이름 작성

저는 개발자 프로그램에 가입하기는 off 했습니다.

개발자 프로그램 가입하기 off

Gemini 사용 설정 화면이 나옵니다. 저는 사용하지 않았습니다.

gemini 사용 설정 off

Google 애널리틱스를 설정하는 화면이 나옵니다.

지금 당장은 필요하지 않다고 생각되어 설정하지 않았습니다.

프로젝트 만들기 클릭

기다리기

로딩 중

계속 클릭

프로젝트 개요 > 설정 > 프로젝트 설정

프로젝트 개요 > 설정

프로젝트 설정 클릭

프로젝트에 대한 정보가 나온다.

프로젝트 정보

저는 앱보다는 웹을 만들어보고 싶어 웹을 클릭했습니다.

웹 클릭

웹 앱의 이름 입력 > 앱 등록 클릭

Firebase에서 호스팅을 원하면 체크하면 됩니다.

저는 호스팅을 Vercel에서 할 예정이기 때문에 설정하지 않았습니다.

프로젝트 앱 등록

앱 등록을 클릭한 다음 화면에서 시크릿키가 나옵니다.

콘솔로 이동을 클릭해 줍니다.

시크릿 키

프로젝트 시크릿키

이제 Firebase 프로젝트를 생성했으니 실제로 데이터를 저장할 Firestore를 설정해 보겠습니다.

사이드바에서 모든 제품 클릭

모든 제품 클릭

cloud Firestore 클릭

데이터베이스 만들기 클릭

데이터베이스 만들기에서 위치를 서울로 설정

(서버 위치는 서비스와 운영되는 곳과 가까우면 좋습니다.)

이때 위치를 설정한 후에는 수정이 불가능합니다.

데이터베이스 위치 설정

저는 테스트 모드에서 시작을 했습니다.

테스트 모드에서 시작 > 만들기 클릭

테스트 모드에서 시작

만드는 중

컬렉션은 데이터를 그룹으로 묶는 단위입니다.

컬렉션 시작 클릭

컬렉션 ID를 입력합니다.

간단한 테스트로 게시판 내용을 만들어볼 예정입니다.

그래서 저는 컬렉션 ID를 board로 하였습니다.

컬렉션 ID

문서 ID는 자동 ID를 클릭하였습니다.

board 컬렉션 문서 id

그리고 필드를 생성해 주었습니다.

문서 구조

저장 버튼을 클릭하면 다음과 같은 결과가 나옵니다.

Firebase에서 Firestore 데이터 설계가 완료되었습니다.

[Next.js에서 Firebase 연동하기]

[Firebase 공식문서 바로가기]

<연동단계>

Firebase SDK 설치
Firebase 앱 초기화
Firestore 연결 설정

1. Firebase SDK 설치

Firebase 프로젝트 생성과 Firestore 데이터 설계까지 완료하였습니다.

지금 상태는 Firebase 콘솔에만 데이터가 존재할 뿐 Next.js 애플리케이션에서는 해당 데이터를 사용할 수 없습니다.

따라서 Firebase SDK를 설치하고 Next.js에서 Firestore에 접근할 수 있도록 연동이 필요합니다.

Firebase는 클라이언트에서도 직접 접근할 수 있지만, 보안을 고려하여 API Route를 통해 접근하는 구조로 설계했습니다.

npm install firebase

vscode 화면

명령어 실행

2. Firebase 앱 초기화

Firebase를 사용하려면 프로젝트 설정 정보를 기반으로 앱을 초기화해야 합니다.

발급받은 프로젝트 시크릿키를 설정해 줍니다.

src/data/firestore.ts

firestore.ts

3. Firestore연결

DB랑 연결해 주기 위해 코드를 추가해 줍니다.

firestore 연결

그리고 컬렉션의 모든 문서를 읽을 수 있도록 설정해주어야 합니다.

firestore.ts에 코드를 추가합니다.

import { collection, getDocs } from "firebase/firestore";

const querySnapshot = await getDocs(collection(db, "board"));
querySnapshot.forEach((doc) => {
    // doc.data() is never undefined for query doc snapshots
    console.log(doc.id, " => ", doc.data());
});

컬렉션 문서 읽기

비동기로 가져오기 위해 async를 사용해 줍니다.

import { initializeApp } from "firebase/app";
import { collection, getDocs, getFirestore } from "firebase/firestore";

// Your web app's Firebase configuration
const firebaseConfig = {
    apiKey: process.env.API_KEY,
    authDomain: process.env.AUTH_DOMAIN,
    projectId: process.env.PROJECT_ID,
    storageBucket: process.env.STORAGE_BUCKET,
    messagingSenderId: process.env.MESSAGING_SENDER_ID,
    appId: process.env.APP_ID,
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);
const db = getFirestore(app);

export async function fetchData() {
    const querySnapshot = await getDocs(collection(db, "cities"));
    querySnapshot.forEach((doc) => {
        // doc.data() is never undefined for query doc snapshots
        console.log(doc.id, " => ", doc.data());
    });
}

async 적용

<코드 설명>

const querySnapshot = await getDocs(collection(db, "cities")); : db에 "cities"라는 컬렉션을 가져온다.

저는 데이터베이스에 board라는 컬렉션을 만들어 둬서 board로 수정해 주었습니다.

querySnapshot은 Firestore에서 가져온 문서들의 집합이며 각 문서는 doc 객체로 접근할 수 있습니다.

<초기화 전체 코드>

import { initializeApp } from "firebase/app";
import { collection, getDocs, getFirestore } from "firebase/firestore";

// Your web app's Firebase configuration
const firebaseConfig = {
    apiKey: process.env.API_KEY,
    authDomain: process.env.AUTH_DOMAIN,
    projectId: process.env.PROJECT_ID,
    storageBucket: process.env.STORAGE_BUCKET,
    messagingSenderId: process.env.MESSAGING_SENDER_ID,
    appId: process.env.APP_ID,
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);
const db = getFirestore(app);

export async function fetchData() {
    const querySnapshot = await getDocs(collection(db, "board"));
    querySnapshot.forEach((doc) => {
        // doc.data() is never undefined for query doc snapshots
        console.log(doc.id, " => ", doc.data());
    });
}

초기설정 전체 코드

<모든 게시글 가져오기>

import { initializeApp } from "firebase/app";
import firebase from "firebase/compat/app";
import { collection, getDocs, getFirestore } from "firebase/firestore";

type BoardItem = {
    id: string;
    title: string;
    content: string;
    createAt: firebase.firestore.Timestamp;
};

// Your web app's Firebase configuration
const firebaseConfig = {
    apiKey: process.env.API_KEY,
    authDomain: process.env.AUTH_DOMAIN,
    projectId: process.env.PROJECT_ID,
    storageBucket: process.env.STORAGE_BUCKET,
    messagingSenderId: process.env.MESSAGING_SENDER_ID,
    appId: process.env.APP_ID,
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);
const db = getFirestore(app);

// 모든 게시글 가져오기
export async function fetchData() {
    const querySnapshot = await getDocs(collection(db, "board"));
    if (querySnapshot.empty) {
        return [];
    }
    const fetchArray: BoardItem[] = [];
    querySnapshot.forEach((doc) => {
        // doc.data() is never undefined for query doc snapshots
        console.log(doc.id, " => ", doc.data());
        const getData: BoardItem = {
            id: doc.id,
            title: doc.data()["title"],
            content: doc.data()["content"],
            createAt: doc.data()["createAt"].toDate(),
        };
        fetchArray.push(getData);
    });
    return fetchArray;
}

module.exports = {
    fetchData,
};

Firestore의 Timestamp 타입은 그대로 사용할 수 없기 때문에 JavaScript Date 객체로 변환해 주어야 합니다.

그래서. toDate()를 사용합니다.

[API Router 구성하기]

클라이언트가 Firebase에 직접 접근할 수 있지만 보안과 구조 분리 위해 서버(API Route)를 통해 데이터를 가져오는 방식으로 설계했습니다.

이 구조를 사용하면

민감한 로직을 서버에 숨길 수 있다.
권한 검증 로직 추가가 쉽다.
유지보수와 확장이 용이다.

Firebase에서 데이터를 가져오는 fetchdata()를 호출하는 GET Method를 생성해 줍니다.

이때 데이터를 JSON 형태로 클라이언트에 반환합니다.

// src/app/api/board/route.ts
import { fetchData } from "@/data/firestore";
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
    try {
        const fetchedData = await fetchData();
        return NextResponse.json(
            { message: "데이터 가져오기 성공", data: fetchedData },
            { status: 200 }
        );
    } catch (error) {
        console.error("서버 에러:", error);
        return NextResponse.json({ message: "서버 에러", error: String(error) }, { status: 500 });
    }
}

localhost에서 확인하면 다음과 같이 나옵니다.

[클라이언트에서 데이터 호출하기]

클라이언트에서는 API를 호출하여 데이터를 가지고 옵니다.

/api/board API를 호출하여 데이터를 가져와야 합니다.

응답데이터를 state에 저장 후 UI에 렌더링 하는 방식으로 진행했습니다.

// src/app/board/page.tsx

"use client";

import { useEffect, useState } from "react";

type BoardItem = {
    id: string;
    title: string;
    content: string;
    createAt: string;
};

export default function Page() {
    const [boardData, setBoardData] = useState<BoardItem[]>([]);
    const [loading, setLoading] = useState(true);

    useEffect(() => {
        async function fetchBoard() {
            try {
                const response = await fetch("/api/board");
                const result = await response.json();
                setBoardData(result.data);
            } catch (error) {
                console.error("데이터 불러오기 실패", error);
            } finally {
                setLoading(false);
            }
        }
        fetchBoard();
    }, []);

    if (loading) {
        return <div>로딩중...</div>;
    }

    return (
        <div className="p-4">
            <h1 className="text-2xl font-bold mb-4">게시판 데이터</h1>
            <ul className="space-y-2">
                {boardData.map((item) => (
                    <li key={item.id} className="border p-2 rounded">
                        <h2 className="text-xl">{item.title}</h2>
                        <p>{item.content}</p>
                        <small>{item.createAt.toLocaleString()}</small>
                    </li>
                ))}
            </ul>
        </div>
    );
}

브라우저 화면에서 데이터가 잘 나오는 것을 확인할 수 있습니다.

브라우저에서 api 호출

[전체구조 흐름 정리]

Next.js + Firebase를 이용해서 게시판 데이터를 가져오는 구조이다.

Next.js와 Firebase의 구조

데이터베이스의 구조는 다음과 같다.

// board(Collection)
//  └─ {id} (Document)
//       ├─ id
//       ├─ title
//       ├─ content
//       └─ createAt

type BoardItem = {
    id: string;
    title: string;
    content: string;
    createAt: firebase.firestore.Timestamp;
};

Firestore(데이터베이스 계층)
- firebase SDK를 사용해 Firebase에 연결
- fetchData() : "board" 컬렉션에 데이터를 가져오는 함수 → board 컬렉션을 읽고 BoardItem[] 배열로 변환
Next.js API Route(서버 계층)
- Next.js API Route
- 클라이언트가 직접 Firebase에 접근하지 않고 /api/board라는 API를 만들어 fetchData를 호출
- 가져온 데이터를 JSON 응답으로 반환
Next.js Page(클라이언트 계층)
- /board 페이지에서 API(/api/board)를 호출해 데이터를 불러 옴
- React 컴포넌트로 UI에 렌더링

<설계 구조>

설계 구조

데이터베이스 : "board" 컬렉션 저장
서버 : 클라이언트 요청을 받아 Firestore에서 데이터 가져오기
클라이언트 : API 응답을 받아 UI에 렌더링

<코드 구성>

코드 구성

firestore.ts : Firestore연결& 데이터 fetch함수 정의
route.ts : API 엔드 포인트(/api/board)
page.tsx : 클라이언트에서 API 호출 & 화면 출력

<데이터 흐름>

/board 접속
클라이언트 → /api/board API 호출
API → firestore에서 "board" 컬렉션 데이터 조회
Firestore → API → 클라이언트(JSON) 응답
클라이언트 UI 렌더링

<구현 특징>

비동기 흐름 : fetch → API → Firestore의 데이터 요청 과정이 비동기적으로 이루어짐
보안 : 클라이언트가 직접 Firestore에 접근하지 않고 API 경유
타입 안전성 : BoardItem 타입으로 데이터 구조 관리
UX 고려 : 로딩 상태 표시
확장성 : 추후 데이터 추가/수정 API 확장 가능

잘못된 정보는 댓글에 남겨주시면 감사하겠습니다!

댓글과 좋아요는 큰 힘이 됩니다!

ps) 내용을 어떻게 하면 더 잘 정리할 수 있을까..

[ 참고자료 ]

https://vercel.com/geist/brands#next-js

Geist

Vercel's design system called Geist. Made for building consistent and delightful web experiences.

vercel.com

https://firebase.google.com/brand-guidelines?hl=ko

Firebase Brand Guidelines

Firebase 브랜드 표시

firebase.google.com

https://firebase.google.com/docs/firestore/quickstart?hl=ko&_gl=1*9fvdc0*_up*MQ

Firestore Standard 버전 시작하기 | Firebase

데이터베이스를 만들고, 데이터를 추가하고, 데이터를 읽는 방법을 비롯하여 Cloud Firestore를 시작하는 방법을 안내합니다.

firebase.google.com

https://www.youtube.com/watch?v=aWI5NDJ1J_4

[VSCODE] postman 사용법

dev_y.h — Fri, 8 May 2026 18:10:02 +0900

vscode postman 사용법

[Postman이란?]

Postman은 개발자가 만든 API를 테스트하고 테스트 결과를 공유하여 API 개발의 생산성을 높여주는 도구이다.

API 테스트뿐만 아니라 설계, 관리를 할 수 있도록 지원하고 있다.

REST/SOAP/WebSocket 등 다양한 프로토콜 지원과 모의 서버 생성 기능을 제공한다.

<주요 개념>

요청(Request) : GET, POST, PUT, DELETE 등 다양한 HTTP 요청을 실행
환경(Environment) : API 주소, 토큰 등을 변수로 관리
Collection : 여러 API 요청을 하나의 프로젝트로 묶어 관리
Script : 테스트 코드나 pre-request 스크립트 작성
Mock Server/Monitor : API를 시뮬레이션하거나 주기적으로 모니터링

API 요청 후 응답(Response)에는 JSON 형식의 데이터가 반환된다.

[Postman 설치]

postman은 무료로 사용할 수 있고 설치 방법도 간단하다.

<설치 가능한 종류>

웹
앱
vscode

TIP) Sync 기능을 사용하기 위해 로그인을 하여 사용하는 것을 추천한다.

1. 웹에서 사용하기

웹에서는 포스트맨 사이트에서 가입을 하고 Sign in으로 계정을 로그인하면 사용 가능하다.

하지만 웹으로 사용하게 되면 보안 이슈로 요청이 실패할 수 있다.

그래서 앱 설치를 추천한다.

https://www.postman.com/ 에서 Sign in을 클릭

Postman: The World's Leading API Platform | Sign Up for Free

Accelerate API development with Postman's all-in-one platform. Streamline collaboration and simplify the API lifecycle for faster, better results. Learn more.

www.postman.com

postman 홈페이지에서 sign in 클릭

원하는 회원가입 방식을 클릭한다.

저는 구글로 회원가입 했습니다.

회원가입 화면

자신의 직업을 선택한 후 Continue 클릭

직업 선택 화면

저는 Run test automation for existing APIs (기존 API에 대한 테스트 자동화 실행)을 클릭하였습니다.

기존 API에 대한 테스트 자동화 실행
기존 API와 통합
기존 API 탐색
API 배포
새로운 API를 처음부터 설계하고 구축하기
기존 API 구축 또는 향상
Postman 사용법 배우기

시작하기 클릭

2. 앱설치

저는 윈도우를 사용하고 있어 윈도우 아이콘을 클릭했습니다.

윈도우 아이콘 클릭

Windows 64-bits를 클릭

설치 버튼클릭

다운로드가 완료되면 설치 파일 실행

설치가 완료되면 바탕 화면에 아이콘이 생긴다.

바탕화면 아이콘

로그인을 한다.

로그인 화면

postman 열기 클릭 후 팝업창이 나오는데 허용하면 된다.

postman 허용

설치 완료

앱 실행 화면

3. VSCODE에서 사용하기

vscode에서 postman을 사용할 수 있다.

vscode에서 extension 클릭

vscode 화면

postman 입력

install 클릭

extension 검색 화면

trust 클릭

접근 허용

로그인/회원가입

open클릭

Open 클

설치 완료

[postman 사용 방법]

vscode postman 기준으로 설명하겠습니다.

'+' 버튼 클릭

생성하기

New Collection이 생성되었습니다.

New Collection 생성

Collection의 이름을 수정할 수 있습니다.

collection 이름 수정

Add Request 클릭

url에 따라 사용할 수 있습니다.

API 테스트를 보여드리기 위해 https://jsonplaceholder.typicode.com/ 로 테스트 해보겠습니다.

api 테스트

https://jsonplaceholder.typicode.com/를 입력해 줍니다.

입력 후 Send 클릭

Send 클릭

결과를 확인할 수 있습니다.

api 요청 결과화면

HTTP 메서드를 사용할 수 있습니다.

HTTP 메서드

<요청 시 데이터를 body로 보내는 방법>

Body 탭에서 raw 선택 > 데이터 타입을 JSON으로 선택

body로 요청 보내기

[Postman에서 토큰 등록하는 방법]

Collectoin을 클릭

Collection 화면

Authorization 클릭 > Type에서 선택

저는 JWT에서 Bearer Token을 사용 중입니다.

Bearer Token 선택

Authorization 설정

사용할 JWT 토큰 값을 입력해 줍니다.

JWT 토큰값 입력

Request 탭에서 Authorization 설정을 진행합니다.

이 요청은 상위(부모) Collection에서 지정한 인증 정보를 자동으로 상속받도록 구성했습니다.

그 결과, 요청을 보낼 때 필요한 토큰이 헤더에 자동으로 포함되어 전송되도록 설정됩니다.

잘못된 정보는 댓글에 남겨주시면 감사하겠습니다!

댓글과 좋아요는 큰 힘이 됩니다!

[ 참고자료 ]

https://www.youtube.com/watch?v=hZJNwZssuhg

https://www.youtube.com/watch?v=3c7L3fFUj-4

https://www.youtube.com/watch?v=2TZXMYYD1bs

[이미지 출처]

https://uxwing.com/postman-icon/

Postman Icon PNG and SVG Vector Free Download

Postman Icon PNG and SVG free use any commercial projects no attribution required.

uxwing.com

[IT노트] 인증과 인가, JWT 정리

dev_y.h — Wed, 6 May 2026 18:10:29 +0900

JWT란? 인증과 인가

[인증(Authentication)과 인가(Authorization)]

로그인 기능을 구현할 때 단순히 데이터베이스에 있는 내용과 일치하면 로그인이 가능하게 구현하였다.

로그인 과정

하지만 이 방식은 보안상 취약하다.

사용자가 입력한 정보로 데이터베이스에서 필드를 찾는 방식은 사용자의 인증 정보를 안전하게 처리하지 못할 뿐 아니라 로그인 상태를 유지하는 데도 한계가 있다.

이러한 기본적인 로그인 구현을 넘어서 마주한 문제는 안전하게 로그인 상태를 유지하는 것이다.

단순히 사용자 인증에 성공하는 것만으로는 충분하지 않다.

사용자가 한 번 로그인을 하면 사용자가 로그인한 상태인 것을 서버가 알고 있어야 한다.

만약 로그인 상태가 유지가 안된다면 사용자가 메일함에 들어갈 때마다, 메일을 읽거나 삭제, 전송을 할 때마다 매번 로그인을 해야 하는 불편함을 겪게 된다.

그래서 인증과 인가를 어떻게 처리할지, 로그인 상태를 유지하는 것이 가장 까다로운 부분이다.

로그인 구현 시 단순한 사용자 확인을 넘어서 세션관리, 토큰 기반 인증 등의 보안 방식을 고려해야 한다.

이때 가장 기본적으로 알아야 하는 것은 인증과 인가이다.

인증(Authentication) : "누구세요?"
- 사용자가 본인임을 증명하는 단계
- 예 : 로그인
인가(Authorization) : "나 이거 해도 돼?"
- 사용자가 사이트에 대한 권한을 허락하는 것
- 접근 권한을 부여하거나 거부하는 행위
- 예 : 로그인 사용자만 이용 가능, 관리자만 접근 가능한 페이지

	인증(Authentication	인가(Authorization)
의미	사용자가 누구인지 확인하는 과정으로 증명을 하는 행위	사용자가 사이트에 대한 권한을 허락하는 것으로 접근 권한을 부여하거나 거부하는 행위
예시	회원가입, 로그인	관리자 권한 확인
순서	먼저 수행된다.	인증 후 수행된다.

[로그인 상태 인식하기]

로그인 상태를 유지하려면 로그인을 한 상태를 인식해야 한다.

<로그인 상태를 인식하는 두 가지 방법>

로그인 상태
비로그인 상태

사용자 중 로그인을 한 사용자와 로그인을 하지 않은 비로그인 상태의 사용자가 있다.

서버는 사용자가 요청을 보내면 사용자가 로그인이 되어있는 상태인지 먼저 확인을 한 후 로그인한 사용자에게만 허용된 기능을 이용할 수 있도록 응답한다.

예를 들어, 로그인을 한 상태라면 메일을 보내거나 댓글을 작성할 수 있는 기능을 사용할 수 있다.

비로그인 사용자는 이용할 수 없는 기능이다.

로그인 상태인 사용자와 비로그인 상태의 사용자

이렇게 매번 서버에 요청할 때마다 아이디와 비밀번호를 같이 보내면 서버는 그걸 보고 로그인 여부를 판단할 수 있다.

하지만 이 방식에는 큰 문제점이 있다.

<문제점>

성능 문제
보안 문제

1. 성능 문제

서버는 로그인 정보를 확인하기 위해 데이터베이스에 있는 사용자 정보를 확인해야 한다.

이때 데이터베이스에 저장된 사용자 정보는 암호화(해시)되어 있다.

암호화 되어 있는 사용자 정보

단순히 암호화된 데이터를 꺼내서 사용하는 것이 아닌 데이터를 비교할 수 있도록 복잡한 알고리즘으로 계산해서 비교해야 한다.

이 방식은 계산하기에는 많은 시간이 소요된다.

또한 이걸 매번 요청한다면 서버에 부담이 커진다.

비밀번호 해시 비교 과정 : 보안을 위한 복잡한 연산이 서버 성능에 영향을줄 수 있음

2. 보안 문제

만약 요청마다 아이디랑 비밀번호를 계속 보내면 누군가(해커)가 그 요청을 중간에서 가로채면 비밀번호가 유출될 위험이 있다.

특히 보안이 완벽하지 않은 네트워크(예 : 공공 와이파이)에서는 위험하다.

보안 문제

이런 문제를 해결하기 위해 나온 것이 토큰이다.

보통 처음 한 번만 로그인하고 서버가 '이 사용자는 로그인을 한 상태다'라는 것을 나타내는 토큰을 만들어준다.

이 토큰을 브라우저가 저장해 두고 서버에 요청할 때는 아이디/비밀번호 대신 토큰만 보낸다.

그럼 서버는 빠르고 안전하게 로그인한 사용자라는 것을 확인할 수 있다.

[로그인 상태를 유지하는 방식]

로그인 상태를 유지하는 두 가지 방법이 있다.

<로그인 상태를 유지하는 방법>

세션(Session) 기반
토큰(Token) 기반

로그인 상태를 유지하는 방법으로는 세션과 토큰 방법 중 하나를 이용하면 된다.

둘 다 인증 방식은 유사하다.

사용자가 로그인을 하면 서버는 사용자에게 입장권을 발급해 준다.

사용자 조회 확인 후 입장권 발급

사용자가 웹사이트에 게시글을 작성하거나, 데이터를 요청할 때마다 입장권을 함께 보낸다.

서버에 요청시 입장권과 함께 전달

그러면 서버는 입장권을 확인하여 인증된 사용자라는 것을 판단한다.

입장권 확인

입장권에 문제가 없다면 서버는 요청을 받아들이고 사용자는 정상적으로 웹사이트를 이용할 수 있다.

요청에 대한 응답

만약 입장권에 문제가 있다면 웹사이트를 이용할 수 없다.

유효하지 않은 입장권

인증 실패

[세션 방식 이해하기]

사용자가 로그인에 성공하면 서버는 사용자를 기억하기 위해 '세션 id'를 만든다.

이 세션 id는 고윳값으로 세션 id 전체를 사용자 브라우저에 쿠키 형태로 보낸다.

사용자가 로그인 요청을 보냄

요청을 처리

로그인 요청에 대한 응답을 보냄

서버는 이 세션 id를 키로 하여 로그인한 사용자 정보를 서버 측 메모리, 하드디스크, 데이터베이스 중 한 곳에 저장해 둔다.

로그인한 사용자는 세션 ID를 받는다.

이후 사용자가 세션 id를 받은 상태로 브라우저를 통해 사이트를 이용한다.

사용자가 사이트의 기능을 이용하여 브라우저에서 서버에 요청을 보낼 때마다 이 세션 ID 쿠키가 서버에 함께 전송된다.

사이트의 기능을 이용하는 사용자

요청을 받은 서버는 전달받은 세션 id와 서버에 저장된 세션 정보와 일치하는지 확인하여 로그인이 된 사용자인지 확인한다.

확인이 되면 로그인 상태를 유지한다.

이처럼 세션 id를 사용해서 사용자가 로그인 상태임을 유지하는 이 상태를 '세션'이라고 한다.

<세션 저장소별 특징>

메모리

장점
- 빠르다
단점
- 서버가 꺼지면 세션 정보가 날아간다.(휘발성)
- 접속자가 많아지면 메모리가 부족해지고 서버에 부담이 된다.
- 세션 정보가 없어지면 사용자들은 다시 로그인을 해야 한다.

하드디스크

장점
- 서버가 꺼져도 세션 정보가 유지된다.
- 상대적으로 메모리보다 안정적이다.
단점
- 디스크 입출력으로 인해 처리 속도가 느려 성능에 영향을 줄 수 있다.

데이터베이스

장점
- 세션 정보를 안정적으로 저장할 수 있다.
- 다수의 서버에서 세션 공유가 용이하다.
단점
- 메모리보다는 속도가 느리다.
- 트래픽이 많아지면 데이터베이스에 부하가 증가할 수 있다.

redis나 Memcached 같은 인메모리 저장소

장점
- 메모리 기반이라 빠르다.
- 클러스터링과 확장을 통해 대용량 처리도 가능하다.
단점
- 서버가 여러 대일 경우 각 서버가 공유 메모리를 사용하지 않으면 세션 정보가 공유되지 않아 세션 유지에 문제가 발생한다.
- Redis 자체가 장애 시 전체 세션 관리에 문제가 생길 수 있다.

[서버가 여러 대일 때]

서버가 여러 대일 경우 로드밸런싱을 통해 트래픽을 분산시킨다.

서버 1번이 사용자의 로그인 요청을 처리 후 서버 2번으로 가야 할게 서버 3번으로 간다면 서버 3번은 해당 사용자의 세션 정보가 없어 로그인 상태를 확인할 수 없다.

그래서 세션이 유지되지 않는 문제가 발생한다.

이 문제를 해결하려면 다음과 같은 방식이 필요하다.

세션 정보를 공통 저장소(Redis,DB 등)에 저장하여 모든 서버가 공유하게 한다.
또는 특정 사용자 요청이 항상 같은 서버로 가도록 '세션 스티키(Session Sticky) 전략을 사용한다.

세션은 사용자의 로그인 상태를 유지하기 위한 서버의 기억장치이다.

어디에 세션을 저장하느냐에 따라 속도, 안정성, 확장성이 달라진다.

프로젝트의 규모가 커질수록 이 세션을 안전하고 빠르게 유지하는 게 어려워지고 설계가 중요해진다.

그래서 이런 부담 없이 구현하기 위해 나온 방법이 토큰 방식인 JWT이다.

[JWT 토큰 방식]

JWT(JSON Web Token)란?

JWT는 인증과 인가에 관련된 기술이다.

토큰 관련된 인증은 대부분 로그인할 때 사용
JWT는 웹 표준을 따르고 있다.
JSON 객체를 사용하여 정보를 전달한다.
필요한 모든 정보를 한 객체에 담아서 전달하기 때문에 JWT 한 가지로 인증을 마칠 수 있다.

JWT를 사용한 토큰 방식은 서버가 상태를 저장하지 않는 방식이다.(stateless)

단순히 '이 사용자는 인증됐다'라는 정보를 토큰에 담아서 준다.

사용자는 이 토큰을 들고 다니면서 서버에 요청할 때마다 토큰을 보내면 된다.

토큰 인증 방식

사용자가 로그인을 하면 서버는 JWT 토큰을 발급한다. (긴 암호문 같은 문자열)

브라우저는 이 토큰을 쿠키나 로컬스토리지에 저장한다.

JWT 토큰 발급 과정

사용자가 사이트의 기능을 이용하여 브라우저에서 서버에 요청을 보낼 때마다 이 토큰을 같이 보낸다.

서버는 토큰 안의 정보와 서명으로 유효한 토큰인지 검증만 하면 된다.

서버에 요청 시 토큰과 함께 전달

<장점>

서버가 세션을 저장하지 않아도 됨 → 확장성 뛰어남
어떤 서버에 요청이 가도록 처리 가능 → 로드밸런싱에 유리
서버 여러 대여도 상관없다. 어디서든 토큰만 있다면 처리 가능

<단점>

토큰이 노출되면 위험 → HTTPS로 전송해야 함
토큰이 만료되기 전까지는 강제로 무효화하기 어려움(로그아웃 처리 복잡)

[JWT 구조]

JWT는 세 부분으로 구성되며 각 부분은.(dot 점)으로 구분된다.

인코딩 또는 암호화된 3가지 데이터를 이어 붙인 것이다.

 HEADER.PAYLOAD.SIGNATURE

HEADER : 헤더
PAYLOAD : 내용
SIGNATURE : 서명

1. HEADER(헤더)

이 입장권이 어떤 방식으로 발급되었는지 알려주는 "양식"같은 부분
어떤 알고리즘으로 서명되어 있는지 명시(예 : HMAC, SHA256)
일반적으로 다음과 같은 정보를 포함

{
	"alg" : "HS256",
	"typ" : "JWT"
}

type
- 토큰의 타입을 나타낸다.
- 항상 JWT로 고정하여 JWT임을 나타내는 식별자
alg
- SIGNATURE(서명) 생성에 사용하는 암호화 알고리즘
- 예 : HS256, RS256 등

2. PAYLOAD(내용)

영화관 입장권에 적힌 "티켓의 주인, 어떤 권한이 있는지"에 해당하는 정보
토큰에 담길 실제 정보(예: 사용자 ID, 권한 등)
Base64로 인코딩 되어 있어서 누구나 디코딩하면 읽을 수 있다.
클레임(Claim)이라 불리는 사용자 정보 및 기타 데이터가 포함된다.
- Claim : 사용자의 정보를 담고 있는 데이터 조각
- 클라이언트(사용자)가 로그인 후 발급받은 토큰에 이 클레임들이 포함되어 있다.
예시

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1516239022
}

3. SIGNATURE(서명)

이 티켓이 진짜라는 것을 증명하는 "도장"같은 부분
무결성과 위변조 방지를 위해 사용
토큰 위변조를 막기 위해 반드시 서버가 서명을 검증해야 한다.
HEADER + PAYLOAD + 서버만 알고 있는 비밀키(Secret Key) = SIGNATURE
- 이 세 가지를 alg에 명시된 암호화 알고리즘에 넣고 돌리면 SIGNATURE이 생성된다.
- Secret Key는 개발자 마음대로 세팅할 수 있다.
예시

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

또는a-string-secret-at-least-256-bits-long

<SIGNATURE가 중요한 이유>

사용자가 토큰을 위조하거나 PAYLOAD를 조작하더라도 서버가 서명을 다시 계산해서 검증하면 서명이 일치하지 않으면 즉시 거부된다.
이 서명은 비밀키 없이는 절대 만들 수 없다. 토큰을 탈취해도 글자 하나만 바꿔도 서명값은 완전히 달라지기 때문이다.
단방향 알고리즘 사용으로 서명값으로부터 비밀키나 원래 데이터를 역산하는 건 사실상 불가능하다.

<전체 예시>

위 JSON의 내용을 암호화하면 다음과 같은 결과가 나타난다.

HEADER와 PAYLOAD를 인코딩한 것이 아래와 같다.

// 원래는 한줄인데 보기 편하게 .에 줄바꿈을 했습니다.
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HEADER : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
PAYLOAD : eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ
SIGNATURE : SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

서버에 로그인 요청을 보냄

요청 처리 중

JWT 토큰 만드는 중

JWT 토큰완성

완성된 토큰과 함께 응답을 전달

받은 토큰을 쿠키에 저장

사용자가 토큰과 함께 서버에 요청을 보냄

토큰을 디코딩 중(토큰 분해)

SIGNATURE 비교

유효한 사용자임을 인증 완료

[세션 vs JWT]

세션 방식
- 입장권에 쓰여있는 정보가 많이 없다.
- 입장권 발급 번호 정도로 기본적인 정보들만 적혀있다.
- 사용자가 입장권을 제시하면 서버가 메모리나 DB에 만들어 두었던 입장권 발급 목록 파일(=세션 스토어)에서 발급 번호를 가진 데이터를 조회하여 사용자를 통과시켜 주는 방식으로 진행된다.
- 구현이 복잡하고 부하가 크지만 통제와 보안이 강하다.
토큰 방식
- 입장권에 쓰여있는 정보가 많다.
- 사용자 이름, 이메일, 발급일, 유효기간 등이 적혀있다.
- 서버는 입장권을 검사할 때 입장권 자체 하나만으로 검사하여 사용자를 통과시킨다.
- 편리하고 확장성이 좋지만 통제가 어렵다.

그래서 프로젝트 상황에 따라 다르게 사용해야 한다.

추천 방식	상황
JWT	단순 로그인, 서버 확장이 중요할 때, 또는 회원이 많아 입장권 목록을 조회하기 힘든경우
세션	민감한 정보를 다루고 통제가 중요할 때

<JWT 방식의 장점>

stateless : 서버가 사용자 상태를 기억하지 않는다.
사이트에 사용자가 많아질수록 서버에 부담이 적어진다.
기존의 세션 방식은 사용자가 입장권을 제시할 때마다 서버에 있는 입장권 발급 목록 파일(=세션 스토어)에서 조회해야 하기 때문에 힘들어진다.
JWT는 사용자가 입장권을 제시하면 입장권만 확인하면 되기 때문에 처리가 매우 빨라진다.
서버가 매 요청마다 데이터베이스를 조회하지 않아도 된다.(토큰자체에 사용자의 권한 및 상태 정보가 담겨 있으므로)
클라이언트가 토큰을 가지고 다니며, 요청 시마다 서버에 함께 전송. 즉, 토큰 === 인증증명서
서버는 토큰 자체만 검증하고 그 내용을 신뢰한다.

<JWT 방식의 단점 및 문제>

보안 이슈
- PAYLOAD는 암호화되어 있지 않다.
  - Base64로 인코딩 되어 있어서 누구나 디코딩하면 읽을 수 있다.
  - 그래서 JWT에 민감한 정보를 넣어서는 안 된다. 최소한의 정보만 넣어야 한다.
- 클라이언트가 임의로 PAYLOAD를 조작할 수 있다.
  - 예 : isAdmin:false → true로 바꿈, exp(만료시간)을 미래로 설정
- 하지만 서버는 토큰의 SIGNATURE(서명)을 검증하기 때문에 PAYLOAD가 조작되었으면 서명이 일치하지 않게 된다 → 거부됨
무효화가 불가능하다.
- 이미 발급된 토큰은 서버가 통제할 수 없다.
- 만약 해커가 토큰을 탈취하면 서버가 몰라도 계속 사용이 가능하다.
- 토큰이 탈취되면 그 유효기간 동안은 막을 방법이 없다.
- 세션 방식이면 세션 삭제로 끝나지만 JWT는 그런 중앙제어 포인트가 없다.
- 사용자를 강제로 로그아웃 시키는 기능도 없다.

예시 상황

어떤 유저가 A 기기에서 로그인한 상태에서 B기기에서 로그인을 하면 A기기를 자동로그아웃 시키고 싶다?

→ 세션 방식이면 가능,

→ JWT는 이미 발급된 토큰을 제거 못 해서 불가능

[JWT의 한계와 보완 방법(Refresh Token)]

JWT의 단점을 보완하기 위한 구조로 Access Token과 Refresh Token이 있다.

Access Token
- 짧은 수명(n분~n시간)
- 인가(Authorization)를 받을 때마다 사용하는 주요 토큰
- 탈취되더라도 금방 만료되므로 위험이 제한적
Refresh Token
- 긴 수명(보통 2~3주)
- Access Token이 만료됐을 때만 사용
- 서버는 Refresh Token을 DB에 저장하여 관리
- 클라이언트가 Refresh Token을 보내면 서버는 DB에서 검증 후 새 Access Token을 발급

[장점]

Access Token이 탈취돼도 수명이 짧아 오래 쓸 수 없다.
Refresh Token을 DB에서 삭제하면 해당 사용자의 인증 갱신은 차단됨 →사실상의 강제 로그아웃 기능

[단점]

완전 무효화는 불가능하다.
- Access Token은 만료 전까지 유효
- 탈취 시 일정 시간 동안은 막을 수 없다.
구현 복잡도가 증가한다
- 토큰 재발급 로직, 만료처리, 예외 처리 등 추가 작업 필요
Refresh Token 탈취 시 더 큰 위험
- 긴 수명을 가지므로 탈취되면 지속적으로 Access Token 재발급 가능
완전한 Stateless 구조가 아니다
- Refresh Token을 서버(DB)에 저장해야 하므로 상태 관리가 필요
기기별 로그인 관리가 복잡하다
- 여러 디바에스에서 로그인 시 토큰 관리 전략이 필요

[정리]

항목	세션 방식	JWT 방식
상태 저장	서버가 세션 기억	서버는 아무것도 기억 안함
저장 위치	서버 메모리, Redis 등	클라이언트가 JWT 보관
서버 확장성	따로 관리 필요 서버 1대면 쉬움 여러대면 복잡 사용자 수가 많아지면 세션 관리 부담 커짐	유리 서버 여러대여도 문제 없음 서버 확장에 유리(무상태 처리)
보안	상대적으로 안전 세션 ID 만료/삭제로 무효화 가능	노출되면 위험함 JT는 한 번 발급되면 서버에서 취소 불가
로그아웃	세션 삭제	토큰 만료 기다려야함
유실 위험	서버 꺼지면 세션 날아감	토큰은 클라이언트에 있으니 유지됨
속도	빠름(메모리),느림(DB)	토큰 검증만 하면 되니 빠름
관리와 제어	서버에서 개별 세션을 삭제/제어 가능	JWT는 한 번 발급되면 서버에서 취소 불가

잘못된 정보는 댓글에 남겨주시면 감사하겠습니다!

댓글과 좋아요는 큰 힘이 됩니다!

[ 참고자료 ]

https://jwt.io/

JSON Web Tokens - jwt.io

JSON Web Token (JWT) is a compact URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is digitally signed using JSON Web Signature (JWS).

www.jwt.io

https://www.youtube.com/watch?v=XXseiON9CV0

https://www.youtube.com/watch?v=1QiOXWEbqYQ

[아이콘 출처]

<a href="https://www.flaticon.com/kr/free-icons/ui" title="ui 아이콘"> Ui 아이콘 제작자: Freepik - Flaticon </a>

<a href="https://www.flaticon.com/kr/free-icons/" title="암호화 아이콘"> 암호화 아이콘 제작자: Freepik - Flaticon </a>

<a href="https://www.flaticon.com/kr/free-icons/" title="하드디스크 아이콘"> 하드디스크 아이콘 제작자: kerismaker - Flaticon </a>

<a href="https://www.flaticon.com/kr/free-icons/-" title="데이터 베이스 아이콘"> 데이터 베이스 아이콘 제작자: Vectorslab - Flaticon </a>

<a href="https://www.flaticon.com/kr/free-icons/-" title="램 메모리 아이콘"> 램 메모리 아이콘 제작자: Freepik - Flaticon </a>

[React] 아토믹 디자인 패턴React] 아토믹 디자인 패턴 (Atomic Design Pattern)

dev_y.h — Thu, 30 Apr 2026 18:10:37 +0900

아토믹 디자인 패턴

[들어가며]

프론트엔드 멘토링을 하면서 멘토링 프로젝트를 진행하게 되었다.

프로젝트를 진행하면서 협업 효율성과 유지보수성을 높이기 위해 디자인 패턴을 도입하게 되었다.

컴포넌트 구조를 명확히 정의하고 역할과 복잡도에 따라 체계적으로 분리할 수 있다는 점, 그리고 일관된 UI를 빠르게 구현할 수 있다는 점에서 아토믹 디자인 패턴을 선택하게 되었다.

[아토믹 디자인 패턴(Atomic Design Pattern)이란?]

프로젝트가 점점 커지면서 유지보수가 어려워지거나 코드가 복잡해지는 경우가 발생하기도 하였다.

페이지마다 폰트 크기, 색상, 테두리 스타일, 여백 등 디테일이 수정되면서 UI의 일관성이 무너져 사용자 경험이 저하되는 문제가 생기기도 한다.

<원인>

컴포넌트의 파편화 : 디자이너난 개발자들이 각자 따로 버튼을 만들게 됨
- 버튼마다 폰트 크기, 색상, 모양(테두리 둥글기), 등이 페이지마다 다르게 만들어진다.
명확한 컴포넌트 설계 기준 미비 : 팀원들 마다 컴포넌트를 나누는 기준이 다름

<발생하는 문제점>

불필요한 대화 시간이 길어지고 소통에 오류가 생겨 유지보수가 힘들어진다.
많음 컴포넌트로 재사용이 어렵거나 확장하기 어려운 구조가 생긴다.
코드 리뷰가 어렵다.

이러한 문제를 해결할 수 있도록 아토믹 디자인 패턴이 생겨났다.

<디자인 시스템>

어떤 조직이 디지털 인터페이스를 디자인하고 구축하는 방식
버튼의 크기, 색
폰트 크기
여백
디자인 시스템을 잘 구성하면 컴포넌트들이 통일되고 유지보수가 쉽다.

<아토믹 디자인 패턴(Atomic Design Pattern)>

: 원자(Atom), 분자(Molecule), 유기체(Organism), 템플릿(Template), 페이지(Page)가 동시에 함께 작동하여 효과적인 인터페이스 디자인 시스템을 만드는 것

아토믹 디자인 패턴의 구성

디자인 시스템을 만드는 방법론
화학에서 원자(Atom) → 분자(Molecule) → 유기체(Organism) 순서로 점점 복잡한 구조로 쌓아가는 개념이다.

단계	설명	예시
Atom	가장 작은 단위	버튼, 라벨, 텍스트 입력 창
Molecule	Atom 여러개를 합친 것	검색 창(입력창 + 버튼)
Organism	여러 Molcule/Atom을 묶은더 큰 덩어리	헤더(로고 + 메뉴 + 검색창)
Template	실제 페이지 구조를 잡는 뼈대	상품 상세페이지 레이아웃
Page	실제 데이터가들어간 완성된 화면	진짜 사용자가 보는 장바구니 페이지

이렇게 컴포넌트를 나누면 컴포넌트를 체계적으로 재사용성 높게 만들 수 있다.

아토믹 디자인은 선형(Linear) 프로세스가 아니다.

UI 응집력을 있는 전체와 구성요소들의 집합으로 이해하는 데 도움이 되는 하나의 사고 모델이다.

원자, 분자, 유기체, 템플릿, 페이지로 이어지는 다섯 단계는 인터페이스 디자이 시스템의 계층 구조 안에서 각각 중요한 역할을 한다.

아토믹 디자인 패턴의 폴더 구조

아토믹 디자인 패턴을 사용하는 프로젝트의 폴더 구조이다.

Atoms → ㅡMolecules → Organisms → Template → Pages 순으로 구성되며, 컴포넌트의 추상화 수준에 따라 계층적으로 나뉜다.

하지만 대부분의 IDE에서는 폴더가 알파벳 순으로 정렬되기 때문에 Atoms → Molecules → Organisms → Template → Pages 순서로 폴더를 구성하더라도 Pages 폴더가 Tamplates보다 먼저 나오는 문제가 발생합니다.

그래서 저는 정렬 문제를 해결하고 의도한 계층 구조를 명확히 드러내기 위해 Pages를 제외한 폴더들(Atoms , Molecules, Organisms , Templates) 앞에 _(언더바)를 붙여주었습니다.

[아토믹 디자인 패턴 구조(5단계)]

원자(Atoms)

사용자 인터페이스를 구성하는 기본 구성 요소
더 이상 분해할 수 없는 기본 컴포넌트
모든 기본 스타일을 한눈에 보여준다.
ex) Label, Input, Button
기본 HTML element 태그, 글꼴, 애니메이션, 컬러 팔레트, 레이아웃과 같이 추상적인 요소도 포함

분자(Molecules)

하나의 단위로 함께 기능하는 비교적 단순한 UI 요소의 집합
여러 Atom을 결합하여 최소 한 가지 기능을 수행한다.
단일 책임 원칙(SRP : Sigle Responsibillity Principle)을 준수
- 한 가지 일을 잘하라는 사고방식을 장려하는 오래된 컴퓨터 과학 원칙
재사용이 가능한 컴포넌트가 생긴다.
molecule의 SRP는 재사용성과 UI에서의 일관성, 테스트하기 쉬운 장점을 가지고 있다.
[단점] 단일 패턴에 너무 많은 복잡성을 부여하면 소프트웨어가 다루기 어려워진다.

유기체(Organisms)

Molecules + Atoms을 모아서 만들며 사용자에게 의미와 역할이 존재하는 단위
Atom이나 Molecule보다 더 복잡하다.
재사용 가능하지만 재사용성은 Atom/Molecule보다 낮다.
- 특정한 컨텍스트와 목적에 맞춰 구성되기 때문
서비스에서 표현될 수 있는 명확한 영역과 특정 컨텍스트를 가진다.
단순한 기능 이상의 구체적인 목적과 맥락을 가진 UI 덩어리다.
인터페이스의 각 부분을 구성하며 명확한 기능과 의미를 가진 독립적인 영역이다.
특정 페이지나 인터페이스에서 반복적으로 사용될 수 있는 패턴 단위로 작동

템플릿(Template)

여러 개의 organism, molecule로 구성
레이아웃에 실제 콘텐츠나 데이터 없이 컴포넌트를 배치해 page 구조를 설계
페이지의 뼈대와 기본 콘텐츠 구조를 정의
콘텐츠 구조를 명확히 하는 것이 중요

페이지(page)

템플릿에 실제 data가 결합이 되어 사용자에게 전달이 되는 최종 디자인의 형태
유저가 볼 수 있는 실제 콘텐츠를 담고 있다.
template의 인스턴스
page template에 대표 텍스트, 이미지, 미디어를 추가하여 실제 콘텐츠가 어떻게 동작하는지 보여줄 수 있다.

<요약>

Atom : 더 이상 쪼갤 수 없는 디자인의 최소 단위
Molecule : Atoms를 모아서 만들어진다. 최소 한 가지 기능을 수행한다.
Organism : Molecule + Atom을 모아서 만들며 사용자에게 의미와 역할이 존재하는 단위
Template : 아직 데이터는 연결되어있지 않은 최종 레이아웃의 형태, 여러 개의 Organism으로 구성된다.
Page : 템플릿에 실제 data가 결합이 되어 사용자에게 전달이 되는 최종 디자인의 형태

[아토믹 디자인 패턴의 문제점]

컴포넌트 분류 기준의 모호함
유사한 UI 변형으로 인한 중복 또는 과도한 props
Organism 책임 범위의 정의 재정립

1. 컴포넌트 분류 기준의 모호함

<문제점>

Atom, Molecule, Organism의 구분 기준이 명확하지 않아 팀원마다 해석이 달라지고 설계 일관성이 떨어진다.

팀 내 컴포넌트 리뷰나 재사용 시 오해가 발생한다.

카카오 페이지 웹에서 실제로 작성한 molecule, organism 컴포넌트

<원인>

SRP(single Responsibility Principle)에 기반하지 않은 직관적 분류

명확한 기준 없이 직관적으로 분류하다 보니 컴포넌트가 의도치 않게 중복되거나 역할 범위가 애매해진다.

특히 Molecule과 Organism의 구분이 자주 헷갈림

<해결책>

Atom
- 더 이상 쪼갤 수 없는 UI 단위
- ex) 텍스트, 버튼, 아이콘 등
Molecule
- Atom으로 구성된 UI적 요소
- 재사용하기 쉬움
- context 없음
- ex) 버튼 크룹, 입력 박스
Organism
- Atom, Molecule, Organism으로 구성된 Layout 중심의 블록
- context 포함
- ex) 댓글 목록 영역, 툴바 등
모호한 경우 Organism으로 작성한 후에 코드 리뷰로 조정한다.

2. 유사한 UI 변형으로 인한 중복 또는 과도한 props

<문제점>

비슷한 디자인이지만 구조가 다른 경우 중복된 컴포넌트 생성 또는 props 남용

댓글과 디자인이 비슷하지만 약간 다른 대댓글 디자인

<원인>

기존 해결 방안

새 컴포넌트 만들기 → 중복되는 컴포넌트가 많아지고 중복 코드가 많아진다.
기존 컴포넌트에 props를 계속 추가하기 → props가 점점 많아져서 쓰기 복잡해 유지보수성이 떨어진다.

아토믹 디자인 구조에서는 고정된 컴포넌트 구조에 다양한 UI 변형을 대응하기 어렵다.

<해결법>

Compound 컴포넌트 패턴 사용

<Comment>
  <div>
    <Comment.ProfileImage />
    <Comment.Name />
    <Comment.Info />
  </div>
  <Comment.Content />
  <div>
    <Icon type={IconType.Heart} />
    ...
  <div />
</Comment>

필요한 부분만 조합해서 사용 가능
컴포넌트 수와 props 수를 동시에 줄임
Organism 구조를 다시 정의
atom/molecule 단위로 더 쪼개서 재조

3. Organism 책임 범위의 정의 재정립

<문제점>

Organism을 어디까지 묶어야 할지 명확하지 않아 과도하게 크거나 작은 단위로 분리되는 문제가 발생 → 팀원 간 기준이 달라 정리와 협업에 어려움이 생김

카카오 페이지의 댓글

<원인>

역할의 경계가 불분명

Layout 기분만으로 Organism을 정의하면 기능적 책임이 불분명해질 수 있고 네이밍이나 구조도 일관성을 잃기 쉽다.

<해결법>

Orgnism은 단순히 시각적으로 나뉜 영역이 아닌 의미 있는 기능적 책임을 갖는 UI 단위로 정의해야 한다.

Layout 책임 단위로 정의
Layout에서 명확히 나뉘는 영역을 기준으로 Oragnism 분할
하나의 UI 책임 단위를 기준으로 묶기(ex: 댓글 툴바, 댓글 리스트 등)
기능 중심 네이밍보다는 역할 중심 네이밍 사용

<판단 기준>

UI 상에서 명확히 구분되는 영역 : 페이지에서 시각적으로 독립된 UI 블록을 기준으로 나눈다.(ex: 댓글 영역, 추천 콘텐츠 영역)
기능적 책임 : 해당 UI가 하나의 기능을 독립적으로 수행하는가? (ex: 댓글 작성, 댓글 리스트 출력 등)
컨텍스트 포함 여부 : 도메인 데이터나 비즈니스로직(이벤트 처리 등)을 내부에서 다루고 있는가?
너무 작게 나누지 않고 컴포넌트가 적절한 수준의 책임을 갖도록 구성되어 있는가?

<예시>

CommentListToolBar : 댓글 데이터를 정렬, 필터 하는 기능이 있는 Organism
CommentList : 각 댓글의 레이아웃을 구성하며, 댓글 아이템을 리스트로 나열하고 spacing을 관리

[아토믹 디자인 패턴의 장단점]

<장점>

부분과 전체를 모두 고려한 설계 가능
- UI를 원자, 분자, 유기체, 템플릿, 페이지 단위로 나누어 구성
- 각 컴포넌트 단위의 품질뿐만 아니라 전체 맥락에서의 일관성과 기능성 확인 가능
구조와 콘텐츠 분리로 유연한 디자인
- 콘텐츠와 레이아웃 구조를 분리해 다양한 상황에 대응 가능
- 예 : 템플릿에서 콘텐츠 구조만 설정, 페이지 단계에서 실제 데이터 주입
협업 효율성 증가
- 디자이너와 동일한 용어(피그마와 코드 네이밍 일치) 사용
- UI 모델링을 공동으로 진행하며 명확한 기준을 마련
컴포넌트 재사용성과 유지보수 용이
- UI 상태나 로직은 외부에서 주입(props활용)
- 레이아웃 관련 스타일은 컴포넌트 밖에서 처리
- 결과적으로 컴포넌트는 더 순수해지고, 테스트와 관리가 쉬워짐
멘탈 모델로서의 유용성
- 단계 간 계층 구조를 쉽게 이해할 수 있어 팀원 같 커뮤니케이션에 효과적
- 원자-분자-유기체처럼 이름만으로도 구조 이해가능

<단점>

컴포넌트 분류 기준의 모호함
유사한 UI 변형으로 인한 중복 또는 과도한 props
Organism 책임 범위의 정의 재정립
과도한 분해로 복잡성 증가
- 너무 작은 단위까지 나누다 보면 오히려 컴포넌트 간 연결 관계가 복잡해짐.
- 결과적으로 유지보수가 오히려 어려워질 수 있음
설계 초기 비용 증가
- UI를 구조적으로 나누고 모델링하는 데 초기 시간이 많이 소요됨
- 빠른 MVP 단계에서는 부담이 될 수 있음
조직과 팀마다 다른 해석 가능
- "원자, 분자, 유기체" 용어가 명확해 보여도 조직마다 의미 해석이 다를 수 있음
- 문서 내에서도 GE 팀처럼 자체 분류법을 따르는 사례가 나옴 → 표준화 어려움
정적 구조에 치중할 위험
- 디자인 시스템이 너무 구조 중심으로 고정되면 콘텐츠나 상호작용의 다양성을 반영하기 어려움
- 예 :유연한 인터렉션이 많은 UI에는 부적합할 수 있음

[아토믹 디자인 패턴 예시]

Atomic design applied to the native mobile app Instagram.

원자(Atom)
- 인스타그램 UI
- 아이콘, 텍스트 수준의 요소로 두 가지 이미지 유형( 게시글이미지, 프로필 이미지)으로 구성
분자(Molecule)
- 간단하고 실용적인 구성요소를 형성
- 아이콘 그룹으로 만들어진 Navbar
- 사용자가 사진에 좋아요를 누르거나 댓글을 달 수 있는 사진 작업 바
- 텍스트 + 이미지 조합으로 만들어진 프로필 바
유기체(Organism)
- 유기체가 형성되는 복합 구성으로 인스타그램 전체 경험의 초석이 된다.
- 사용자 정보, 이미지, 사진과 관련된 동작, 좋아요 수 등 사진 관련 정보로 구성
템플릿(Template)
- 레이아웃의 맥락에서 구성요소들이 어떻게 결합되는지 확인할 수 있다.
- 인스타그램의 콘텐츠 골격을 보여준다.
- 사용자 아이디, 아바타, 사진, 좋아요 수 같은 동적 콘텐츠 강조
페이지(Page)
- 실제 콘텐츠가 주입된 최종 제품
- 기본 디자인 시스템이 함께 모여 기능적인 UI를 형성

[마무리 : 나의 생각]

아토믹 디자인 패턴을 공부하면서 의문이 생겼다.

"파란색 기본 버튼이 atom이라면 빨간색 취소 버튼은 뭐지?", "아이콘이 들어간 버튼은 atom일까 molecule일까?"

처음엔 버튼의 변형들을 Molecule이라고 생각했다.

atom 단계에서는 버튼의 기본 형태만 만들고 빨간색 취소 버튼이나 아이콘이 들어간 버튼처럼 디자인이 바뀌거나 기능이 추가된 형태는 Molecule이라고 생각했다.

즉 atom은 단순 베이스 역할을 하고 실제로 사용하는 molecule에서 만든다는 논리라고 생각했다.

<내가 생각한 아토믹 디자인 패턴>

atom : 기본 버튼, 기본 텍스트, 컬러 같은 기본 단위 만들기
molecule : 기본 버튼, 취소 버튼, 아이콘 버튼, 제목 텍스트, 설명 텍스트 등
organism : molecule들을 조합해서 organism으로 만들기
template : organism들을 레이아웃에 배치
page : template에 실제 데이터를 넣은 것

아토믹 디자인 패턴을 공부하면서 내가 잘못 이해하고 있었다는 것을 알게되었다.

버튼은 여전히 atom이다.

버튼의 색상, 텍스트, 아이콘 유무 같은 것은 props로 조절되는 속성일 뿐이다.

즉 파란색이든 빨간색이든 텍스트만 있던 아이콘이 있든 기능적으로 버튼이라는 역할을 하고 있다면 여전히 atom이라는 것이다.

Molecule은 서로 다른 Atom이 조합되어 새로운 의미를 가지는 경우에 해당한다.

예를 들어 text와 input 필드가 함께 있는 FormField 같은 것이 대표적이다.

서로 독립적으로 사용될 수 있는 Atom들이 조합되어 하나의 유의미한 UI 조각을 이룰 때 그것이 Molecule이 되는 것이다.

결국 내가 처음에 헷갈렸던 이유는 "디자인이 다르면 다른 단위로 나워야 한다"라는 생각 때문이었다.

하지만 아토믹 디자인에서는 스타일이 아닌 역할과 조합 방식이 기준이다.

이걸 깨닫고 나니 atomic design을 조금 더 명확하게 이해할 수 있었다.

같은 컴포넌트라도 기능과 조합 구조를 기준으로 나누어야 하고 스타일이나 변형은 컴포넌트 안에서 props로 유연하게 처리하면 되는 것이다.

이렇게 이해하고 나닌 컴포넌트를 나누는 기준을 알게 되었고 스타일기준이 아닌 기능과 조합이 기준이라는 것을 알게 되었다.

잘못된 정보는 댓글에 남겨주시면 감사하겠습니다!

댓글과 좋아요는 큰 힘이 됩니다!

[ 참고자료 ]

https://atomicdesign.bradfrost.com/chapter-2/

Atomic Design Methodology | Atomic Design by Brad Frost

Learn how to create and maintain digital design systems, allowing your team to roll out higher quality, more consistent UIs faster than ever before.

atomicdesign.bradfrost.com

https://tech.kakaoent.com/front-end/2022/220505-how-page-part-use-atomic-design-system/

아토믹 디자인을 활용한 디자인 시스템 도입기 | 카카오엔터테인먼트 테크블로그

정호일(harry) 카카오페이지에서 웹 프론트엔드를 개발하고 있습니다. 집보다 밖에 돌아다니는 걸 좋아합니다.

tech.kakaoent.com

https://slash.tistory.com/14

Atomic Design 예시

목표 이전 글에서 Atomic Design 패턴에 대해서 알아보았다. 이번에는 Atomic Design 패턴을 통해 직접 간단한 페이지 하나를 만들 예정이다. 사용한 기술 정리 [x] React.js [x] Styled-Components 시작하기 우선

slash.tistory.com

https://yozm.wishket.com/magazine/detail/1531/

Atomic Design Pattern의 Best Practice 여정기 | 요즘IT

좋은 폴더 구조에 관한 이야기는 개발자들 간의 끊임없는 떡밥입니다. 정답이 있지 않고 프로젝트의 특징이나 크기, 주관적인 해석에 따라 정말 여러 가지 방법들이 존재하기 때문입니다. 마치

yozm.wishket.com

[IT노트] 패키지 매니저란? / npm, yarn, pnpm 정리

dev_y.h — Wed, 29 Apr 2026 18:10:56 +0900

패키지 매니저란?

[패키지 매니저가 필요한 이유]

패키지 매니저는 프로젝트에서 라이브러리, 프레임워크, 모듈 등의 패키지를 관리하는 도구다.

필요한 패키지를 설치, 업데이트, 삭제, 설정할 수 있도록 도와준다.

자바스크립트에서는 npm, yarn, pnpm 등이 대표적이다.

<자바스크립트에서 패키지 매니저가 필요한 이유>

문제 상황 : 경로만 쓰면 버전이 모호하다.

자바스크립트/타입스크립트에서 외부 라이브러리를 가져올 때 개발자는 'react'와 '@toass/utils'처럼 간단히 라이브러리 이름만 작성한다.

import React from 'react';
import { sum } from '@toss/utils';

하지만 컴퓨터는 이 파일을 어디서 가져와야 하는지, 어떤 버전의 라이브러리를 사용해야 하는지 모른다.

자바스크립트 표준에서는 라이브러리를 가져올 때 정확한 경로를 알아야 하기 때문이다.

예를 들어 React 라이브러리는 18 버전과 19 버전이 있다.

'react'라고만 작성해 두면 컴퓨터는 어떤 버전을 사용해야 할지 모른다.

버전과 경로를 매번 직접 명시하면 해결할 수 있겠지만 개발 과정에서 긴 경로를 계속 작성하는 것은 번거로운 일이다.

해결책 : package.json

이러한 문제를 해결하기 위해 package.json에 필요한 라이브러리와 버전 범위를 명시해 둔다.

{
  "dependencies": {
    "react": "^18.2.0"
  }
}

"^18.2.0" : 18.2.0 이상, 19 버전 미만

그리고 설치된 라이브러리는 우리가 코드에서 import React from 'react'라고 썼을 때 자동으로 연결되어 사용할 수 있게 된다.

이렇게 라이브러리를 정확한 버전으로 설치할 수 있도록 도와주는 것이 패키지 매니저다.

[패키지 매니저란?]

패키지 매니저는 package.json에 적힌 라이브러리를 정확한 버전으로 설치하고 코드에서 문제없이 불러올 수 있도록 연결해 준다.

출처 : https://toss.tech/article/lightning-talks-package-manager -> yarn을 터미널에 실행했을 때 볼 수 있는 화면

[패키지 매니저의 동작 원리]

패키지 매니저가 동작하는 세 단계가 있다.

Resolution 단계
- 라이브러리 버전 고정
- 라이브러리의 다른 의존성 확인
- 라이브러리의 다른 의존성 버전 고정
Fetch 단계
- 결정된 버전의 파일을 다운로드하는 과정
Link 단계
- Resolution/Fetch 된 라이브러리를 소스코드에서 사용할 수 있는 환경을 제공하는 과정

<Resolution 단계>

Resolution 단계는 package.json에 적힌 범위를 실제 설치할 구체적인 버전으로 확정하고 모든 의존성과 그 하위 의존성까지 버전을 고정해 lock파일에 기록하는 과정이다.

모든 기기에서 고정된 버전을 사용할 수 있도록 한다.

의존성 버전을 전부 고정시키고 의존성의 의존성을 다 찾아서 그 버전도 고정시켜 yarn.lock이나 package-lock.json에 저장한다.

버전을 고정하기 위해서는 세 가지의 단계를 거쳐야 한다.

라이브러리 버전 고정
라이브러리의 다른 의존성 확인
라이브러리의 다른 의존성 버전 고정

[Resolution 1. 라이브러리 버전 고정]

첫 번째 단계에서는 package.json에 명시된 라이브러리 버전 범위를 실제 버전으로 확정하는 단계다.

package.json에는 버전의 범위가 적혀있다.

패키지 매니저는 이 범위 안에서 가장 적절한 버전을 딱 하나 골라야 한다.

{
  "dependencies": {
    "react": "^18.2.0"
  }
}

예를 들어 react:^18.2.0이라고 적혀있다면 18.2.0 이상 19 미만이라는 뜻이다.

보통은 가장 최신 버전을 선택한다.

그래서 실제 설치는 최신 버전인 18.3.1을 선택할 수 있다.

[Resolution 2. 라이브러리의 다른 의존성 확인]

두 번째 단계는 의존성의 의존성을 확인한다.

자바스크립트에서는 패키지끼리 의존성을 갖는 상황이 흔하다.

예를 들어 @toss/use-overlay라는 라이브러리는 내부적으로 react를 필요로 한다.

그런데 react도 또 다른 의존성이 있을 수 있다.

즉 설치한 라이브러리가 또 다른 라이브러리를 요구하고 그 라이브러리가 또 다른 걸 요구하는 "의존성 체인"이 생긴다.

그래서 의존성이 또 어떤 의존성을 가지는지 확인하는 작업이 필요하다.

Resolution 단계에서는 이런 "줄줄이 딸려 오는" 의존성들을 전부 확인한다.

[Resolution 3. 라이브러리의 다른 의존성 버전 고정]

마지막 세 번째 단계는 모든 의존성 버전을 고정한다.

즉 팀원 모드 환경에서 동일한 버전을 사용 가능하도록 lock파일을 생성하는 단계다.

(package-lock.json, yarn.lock, pnpm-lock.yaml)

자바스크립트에서는 의존성의 버전을 범위로 명시하고 패키지 간에도 의존성을 가지기 때문에 똑같은 package.json에 대해서도 사용하는 의존성 버전이 완전히 달라질 수 있다.

왜냐하면 package.json에는 범위만 적혀있어서 같은 프로젝트라도 누가 설치하느냐에 따라 버전이 달라질 수 있다.

예를 들어 내 컴퓨터에서는 React 18.1.0이 설치되었는데

동료 컴퓨터에서는 React 18.2.0이 설치될 수 있다.

이렇게 되면 같은 코드를 실행했는데 내 컴퓨터에서는 잘 되고 다른 동료 컴퓨터에서는 버그가 생길 수도 있다.

<Fetch 단계>

Fetch 단계에서는 Resolution에서 고른 정확한 버전의 패키지를 실제로 다운로드하는 과정이다.

예를 들어 Resolution에서 React 18.3.1을 사용하자고 결정했다면 패키지 매니저가 npm 서버(레지스트리)에 가서 React 18.3.1 압축 파일을 받아온다.

이 과정을 거쳐야 내 컴퓨터 안에 실제로 React, Next.js 같은 라이브러리 파일들이 생긴다.

내 코드에서 import React from 'react'라고 했을 때 정상적을 동작할 수 있다.

<Link 단계>

Linker 단계는 내 코드에서 import/require가 잘 동작하도록 설치한 라이브러리를 어떻게 연결할지 정하는 과정이다.

Resolution/Fetch 된 라이브러리를 소스코드에서 사용할 수 있는 환경을 제공하는 과정이다.

즉 내 코드에서 라이브러리를 실제로 쓸 수 있게 연결해 주는 과정이다.

이때 패키지 매니저(npm, yarn, pnpm, PnP : Plug n Play)마다 방식을 다르게 가져간다.

[Link 방식에 따른 차이]

npm Linker
pnpm Linker
yarn PnP Linker

1. npm Linker(node_modules)

npm은 설치한 라이브러리를 node_modules 폴더에 그대로 복사해서 넣는 방법을 사용한다.

그래서 라이브러리를 설치할수록 폴더가 커진다.

같은 라이브러리를 여러 프로젝트에서 사용하면 중복 설치가 발생한다.

예를 들어 100개 프로젝트에서 React 18.2.0을 사용한다면 React가 100번 설치된다.

import나 require를 할 때, Node.js가 node_moduls를 계속 위로 올라가며 찾아야 해서 속도가 느려질 수 있다.

2. pnpm Linker

이런 단점들 때문에 pnpm(performant npm)이 생겨났다.

똑같이 node_modules를 사용하지만 라이브러리를 실제로 복사하지 않고 바로가기(하드링크 : HardLinker)만 걸어둔다.

그래서 속도도 더 빠르고 디스크 용량도 덜 차지한다.

대신 npm 보다는 낫지만 여전히 node_modules가 필요하다는 한계가 있다.

3. yarn PnP Linker

yarn PnP Linker라고 해서 yarn과 PnP는 다른 패키지 매니저라고 생각할 수 있다.

yarn : 패키지 매니저 이름으로 npm과 같은 역할을 한다.

PnP : yarn에서 제공하는 라이브러리 연결(Link) 방식 중 하나다.

즉 yarn에는 node_modules 방식과 pnp 방식으로 두 가지 Link 방식이 있다.

기본 yarn : node_modules 폴더 사용
yarn PnP : node_modules 없이 .pnp.cjs라는 Map 파일을 만들어 메모리에서 의존성을 바로 연결

패키지를 설치하면 node_modules 폴더가 생긴다.

npm, pnpm은 이 node_modules를 만들어서 파일들을 넣는다.

그런데 yarn의 PnP 방식은 다르다.

yarn install을 하면 node_modules 폴더를 만들지 않는다.

그래서 디스크 용량을 덜 차지한다.

대신 .pnp.cjs라는 "지도(Map)"파일을 하나 만든다.

여기에는 "React는 18.2.0 버전은 여기에 있어요!(= 사용해요!)" 같은 정보가 적혀있다.

Node.js가 import React 같은 걸 실행할 때 node_modules 폴더에서 찾아야 하는데 .pnp.cjs 파일에서 보고 위치로 이동한다.

폴더를 만들지 않아도 되어 설치 속도는 빠르다.

Map의 역할을 하는 .pnp.cjs만 보면 되어서 실행속도는 빠르다.

단점은 호환성이 낮다.

yarn PnP는 node_modules가 없기 때문이다.

많은 도구들이 node_modules폴더가 반드시 있을 거라 가정하고 만들어진다.

하지만 PnP에는 node_modules가 없어서 문제가 생길 수 있다.

<요약>

npm : 전부 복사해서 node_modules에 넣는다.(느리고 무겁다)
pnpm : 복사 대신 "바로가기"를 걸어서 효율적으로 관리(빠르고 가볍다)
yarn PnP : node_modules 자체를 없애버리고 Map 파일로 관리(초고속, 하지만 호환성 문제가 있다.)

[npm, yarn, pnpm 한눈에 비교]

1. npm이란?

npm install react

Lock 파일 : package-lock.json

개요

npm(Node Package Manager)은 자바스크립트 패키지 매니저이다.

사용할 수 있는 모듈들을 패키지화하여 모아두는 장소 역할과 패키지 설치 및 관리를 위한 CLI를 제공한다.

프로젝트에서 필요한 라이브러리를 설치하고 버전을 관리하며 의존성을 쉽게 다룰 수 있다.

주요 특징

node_modules 폴더에 라이브러리를 복사하는 방식으로 설치
설치 시 package.json의 범위를 기준으로 정확한 버전을 결정
package-lock.json 파일을 통해 동일한 버전으로 설치할 수 있도록 돕는다.
대부분의 Node.js 패키지 호환이 가능하다.

장단점

장점

안정적이고 호환성이 좋다.
Node.js 공식 도구라 별도 설치 없이 바로 사용할 수 있다.
패키지를 설치할 때 의존성도 자동으로 설치된다.
package.json 파일 내의 스크립트 섹션을 통해 자동화 작업이 가능

단점

디스크 공간을 많이 사용한다.(중복 설치 발생)
대규모 프로젝트에서 node_modules폴더가 매우 커질 수 있다.
설치 속도가 yarn, pnpm보다 느리다.

2. yarn 이란?

yarn add react

Lock 파일 : yarn.lock

개요

Facebook(현 Meta)에서 npm의 단점을 개선하기 위해 만든 자바스크립트 패키지 매니저이다.

빠른 설치 속도와 안정적인 버전 관리를 목표로 만들어졌다.

npm과 호환된다.

대규모 프로젝트에서도 패키지 의존성을 더 효율적으로 관리할 수 있게 해 준다.

주요 특징

yarn.lock 파일을 사용해 모든 개발자가 동일한 라이브러리 버전 설치
병렬 다운로드와 캐싱으로 설치 속도 개선
npm과 거의 동일하게 동작하여 대부분의 라이브러리 호환

장단점

장점

캐싱 기능으로 설치 속도가 npm보다 빠르다.
yarn.lock 파일을 통해 모든 개발 환경에서 동일한 패키지 버전을 보장
단일 레포지토리 내에서 여러 패키지를 관리할 수 있어 모노레포에서 유용
checksum을 통해 패키지의 무결성을 확인하여 설치 과정의 신뢰성을 높인다.
플러그인 시스템 제공

단점

일부 오래된 Node.js 환경에서 호환성 문제가 있다.
node_modules 구조를 여전히 사용하므로 디스크 최적화는 제한적
npm 보다 약간 복잡할 수 있다.

3. pnpm(Performant npm) 이란?

pnpm add react

Lock 파일 : pnpm-lock.yaml

개요

pnpm은 npm과 yarn 보다 디스크 공간과 설치 속도를 최적화한 패키지 매니저이다.

Hard Link를 사용해 라이브러리를 한 번만 설치하고, 각 프로젝트에서 공유하도록 설계되어 있다.

주요 특징

node_modules 구조를 유지하면서 디스크 사용량 최소화
속도 빠르고 큰 프로젝트에서 효율적
패키지를 중복으로 설치하지 않고, Hard link를 사용하여 디스크 공간을 절약하고 설치 속도를 높여준다.
대규모 프로젝트에서의 성능 향상과 더불어 디스크 공간도 효율적으로 사용할 수 있다.

장단점

장점

중복된 패키지를 제거하여 디스크 공간 절약
설치 속도가 빠름
pnpm-lock.yaml 파일을 통해 모든 개발자 환경에서 동일한 패키지 버전을 보장
프로젝트별로 의존성을 격리하여 서로 영향을 주지 않도록 한다.
프로젝트마다 같은 라이브러리 버전을 보장
패키지를 중복으로 설치하지 않고, 하드 링크를 사용하여 빠르고 효율적으로 패키지를 관리
모노레포를 지원하여 여러 프로젝트를 단일 레포지토리에서 관리할 때 효율적

단점

일부 구형 라이브러리나 툴에서 호환성 문제 발생 가능
npm/yarn에 비해 상대적으로 덜 알려져 있다.

[왜 여러 패키지 매니저가 존재할까?]

패키지 매니저는 의존성을 관리하는 방식에 따라 차이가 있다.

모든 상황에 맞는 하나의 정답은 없고 프로젝트의 성격, 팀 문화, 개발 환경에 맞춰 도구를 선택하는 것이 중요하다.

운영체제와 언어 환경이 다르면 설치 방식과 의존성 처리, 빌드 환경 요구사항도 달라진다.

그래서 각각에 맞는 도구가 필요하다.

예 : pip vs conda

pip : Python 패키지 중심
conda : Python 뿐 아니라 시스템 라이브러리까지 관리 가능(데이터 과학에서 선호)

예 : npm vs yarn vs pnpm

npm : 유연하지만 일부 상황에서 의존성 충돌 가능
yarn : 더 엄격하게 버전을 고정하고 빠른 설치와 캐싱 지원
pnpm : 대규모 프로젝트에서 디스크 공간을 절약하고 설치 속도를 개선

<어떤 패키지 매니저를 사용해야할까?>

npm은 호환성이 중요하거나 작은 프로젝트에서 사용한다.

yarn은 안정적인 버전관리와 빠른 설치 속도를 제공하여 중간 규모의 프로젝트에 사용한다.

pnpm은 대규모 프로젝트에서 디스크 공간을 절약하고 설치 속도를 개선하기 위해 사용한다.

패키지 매니저가 여러개인 이유는 통일하지 못해서가 아니라 각기 다른 목적과 환경에 맞게 발전해 왔기 때문이다.

[정리]

목적과 설계 철학 차이 : 속도, 안정성, 디스크 효율, 호환성 등
팀 문화, CI/CD 환경, 프로젝트 요구사항에 따라 선택
운영체제와 언어 환경 차이도 고려 필요

예시 : Python

pip : Python 패키지 중심
conda : Python + 시스템 라이브러리 관리

예시 : JavaScript

npm : 호환성과 안정성 중시, 작은 프로젝트 적합
yarn : 빠른 설치와 안정적 버전 관리, 중규모 프로젝트 적합
pnpm : 성능과 디스크 효율, 대규모 프로젝트 적합

npm
- 가장 널리 사용되며, 기본적인 기능에 충실
- 속도나 효율성에 크게 민감하지 않을 경우 사용하기 좋다.
yarn
- 빠른 속도와 안정성을 원하는 사용자에게 적합
- 특히 대규모 프로젝트나 모노레포에서 유용
pnpm
- 성능과 디스크 공간 효율성을 중시하는 사용자에게 적합
- 모노레포와 의존성 관리가 중요한 프로젝트에 유용

게시글에서는 npm은 작은 프로젝트, yarn은 중간, pnpm 대규모라고 설명하였다.

하지만 실제로 프로젝트 크기보다 팀 문화, CI/CD 환경, 호환성 요구도 중요하다.

어떤 패키지 매니저를 선택할지는 프로젝트규모, 팀 협업 환경, 빌드 도구와의 호환성, CI/CD환경도 고려하여 선택해야 한다.

항목	npm	yarn	pnpm
속도	보통	빠름	매우 빠름
디스크	큼	큼	매우 효율적
방식	복사	복사/PnP	하드링크

잘못된 정보는 댓글에 남겨주시면 감사하겠습니다!

댓글과 좋아요는 큰 힘이 됩니다!

[ 참고자료 ]

https://toss.tech/article/lightning-talks-package-manager

패키지 매니저의 과거, 토스의 선택, 그리고 미래

토스는 왜 패키지 매니저로 Yarn을 선택했을까요? 이번 라이트닝 토크에서는 JavaScript의 패키지 매니저, 동작 방식, 그리고 토스의 선택과 앞으로의 방향성에 대해 이야기해 보려고 해요.

toss.tech

https://www.frontoverflow.com/magazine/12/%ED%8C%A8%ED%82%A4%EC%A7%80%20%EB%A7%A4%EB%8B%88%EC%A0%80

https://inpa.tistory.com/entry/NODE-%F0%9F%93%9A-%EB%85%B8%EB%93%9C-npmnode-package-manager

[NODE] npm(node package manager) 완벽 정리

npm(node package manager) npm(node package manager)은 자바스크립트 패키지 매니저이다. Node.js에서 사용할 수 있는 모듈들을 패키지화하여 모아둔 저장소 역할과 패키지 설치 및 관리를 위한 CLI(Command line int

inpa.tistory.com

https://poiemaweb.com/nodejs-npm

Node.js & npm | PoiemaWeb

npm(node package manager)은 자바스크립트 패키지 매니저이다. Node.js에서 사용할 수 있는 모듈들을 패키지화하여 모아둔 저장소 역할과 패키지 설치 및 관리를 위한 CLI를 제공한다. 자신이 작성한 패

poiemaweb.com

[JavaScript] 옵셔널체이닝(?.) 사용법 총정리JavaScript 옵셔널체이닝(?.) 사용법 정리

dev_y.h — Mon, 27 Apr 2026 18:10:07 +0900

자바스크립트 옵셔널 체이닝

[객체 속성 접근 시 발생하는 문제]

자바스크립트로 객체를 다루다 보면 깊이 중첩된 속성에 접근해야 하는 상황이 생긴다.

이때 중간에 속성이 존재하지 않으면 TypeError가 발생하며 코드 실행이 중단된다.

예를 들어 다음과 같은 자바스크립트 객체가 있다.

const user = {
  profile: {
    name: "홍길동",
    contact: {
      email: "hong@example.com",
    },
    address: {
      city: "서울",
      zipCode: "06123",
    }
  },
  orders: [
    { id: 1, item: "노트북" },
    { id: 2, item: "키보드" }
  ],
  getProfile() {
    return "사용자 프로필입니다.";
  }
};

객체 user의 전화번호가 필요한 상황이다.

콘솔 로그로 user profile.contact.phone에 접근하면 phone이 존재하지 않아 Cannot read properties of undefined오류가 발생한다.

// 존재하지 않는 속성 접근 시 오류 발생
console.log(user.profile.contact.phone); // undefined
// Error: Cannot read properties of undefined

기존에는 이 문제를 피하기 위해 조건문이나 && 연산자를 중첩해서 안전하게 접근했다.

하지만 아래와 같이 코드를 작성하면 코드가 길어지고 가독성이 떨어지는 문제가 있었다.

if (user &&user.profile && user.profile.contact && user.profile.contact.phone) {
  console.log(user.profile.address.phone); // 출력되지 않음
}

// 혹은
console.log(user && user.profile && user.profile.contact && user.profile.contact.phone); // undefined

이러한 문제를 해결하기 위해 ES2020에서는 옵셔널체이닝(Optional Chaining, ?.) 문법이 도입되었다.

[옵셔널 체이닝(Optional Chaining,?.)이란?]

옵셔널 체이닝은 존재하지 않을 수 있는 객체 속성에 안전하게 접근할 수 있게 해주는 문법이다.

console.log(user?.profile?.contact?.phone) //undefined (에러 발생 x)

앞의 값이 null 또는 undefined라면 평가를 중단하고 undefined를 반환한다.

즉, 조건문 없이도 안전하게 속성에 접근할 수 있는 문법이다.

옵셔널 체이닝을 잘 활용하면 예외 상횡에서도 안정적으로 동작하는 코드를 작성할 수 있다.

API 응답 데이터나 사용자 입력값처럼 존재하 확실하지 않은 데이터를 다룰 때 유용하다.

[옵셔널 체이닝 사용법]

객체 속성 접근
배열 요소 접근
함수 호출
null 병합 연산자와의 조합

1. 객체 속성 접근

// phone은 없는 속성
const phone = user?.profile?.contact?.phone;
console.log(phone); // undefined (에러 발생 X)

2. 배열 요소 접근

const firstOrder = user?.orders?.[0];
console.log(firstOrder); // { id: 1, item: "노트북" }

const thirdOrder = user?.orders?.[2];
console.log(thirdOrder); // undefined (에러 발생 X)

3. 함수 호출

console.log(user.getProfile?.()); // "사용자 프로필입니다."

const guest = {};
console.log(guest.getProfile?.()); // undefined

4. null 병합 연산자와의 조합

옵셔널체이닝은 ?? 와 ||가 자주 함께 사용된다.

값이 없을 경우 기본값을 설정하기 위해서다.

const city1 = user?.profile?.address?.city ?? "Unknown city";
console.log(city1); // "서울"

const guest = {};
const city2 = guest?.profile?.address?.city ?? "Unknown city";
console.log(city2); // "Unknown city"

[ ||와?? 차이점]

||
- 왼쪽 값이 falsy면 오른쪽 값을 반환
- falsy 값 : 0, "", false, null, undefined, NaN
??
- 오직 Null이나 undefined일 때만 오른쪽 기본값을 반환
- 0, "", false 같은 값은 그대로 유지

[주의할 점]

Reference는 잡지 못한다.
읽기/삭제만 가능, 쓰기는 불가
남용하지 말아야 한다.

1. Reference는 잡지 못한다.

선언조차 되지 않은 변수에서는 사용할 수 없다.

console.log(a?.b);
// ReferenceError: a is not defined

선언만 되어 있으면 안전하게 접근 가능하다

let obj; 
console.log(obj?.prop); // undefined

2. 읽기/삭제만 가능, 쓰기는 불가

옵셔널체이닝은 값을 반환만 하기 때문에 직접 할당에는 사용할 수 없다.

delete user?.profile?.name; // 안전하게 삭제 가능
user?.profile?.name = "Violet"; // SyntaxError

3. 남용하지 말 것

꼭 존재해야 하는 값에는 사용하지 않는 게 좋다.

예를 들어 user객체는 필수라면 user?.profile 대신 user.profile을 사용하는 것이 디버깅에 유리하다.

그래야 실수로 user가 할당되지 않았을 때 에러가 발생하고 디버깅이 쉬워지기 때문이다.

그래서 반드시 존재 여부가 불확실한 값에만 선택적으로 사용하는 것이 좋다.

[정리]

옵셔널체이닝(?.)은 중첩된 객체 속성에 안전하게 접근할 수 있게 해주는 문법이다.

객체 속성 접근 : obj?.prop
배열 접근 : obj?.[props]
함수 호출 : obj?.method()
??와||을 함께 사용하는 기본값 설정 가능

옵셔널 체이닝 사용 적절 예 : 외부 API 데이터, 사용자 입력

사용 지양 예 : 필수 객체, 반드시 존재해야 하는 값

옵셔널 체이닝을 잘 활용하면 코드가 간결해지고 예외 상횡에서도 안정적을 동작할 수 있다.

꼭 필요한 값까지 옵셔널체이닝을 사용하면 버그를 놓치기 쉽다는 점을 기억해야 한다.

잘못된 정보는 댓글에 남겨주시면 감사하겠습니다!

댓글과 좋아요는 큰 힘이 됩니다!

[ 참고자료 ]

https://ko.javascript.info/optional-chaining

옵셔널 체이닝 '?.'

ko.javascript.info

https://developer.mozilla.org/ko/docs/Web/JavaScript/Reference/Operators/Optional_chaining

Optional chaining - JavaScript | MDN

developer.mozilla.org