IT의 IT 블로그

사이드 프로젝트 | NBA Game Picker (4) - Matchup Score 설명 페이지 구성

IT의 IT 블로그 — Mon, 18 May 2026 18:32:45 +0900

안녕하세요.

지난 글에서는
NBA Game Picker 프로젝트에서

홈 화면
경기 목록 페이지
경기 상세 페이지

까지 어떻게 확장했는지 정리했습니다.

이번 글에서는 그다음 단계로 진행한

Matchup Score 설명 페이지(/about-score) 구성 과정

을 정리해보려고 합니다.

이 프로젝트는 단순히 NBA 경기 일정을 보여주는 것이 아니라,
오늘 가장 볼 만한 경기를 추천하는 것이 핵심입니다.

그래서 추천 점수를 보여주는 것만으로는 부족했고,
사용자가 그 점수를 이해할 수 있는 페이지가 필요하다고 생각했습니다.

1. /about-score 페이지가 필요했던 이유

홈 화면과 상세 페이지에는
Watchability Score가 이미 표시되고 있었습니다.

표시된 점수

예를 들어 사용자는 홈에서 추천 경기를 보면서
이런 궁금증을 가질 수 있습니다.

왜 이 경기가 91점인지
이 점수는 어떤 기준으로 붙은 것인지
단순히 인기 팀 경기라서 높은 것인지
점수가 높다는 것이 정확히 무엇을 의미하는지

이런 질문에 답하지 못하면
점수는 결국 그냥 숫자로만 보이게 됩니다.

그래서 /about-score 페이지는
단순한 보조 페이지라기보다,

추천 점수를 해석할 수 있게 만드는 페이지

로 구성해야 한다고 생각했습니다.

즉 이 페이지의 목적은

Watchability Score가 무엇인지 설명하고
어떤 요소로 점수가 구성되는지 보여주고
사용자가 그 숫자를 읽을 수 있게 만드는 것

이었습니다.

2. 페이지 설계 전 정리한 핵심 내용

이 페이지를 만들기 전에
먼저 “사용자가 여기서 무엇을 알아야 하는가”를 정리했습니다.

핵심은 크게 4가지였습니다.

1) Watchability Score의 역할

이 점수가 단순 수치가 아니라
오늘 볼 경기를 빠르게 고르기 위한 기준이라는 점

2) 점수를 구성하는 요소

현재 기준으로는 다음 3가지를 핵심 요소로 잡았습니다.

Closeness
Scoring
Momentum

3) 각 요소의 의미

예를 들면

Closeness → 접전 가능성
Scoring → 득점 기대치
Momentum → 최근 흐름

처럼 해석할 수 있어야 했습니다.

4) 점수 해석 기준

예를 들어

90점 이상 → 가장 먼저 볼 만한 경기
80점대 → 충분히 기대할 수 있는 경기
70점대 → 상황에 따라 볼 가치가 있는 경기

처럼 점수를 읽을 수 있도록 정리해야 했습니다.

즉 이 페이지는
긴 설명을 읽는 페이지보다

점수 구조를 빠르게 이해하는 페이지

가 되어야 한다고 생각했습니다.

3. 초기 구성에서 아쉬웠던 부분

초기에는 설명문과 카드 위주로 페이지를 구성했습니다.

예를 들어

Watchability Score 개요
Closeness / Scoring / Momentum 설명
샘플 점수 계산
해석 기준

이런 구조로 정리했습니다.

정보 자체는 충분했지만, 실제로 구현해보니 아쉬운 점도 있었습니다.

1) 텍스트가 많아 보였다

내용은 맞았지만
전체적으로 읽어야 이해되는 구조라서
가독성이 조금 떨어졌습니다.

2) 프로젝트 성격이 잘 드러나지 않았다

일반적인 설명 페이지처럼 보였고,
NBA 프로젝트 특유의 분위기나 개성이 약했습니다.

3) 카드 구성이 단조로웠다

정보는 나뉘어 있었지만
시각적인 위계가 약해서
어디부터 봐야 할지 바로 들어오지 않았습니다.

즉, 설명은 가능했지만
프로젝트의 성격을 더 잘 보여주는 방식으로 정리할 필요가 있었습니다.

4. 설명 페이지의 방향성 정리

이후에는 /about-score 페이지를
단순 설명 카드 모음이 아니라,

프로젝트의 핵심 컨셉을 더 잘 보여주는 구조로 정리하려고 했습니다.

이번 작업에서 중요하게 본 기준은 다음과 같습니다.

1) 설명보다 구조가 먼저 보여야 한다

사용자가 긴 문장을 읽기 전에
이 페이지가 무엇을 설명하는지 먼저 보여야 했습니다.

2) 점수 요소가 한눈에 들어와야 한다

Closeness, Scoring, Momentum
이 세 가지가 핵심이라는 점이 바로 보여야 했습니다.

3) 샘플 점수 예시가 있어야 한다

실제 경기 예시를 통해
점수가 어떻게 구성되는지 보여줄 필요가 있었습니다.

4) 프로젝트 분위기와 연결되어야 한다

NBA 기반 프로젝트인 만큼
단순 문서형 설명 페이지보다는
스포츠 서비스에 가까운 분위기를 유지하고 싶었습니다.

5. 최종 페이지 구조

최종적으로 /about-score 페이지는
다음과 같은 흐름으로 구성했습니다.

1) 상단 소개 영역

Watchability Score가 무엇인지 간단히 설명하고,
이 페이지가 어떤 역할을 하는지 보여주는 영역

2) 핵심 요소 3가지

Closeness
Scoring
Momentum

각 요소의 의미와 반영 예시를 카드 형태로 정리

3) 샘플 경기 점수 예시

특정 경기의 점수를 예시로 보여주고,
각 항목이 점수에 어떻게 반영되는지 시각적으로 설명

4) 점수 해석 기준

90+, 80s, 70s, 60↓
처럼 점수를 어떻게 읽으면 되는지 정리

5) 페이지가 필요한 이유

이 프로젝트가 단순 일정 서비스가 아니라
추천 중심 서비스라는 점을 다시 정리하는 마무리 섹션

이렇게 정리하고 나니
페이지 역할이 훨씬 분명해졌습니다.

6. 이번 작업의 핵심 포인트

1) 설명문을 줄이고 구조를 먼저 보이게 했다

이 페이지에서 가장 중요했던 것은
정보를 많이 넣는 것이 아니라
한눈에 이해되는 구조를 만드는 것이었습니다.

예를 들어 긴 문단으로 설명하는 것보다

핵심 요소 3개
짧은 설명
반영 예시
샘플 점수
해석 기준

처럼 나눠 보여주는 방식이 더 효과적이었습니다.

2) 점수는 숫자보다 해석이 중요했다

점수 자체를 붙이는 것은 어렵지 않지만,
그 점수를 사용자가 이해하고 받아들이게 만드는 것은 다른 문제였습니다.

그래서 이번 작업은
단순히 UI를 추가한 것이 아니라,

추천 로직을 사용자 관점에서 설명하는 작업

에 더 가까웠습니다.

3) 프로젝트 성격이 드러나도록 정리했다

이 페이지는 설명용 페이지이지만,
프로젝트 전체 흐름 안에서 보면
서비스의 핵심 개념을 가장 직접적으로 보여주는 페이지이기도 합니다.

그래서 일반적인 문서형 페이지보다는
NBA 프로젝트 안에 들어 있는 페이지처럼 보이도록
색감과 구조도 함께 정리했습니다.

7. 구현 과정에서 느낀 점

1) 추천 서비스는 설명 가능한 구조가 있어야 한다

홈에서 추천 경기를 보여주고,
상세 페이지에서 추천 이유를 보여주는 것도 중요하지만,
그보다 더 중요한 것은

그 추천 기준을 별도로 설명할 수 있느냐

였습니다.

/about-score 페이지를 만들고 나니
프로젝트가 단순한 UI 중심이 아니라
추천 기준을 가진 서비스처럼 보이기 시작했습니다.

2) 설명 페이지가 프로젝트 흐름을 더 또렷하게 만든다

처음에는 이 페이지가 꼭 필요할까 싶었지만,
실제로 만들고 나니 프로젝트의 핵심 컨셉이 훨씬 분명해졌습니다.

홈과 상세 페이지는
“무엇을 추천하는지”를 보여주고,

/about-score는
“왜 이렇게 추천하는지”를 설명하는 역할을 하게 되었습니다.

즉 이 페이지가 추가되면서
프로젝트 전체 흐름이 더 명확해졌다고 느꼈습니다.

8. 현재까지의 프로젝트 흐름

지금까지 정리된 흐름은 다음과 같습니다.

1단계

프로젝트 기획과 서비스 방향 정리

2단계

홈 화면 구조와 컴포넌트 분리

3단계

경기 목록과 상세 페이지 설계

4단계

Watchability Score 설명 페이지 구성

즉, 이제는 단순히 홈 화면이 있는 프로젝트가 아니라

홈
목록
상세
점수 설명

까지 이어지는 기본 구조가 갖춰진 상태입니다.

9. 다음 단계

현재까지는 추천 점수를

홈에서 보여주고
상세에서 활용하고
설명 페이지에서 해석할 수 있게

정리한 상태입니다.

다음 단계에서는

상세 페이지 데이터 확장
favorites 기능
상태 관리 구조 정리
실제 API 연결 준비
Watchability Score 계산 로직 고도화

등으로 확장해보려고 합니다.

특히 다음부터는
점수를 “보여주는 단계”를 넘어서,
점수 계산에 들어가는 데이터 구조를 더 구체적으로 정리하는 것이 중요하다고 생각합니다.

10. Watchability Score 페이지를 만들며 느낀 점

이번 작업을 통해 느낀 점은
추천 서비스에서 점수는 단순 숫자가 아니라
사용자의 선택을 돕는 기준이어야 한다는 것이었습니다.

그리고 그 기준이 제대로 전달되려면
점수를 보여주는 것만으로는 부족하고,
그 점수를 설명할 수 있는 구조가 필요하다는 것도 느꼈습니다.

/about-score 페이지는
그런 의미에서 프로젝트의 보조 페이지이면서도,
프로젝트 핵심 개념을 가장 분명하게 보여주는 페이지라고 생각합니다.

다음 글에서는
상세 페이지 데이터를 더 확장하고,
추천 경기의 설득력을 높이기 위해 어떤 정보를 추가했는지 정리해보려고 합니다.

사이드 프로젝트 | NBA Game Picker (3) - 경기 목록과 상세 페이지 설계

IT의 IT 블로그 — Fri, 8 May 2026 14:54:07 +0900

안녕하세요.

지난 글에서는
NBA Game Picker 프로젝트를 왜 만들었고,
어떤 방향으로 설계했는지 정리했고,

이후에는
홈 화면을 어떻게 구조화하고 컴포넌트로 분리했는지 정리했습니다.

이번 글에서는 그다음 단계로 진행한

경기 목록 페이지(/games)와 경기 상세 페이지(/games/[gameId]) 구현 과정

을 정리해보려고 합니다.

홈 화면이 오늘 볼 만한 경기를 빠르게 보여주는 역할이었다면,
이번에 만든 두 페이지는

추천 → 비교 → 상세 확인

으로 이어지는 흐름을 만드는 작업이었습니다.

1. 홈 화면 다음에 필요했던 것

홈 화면만 있을 때도
오늘 경기, 추천 경기, 팀 순위, 득점 리더처럼
핵심 정보는 어느 정도 한 화면에서 볼 수 있었습니다.

하지만 실제로 서비스를 사용한다고 생각해보면
아쉬운 점이 분명히 있었습니다.

예를 들면 이런 흐름입니다.

오늘 경기가 여러 개 있을 때 전체를 보고 싶다
추천 점수가 높은 경기들을 빠르게 비교하고 싶다
특정 경기 하나를 더 자세히 보고 싶다
왜 이 경기가 추천 경기인지 근거를 확인하고 싶다

즉, 홈 화면은 요약과 진입 역할에는 적합했지만
전체를 비교하거나 하나를 깊게 확인하는 흐름까지는 부족했습니다.

그래서 다음 단계로

/games → 전체 경기 목록
/games/[gameId] → 경기 상세 정보

이 두 페이지를 추가하게 되었습니다.

2. 각 페이지의 역할 정리

이번 작업에서는 먼저
각 페이지가 어떤 역할을 가지는지부터 정리했습니다.

홈 (/)

오늘 가장 볼 만한 경기와 핵심 정보 요약

경기 목록 (/games)

오늘 경기 전체를 추천 점수 기준으로 빠르게 비교

경기 상세 (/games/[gameId])

선택한 경기를 왜 봐야 하는지 더 자세히 설명

이렇게 나누고 나니
페이지마다 어떤 정보를 보여줘야 하는지 기준이 분명해졌습니다.

특히 상세 페이지는
단순히 경기 정보를 다시 보여주는 것이 아니라,

“추천의 근거를 납득시키는 페이지”

가 되어야 한다고 생각했습니다.

3. 경기 목록 페이지에서 정리한 것

/games 페이지는
그냥 홈 화면의 리스트를 크게 늘려놓는 느낌으로 만들고 싶지는 않았습니다.

이 페이지에서 중요하게 본 것은

전체 경기를 빠르게 훑고 우선순위를 정할 수 있느냐

였습니다.

그래서 목록 페이지에서는 아래 정보가 바로 보이도록 구성했습니다.

경기 시간
팀 매치업
Watchability Score

목록 페이지의 목적은
깊게 읽는 것이 아니라 빠르게 비교하는 것이기 때문에,
정보량을 과하게 넣기보다 핵심만 먼저 보이도록 설계했습니다.

또 홈에서 사용하던 경기 데이터 구조를 그대로 재사용하면서
홈 → 목록 흐름도 자연스럽게 이어지도록 했습니다.

즉, 홈에서는 일부 경기만 요약해서 보여주고
/games에서는 그 데이터를 전체 목록 형태로 확장하는 방식입니다.

4. 경기 상세 페이지에서 중요했던 부분

상세 페이지는 목록보다 더 중요하다고 생각했습니다.

이 프로젝트의 핵심은
단순히 경기 정보를 보여주는 것이 아니라
**“오늘 어떤 경기를 보면 좋을지 추천하는 것”**이기 때문입니다.

그래서 상세 페이지에서는
경기 시간이나 팀 이름만 보여주는 것이 아니라
추천 근거를 설명할 수 있는 정보가 필요했습니다.

현재 상세 페이지에는 다음과 같은 내용을 넣었습니다.

경기 시간
away / home 팀
Watchability Score
추천 이유
최근 5경기 비교
평균 득점
평균 실점
시즌 승률
최근 맞대결

즉, 이 페이지는
“경기 정보를 보여주는 화면”이면서 동시에

“왜 이 경기가 추천되는지 설명하는 화면”

이 되도록 구성했습니다.

홈에서 사용자가 가질 수 있는 질문은 보통 이런 형태입니다.

왜 이 경기가 높은 점수지?
단순히 인기 팀 경기라서 추천된 건가?
실제로 접전 가능성이 높은가?
최근 흐름이 좋은 팀들인가?

상세 페이지는 이런 질문에 답해주는 구조를 목표로 했습니다.

5. App Router 기준으로 연결하기

이번 작업에서 기술적으로 가장 중요했던 부분 중 하나는
Next.js App Router 기준으로 라우팅 구조를 정리한 것이었습니다.

현재 페이지 구조는 다음과 같습니다.

src/app
├─page.tsx
└─games
├─page.tsx
└─[gameId]
└─page.tsx

여기서

src/app/games/page.tsx → /games
src/app/games/[gameId]/page.tsx → /games/:gameId

역할을 합니다.

처음에는 [gameId] 폴더를 사용하는 방식이 조금 낯설었지만,
정리하고 나니 오히려 페이지 역할이 더 명확하게 느껴졌습니다.

특히 gameId를 기준으로 상세 데이터를 연결하는 흐름이 생기면서
목록 → 상세 이동 구조가 자연스럽게 이어졌습니다.

6. 상세 데이터는 mock 기반으로 구성

현재 단계에서는 아직 실제 API를 연결하지 않고
mock 데이터 기반으로 상세 페이지를 구성했습니다.

이렇게 진행한 이유는 이전과 같습니다.

UI 구조를 먼저 잡기 위해
상세 페이지에서 어떤 데이터가 필요한지 먼저 정리하기 위해
실제 API 형태와 무관하게 화면 흐름을 먼저 검증하기 위해

현재는 gameDetailMap 형태로 상세 데이터를 관리하고 있습니다.

예를 들어

lakers-warriors
celtics-bucks

같은 경기 id를 기준으로
각 경기의 상세 데이터를 연결하는 방식입니다.

이 과정에서 중요했던 점은

홈 데이터, 목록 데이터, 상세 데이터의 id를 일관되게 맞추는 것

이었습니다.

이 부분이 정리되자
홈에서 누른 경기 카드와 목록에서 누른 경기 카드가
같은 상세 페이지로 자연스럽게 연결될 수 있었습니다.

7. 구현하면서 느낀 점

1) 목록 페이지와 상세 페이지는 역할이 다르다

처음에는 둘 다 경기 데이터를 보여주는 페이지라고 생각했지만,
직접 만들어보니 성격이 확실히 달랐습니다.

목록 페이지 → 빠르게 비교
상세 페이지 → 추천 근거 설명

즉, 같은 데이터라도
어떤 페이지에서 보여주느냐에 따라 배치 방식이 달라져야 했습니다.

2) 추천 근거를 설명하는 상세 화면

홈 화면에서 추천 경기를 강조하는 것만으로는
추천 서비스라고 말하기 어렵다고 느꼈습니다.

진짜 중요한 것은

상세 페이지에서 그 추천을 어떻게 설명하느냐였습니다.

그래서 이번 작업은
단순히 페이지를 추가한 것이 아니라

추천 중심 서비스 구조를 한 단계 더 확장한 작업

이라고 생각합니다.

3) 목록과 상세를 연결하는 id 기준

지금은 아직 실제 API를 연결한 단계가 아니라서,
복잡한 식별자 체계를 만드는 것보다

서로 연결되는 데이터끼리 id를 일치시키는 것

이 훨씬 중요했습니다.

현재는 간단한 문자열 id를 사용하고 있지만,
이후 실제 API를 연결하게 되면
외부 경기 id를 기준으로 더 안정적인 구조로 확장할 계획입니다.

8. 현재까지의 흐름

지금까지 정리된 흐름은 다음과 같습니다.

1단계

홈 화면 대시보드 구성

2단계

홈 화면 구조 분리 및 컴포넌트화

3단계

경기 목록 페이지 추가

4단계

경기 상세 페이지 추가

즉, 이제는 단순히 홈 화면 하나만 있는 프로젝트가 아니라

홈 → 목록 → 상세

로 이어지는 기본 흐름이 갖춰진 상태입니다.

9. 현재 기준 프로젝트 구조 일부

이번 작업 이후 기준으로 보면
프로젝트는 대략 다음과 같은 흐름으로 확장되고 있습니다.

src
├─app
│ ├─page.tsx
│ └─games
│ ├─page.tsx
│ └─[gameId]
│ └─page.tsx
│
└─features
└─nba
├─components
├─data
│ ├─home
│ └─games
├─lib
└─types

이 구조를 통해

홈에 필요한 데이터
목록에 필요한 데이터
상세에 필요한 데이터

를 역할 기준으로 계속 확장할 수 있게 되었습니다.

10. 다음 단계

현재까지 홈, 목록, 상세까지 연결하면서
서비스의 기본 흐름은 어느 정도 정리되었습니다.

다음 단계에서는

Watchability Score를 설명하는 /about-score 페이지
상세 페이지 데이터 확장
favorites 기능
상태 관리 구조 정리
실제 API 연결 준비

등으로 확장해보려고 합니다.

특히 다음 단계에서는
단순히 페이지를 더 만드는 것이 아니라,

추천 점수의 기준을 더 설득력 있게 보여주는 방향

으로 발전시키는 것이 핵심이라고 생각합니다.

11. 마무리

이번 작업을 통해 느낀 점은
홈 화면만으로는 서비스가 완성되지 않는다는 것이었습니다.

사용자가 실제로 탐색하고 선택하려면

전체를 비교할 수 있는 목록 페이지
선택 근거를 확인할 수 있는 상세 페이지

가 반드시 필요했습니다.

결국 추천 서비스의 핵심은

정보를 많이 보여주는 것이 아니라,

사용자가 선택할 수 있게 흐름을 설계하는 것

이라는 점을 다시 느꼈습니다.

사이드 프로젝트 | NBA Game Picker (2) - 홈 화면 구조와 컴포넌트 분리

IT의 IT 블로그 — Mon, 4 May 2026 10:47:17 +0900

안녕하세요.

지난 글에서는
NBA Game Picker 프로젝트를 왜 만들었고,
어떤 방향으로 설계했는지에 대해 정리했습니다.

이번 글에서는

홈 화면을 어떻게 구조화하고, 컴포넌트로 분리했는지

그 과정을 정리해보려고 합니다.

1. 왜 컴포넌트 분리를 하게 되었는가

홈 화면을 처음 구현할 때는
모든 코드를 page.tsx 하나에 작성했습니다.

초기에는 문제가 없어 보였지만
기능이 추가되면서 점점 구조가 복잡해졌습니다.

예를 들면 다음과 같은 요소들이 한 파일 안에 모두 들어가 있었습니다.

오늘 경기 리스트
오늘의 추천 경기
팀 순위
득점 리더
매치업 데이터
카드 UI 스타일
점수 관련 로직

이 상태에서는

어느 하나를 수정하려고 해도 전체 파일을 같이 봐야 하는 상황이 발생했습니다.

2. 문제의 핵심

문제는 단순히 코드가 길어진 것이 아니라

역할이 섞여 있다는 점이었습니다.

하나의 파일 안에

UI
데이터
로직

이 모두 섞여 있다 보니
코드를 이해하고 수정하는 데 부담이 커졌습니다.

3. 구조를 나누는 기준

그래서 구조를 나눌 때
기준을 명확하게 잡았습니다.

기준

UI → components
데이터 → data
로직 → lib
타입 → types

이 기준을 기반으로
기존 구조를 점진적으로 분리했습니다.

4. 현재 구조

현재는 다음과 같은 구조로 정리했습니다.

features/nba
├─constants
├─data
├─lib
└─types

여기서 핵심은

**“기능이 아니라 역할 기준으로 나눈 것”**입니다.

5. 컴포넌트 분리 대상

홈 화면을 기준으로
다음 컴포넌트들을 분리했습니다.

1) Card

가장 기본이 되는 UI 컴포넌트입니다.

title
action
children

형태로 구성해서
모든 섹션에서 재사용할 수 있도록 만들었습니다.

하나의 레이아웃을 여러 곳에서 공통으로 사용하는 역할입니다.

2) GameRow

경기 리스트에서 사용하는 컴포넌트입니다.

경기 시간
팀 매치업
추천 점수

홈 화면과 /games 페이지에서 모두 재사용할 수 있도록 설계했습니다.

3) RankingList

팀 순위를 보여주는 컴포넌트입니다.

순위
팀 이름
승률

단순 테이블 구조지만
별도 컴포넌트로 분리하면서 재사용성을 확보했습니다.

4) ScoringLeaders

득점 리더를 보여주는 컴포넌트입니다.

순위
선수 이름
팀
평균 득점

이후 별도 페이지로 확장하기 쉽게 구조를 잡았습니다.

6. 분리하면서 중요했던 점

1) props 설계

컴포넌트를 나누면서 가장 중요했던 부분은

props를 어떻게 설계할 것인가였습니다.

예를 들어 GameRow는
필드를 하나씩 나누지 않고

interface GameRowProps {
game: HomeGameItem;
}

이처럼 데이터 단위로 전달하는 방식으로 구성했습니다.

이렇게 하면 구조가 단순해지고 유지보수가 쉬워집니다.

2) 재사용성 고려

처음부터 재사용을 고려해서 설계했습니다.

Card → 모든 섹션 공통
GameRow → 홈 / games 페이지 공통
RankingList → 다른 페이지 확장 가능
ScoringLeaders → 별도 페이지로 확장 가능

단순 분리가 아니라 확장을 고려한 구조로 가져갔습니다.

3) 스타일 일관성

컴포넌트를 나누면서
UI도 자연스럽게 정리되었습니다.

border 스타일 통일
radius 통일
spacing 통일
다크모드 대응 일관화

결과적으로 전체 UI의 완성도가 올라갔습니다.

7. 분리 이후 변화

컴포넌트를 분리한 이후 가장 큰 변화는 다음과 같습니다.

before

page.tsx 하나에 모든 코드 존재
수정 시 영향 범위 큼
구조 파악이 어려움

after

역할별 파일 분리
필요한 부분만 수정 가능
코드 가독성 개선

유지보수성과 확장성이 크게 개선되었습니다.

8. 현재 단계에서의 의미

지금 단계는 단순히 UI를 만든 것이 아니라

**“서비스 구조를 설계하는 단계”**라고 생각합니다.

이 작업을 통해

데이터 흐름
컴포넌트 구조
재사용성

이 세 가지를 정리할 수 있었습니다.

9. 마무리

이번 작업을 통해 느낀 점은

UI를 만드는 것보다 구조를 만드는 것이 더 중요하다는 것이었습니다.

처음에는 빠르게 화면을 만드는 데 집중했지만,
기능이 늘어날수록

구조를 정리하는 작업이 필수라는 것을 느꼈습니다.

사이드 프로젝트 | NBA Game Picker (1) - 프로젝트 기획과 서비스 방향

IT의 IT 블로그 — Fri, 1 May 2026 22:51:26 +0900

안녕하세요.
이번 글에서는 제가 진행하고 있는 사이드 프로젝트인
NBA Game Picker를 소개해보려고 합니다.

이 프로젝트는
NBA 경기 데이터를 기반으로
오늘 가장 볼 만한 경기를 추천해주는 웹 서비스입니다.

단순히 경기 일정을 나열하는 것이 아니라,
사용자가 빠르게 경기를 선택할 수 있도록

추천 중심의 UX로 설계한 것이 핵심입니다.

아래 링크에서 실제 서비스와 코드를 함께 확인하실 수 있습니다.

서비스 바로가기
https://nba-game-picker.vercel.app

GitHub
https://github.com/Ryuintae/nba-game-picker

1. 왜 이 프로젝트를 만들었는가

NBA를 자주 보면서 항상 느꼈던 불편함이 있었습니다.

오늘 경기 많네… 근데 뭐 보지?
접전 경기 뭐지?
득점 많이 나올 경기 어디지?

기존 스포츠 앱들은 대부분

경기 일정
팀 정보
결과

이 정도만 제공하는 경우가 많습니다.

하지만 실제로 사용자가 원하는 건

“오늘 가장 재미있는 경기가 무엇인지” 입니다.

그래서 단순한 일정 서비스가 아니라

경기를 “선택”할 수 있게 도와주는 서비스를 만들고자 했습니다.

2. 프로젝트 목표

이 프로젝트의 핵심 목표는 다음과 같습니다.

오늘 가장 볼 만한 경기 추천
경기별 재미 지수 (Watchability Score) 제공
여러 데이터를 한 화면에서 빠르게 비교 가능

즉,

**“정보 제공”이 아니라 “선택을 도와주는 서비스”**를 만드는 것이 목표입니다.

3. 기술 스택

이번 프로젝트는 프론트엔드 중심으로 진행했습니다.

사용 기술

Next.js (App Router)
TypeScript
Tailwind CSS
next-themes (다크/라이트 모드)
Vercel 배포
PWA 적용

적용 예정 기술

Zustand (클라이언트 상태 관리)
TanStack Query (서버 상태 관리)

선택 이유

Next.js → 페이지 구조 + 확장성
TypeScript → 데이터 구조 명확화
Tailwind → 빠른 UI 구성
next-themes → 테마 전환
Vercel → 간편한 배포
Zustand → UI 상태 관리 단순화
TanStack Query → API 데이터 관리 최적화

4. PWA 적용

이번 프로젝트는 웹 서비스로만 끝내지 않고,
PWA(Progressive Web App) 형태로도 적용하고 있습니다.

PWA를 적용한 이유는
사용자가 브라우저에서만 접속하는 것이 아니라,

홈 화면에 추가해서 앱처럼 접근할 수 있는 경험을 주고 싶었기 때문입니다.

현재는 다음과 같은 기본 설정을 적용한 상태입니다.

manifest.ts 구성
앱 아이콘 설정
PwaRegister 컴포넌트를 통한 등록 처리
InstallPrompt 버튼 구성
HTTPS 환경에서 설치 가능하도록 Vercel 배포

즉,
지금은 추천형 웹 서비스이면서 동시에 앱처럼 설치할 수 있는 형태까지 기본 기반을 마련한 상태입니다.

5. 현재 홈 화면 구성

현재 홈 화면은 단순 소개 페이지가 아니라
스포츠 데이터 대시보드 형태로 구성했습니다.

구성은 다음과 같습니다.

오늘 경기 리스트 (가로 스크롤)
오늘의 추천 경기
팀 순위
득점 리더
매치업 데이터
최근 경기 결과

즉,

앱에 들어오자마자 바로 사용할 수 있는 구조로 설계했습니다.

6. 프로젝트 구조

현재 프로젝트 구조는 다음과 같습니다.

src
├─app
│ globals.css
│ icon.png
│ layout.tsx
│ manifest.ts
│ page.tsx
│ providers.tsx
│
├─components
│ InstallPrompt.tsx
│ PwaRegister.tsx
│ ThemeToggle.tsx
│
└─features
└─nba
├─constants
│ team-brand.ts
│
├─data
│ └─home
│ featured-game.ts
│ games.ts
│ scoring-leaders.ts
│ team-rankings.ts
│
├─lib
│ score.ts
│ team-brand.ts
│
└─types
home.ts

7. 구조를 이렇게 나눈 이유

처음에는 모든 데이터를 page.tsx 안에 넣었지만,
파일이 커지면서 유지보수가 어려워졌습니다.

그래서 다음과 같이 구조를 나눴습니다.

1) data

화면에서 사용하는 mock 데이터 분리

featuredGame
games
teamRankings
scoringLeaders

2) constants

공통적으로 사용하는 값 관리

팀 브랜드 컬러
UI 기준 값

3) lib

로직 분리

점수 계산
데이터 처리

4) types

데이터 구조 정의

타입 명확화
안정적인 개발

이렇게 분리하면서

page.tsx는 렌더링 역할에만 집중하도록 구조를 개선했습니다.

8. 현재는 mock 데이터 기반으로 구현

현재 단계에서는 실제 API를 연결하지 않고
mock 데이터 기반으로 UI를 먼저 구성했습니다.

이렇게 진행한 이유는 다음과 같습니다.

UI 구조를 먼저 확정하기 위해
데이터 형태를 미리 설계하기 위해
API 변경에 영향을 받지 않도록 하기 위해

즉,

“UI → 데이터 구조 → API 연동” 순서로 개발하고 있습니다.

9. 구현하면서 느낀 점

1) 데이터 구조 설계가 중요하다

처음에는 화면부터 만들었지만,
결국 중요한 건

데이터를 어떻게 설계하고 관리하느냐였습니다.

2) 서비스형 UI와 랜딩 UI는 완전히 다르다

랜딩 페이지는
설명 중심

서비스 홈은
데이터 중심

이 차이를 직접 경험한 것이 가장 큰 수확이었습니다.

10. 현재 구현 상태

현재까지 진행된 내용은 다음과 같습니다.

Next.js 프로젝트 세팅
Tailwind 적용
다크/라이트 모드 구현
Vercel 배포 완료
PWA 기본 적용
홈 화면 대시보드 구조 구현
mock 데이터 기반 UI 구성
데이터 / 상수 / 유틸 분리 완료

11. 마무리

이 프로젝트를 진행하면서 가장 크게 느낀 점은

좋은 서비스는 데이터를 어떻게 보여주느냐에 달려있다는 것이었습니다.

단순히 정보를 나열하는 것이 아니라,
사용자가 빠르게 판단할 수 있도록 구조를 만드는 것이 중요하다고 느꼈습니다.

현재는 전체 구조와 UI 방향을 잡는 단계까지 진행했고,
다음 단계에서는

홈 화면의 Card, GameRow, RankingList, ScoringLeaders 컴포넌트 분리 과정을 정리해보려고 합니다.

이 과정을 통해
UI 구조를 어떻게 나누고 재사용성을 높였는지에 대해
좀 더 자세하게 다뤄볼 예정입니다.

[후기/전시] World IT Show 2026 코엑스 관람 후기 - WIS

IT의 IT 블로그 — Sun, 26 Apr 2026 21:22:30 +0900

안녕하세요.

이번에는 월드 IT Show 2026(World IT Show 2026)에 직접 다녀온 후기를 정리해보려고 합니다.

이번 박람회는 단순히 “최신 기술이 많았다”는 정도를 넘어서,
현재 IT 업계가 어떤 방향으로 움직이고 있는지를 비교적 구체적으로 보여주는 자리라는 느낌이 강했습니다.

특히 이번 행사에서 가장 인상 깊었던 키워드는 크게 두 가지였습니다.
첫째는 AI 에이전트(Agentic AI),
둘째는 VR/XR, 3D 공간 기술과 같은 디지털 공간 계열 기술이었습니다.

예전에는 AI가 “무엇을 할 수 있다”는 기술 소개 중심으로 보였다면,
이번 행사에서는 AI가 실제로 어떤 업무를 대신하고, 어떤 데이터를 연결하고, 어떤 사용자 경험으로 서비스되는지가 훨씬 구체적으로 보였습니다.

이번 글에서는 월드 IT Show 2026 현장 분위기와 함께,
직접 둘러보면서 인상 깊었던 흐름들을 후기 형식으로 정리해보겠습니다.

1. 월드 IT Show 2026 전체 분위기

이번 월드 IT Show 2026은 규모가 꽤 크고,
전시장 구성도 한눈에 봐도 성격이 나뉘어 있다는 점이 인상적이었습니다.

행사 배치도를 보면 전시가 크게 1F Hall A / Hall B, 그리고 3F Hall C로 나뉘어 있었고,
각 공간이 보여주는 분위기도 꽤 달랐습니다.

1F Hall A
ITRC 인재양성대전 2026, 2026 ICT 기술사업화 페스티벌, 어워드테크관, 글로벌관 등
비교적 연구·실증·기술사업화 성격이 강한 공간
1F Hall B
Mingling Zone / Startup Pavilion
AI & Digital Intelligence, ICT Convergence 중심의 스타트업·융합기술 성격이 강한 공간
3F Hall C
에이전틱 AI, AI 플랫폼, K-AI 반도체 생태계관, Mobility, Smart Live, Data Tech, EnterTech 등
대기업과 주요 플랫폼 중심의 메인 전시장 분위기가 강한 공간

즉, 같은 박람회 안에서도
한쪽에서는 연구와 실증 기술을 보고,
다른 한쪽에서는 실제 서비스화된 대형 부스를 볼 수 있다는 점이 좋았습니다.

2. 1층에서 확인한 기술 실증과 체험형 부스

1층을 둘러보면서 가장 먼저 느낀 점은,
이 공간이 단순한 홍보형 전시장보다는 기술 실증과 체험 중심의 공간에 더 가깝다는 것이었습니다.

ITRC 인재양성대전과 ICT 기술사업화 페스티벌이 함께 운영되고 있어서 그런지,
기업 부스뿐 아니라 연구기관·대학·기술 실증형 전시가 많이 보였습니다.

직접 본 부스들 중에는

VR/XR 기반 가상 공간 체험
국방 메타버스 플랫폼
AI 기반 휴대용 3D 공간 정보 스캐너
실시간 통역 및 기업 검증
제조/운영 데이터 기반 AI 시스템
산업형 ERP 및 데이터 대시보드

같이 **“이 기술이 실제로 어디에 쓰이는가”**를 보여주는 전시가 많았습니다.

이 점이 흥미로웠던 이유는,
기술이 추상적인 개념으로 제시되는 것이 아니라
공간, 산업, 공공, 제조, 업무 자동화처럼 비교적 명확한 사용처와 함께 전시되고 있었기 때문입니다

3. VR/XR 및 메타버스 계열 기술 전시 흐름

이번 행사를 보기 전에는 솔직히
예전보다 메타버스라는 단어의 존재감이 많이 줄었을 것이라고 생각했습니다.
그런데 실제 현장에서는 메타버스나 XR/VR 계열 기술이 완전히 사라진 것이 아니라,
조금 더 구체적인 목적을 가진 형태로 남아 있다는 인상을 받았습니다.
예를 들어 현장에서는

VR 헤드셋을 이용한 가상 공간 체험
VR Concert처럼 고글을 착용하고 즐기는 콘텐츠형 체험
국방 메타버스 플랫폼처럼 특정 목적을 가진 시뮬레이션형 기술
실제 공간을 스캔하고 데이터화하는 3D 공간 정보 스캐너
제조 설비와 공간을 디지털로 구현한 3D 시각화/시뮬레이션

같은 전시가 눈에 띄었습니다.
즉, 예전처럼 막연하게 “모든 것이 메타버스”라고 말하는 분위기보다는,
지금은

훈련
시뮬레이션
공간 시각화
디지털 트윈
몰입형 콘텐츠

처럼 쓰임새가 구체적인 방향으로 정리되고 있다는 느낌이 더 강했습니다.
특히 3D 공간 스캐너 부스는
메타버스나 디지털 공간 기술이 단순히 보여주기용이 아니라,
현실 공간을 데이터로 전환하고 시뮬레이션 환경까지 연결하는 기술이라는 점을 보여줘서 인상적이었습니다.

4. 산업형 AI와 공간 데이터 기술 전시 특징

이번 행사에서는 일반 사용자 대상 서비스형 AI뿐 아니라,
산업 현장과 운영 데이터에 붙는 AI도 꽤 많이 보였습니다.
예를 들어

제조 산업 실증 사례
설비 정보 3D 시각화 시뮬레이션
산업 부산물 및 자원 관리 어시스턴트
제조 원가 예측/운영 데이터 기반 ERP
시계열 데이터 기반 모니터링 시스템

같은 전시가 반복적으로 보였습니다.
이런 부스들을 보면서 느낀 점은,
AI가 이제 단순한 텍스트 생성 기능이 아니라
산업 현장 데이터와 연결되어 의사결정을 돕는 방향으로 많이 가고 있다는 것이었습니다.
특히 설비나 공간을 단순 표로 보여주는 것이 아니라,
3D 시각화나 디지털 화면으로 함께 보여주는 사례가 많아서
AI와 데이터 시각화, 디지털 트윈 계열 기술이 함께 움직이고 있다는 인상도 받았습니다.

5. AI 에이전트 중심의 서비스 변화

이번 월드 IT Show 2026에서 가장 많이 느낀 키워드를 하나 고르라고 하면,
저는 AI 에이전트라고 말할 것 같습니다.
이번에 본 부스들을 떠올려보면 단순히 “AI가 답변해준다”는 수준보다,

문서를 읽고
사내 데이터를 연결하고
메시지를 요약하고
통화 내용을 정리하고
민원을 안내하고
상담을 보조하고
반복 업무를 줄여주는

형태의 AI가 굉장히 많이 보였습니다.
즉, 질문에 답하는 챗봇보다는
실제로 무언가를 대신 처리해주는 AI가 많이 등장하고 있다는 느낌이었습니다.
이 흐름은 스타트업 부스에서도 보였고,
업무 자동화 전문 개발사나 문서/ERP/그룹웨어 통합형 AI 솔루션에서도 보였으며,
공공 안내형 AI, 상담형 AI, 음성 AI 부스에서도 공통적으로 드러났습니다.
그래서 이번 행사에서 본 AI는
단순한 생성형 AI 소개가 아니라
“행동하는 AI”, “업무를 도와주는 AI”, “서비스 안으로 들어간 AI”에 훨씬 가까웠습니다.

6. 대기업 부스에서 확인한 AI 에이전트 흐름

이번 행사에서 특히 인상 깊었던 부분은,
AI 에이전트가 스타트업이나 솔루션 기업의 키워드를 넘어서
대기업의 메인 메시지로도 올라오고 있었다는 점입니다.
배치도를 보면 3층 Hall C에는
KT, SK텔레콤, LG전자, 삼성, 카카오 같은 주요 기업들이 큰 부스를 구성하고 있었고,
실제 현장 분위기도 1층과는 다르게 서비스와 플랫폼 중심의 메시지가 강했습니다.
그중에서도 개인적으로 가장 눈에 띈 것은 카카오 Kanana 부스였습니다.
현장에서는
“5천만의 일상 속 Agentic AI”
라는 문구가 전면에 걸려 있었고,

오늘의 브리핑
메시지 요약
통화 요약
일정 챙김
대화 맥락 정리

같이 사용자의 일상 속에서 AI가 직접 보조하는 기능들을 보여주고 있었습니다.
이 부분이 흥미로웠던 이유는,
AI 에이전트라는 개념이 이제 일부 기술 데모 수준이 아니라
실제 메신저, 플랫폼, 일상 서비스 UX 안으로 들어가고 있다는 점을 보여줬기 때문입니다.
예전에는 AI가 “신기한 기능”처럼 보였다면,
이번에는 “내가 실제로 쓰게 될 서비스”처럼 보였다는 점에서 차이가 있었습니다.
또 다른 대기업 부스들도
AI를 단순히 기술 설명으로 보여주기보다
서비스와 사용 경험 단위로 연결하려는 시도가 강하게 느껴졌습니다.

7. 기억에 남았던 주요 부스

이번 행사에서 기억에 남았던 부스를 몇 곳만 정리하면 다음과 같습니다.

7.1 Kanana

대기업도 AI 에이전트를 매우 직접적으로 이야기하고 있다는 점이 인상적이었습니다.
AI를 어렵게 설명하기보다, 브리핑·요약·정리·보조 같은 일상 언어로 풀어낸 점도 눈에 띄었습니다.

7.2 DIMENVUE

3D 공간 정보 스캐너와 공간 데이터 기반 기술이 꽤 실용적으로 보였습니다.
메타버스나 디지털 트윈이 단순한 개념이 아니라, 현실 공간을 실제 데이터로 바꾸는 기술이라는 점을 보여주는 부스였습니다.

7.3 Typecast

AI 보이스가 이제 단순 데모가 아니라 API와 자동화 도구 형태로 실제 서비스에 연결되고 있다는 점이 흥미로웠습니다.

7.4 WISSLY

사내 문서, ERP, 그룹웨어 등을 AI로 연결하는 흐름이 강하게 느껴졌습니다.
기업 내부 데이터 활용형 AI 에이전트의 방향을 보여주는 사례라고 생각했습니다.

7.5 VR Concert

XR이 여전히 매력적인 체험형 콘텐츠로 남아 있다는 점을 보여준 부스였습니다.
고글을 착용하고 직접 몰입해서 즐기는 경험은 여전히 강한 현장성을 가지고 있었습니다.

8. 월드 IT Show 2026을 둘러본 후 느낀 점

지금까지 월드 IT Show 2026을 직접 둘러보며 느낀 점을 정리해보았습니다.
이번 행사는 단순히 “최신 기술이 많았다”는 정도로 끝나는 박람회가 아니라,
현재 IT 업계가 어떤 방향으로 움직이고 있는지를 비교적 선명하게 보여주는 자리였습니다.
특히 가장 인상 깊었던 점은 다음과 같습니다.

AI가 단순 생성 기능을 넘어서 에이전트형 서비스로 진화하고 있다는 점
대기업도 AI 에이전트를 실제 서비스와 일상 UX 안으로 연결하려는 흐름을 보이고 있다는 점
VR/XR과 메타버스 계열 기술이 사라진 것이 아니라, 더 구체적인 목적을 가진 형태로 남아 있다는 점
산업형 AI, 3D 공간 데이터, 디지털 트윈 기술이 함께 커지고 있다는 점

이번 월드 IT Show 2026은
“AI가 많았다”는 행사라기보다,
AI가 실제 서비스와 산업 현장에 어떤 방식으로 들어가고 있는지를 보여준 행사에 더 가까웠다고 생각합니다.
앞으로 이러한 흐름이 실제 제품과 서비스 안에서 어떻게 자리 잡을지 더 궁금해졌습니다.
읽어주셔서 감사합니다.

사이드 프로젝트에 Docker 적용해보기 (self-interior-guide)

IT의 IT 블로그 — Mon, 20 Apr 2026 15:30:49 +0900

안녕하세요.

이전 글에서는 Docker의 기본 개념과 전체 구조를 정리해봤습니다.

이번 글에서는
실제 프로젝트인 self-interior-guide에 Docker를 적용해본 과정을 정리해보겠습니다.

앞선 글에서 Docker의 개념을 이해했다면,
이번에는 그 개념들이 실제로 어떻게 동작하는지 확인하는 단계라고 보면 됩니다.

다만 이번 적용은
실제 배포를 위한 것이 아니라 테스트 및 학습 목적으로 진행했습니다.

현재 프로젝트는
**Vercel**을 통해 배포하고 있고,
Docker는 실행 환경을 직접 구성해보기 위한 용도로 사용했습니다.

1. Docker 적용을 시작하기 전에

Docker를 적용하기 전에
먼저 Docker가 정상적으로 설치되어 있는지 확인했습니다.

docker -v

Docker가 정상적으로 설치되어 있다면
버전 정보가 출력됩니다.

2. hello-world로 Docker 동작 확인

다음으로 Docker가 실제로 동작하는지 확인하기 위해
hello-world 이미지를 실행해봤습니다.

docker run hello-world

이 과정에서 Docker 내부에서는 다음과 같은 흐름이 발생합니다.

Docker Hub에서 이미지 pull
컨테이너 생성
컨테이너 실행
결과 출력

즉, 이 한 번의 실행으로
Docker의 전체 흐름을 간단하게 확인할 수 있습니다.

3. 프로젝트 이미지 빌드

이제 실제 프로젝트를 Docker로 실행하기 위해
이미지를 생성했습니다.

docker build -t self-interior-guide .

빌드 과정에서는
Dockerfile을 기준으로 이미지가 생성되며,

Node 환경 구성
패키지 설치
프로젝트 파일 복사

와 같은 과정이 단계별로 실행됩니다.

4. 실행 시 발생한 문제 (Node 버전 이슈)

이미지를 생성한 후 컨테이너를 실행했지만
바로 문제가 발생했습니다.

docker run -p 5173:5173 self-interior-guide

에러 내용을 보면 다음과 같습니다.

Vite requires Node.js version 20.19 or 22.12+

즉, Dockerfile에서 사용한 Node 버전이
프로젝트 요구사항과 맞지 않았던 것입니다.

이 부분을 통해 확인할 수 있는 점은 다음과 같습니다.

Docker도 결국 실행 환경이기 때문에
런타임 버전이 매우 중요하다

5. Dockerfile 수정 후 재빌드

문제를 해결하기 위해
Node 버전을 22로 수정했습니다.

FROM node:22-alpine

이후 다시 이미지를 빌드했습니다.

docker build -t self-interior-guide .

6. 정상 실행 확인

수정 후 다시 컨테이너를 실행했습니다.

docker run -p 5173:5173 self-interior-guide

정상적으로 실행되며
다음과 같은 결과를 확인할 수 있습니다.

Local: http://localhost:5173

즉, 컨테이너 환경에서도
로컬과 동일하게 프로젝트가 실행됩니다.

7. Docker Desktop에서 이미지 확인

Docker Desktop에서도
생성된 이미지를 확인할 수 있습니다.

여기서 확인할 수 있는 점은 다음과 같습니다.

self-interior-guide 이미지 생성 완료
hello-world 이미지 존재
동일 이미지에 대한 tag 존재

즉, CLI에서 생성한 결과를
GUI에서도 확인할 수 있습니다.

8. Docker Hub에 이미지 업로드

이미지를 Docker Hub에 업로드하면
다른 환경에서도 동일하게 실행할 수 있습니다.

이렇게 업로드된 이미지는
다른 환경에서 다음과 같이 사용할 수 있습니다.

docker pull ryuintae/self-interior-guide
docker run -p 5173:5173 ryuintae/self-interior-guide

9. Docker 배포 방식 (개발 vs 운영 관점)

Docker를 사용하다 보면
단순히 이미지를 만들고 실행하는 것에서 끝나는 것이 아니라,

누가 어떤 목적에서 사용하느냐에 따라 방식이 달라진다는 점을 확인할 수 있습니다.

크게 보면
개발 환경과 운영 환경, 이렇게 두 가지 관점으로 나누어 이해할 수 있습니다.

9.1 개발 환경 (개발자 협업 기준)

개발 단계에서는 보통
이미지를 공유하기보다는 소스코드와 Dockerfile을 함께 공유하는 방식으로 진행합니다.

전체 흐름은 다음과 같습니다.

소스코드 + Dockerfile 공유
→ 각자 docker build
→ 로컬에서 실행

왜 이런 방식을 사용할까요?

개발 단계에서는 프로젝트가 계속 바뀌기 때문입니다.

기능이 추가되기도 하고
버그를 수정하기도 하며
의존성이 변경되기도 합니다.

이처럼 코드가 자주 바뀌는 상황에서는
매번 이미지를 새로 만들어 공유하는 것이 오히려 비효율적일 수 있습니다.

그래서 개발 환경에서는
이미지 자체를 공유하기보다, 동일한 실행 환경을 맞추는 데 Docker를 활용하게 됩니다.

개발 환경에서 Docker의 역할

개발 환경에서 Docker의 가장 큰 역할은
환경 통일이라고 볼 수 있습니다.

예를 들어 협업을 하다 보면 다음과 같은 문제가 생길 수 있습니다.

Node 버전이 다를 수 있고
npm 패키지 충돌이 발생할 수 있으며
운영체제 차이로 인해 실행 결과가 달라질 수도 있습니다.

이런 문제를 줄이기 위해
Dockerfile을 기준으로 실행 환경을 고정하게 됩니다.

즉,
같은 소스코드를 받아도
각 개발자가 같은 방식으로 이미지를 빌드하고 실행할 수 있도록 만드는 것입니다.

실제 협업 흐름

실제 협업 흐름을 단순하게 정리하면 다음과 같습니다.

Git clone
↓
docker build
↓
docker run

이렇게 하면
모든 개발자가 동일한 환경에서 프로젝트를 실행할 수 있습니다.

핵심 특징

개발 환경에서의 Docker 사용 특징을 정리하면 다음과 같습니다.

코드 수정이 가능합니다.
실행 환경만 Docker로 통일합니다.
이미지를 공유하기보다는 소스코드를 공유합니다.
빠르게 반복 개발하는 데 적합합니다.

9.2 운영 환경 (배포 기준)

반면 운영 환경에서는 방식이 완전히 달라집니다.

운영 단계에서는
소스코드를 전달하지 않고 이미지를 전달하는 방식으로 진행합니다.

전체 흐름은 다음과 같습니다.

Dockerfile → build → image 생성
→ Docker Hub push
→ 서버에서 pull → 실행

왜 이렇게 할까?

운영 환경에서는 개발 환경과 중요하게 보는 기준이 다릅니다.

안정적으로 실행되어야 하고
항상 동일한 결과가 나와야 하며
배포도 빠르고 일관되게 이루어져야 합니다.

즉, 운영 환경에서는
코드를 수정하는 것보다
정확하게 실행되는 것 자체가 더 중요합니다.

운영 환경에서 Docker의 역할

운영 환경에서 Docker의 역할은
완성된 실행 환경을 그대로 전달하는 것입니다.

여기서 전달되는 이미지 안에는

Node 버전
라이브러리
애플리케이션 코드

가 모두 포함되어 있습니다.

즉, 서버에서는 소스코드를 다시 세팅하거나
환경을 하나씩 맞출 필요 없이,
이미지를 pull 받아 실행하기만 하면 됩니다.

실제 운영 흐름

운영 흐름을 단순하게 정리하면 다음과 같습니다.

개발 서버에서 build
↓
Docker Hub push
↓
운영 서버 pull
↓
docker run

이 방식의 핵심은
서버에서는 별도의 추가 설정 없이
이미지를 실행하는 것만으로 동일한 환경을 그대로 재현할 수 있다는 점입니다.

핵심 특징

운영 환경에서의 Docker 사용 특징을 정리하면 다음과 같습니다.

코드 수정은 불가능합니다.
환경과 코드가 함께 고정됩니다.
이미지 기반으로 배포가 이루어집니다.
CI/CD와 연결하기에 적합합니다.

9.3 개발 vs 운영 차이 정리

개발 환경과 운영 환경의 차이를 정리하면 다음과 같습니다.

구분	개발 환경	운영 환경
목적	개발	배포
전달 방식	소스코드	이미지
Docker 역할	환경 통일	실행 환경 전달
수정	가능	불가능
속도	빠른 반복	안정적 실행
사용 위치	로컬	서버

9.4 이번 프로젝트 기준 적용

self-interior-guide 프로젝트 기준으로 보면
이번 Docker 적용은 운영 배포보다는
개발 및 학습 환경에 더 가까운 방식이라고 볼 수 있습니다.

실제로 이번 과정에서는

Dockerfile을 작성했고
이미지를 빌드했으며
로컬에서 직접 실행해보았습니다.

하지만 실제 서비스는
Vercel을 통해 배포하고 있습니다.

즉, 이번 프로젝트에서는 Docker를
실제 배포 도구로 사용한 것이 아니라,
실행 환경을 직접 구성하고 Docker의 동작 흐름을 이해해보기 위한 도구로 사용했다고 볼 수 있습니다.

9.5 한 줄로 정리하면

정리하면 다음과 같습니다.

개발 환경에서는 환경을 맞추기 위해 Docker를 사용하고
운영 환경에서는 환경을 그대로 전달하기 위해 Docker를 사용합니다.

즉, 같은 Docker를 사용하더라도
목적에 따라 사용하는 방식은 달라질 수 있습니다.

10. 정리

이번 글에서는
self-interior-guide 프로젝트에 Docker를 적용해본 과정을 정리했습니다.

핵심 내용을 정리하면 다음과 같습니다.

Docker는 실행 환경을 포함한 구조로 동작한다
이미지 → 컨테이너 흐름을 직접 확인할 수 있다
환경 문제(Node 버전)도 컨테이너에서 동일하게 발생한다
Docker Desktop을 통해 상태를 시각적으로 확인할 수 있다
Docker Hub를 통해 이미지 배포가 가능하다

이번 프로젝트에서는 Docker를 실제 배포에는 사용하지 않았지만,
적용 과정을 통해 Docker의 실행 구조와 흐름을 직접 경험해볼 수 있었고,
개념으로만 이해하던 내용을 실제 동작과 연결해볼 수 있었습니다.

Docker 기본 개념 정리

IT의 IT 블로그 — Mon, 13 Apr 2026 13:56:30 +0900

안녕하세요.

이번 글에서는 Docker의 기본 개념을 정리해보겠습니다.

Docker를 공부하다 보면
이미지(Image), 컨테이너(Container), Dockerfile, Registry, Compose 같은 용어가 계속 등장합니다.

이 개념들은 각각 따로 보이지만,
실제로는 서로 연결되어 있기 때문에 흐름으로 이해하는 것이 중요합니다.

이번 글에서는 Docker를 왜 사용하는지부터 시작해서,
Docker Desktop과 CLI, 이미지와 컨테이너의 관계, Dockerfile의 역할,
그리고 Compose와 Registry까지 전체 구조를 한 번에 정리해보겠습니다.

단순히 명령어만 보는 것이 아니라,
Docker가 어떤 문제를 해결하고 어떤 방식으로 동작하는지를 중심으로 살펴보겠습니다.

0. Docker Desktop과 CLI

Docker를 사용하는 방법은 크게 두 가지가 있습니다.

하나는 터미널에서 직접 명령어를 입력하는 CLI 방식이고,
다른 하나는 화면에서 컨테이너와 이미지를 확인하고 관리할 수 있는 Docker Desktop 방식입니다.

윈도우 환경에서는 보통 Docker Desktop을 먼저 설치해서 사용하게 되는데,
실제로 Docker를 다룰 때는 CLI와 Docker Desktop을 함께 사용하는 경우가 많습니다.

즉, Docker Desktop은 Docker를 좀 더 쉽게 관리하고 상태를 확인하게 해주는 도구이고,
CLI는 Docker를 실제로 실행하고 제어하는 기본 방식이라고 볼 수 있습니다.

0.1 CLI (Command Line Interface)

CLI는 터미널에서 직접 명령어를 입력하는 방식입니다.

예를 들어 아래와 같은 명령어들이 있습니다.

docker build
docker run
docker ps
docker images

이 방식은 처음에는 다소 낯설 수 있지만,
Docker를 실제로 다룰 때 가장 기본이 되는 방식입니다.

CLI 방식의 장점은 다음과 같습니다.

명령어로 세밀하게 제어할 수 있음
반복 작업을 자동화하기 쉬움
CI/CD나 서버 환경에서 그대로 사용 가능
Docker의 동작 원리를 익히기에 좋음

즉, CLI는
Docker를 실제로 다루는 가장 표준적인 방식이라고 볼 수 있습니다.

0.2 Docker Desktop

반면 윈도우나 Mac 환경에서는 Docker Desktop이라는 GUI 프로그램을 함께 사용할 수 있습니다.

Docker Desktop은
Docker Engine을 조금 더 쉽게 사용할 수 있도록 도와주는 관리 도구입니다.

예를 들어 Docker Desktop에서는 다음과 같은 작업을
UI 화면에서 비교적 직관적으로 할 수 있습니다.

현재 실행 중인 컨테이너 확인
이미지 목록 확인
컨테이너 시작 / 중지 / 삭제
로그 확인
볼륨 / 네트워크 상태 확인

즉, 명령어를 모두 외우지 않아도
현재 Docker 상태를 눈으로 확인하고 관리하기가 쉽습니다.

특히 Docker를 처음 공부할 때는
컨테이너가 실제로 생성되고 실행되는 모습을
GUI 화면으로 보는 것이 이해에 도움이 됩니다.

0.3 Windows에서는 왜 Docker Desktop을 많이 쓰는가

리눅스에서는 Docker를 비교적 직접 설치해서 사용하는 경우가 많지만,
윈도우에서는 Docker Desktop을 통해 Docker 환경을 구성하는 경우가 많습니다.

그 이유는 윈도우가 리눅스 커널을 직접 사용하는 환경이 아니기 때문에,
Docker Desktop이 내부적으로 필요한 실행 환경을 함께 관리해주기 때문입니다.

사용자 입장에서는 복잡한 내부 구조를 모두 신경 쓰기보다
Docker Desktop을 설치하고 실행한 뒤,
CLI와 GUI를 함께 사용하는 방식으로 시작하는 경우가 일반적입니다.

즉, 윈도우 기준으로는 보통 다음처럼 이해하면 됩니다.

Docker Desktop = Docker를 쉽게 실행하고 관리할 수 있게 해주는 프로그램
CLI = Docker를 실제로 조작하는 핵심 명령 방식

0.4 Docker Desktop과 CLI의 관계

이 둘은 서로 대체 관계라기보다는
함께 사용하는 관계에 가깝습니다.

예를 들어

이미지는 CLI로 docker build
컨테이너 상태는 Docker Desktop에서 확인
실행과 삭제는 CLI 또는 GUI 둘 다 가능

이런 식으로 함께 사용할 수 있습니다.

정리하면 다음과 같습니다.

CLI는 Docker를 직접 다루는 핵심 방식
Docker Desktop은 Docker를 더 쉽게 관리하고 시각적으로 확인하게 해주는 도구

처음에는 Docker Desktop으로 전체 구조를 이해하고,
점점 CLI 중심으로 익숙해지는 방식이 가장 자연스럽습니다.

1. 왜 Docker를 사용하는가

개발을 하다 보면
같은 프로젝트라도 실행 환경에 따라 정상적으로 동작하지 않는 경우를 자주 마주하게 됩니다.

예를 들어, 로컬에서는 잘 동작하던 코드가
서버에서는 오류가 발생하거나 실행되지 않는 상황이 생길 수 있습니다.

같은 프로젝트라도 실행 환경이 다르면 문제가 생길 수 있가 때문입니다.

운영체제가 다를 수 있고
Node.js 버전이 다를 수 있고
설치된 라이브러리가 다를 수 있고
배포 서버와 로컬 환경이 다를 수 있습니다

이런 차이 때문에
로컬에서는 잘 되지만 서버에서는 동작하지 않거나,
협업 중에 같은 코드를 받아도 실행이 안 되는 경우가 생깁니다.

Docker는 이런 문제를 해결하기 위해 사용합니다.

애플리케이션을 단순히 코드만 옮기는 것이 아니라,
실행에 필요한 환경까지 함께 묶어서
어디서든 동일하게 실행할 수 있도록 만들어줍니다.

즉, Docker의 가장 큰 목적은
환경 차이를 줄이고 실행 환경을 표준화하는 것입니다.

2. Docker란?

Docker는 컨테이너 기반 가상화 기술을 활용해
애플리케이션을 더 쉽게 실행하고 관리할 수 있도록 도와주는 플랫폼입니다.

조금 더 쉽게 말하면,
프로그램을 실행하는 데 필요한 환경을 하나로 묶어서
격리된 상태로 실행할 수 있게 해주는 도구입니다.

예를 들어 어떤 애플리케이션을 실행하려면 다음과 같은 요소가 필요할 수 있습니다.

운영체제 기반 환경
언어 런타임(Node.js, Python 등)
라이브러리
애플리케이션 코드
실행 명령어

Docker는 이런 요소들을 하나의 실행 단위로 정리해
어디서든 같은 방식으로 실행할 수 있게 만들어줍니다.

핵심은 다음과 같습니다.

실행 환경을 함께 묶을 수 있음
격리된 환경에서 실행 가능
다른 컴퓨터에서도 동일하게 실행 가능
배포와 실행이 단순해짐

즉, Docker는
**“프로그램을 실행하기 위한 환경까지 함께 포장해서 배포하는 방식”**이라고 이해하면 가장 쉽습니다.

3. Virtual Machine과 Docker Container의 차이

Docker를 이해할 때 가장 많이 비교되는 대상이 바로 Virtual Machine입니다.

둘 다 격리된 환경을 만든다는 공통점은 있지만,
동작 방식은 꽤 다릅니다.

3.1 Virtual Machine(가상머신)

기존 가상화 방식은 하이퍼바이저(Hypervisor)를 이용해
하나의 호스트 위에 여러 개의 운영체제를 올려서 사용하는 방식입니다.

각 가상머신은 독립된 Guest OS를 가지고,
그 안에서 필요한 프로그램을 설치하고 실행합니다.

즉, 애플리케이션 하나를 실행하기 위해
운영체제 전체를 하나 더 올리는 구조라고 볼 수 있습니다.

이 방식의 장점은
운영체제 단위로 완전히 분리된 환경을 만들 수 있다는 점입니다.

하지만 단점도 있습니다.

Guest OS가 각각 필요함
커널과 라이브러리까지 모두 포함해야 함
이미지 크기가 큼
실행 속도가 상대적으로 느림
하이퍼바이저를 거치므로 성능 오버헤드가 발생할 수 있음

즉, VM은 강력한 격리를 제공하지만 무겁습니다.

VM → OS 포함

3.2 Docker Container(도커 컨테이너)

Docker 컨테이너는 가상머신처럼 운영체제를 통째로 새로 만들지 않습니다.

호스트 OS의 커널을 공유하면서
프로세스 단위로 애플리케이션을 격리해서 실행합니다.

즉, 필요한 것은 분리하되
운영체제 전체를 복제하지는 않는 방식입니다.

이 방식 덕분에 다음과 같은 장점이 생깁니다.

훨씬 가볍다
실행 속도가 빠르다
이미지 크기가 작다
성능 손실이 적다

컨테이너 안에는
애플리케이션 실행에 필요한 라이브러리와 파일만 포함되고,
커널은 호스트와 공유합니다.

그래서 Docker는
가상머신보다 더 빠르고 효율적으로 실행 환경을 제공할 수 있습니다.

4. Docker가 가볍고 빠른 이유

Docker가 빠르다고 많이 이야기하지만,
중요한 것은 왜 빠른가를 이해하는 것입니다.

Docker가 가볍고 빠른 이유는 크게 세 가지로 볼 수 있습니다.

4.1 운영체제를 통째로 포함하지 않는다

OS 전체 포함 vs 필요한 실행 환경만 포함

컨테이너는 Guest OS를 따로 가지지 않습니다.
호스트의 커널을 공유하기 때문에
운영체제 전체를 매번 포함할 필요가 없습니다.

4.2 필요한 것만 포함한다

필요한 것만 포함

컨테이너에는 애플리케이션 실행에 필요한 파일과 라이브러리만 들어갑니다.

예를 들어 Node.js 애플리케이션이라면
Node 런타임, 패키지, 소스 코드 정도만 포함하면 됩니다.

4.3 프로세스 단위로 격리한다

가상머신은 OS 단위 가상화에 가깝지만,
Docker는 프로세스 단위 격리이기 때문에 훨씬 효율적입니다.

결국 Docker는
무겁게 전체 시스템을 가상화하는 대신, 필요한 실행 환경만 분리해서 사용하기 때문에 빠르고 가볍습니다.

프로세스 단위 비교 인포그래픽

5. Docker의 핵심 구성요소

Docker를 사용할 때 자주 등장하는 구성요소는 다음과 같습니다.

도커 흐름도

5.1 Docker Client

우리가 터미널에서 사용하는 docker 명령어가 바로 Docker Client입니다.

예를 들어

docker build
docker pull
docker run

이런 명령어를 입력하면
Docker Client가 그 요청을 Docker Engine에 전달합니다.

즉, 사용자의 입력을 받아 실제 엔진에 명령을 전달하는 역할입니다.

5.2 Docker Engine(Docker Daemon)

Docker의 실제 동작 주체입니다.

Docker Engine은 다음과 같은 작업을 수행합니다.

이미지 빌드
이미지 다운로드 및 저장
컨테이너 생성 및 실행
네트워크 / 볼륨 관리

즉, Docker의 핵심은 결국 Docker Engine이라고 볼 수 있습니다.

5.3 Docker Host

Docker Engine이 실행되는 환경입니다.
이미지와 컨테이너가 실제로 존재하고 관리되는 서버 또는 PC라고 보면 됩니다.

5.4 Registry

이미지를 저장하는 원격 저장소입니다.

대표적으로 다음이 있습니다.

Docker Hub
AWS ECR
GitHub Container Registry

이미지를 Registry에 올려두면
다른 환경에서 pull 받아서 그대로 실행할 수 있습니다.

6. Docker Image와 Docker Container

Docker를 이해할 때 가장 중요한 개념은
이미지와 컨테이너입니다.

이 둘은 서로 연결되어 있지만 역할이 다릅니다.

6.1 Docker Image란?

Docker Image는 컨테이너를 생성하기 위한 실행 패키지입니다.

쉽게 말하면
애플리케이션을 실행하는 데 필요한 환경을 담아둔 묶음입니다.

여기에는 보통 다음이 포함됩니다.

베이스 이미지 정보
런타임
라이브러리
소스 코드
실행 명령

즉, 이미지는 실행 환경이 미리 구성된 결과물입니다.

비유하면 다음과 같습니다.

클래스와 인스턴스 관계에서의 클래스
프로그램과 프로세스 관계에서의 프로그램 파일
건축으로 보면 설계도

즉, 이미지는
실행되기 전의 정적인 패키지입니다.

6.2 Docker Container란?

컨테이너는 이미지를 실제로 실행한 상태입니다.

이미지가 정적인 실행 패키지라면,
컨테이너는 그 패키지가 메모리 위에서 실제로 동작하고 있는 실행 인스턴스입니다.

같은 이미지 하나로 여러 개의 컨테이너를 만들 수 있기 때문에
이미지와 컨테이너는 1:N 관계입니다.

예를 들어 하나의 웹 서버 이미지로부터
여러 개의 웹 서버 컨테이너를 띄울 수 있습니다.

즉, 이미지는 재사용 가능한 원본이고,
컨테이너는 그 원본으로부터 만들어진 실행 결과입니다.

6.3 이미지와 컨테이너의 차이

이미지는 읽기 전용입니다.
한 번 만들어진 이미지는 직접 수정하는 개념보다
새로 빌드해서 교체하는 방식에 가깝습니다.

반면 컨테이너는 실행 중 상태가 바뀔 수 있습니다.

예를 들어 컨테이너 안에서 파일을 수정하거나 프로그램을 설치할 수 있지만,
그 변경은 원본 이미지에 직접 반영되는 것이 아니라
컨테이너의 쓰기 계층에 따로 저장됩니다.

즉,

이미지는 원본
컨테이너는 실행본
컨테이너의 변경 사항은 해당 컨테이너에만 적용

됩니다.

같은 이미지로 만든 A 컨테이너를 수정해도
B 컨테이너에는 영향을 주지 않는 이유가 바로 이것입니다.

7. 이미지의 핵심 특징: 불변성과 레이어 구조

Docker 이미지가 어떻게 관리되는지를 이해하려면
불변성(Immutable) 과 레이어(Layer) 개념을 꼭 알아야 합니다.

7.1 이미지는 변경할 수 없다

Docker 이미지는 기본적으로 불변입니다.

즉, 한 번 생성된 이미지를 직접 수정해서 덮어쓰는 방식이 아니라
변경이 필요하면 새로운 이미지를 다시 빌드합니다.

예를 들어 코드가 수정되었거나 패키지가 추가되었다면
기존 이미지를 고치는 것이 아니라
그 상태를 반영한 새로운 이미지를 다시 만들어야 합니다.

이 방식은 번거로워 보일 수 있지만 장점이 분명합니다.

실행 환경이 항상 예측 가능함
같은 이미지라면 어디서 실행해도 동일한 결과 보장
버전 관리가 쉬움
배포 이력이 명확해짐

즉, Docker는
“실행 중인 환경을 직접 고쳐 쓰는 방식”보다
“새로운 버전을 다시 만들어 교체하는 방식”에 더 가깝습니다.

7.2 이미지는 여러 레이어로 구성된다

Docker 이미지는 하나의 덩어리 파일처럼 보이지만,
내부적으로는 여러 레이어가 쌓여서 구성됩니다.

예를 들어 아래와 같은 Dockerfile이 있다고 해보겠습니다.

FROM node:22-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install
COPY . .
CMD ["npm", "run", "dev"]

이 Dockerfile은 한 번에 전체가 만들어지는 것이 아니라,
각 명령어 단위로 레이어가 쌓이는 구조입니다.

대략적인 흐름은 다음과 같습니다.

FROM node:22-alpine
→ Node.js 22 기반의 베이스 이미지 레이어
WORKDIR /app
→ 작업 디렉토리 설정 레이어
COPY package.json package-lock.json ./
→ 의존성 파일 복사 레이어
RUN npm install
→ 패키지 설치 레이어
COPY . .
→ 실제 소스 코드 복사 레이어
CMD ["npm", "run", "dev"]
→ 컨테이너 실행 기본 명령 설정

즉, 이미지는 여러 단계의 파일 시스템 변경이 차곡차곡 쌓인 결과입니다.

7.3 레이어 구조가 중요한 이유

레이어 구조는 Docker의 성능과 효율성에 매우 중요합니다.

1) 캐시를 활용할 수 있다

이전에 빌드한 레이어와 동일하면 다시 만들지 않고 재사용할 수 있습니다.

예를 들어 package.json이 바뀌지 않았다면
RUN npm install 레이어를 다시 만들지 않고 캐시를 사용할 수 있습니다.

그래서 보통 Dockerfile 작성 시에는

COPY package.json package-lock.json ./
RUN npm install
COPY . .

처럼 의존성 파일을 먼저 복사하고 설치한 뒤, 나중에 소스 코드를 복사하는 패턴을 많이 사용합니다.

이렇게 하면 코드만 수정됐을 때 매번 npm install을 다시 하지 않아도 되기 때문입니다.

2) 이미지 확장이 쉽다

기존 베이스 이미지 위에 필요한 레이어만 추가하면 되기 때문에
Node 이미지, Python 이미지 같은 공식 이미지를 기반으로 손쉽게 확장할 수 있습니다.

3) 저장과 전송이 효율적이다

변경된 레이어만 전송하거나 재사용할 수 있기 때문에
빌드와 배포 과정이 더 효율적입니다.

즉, 레이어 구조는 단순한 내부 구현이 아니라
Docker가 빠르고 효율적으로 동작하는 핵심 이유 중 하나입니다.

8. Dockerfile이란?

Dockerfile은 이미지를 만들기 위한 명령어들을 작성하는 파일입니다.

즉,
**“이 애플리케이션을 어떤 환경에서, 어떤 순서로 이미지화할 것인가”**를 정의한 빌드 스크립트입니다.

Dockerfile은 단순히 명령어를 적는 파일이 아니라,
이미지 생성 과정을 문서처럼 선언적으로 표현하는 파일입니다.

즉, Dockerfile만 보면

어떤 베이스 이미지를 사용할지
어떤 파일을 복사할지
어떤 패키지를 설치할지
어떤 명령으로 실행할지

를 한눈에 파악할 수 있습니다.

8.1 Dockerfile의 역할

Dockerfile의 역할은 크게 네 가지로 볼 수 있습니다.

1) 실행 환경 정의

어떤 런타임과 어떤 OS 기반에서 시작할지를 정합니다.

예를 들어

FROM node:22-alpine

는
Node.js 22가 설치된 Alpine Linux 기반 환경에서 시작하겠다는 의미입니다.

2) 애플리케이션 파일 복사

내 로컬에 있는 프로젝트 파일을 이미지 안으로 복사합니다.

예를 들어

COPY . .

는 현재 폴더의 파일을 이미지 내부로 복사하겠다는 뜻입니다.

3) 필요한 의존성 설치

애플리케이션 실행에 필요한 패키지를 이미지 안에 설치합니다.

예를 들어

RUN npm install

는 컨테이너 내부 환경에서 npm install을 실행해
필요한 패키지를 설치하겠다는 의미입니다.

4) 컨테이너 시작 명령 정의

이미지를 실행했을 때 어떤 명령어를 기본으로 실행할지를 정합니다.

예를 들어

CMD ["npm", "run", "dev"]

는 컨테이너가 시작될 때 npm run dev를 실행하겠다는 의미입니다.

8.2 자주 쓰는 Dockerfile 명령어

FROM

베이스 이미지 지정

FROM node:22-alpine

WORKDIR

작업 디렉토리 지정

WORKDIR /app

이후 명령어들은 /app 기준으로 실행됩니다.

COPY

파일 복사

COPY . .

현재 프로젝트 파일을 이미지 내부로 복사합니다.

RUN

이미지 빌드 과정에서 실행할 명령어

RUN npm install

빌드 시점에 패키지를 설치합니다.

CMD

컨테이너 실행 시 기본으로 실행할 명령어

CMD ["npm", "run", "dev"]

컨테이너가 시작될 때 실행됩니다.

8.3 Dockerfile은 왜 중요한가

Dockerfile이 중요한 이유는
이미지를 사람 손으로 직접 만드는 것이 아니라
코드처럼 재현 가능하게 만들 수 있기 때문입니다.

즉, Dockerfile이 있으면

누구나 동일한 이미지 생성 가능
배포 환경 재현 가능
버전 관리 가능
빌드 과정을 문서화할 수 있음

결국 Dockerfile은
이미지 빌드 과정을 코드로 관리하는 파일이라고 볼 수 있습니다.

9. 이미지는 어떻게 만들어지는가

Docker 이미지는 보통 다음 흐름으로 생성됩니다.

9.1 Dockerfile 작성

프로젝트 루트에 Dockerfile을 작성합니다.

9.2 이미지 빌드

docker build -t my-app .

이 명령어를 실행하면 Dockerfile을 기반으로 이미지가 생성됩니다.

9.3 컨테이너 실행

docker run -p 5173:5173 my-app

생성된 이미지를 실행하면 컨테이너가 됩니다.

즉, 전체 흐름은 다음과 같습니다.

Dockerfile
↓
docker build
↓
Docker Image
↓
docker run
↓
Docker Container
 
 

10. 이미지 이름은 어떻게 구성되는가

Docker 이미지 이름은 보통 아래 형태를 따릅니다.

[저장소 이름]/[이미지 이름]:[태그]

예를 들면 다음과 같습니다.

myrepo/my-app:1.0

각 부분의 의미는 다음과 같습니다.

저장소 이름: 이미지가 저장되는 위치
이미지 이름: 이미지의 역할
태그: 버전 정보

태그를 생략하면 일반적으로 latest로 인식합니다.

즉, 이미지 이름은 단순한 문자열이 아니라
어디 저장되어 있고, 어떤 역할을 하며, 어떤 버전인지까지 포함하는 식별자입니다.

11. Registry와 Repository

이 둘은 이름이 비슷해서 많이 헷갈립니다.

11.1 Registry

Registry는 이미지를 저장하는 중앙 저장소입니다.

예를 들어 Docker Hub는 대표적인 Registry입니다.

즉, 이미지를 push 하고 pull 받는 서버입니다.

11.2 Repository

Repository는 Registry 안에서 관련 이미지들을 묶어두는 단위입니다.

하나의 프로젝트 폴더처럼 생각하면 이해하기 쉽습니다.

예를 들어 Docker Hub라는 Registry 안에
my-app이라는 Repository가 있고,
그 안에 1.0, 1.1, latest 같은 태그가 존재할 수 있습니다.

즉,

Registry = 전체 이미지 저장소
Repository = 특정 프로젝트 이미지 모음

입니다.

12. 왜 이미지를 만들어두면 편한가

이미지를 한 번 잘 만들어두면
다른 컴퓨터에서도 동일한 방식으로 쉽게 실행할 수 있습니다.

즉, 내 컴퓨터에서 동작하던 환경을
그대로 다른 환경으로 옮길 수 있습니다.

이 방식은 특히 다음 상황에서 강력합니다.

협업 환경 통일
배포 자동화
서버 이전
테스트 환경 재현

이미지를 Registry에 올려두면
다른 사람은 복잡한 설정 없이 pull 받아 실행만 하면 됩니다.

그래서 Docker는 개발 환경뿐 아니라
운영 환경과 CI/CD에서도 많이 사용됩니다.

13. 컨테이너는 하나의 역할만 맡는 것이 좋다

컨테이너를 사용할 때 자주 언급되는 원칙이 있습니다.

하나의 컨테이너는 하나의 역할에 집중하는 것이 좋다는 점입니다.

예를 들면 다음처럼 나누는 방식입니다.

프론트엔드 컨테이너
백엔드 컨테이너
데이터베이스 컨테이너
캐시 서버 컨테이너

이렇게 역할을 나누면 다음 장점이 있습니다.

관리가 쉬움
장애 범위 분리 가능
확장 용이
배포 단위 명확

즉, 컨테이너는 작고 분리된 단위로 설계할수록 관리가 쉬워집니다.

14. Docker Compose란?

실제 애플리케이션은 하나의 컨테이너만으로 끝나지 않는 경우가 많습니다.

예를 들면

프론트엔드
백엔드
데이터베이스
Redis

처럼 여러 서비스가 함께 동작해야 할 수 있습니다.

이때 각각을 docker run으로 하나씩 띄우면
설정도 길어지고 관리도 어려워집니다.

Docker Compose는 이런 문제를 해결하기 위해 사용합니다.

여러 컨테이너와 그 설정을
하나의 YAML 파일에 정의하고,
한 번의 명령으로 함께 실행할 수 있게 해주는 도구입니다.

14.1 Compose 예시

version: "3"

services:
app:
build: .
ports:
- "5173:5173"

db:
image: postgres

이렇게 작성하면

docker compose up

명령어 한 번으로 여러 서비스를 함께 실행할 수 있습니다.

14.2 Compose의 핵심

핵심은 다음과 같습니다.

Dockerfile은 이미지를 만드는 파일
Compose는 실행할 서비스들을 정의하는 파일

즉, Dockerfile은 빌드 중심이고
Compose는 실행 구성 중심입니다.

15. Dockerfile과 Compose는 무엇이 다른가

둘은 비슷해 보이지만 역할이 다릅니다.

Dockerfile

이미지 생성 방법 정의
빌드 과정 담당

Compose 파일

실행할 컨테이너 정의
서비스 간 연결 담당

즉,

Dockerfile → 이미지를 어떻게 만들지
Compose → 컨테이너를 어떻게 실행할지

를 담당합니다.

Dockerfile vs Compose 비교

항목	Dockerfile	Docker Compose
목적	이미지를 만드는 방법 정의	여러 컨테이너를 실행하고 관리
대상	단일 이미지 빌드	여러 서비스(컨테이너) 실행
중심 개념	build	run
작성 파일	Dockerfile	compose.yml 또는 docker-compose.yml
주요 내용	베이스 이미지, 파일 복사, 패키지 설치, 실행 명령 정의	서비스 정의, 포트, 볼륨, 네트워크, 환경변수 설정
사용 시점	이미지를 생성할 때	컨테이너를 실행할 때
대표 명령어	docker build	docker compose up
결과	Docker Image 생성	여러 Container 생성 및 실행
비유	설계도	실행 계획표

16. 전체 흐름으로 다시 정리

지금까지의 내용을 한 번에 정리하면 Docker의 전체 흐름은 다음과 같습니다.

Dockerfile 작성
docker build로 이미지 생성
이미지를 Registry에 push
다른 환경에서 pull
docker run 또는 docker compose up으로 컨테이너 실행

즉, Docker는
실행 환경을 코드처럼 정의하고,
그 결과물을 이미지로 만들고,
그 이미지를 어디서든 동일하게 실행할 수 있도록 해주는 구조입니다.

17. 정리

지금까지 Docker의 기본 개념과 구조를 정리해봤습니다.

Docker는 단순히 컨테이너를 띄우는 도구가 아니라,
애플리케이션 실행 환경을 함께 묶어서
어디서든 동일하게 실행할 수 있도록 해주는 플랫폼입니다.

핵심 개념을 다시 정리하면 다음과 같습니다.

Docker는 실행 환경을 통째로 패키징한다
Image는 실행 환경을 담은 패키지다
Container는 이미지를 실행한 상태다
Dockerfile은 이미지를 만드는 설계서다
Compose는 여러 컨테이너를 관리하는 실행 설정 파일이다
이미지는 불변이며 여러 레이어로 구성된다

결국 Docker의 가장 큰 장점은
환경 차이를 줄이고, 실행과 배포를 단순하게 만든다는 점입니다.

이 글에서는 Docker의 개념과 구조를 정리했습니다.

다음 글에서는
실제 프로젝트(self-interior-guide)에 Docker를 적용한 과정을 통해
이 개념들이 어떻게 활용되는지 살펴보겠습니다.

사이드 프로젝트 소개 | 셀프 인테리어 가이드

IT의 IT 블로그 — Mon, 6 Apr 2026 12:52:48 +0900

안녕하세요.
이번 글에서는 제가 진행한 사이드 프로젝트인
self-interior-guide를 소개해보려고 합니다.

이 프로젝트는
셀프 인테리어를 처음 시작하는 사용자를 위한
“가이드 + 견적” 웹 서비스입니다.

단순히 인테리어 정보를 나열하는 것이 아니라,
실제로 사용자가 참고하면서 진행할 수 있도록
체크리스트형 UX로 설계한 것이 핵심입니다.

아래 링크에서 실제 서비스와 코드를 함께 확인하실 수 있습니다.

서비스 바로가기
https://self-interior-guide.vercel.app

GitHub
https://github.com/Ryuintae/self-interior-guide

1. 왜 이 프로젝트를 만들었는가

셀프 인테리어를 처음 시작하면 대부분 이런 문제를 겪습니다.

무엇부터 해야 할지 모르겠음
순서를 몰라 시행착오가 많음
정보가 많지만 오히려 더 혼란스러움

기존 콘텐츠는 대부분 “정보 제공”에 집중되어 있고,
실제로 따라가면서 사용할 수 있는 구조는 부족하다고 느꼈습니다.

그래서 단순한 정보 전달이 아니라,

**“실제로 참고하면서 진행할 수 있는 구조”**를 만들고자 했습니다.

2. 기존 방식의 한계

일반적인 인테리어 가이드는 대부분 다음과 같은 구조를 가지고 있습니다.

❌ 단계형 튜토리얼

1 → 2 → 3 → 4 순서 강제
모든 단계를 완료해야 한다는 부담
필요한 정보만 선택적으로 보기 어려움

하지만 실제 사용자는 모든 단계를 그대로 따르지 않습니다.

상황에 따라 필요한 부분만 참고하고
순서도 유동적으로 바뀌는 경우가 많습니다.

3. 해결 방식: 체크리스트형 UX

이 프로젝트의 핵심은 하나입니다.

✅ “완료”가 아니라 “확인”

단계 완료 ❌
체크 기반 확인 ✅

즉,

“다음 단계로 진행하세요” → ❌
“이 항목은 확인했나요?” → ✅

이 기준으로 UX 전체를 설계했습니다.

4. UX 설계 핵심

이 프로젝트에서 가장 중요하게 본 것은
사용자의 부담을 줄이는 구조입니다.

4.1 진행률 제거

일반적으로 많이 사용하는 진행률(%), 단계 완료 개념을 제거했습니다.

진행률은 사용자에게 “끝까지 해야 한다”는 압박을 주기 때문입니다.

4.2 체크 UI 위치 변경

초기에는 체크 UI를 상단에 배치했지만,
현재는 하단으로 이동시켰습니다.

상단: 바로 행동 유도 → 부담
하단: 내용 확인 → 체크

“읽기 → 이해 → 체크” 흐름으로 변경했습니다.

4.3 ResultPage 재정의

보통 ResultPage는 “완료 화면”입니다.

하지만 이 프로젝트에서는

전체 체크리스트를 다시 확인하는 화면으로 설계했습니다.

내가 확인한 항목
아직 보지 않은 항목
다시 보고 싶은 항목

을 정리하고,

자연스럽게 견적 페이지로 이동하도록 구성했습니다.

4.4 EstimatePage UX (행동으로 연결)

가이드에서 끝나는 것이 아니라,
사용자가 실제로 다음 행동을 할 수 있도록
견적 페이지로 흐름을 연결했습니다.

EstimatePage는 단순 입력폼이 아니라,

선택한 옵션을 시각적으로 확인하면서 견적을 비교할 수 있는 구조입니다.

공간 타입 선택
벽 / 바닥 / 가구 색상 변경
선택값에 따른 예상 견적 범위 표시

특히 중요한 포인트는

상태 변경 → 3D 화면 즉시 반영

이라는 흐름입니다.

사용자는 단순히 값을 입력하는 것이 아니라,

직접 보고
비교하고
선택할 수 있습니다

즉,

정보 확인 → 상태 정리 → 실제 행동(견적)

으로 이어지는 UX 흐름을 만들고자 했습니다.

5. 페이지 구조

전체 흐름은 다음과 같습니다.

Home
→ GuideStart
→ GuideStep
→ GuideResult
→ Estimate

각 페이지의 역할은 다음과 같습니다.

HomePage: 서비스 소개 및 진입
GuideStartPage: 사용자 조건 선택
GuideStepPage: 가이드 내용 확인
GuideResultPage: 전체 체크 상태 정리
EstimatePage: 3D 기반 견적 확인

이 구조의 핵심은

강제 흐름이 아니라 자유 탐색 구조라는 점입니다.

6. 프로젝트 구조

이 프로젝트는 단순히 페이지를 나열하는 구조가 아니라,
역할과 도메인 기준으로 분리된 구조로 설계했습니다.

실제 src 구조는 다음과 같습니다.

src
├─ index.css
├─ main.tsx
├─ vite-env.d.ts
│
├─ app
│ ├─ RootLayout.tsx
│ └─ router.tsx
│
├─ assets
│ ├─ hero.png
│ ├─ react.svg
│ └─ vite.svg
│
├─ features
│ ├─ configurator
│ │ ├─ components
│ │ │ ├─ RoomCanvas.tsx
│ │ │ └─ RoomScene.tsx
│ │ └─ store
│ │ └─ useConfiguratorStore.ts
│ │
│ ├─ estimate
│ │ ├─ data
│ │ │ └─ estimateData.ts
│ │ └─ types
│ │ └─ estimate.ts
│ │
│ └─ guide
│ ├─ data
│ │ ├─ guideData.ts
│ │ └─ guideRecommendations.ts
│ ├─ store
│ │ └─ useGuideStore.ts
│ └─ types
│ └─ guide.ts
│
├─ pages
│ ├─ HomePage.tsx
│ ├─ GuideStartPage.tsx
│ ├─ GuideStepPage.tsx
│ ├─ GuideResultPage.tsx
│ └─ EstimatePage.tsx
│
└─ shared
└─ ui
├─ PageShell.tsx
├─ ProgressBar.tsx
├─ ScrollToTop.tsx
└─ SectionCard.tsx

6.1 구조 설계 기준

이 프로젝트 구조는 다음 기준으로 나눴습니다.

app → 앱 전체 구조 (라우팅, 레이아웃)
features → 기능/도메인 단위
pages → 실제 화면 단위
shared/ui → 공통 UI 컴포넌트

즉,

“화면”이 아니라 “역할” 기준으로 분리한 구조입니다.

6.2 app: 앱 진입 구조

router.tsx: 전체 라우팅 정의
RootLayout.tsx: 공통 레이아웃

이 영역은 앱의 흐름을 담당합니다.

이 프로젝트는

가이드
결과
견적

처럼 페이지 간 이동이 많기 때문에,

라우팅 구조 자체가 UX 흐름과 연결되는 구조입니다.

6.3 features: 도메인 중심 구조

이 프로젝트에서 가장 중요한 설계 포인트입니다.

왜 features로 나눴는가?

처음에는 pages 중심으로도 구현할 수 있지만,
기능이 커질수록 아래 문제가 발생합니다.

상태와 UI가 섞임
데이터와 로직이 뒤엉킴
유지보수 어려움

그래서 다음 기준으로 분리했습니다.

“기능 단위로 묶는다”

6.3.1 guide (핵심 도메인)

guide
├─ data
├─ store
└─ types

이 프로젝트의 핵심 기능입니다.

guideData.ts → 가이드 콘텐츠
guideRecommendations.ts → 추천 로직
useGuideStore.ts → 상태 관리
guide.ts → 타입 정의

UI / 상태 / 데이터 / 타입을 분리한 구조

이 구조 덕분에

데이터 수정
상태 변경
UI 변경

이 서로 영향을 덜 받도록 만들 수 있습니다.

6.3.2 estimate (견적 계산 영역)

estimate
├─ data
└─ types

이 영역은

견적 계산 기준을 담당합니다.

옵션별 가격
공간별 비용
계산 로직 기준

UI와 분리했기 때문에
나중에 계산 방식이 바뀌어도 영향 범위를 줄일 수 있습니다.

6.3.3 configurator (3D 영역)

configurator
├─ components
└─ store

이 영역은

3D 시각화 + 사용자 인터랙션을 담당합니다.

RoomCanvas → 렌더링 영역
RoomScene → 실제 공간 구성
useConfiguratorStore → 상태 관리

특히

Canvas와 Scene을 분리한 구조

는 중요한 포인트입니다.

Canvas → 렌더링 환경
Scene → 오브젝트 구성

6.4 pages: 사용자 화면 단위

pages
├─ HomePage
├─ GuideStartPage
├─ GuideStepPage
├─ GuideResultPage
└─ EstimatePage

이 폴더는 단순 화면 모음이 아니라,

사용자 흐름을 구성하는 레이어입니다.

Home → 진입
Guide → 정보 탐색
Result → 상태 확인
Estimate → 행동

즉,

페이지 = UX 흐름 단위

6.5 shared/ui: 공통 UI

shared/ui
├─ PageShell
├─ SectionCard
├─ ScrollToTop
└─ ProgressBar

이 영역은 UI 일관성을 담당합니다.

주요 역할

PageShell → 페이지 구조 통일
SectionCard → 카드 UI 통일
ScrollToTop → UX 개선
ProgressBar → 초기 UX 실험 흔적

특히 SectionCard는

가이드, 옵션, 설명을 같은 톤으로 묶어주는 핵심 컴포넌트입니다.

6.6 구조 설계에서 중요했던 포인트

이 구조에서 중요하게 본 것은 다음입니다.

1) 역할 분리

UI / 상태 / 데이터 / 타입 분리

2) 도메인 중심 설계

guide / estimate / configurator

3) 확장성

API 연동 가능 구조
기능 추가 시 영향 최소화

6.7 정리

이 프로젝트 구조는 단순한 파일 분리가 아니라,

가이드 UX, 상태 관리, 3D 견적 기능을 명확히 분리하여
확장성과 유지보수를 고려한 구조로 설계한 것입니다.

결국 느낀 점은,

작은 프로젝트라도 구조를 어떻게 잡느냐에 따라
이후의 확장성과 유지보수 난이도가 크게 달라진다는 것입니다.

7. 기술 스택과 선택 이유

이 프로젝트는 단순 UI 구현이 아니라
UX 흐름, 상태 관리, 3D 인터랙션까지 포함되어 있기 때문에
각 역할에 맞게 기술을 선택했습니다.

7.1 React + TypeScript

React
TypeScript

이 프로젝트는 페이지 흐름이 많고, 상태 변화도 다양한 구조입니다.

단순 정적인 페이지가 아니라
가이드 → 체크 상태 → 견적 → 3D 반영까지 이어지는 구조이기 때문에

컴포넌트 기반 구조와 상태 흐름 관리가 중요한 프로젝트였습니다.

React를 선택한 이유는 다음과 같습니다.

컴포넌트 단위로 UI를 분리하기 용이
상태 기반 렌더링 구조
생태계가 풍부

TypeScript를 사용한 이유는

가이드 데이터 구조 관리
상태 구조 안정성 확보
확장 시 오류 방지

특히 이 프로젝트는
guideData, estimateData, 상태 구조 등이 명확해야 하기 때문에
타입 안정성이 중요했습니다.

7.2 Vite

이 프로젝트는 Vite를 사용해 개발 환경을 구성했습니다.

이유는 단순합니다.

개발 속도와 DX(개발 경험)

빠른 dev server 실행
즉각적인 HMR
설정이 단순함

이 프로젝트는 UI를 계속 수정하고 실험하는 과정이 많기 때문에
빌드 속도보다 개발 반복 속도가 더 중요했습니다.

또한 Vite는

▶ 개발 환경에서는 ESM 기반
▶ 빌드 시에는 Rollup 사용

이라는 구조이기 때문에
최근 프론트엔드 환경에도 잘 맞는 선택이라고 판단했습니다.

7.3 Zustand (상태 관리)

이 프로젝트에서는 Redux 대신 Zustand를 사용했습니다.

이유는 다음과 같습니다.

보일러플레이트가 적음
직관적인 상태 관리
작은 프로젝트에서도 과하지 않음

특히 이 프로젝트의 핵심 상태는 다음과 같습니다.

가이드 선택 값
체크 상태
시나리오별 상태 분리
견적 옵션 상태

이 구조는 전역 상태가 필요하지만,
Redux처럼 복잡한 구조까지는 필요하지 않았습니다.

그래서

▶ 가볍지만 확장 가능한 상태 관리 도구

로 Zustand를 선택했습니다.

7.4 React Router

이 프로젝트는 사용자 흐름이 중요한 구조입니다.

Home → Guide → Step → Result → Estimate

단순 페이지 이동이 아니라
UX 흐름 자체가 중요한 프로젝트이기 때문에

라우팅 구조가 명확해야 했습니다.

React Router를 사용한 이유는

선언적인 라우팅
동적 라우트 지원 (/step/:stepId)
SPA 구조에 적합

7.5 Tailwind CSS

스타일링은 Tailwind CSS를 사용했습니다.

이유는 다음과 같습니다.

빠른 UI 구현
일관된 디자인 시스템 유지
커스터마이징 용이

이 프로젝트는 카드 UI, 체크리스트 UI, 옵션 UI 등
비슷한 패턴이 반복되는 구조입니다.

Tailwind를 사용하면

✅ 클래스 기반으로 빠르게 UI를 조합할 수 있고
✅ 디자인 일관성을 유지하기 쉽습니다.

7.6 Three.js + React Three Fiber

이 프로젝트에서 가장 특징적인 부분은
3D 기반 견적 UI입니다.

이를 위해 다음을 사용했습니다.

Three.js
React Three Fiber
@react-three/drei

왜 3D를 사용했는가

단순 견적 입력폼이 아니라,

사용자가 공간을 “보면서” 선택할 수 있도록 하기 위해서입니다.

벽 색상 변경
바닥 색상 변경
가구 색상 변경

이러한 선택을 숫자가 아니라
시각적으로 확인할 수 있도록 설계했습니다.

React Three Fiber를 선택한 이유

React 방식으로 3D 구성 가능
상태와 3D를 자연스럽게 연결
컴포넌트 단위로 Scene 구성 가능

예를 들어:

상태 변경 → 3D 반영
선택 값 → 즉시 시각화

이 흐름을 자연스럽게 구현할 수 있습니다.

7.7 정리

이 프로젝트의 기술 스택은 단순히 최신 기술을 사용한 것이 아니라,

각 역할에 맞게 선택했습니다.

React → UI 구조
Zustand → 상태 관리
Vite → 개발 경험
Tailwind → UI 생산성
Three.js → 시각적 인터랙션

결과적으로 이 조합은

UX 중심 프로젝트를 빠르게 구현하기 위한 구조

라고 볼 수 있습니다.

8. 구현에서 중요했던 포인트

8.1 시나리오 기반 상태 분리

const scenarioKey = `${spaceType}-${scope}`;

8.2 체크 상태 구조

stepStatusByScenario[scenarioKey][stepId]

8.3 가이드 → 견적 연결

“읽고 끝”이 아니라
행동으로 이어지는 구조

10. 정리하며

복잡한 정보를 최대한 쉽게 전달하려고 했지만,
사용자 입장에서는 여전히 어렵게 느껴지는 부분이 있을 수 있다고 생각합니다.

이번 프로젝트를 통해
기능을 구현하는 것보다
사용자가 어떻게 이해하고 받아들이는지가 더 중요하다는 것을 느꼈습니다.

앞으로는 화면 설계와 기획을 통해
사용자가 더 자연스럽게 이해하고 사용할 수 있도록 개선해 나가고자 합니다.

이 프로젝트는 복잡한 인테리어 과정을
체크리스트 UX로 단순화하고
3D 견적까지 연결한 서비스입니다.

핵심은 기술보다
사용자의 부담을 줄이는 구조였으며,
이 방향으로 계속 개선해 나갈 예정입니다.

읽어주셔서 감사합니다.

Webpack vs Vite: 구조적 차이 정리

IT의 IT 블로그 — Fri, 3 Apr 2026 16:11:02 +0900

안녕하세요.
이전 글에서는 번들러가 내부에서 어떻게 동작하는지, 그리고 의존성 그래프를 생성하고 트리쉐이킹과 코드 스플리팅을 수행하는 과정을 정리했습니다.

이러한 번들링 과정은 실제 번들러마다 구현 방식에 차이가 있습니다.

이번 글에서는 대표적인 번들러인 Webpack과 Vite의 구조적 차이를 살펴보겠습니다.

단순히 “Vite가 더 빠르다”는 수준이 아니라,
왜 그런 차이가 발생하는지를 구조 중심으로 정리해보겠습니다.

1. 왜 Webpack과 Vite를 비교하는가

Webpack은 오랜 기간 프론트엔드 빌드 도구의 표준으로 사용되어 왔고,
Vite는 빠른 개발 환경을 기반으로 최근 빠르게 확산되고 있습니다.

두 도구는 같은 번들링 영역의 도구이지만,
근본적인 동작 방식이 다릅니다.

2. Webpack의 구조

2.1 기본 동작 방식

Webpack은 프로젝트의 모든 모듈을 분석해
하나의 의존성 그래프를 만든 뒤 번들 파일을 생성합니다.

entry
↓
dependency graph 생성
↓
전체 번들 생성
↓
dev server 제공

핵심: 개발 환경에서도 전체 번들링을 수행

2.2 특징

모든 모듈을 미리 분석
하나의 번들로 묶어서 제공
강력한 플러그인 생태계

2.3 단점

초기 실행 속도가 느릴 수 있음
프로젝트가 커질수록 빌드 시간 증가
설정이 복잡해질 수 있음

3. Vite의 구조

3.1 핵심 철학

개발 환경에서는 번들링을 하지 않는다

3.2 동작 방식 (ESM 기반)

Vite는 브라우저의 ES Module 기능을 그대로 활용합니다.

브라우저 → main.js 요청
→ import 따라 개별 요청
→ 필요한 파일만 변환

핵심: 필요한 모듈만 즉시 처리

3.3 내부 구조

Vite는 개발과 빌드를 분리해서 처리합니다.

개발 환경 → esbuild
빌드 환경 → Rollup

정리하면

Vite는 개발 서버 + 빌드 도구이며,
빌드 시 Rollup을 사용해 번들링을 수행합니다.

4. Rollup이란 무엇인가 (Vite와의 관계)

4.1 Rollup이란?

Rollup은 ES Module 기반 번들링에 최적화된 번들러입니다.

트리쉐이킹에 강함
불필요한 코드 제거에 최적화
라이브러리 번들링에 강점

4.2 Vite에서의 역할

Vite는 개발 환경에서는 번들링을 하지 않지만,
배포 시점에서는 반드시 번들링이 필요합니다.

이때 Rollup이 번들링을 담당합니다.

개발 → ESM + esbuild
빌드 → Rollup

5. 왜 Vite가 빠른가

5.1 번들링 시점 차이

Webpack

전체 번들 생성 → 서버 시작

Vite

서버 시작 → 요청된 모듈만 처리

초기 실행 속도 차이 발생

5.2 HMR (Hot Module Replacement)

HMR이란?

HMR은 페이지 전체를 새로고침하지 않고, 변경된 모듈만 교체하는 기능입니다.

5.3 Webpack vs Vite HMR 차이

Webpack

변경된 모듈이 전체 그래프에 미치는 영향 분석
리빌드 과정 발생 가능

Vite

변경된 모듈만 다시 요청
브라우저가 직접 교체

결과

Webpack → 상대적으로 느림
Vite → 거의 즉각 반영

6. 구조적 차이 한눈에 보기

항목	Webpack	Vite
개발 방식	번들 기반	ESM 기반
초기 실행	느림	매우 빠름
HMR	상대적으로 느림	매우 빠름
빌드	자체 번들링	Rollup 사용
구조	통합형	분리형

7. 언제 무엇을 선택해야 할까

Webpack이 적합한 경우

레거시 프로젝트
복잡한 설정 필요
기존 Webpack 환경 유지

Vite가 적합한 경우

신규 프로젝트
빠른 개발 환경 필요
최신 프론트엔드 스택

8. 정리

지금까지 Webpack과 Vite의 구조적 차이를 살펴봤습니다.

두 도구의 가장 큰 차이는 번들링을 언제 수행하느냐입니다.

Webpack은 개발 환경에서도 번들링을 수행하는 번들 중심 구조이고,
Vite는 개발 환경에서는 브라우저의 ES Module을 활용하는 ESM 중심 구조입니다.

이 구조적 차이가 개발 서버 속도, HMR 성능, 그리고 개발 경험에 큰 영향을 미칩니다.

결국 두 도구는 각각 다른 철학을 가지고 있습니다.

Webpack → 강력한 범용 번들러
Vite → 빠른 개발 경험 중심의 빌드 도구

프로젝트의 특성과 환경에 따라 적절한 도구를 선택하는 것이 중요합니다.

읽어주셔서 감사합니다.

번들러 동작 원리 이해하기

IT의 IT 블로그 — Sun, 15 Mar 2026 23:57:45 +0900

안녕하세요.
이번 글에서는 번들러가 내부에서 어떻게 동작하는지를 구조적으로 정리해보려고 합니다.

프론트엔드 프로젝트를 진행하다 보면 Webpack, Vite, Rollup 같은 번들러를 자연스럽게 사용하게 됩니다. 하지만 대부분은 “빌드 도구” 정도로만 이해하고 실제로 번들러가 내부에서 어떤 과정을 거치는지는 깊이 생각해보지 않는 경우가 많습니다.

번들러는 단순히 여러 파일을 하나로 합치는 도구가 아닙니다.
실제로는 다음과 같은 작업을 수행합니다.

모듈 간 의존성을 분석해 의존성 그래프(Dependency Graph) 를 생성하고
사용하지 않는 코드를 제거하는 트리쉐이킹(Tree Shaking) 을 수행하며
필요한 코드만 로딩할 수 있도록 코드 스플리팅(Code Splitting) 을 적용합니다.

이번 글에서는 번들러가 이 과정을 어떤 순서로 처리하는지를 중심으로 살펴보겠습니다.

1. 번들러는 무엇을 하는 도구일까

먼저 번들러의 역할을 간단히 정리해보겠습니다.

번들러는 여러 개의 모듈 파일을 분석하여 하나 또는 여러 개의 최적화된 결과물로 만들어주는 도구입니다.

예를 들어 프로젝트 구조가 다음과 같다고 가정해보겠습니다.

src
├─ main.js
├─ utils.js
├─ api.js
└─ components
└─ Button.js

각 파일은 서로 import로 연결되어 있습니다.

브라우저는 기본적으로 파일 단위로 네트워크 요청을 보내기 때문에, 모듈이 많아질수록 요청 횟수가 증가하게 됩니다.

이 문제를 해결하기 위해 번들러는

모든 모듈을 분석하고
하나의 구조로 묶고
최적화된 파일을 생성합니다.

이 과정의 핵심이 바로 의존성 그래프입니다.

2. 의존성 그래프 생성 과정

2.1 번들링은 엔트리 파일에서 시작된다

번들링은 항상 엔트리 파일(entry file) 에서 시작합니다.

예를 들어 다음과 같은 코드가 있다고 가정해보겠습니다.

import { add } from "./utils.js";
import Button from "./components/Button.js";

console.log(add(2, 3));

이 파일이 바로 번들링의 시작점이 됩니다.

번들러는 이 파일을 읽은 뒤 내부에서 다음 작업을 수행합니다.

import 문을 분석
어떤 파일을 참조하는지 확인
해당 파일을 다시 분석

2.2 import를 따라가며 그래프를 만든다

예를 들어 utils.js가 다음과 같다고 가정해보겠습니다.

export function add(a, b) {
return a + b;
}

그리고 Button.js가 다음과 같다고 해봅시다.

import { fetchData } from "../api.js";

이렇게 되면 번들러는 다음과 같은 구조를 파악합니다.

main.js
├─ utils.js
└─ Button.js
└─ api.js

이 구조가 바로 의존성 그래프(Dependency Graph) 입니다.

번들러는 이 그래프를 기반으로 전체 프로젝트 구조를 이해하게 됩니다.

3. 코드 분석 단계 (AST 분석)

번들러는 코드를 단순 문자열로 읽지 않습니다.

코드를 AST(Abstract Syntax Tree) 로 변환해 분석합니다.

예를 들어 다음 코드가 있다고 가정해보겠습니다.

import { add } from "./utils.js";

번들러는 이를 다음과 같은 구조로 파악합니다.

ImportDeclaration
├─ specifier: add
└─ source: "./utils.js"

이렇게 하면 다음과 같은 정보들을 정확하게 알 수 있습니다.

어떤 모듈을 import 하는지
어떤 export가 사용되는지
사용되지 않는 코드가 무엇인지

이 분석이 바로 트리쉐이킹의 기반이 됩니다.

4. 트리쉐이킹(Tree Shaking)

4.1 트리쉐이킹이란 무엇인가

트리쉐이킹은 사용하지 않는 코드를 제거하는 최적화 기법입니다.

예를 들어 다음 코드가 있다고 가정해보겠습니다.

export function add() {}
export function subtract() {}
export function multiply() {}

그리고 다른 파일에서 다음처럼 사용합니다.

import { add } from "./math.js";

이 경우 실제로 필요한 코드는 add 함수뿐입니다.

번들러는 이를 분석하여 다음처럼 최적화합니다.

math.js
└─ add()

subtract와 multiply는 번들에 포함되지 않습니다.

4.2 트리쉐이킹이 가능한 이유

트리쉐이킹은 ES Module 구조 덕분에 가능합니다.

import { add } from "./math.js";

이 문법은 정적으로 분석할 수 있기 때문에

어떤 함수가 사용되는지
어떤 export가 필요한지

빌드 시점에 정확하게 파악할 수 있습니다.

반면 CommonJS의 경우

const math = require("./math");

이 구조는 런타임에 결정되기 때문에
번들러가 어떤 코드가 필요한지 정확히 판단하기 어렵습니다.

5. 코드 스플리팅(Code Splitting)

5.1 왜 코드 스플리팅이 필요한가

모든 코드를 하나의 파일로 묶는 것이 항상 좋은 것은 아닙니다.

예를 들어 다음 기능이 있다고 가정해보겠습니다.

메인 페이지
관리자 페이지
통계 페이지

사용자는 대부분 메인 페이지만 먼저 접근합니다.

그렇다면 관리자 코드까지 함께 로딩할 필요는 없습니다.

5.2 동적 import

이 문제를 해결하는 방법이 동적 import입니다.

import("./admin.js").then(module => {
module.initAdmin();
});

이 코드는 admin.js를 필요한 순간에만 로딩합니다.

번들러는 이를 분석해 별도의 파일로 분리합니다.

예를 들어 결과물은 다음과 같이 생성될 수 있습니다.

dist
├─ main.js
├─ vendor.js
└─ admin.chunk.js

이렇게 하면 초기 로딩 속도가 크게 개선됩니다.

6. 최종 번들 생성

모든 분석이 끝나면 번들러는 최종 결과물을 생성합니다.

보통 다음과 같은 최적화가 적용됩니다.

코드 압축 (minify)
변수 이름 축소
불필요한 코드 제거
해시 기반 파일명 생성

예를 들어 결과물은 다음처럼 생성될 수 있습니다.

dist
├─ index.html
├─ app.34ab29.js
├─ vendor.82cd11.js
└─ style.91ac20.css

해시 파일명은 브라우저 캐시 관리를 위해 사용됩니다.

7. 정리

지금까지 번들러가 내부에서 어떤 과정을 거치는지 살펴보았습니다.

번들러는 단순히 여러 파일을 하나로 합치는 도구가 아니라,

엔트리 파일을 기준으로 모듈을 분석하고
import 관계를 따라 의존성 그래프(Dependency Graph) 를 생성하며
AST 분석을 통해 코드 구조를 이해하고
사용되지 않는 코드를 제거하는 트리쉐이킹(Tree Shaking) 을 수행하고
필요에 따라 코드 스플리팅(Code Splitting) 을 적용해
최종적으로 최적화된 번들을 만들어냅니다.

즉 번들러는 모듈을 분석하고 최적화하는 빌드 시스템이라고 볼 수 있습니다.

지금까지 번들러가 내부에서 어떻게 동작하는지 정리해봤습니다.

그렇다면 실제로 많이 사용되는 번들러들은
이 과정을 어떤 방식으로 처리하고 있을까요?

다음 글에서는 대표적인 번들러인 Webpack과 Vite의 구조적 차이와 설계철학을 비교해보겠습니다.

읽어주셔서 감사합니다.