현기의 개발블로그

[React] FSD 아키텍처란? 유지보수하기 좋은 프론트엔드 구조

현기 — Wed, 11 Mar 2026 23:40:11 +0900

들어가며

출처 : https://www.instagram.com/p/DR4F7zGiScJ/

어느 정도 프론트엔드 개발에 익숙해지다 보니, 신규 기능 개발은 이제 크게 어렵지 않습니다.

사실상 가장 힘든 일은 이해하기 어렵게 짜여진 코드의 맥락을 추적하고, 파편화되어 흩어져 있는 코드를 유지 보수하는 일입니다.

오늘은 이런 어려움을 해소할 수 있는 방법 중 하나인 Feature-Sliced Design (FSD) 아키텍처 방법론을 소개합니다.

보통 리액트 프로젝트의 폴더구조

우리에게 익숙한 간단하고 대중적인 폴더 구조입니다.

파일의 역할에 따라 폴더를 나눕니다. 계층형 구조 혹은 역할 기반 구조라고 부르기도 합니다.

소규모 앱에는 이런 구조로도 충분하지만, 프로젝트 규모가 커질수록 다소 불편한 점들이 보이기 시작합니다.

이 폴더 구조는 앱이 거대해졌을 때 어떤 고민이 생길 수 있을까요?

나노바나나 - 파일들의 의존성이 복잡하게 얽혀있어 머리아픈 이미지

바로 “컴포넌트가 소비되는 곳과 가까운 곳에 위치하지 않는다.” 입니다.

개발자는 컴포넌트 하나를 수정하기 위해 components, api, hooks 폴더를 이리저리 뒤적여야 합니다.

연관된 파일을 파악하기 어려운 구조는 개발자의 실수를 유발하고, 피로도를 높입니다.

✅ 짧은 팁
IDE의 전체 검색 Ctrl + Shift + F, 이 파일이 어디에서 사용중인지 확인하는 Find Usages를 사용하면
조금 더 편하게 폴더를 이리저리 뒤적일 수 있습니다.

React Colocation - 가까이 둡시다.

// 계층형 구조 : 흩어져있는 코드
src/
 ├── api/ (UserAPI, PostAPI, AuthAPI...)
 ├── components/ (UserCard, PostList, Button...)
 ├── hooks/ (useUser, usePost, useAuth...)
 └── types/ (user.d.ts, post.d.ts...)

// colocation : 자주 함께 변경되는 파일들을 같이 보관해보자
src/
 └── features/
      └── user/
           ├── UserProfile.tsx
           ├── useUser.ts      
           ├── user.api.ts
           ├── user.d.ts
           └── UserProfile.styles.css

React에서 Colocation은 “일반적으로 자주 함께 변경되는 것들을 같이 보관”하는 원칙을 말합니다.

단순히 로직, 파일을 가깝게 배치하는 것만으로도 가독성과 유지보수성이 향상됩니다.

하지만 프로젝트의 규모가 거대해지고, 수십 개의 컴포넌트가 서로 엉키기 시작하면 어떨까요?

단순히 '가깝게 두는 것'만으로는 해결되지 않는 순환 참조와 의존성 지옥이 기다리고 있습니다.

예를 들어, user 폴더의 컴포넌트에서 post 폴더를 참조해도 되는지 등의 규칙이 없기 때문입니다.

따라서 더 견고한 아키텍처를 위한 어떠한 규칙, 방법론이 필요하게 됩니다.

FSD(Feature-Sliced Design)란?

https://feature-sliced.design/kr/docs/get-started/overview

Overview | Feature-Sliced Design

Feature-Sliced Design (FSD) 는 프론트엔드 애플리케이션의 코드를 구조화하기 위한 아키텍처 방법론입니다.

feature-sliced.design

https://feature-sliced.design/docs/get-started/overview

FSD는 프론트엔드 애플리케이션의 코드를 구조화하기 위한 아키텍처 방법론입니다.

대규모 프로젝트에서 유지보수를 쉽게 만들기 위해 등장했습니다.

코드가 얼마나 많은 책임을 가지는지와 다른 모듈에 얼마나 의존하는지에 따라 계층화합니다.

1. 레이어 (Layer)

https://feature-sliced.design/kr/docs/reference/layers

레이어는 FSD에서 코드를 나눌 때 사용하는 가장 큰 구분 단위입니다.

핵심은 “상위 레이어는 하위 레이어만 참조할 수 있다”는 단방향 의존성 규칙입니다.

위 레이어는 아래 레이어를 사용할 수 있지만, 반대는 불가능합니다.

(리액트도 그렇고 프론트엔드 생태계는 단방향을 참 좋아하는 것 같아요.)

6개의 주요 레이어 요약

레이어	설명	예시
App	애플리케이션의 설정, 전역 스타일, 프로바이더(Provider) 등	AppProvider, GlobalStyles, main.tsx
Pages	사용자에게 보여지는 개별 페이지 단위로 실제 콘텐츠를 조립하는 곳	HomePage, ProductDetailPage, LoginPage
Widgets	독립적인 UI 블록으로 여러 페이지에서 재사용되는 대규모 기능 또는 UI	Header, Sidebar, Footer
Features	사용자의 행동(Action)과 관련된 비즈니스 가치를 제공	LoginByEmail, AddToCart, SearchProducts
Entities	비즈니스 실체(객체)를 나타냅니다. 데이터 모델, 상태, API 요청이 포함됩니다.	User, Product, Order, Comment
Shared	프로젝트 전반에서 재사용되는 인프라성 코드와 공통 UI 컴포넌트입니다.	Button, Input, APIClient, DateUtils

2. Slice - 비즈니스 도메인에 따른 최소 단위의 구분

슬라이스는 FSD 아키텍처의 2번째 계층입니다. 레이어 내 코드를 비즈니스 도메인별로 나눕니다.

슬라이스의 이름은 비즈니스 도메인에 맞게 자유롭게 정할 수 있습니다.

핵심 규칙은 "슬라이스끼리는 서로를 알 수 없다." 입니다.

예를 들어, features/auth 슬라이스는 같은 레이어에 있는 features/cart 슬라이스를 참조할 수 없습니다.

(import 못한다는 소리입니다.)

왜 서로 참조하지 못하게 하나요?

파일들을 비즈니스 맥락에 따라 한곳에 모음으로써 높은 응집도를 확보하고, 슬라이스 간의 의존성을 끊어 낮은 결합도를 유지하기 위해서입니다. 덕분에 프로젝트가 거대해져도 특정 기능을 수정할 때 발생하는 사이드 이펙트를 최소화하고 코드 베이스를 훨씬 쉽게 탐색할 수 있습니다.

3. Segment - 파일의 역할에 따른 최종 분류

세그먼트는 FSD 아키텍쳐의 3번째 계층입니다.

슬라이스가 하나의 비즈니스 도메인으로 분류된다면,

세그먼트는 슬라이스의 비즈니스 덩어리를 기술적인 역할에 따라 다시 한번 분리합니다.

이름은 자유롭게 정할 수 있지만 보통 아래와 같은 이름을 사용합니다.

user
 ├ ui     // 화면에 보여지는 모든 것(컴포넌트, 스타일)
 ├ api    // 서버와의 통신
 ├ model  // 데이터 핵심 로직 (인터페이스, 상태 관리/Store)
 ├ lib    // 이 슬라이스에서만 사용하는 보조 도구 (라이브러리, 유틸)
 └ config // 설정 값

모든 레이어에서 세그먼트가 꼭 같아야할까?

반드시 그렇지 않습니다. 대부분의 경우 위의 세그먼트만으로 충분합니다.

하지만, 공유(shared) 레이어나 앱(app) 레이어에서는 필요에 따라 새로운 세그먼트를 만들어도 됩니다. (강제된 규칙이 아닙니다.)

즉, 기본 구조는 유지하되, 필요하면 유연하게 확장할 수 있습니다.

+ FSD 전체 폴더 구조 예시

src
│
├ app
│  ├ providers
│  ├ router
│  ├ styles
│  └ index.tsx
│
├ pages
│  ├ home
│  │  ├ ui
│  │  │  └ HomePage.tsx
│  │  └ index.ts
│  │
│  └ profile
│     ├ ui
│     │  └ ProfilePage.tsx
│     └ index.ts
│
├ widgets
│  ├ header
│  │  ├ ui
│  │  │  └ Header.tsx
│  │  └ index.ts
│  │
│  └ sidebar
│     ├ ui
│     │  └ Sidebar.tsx
│     └ index.ts
│
├ features
│  ├ login
│  │  ├ ui
│  │  │  └ LoginForm.tsx
│  │  ├ model
│  │  │  └ useLogin.ts
│  │  ├ api
│  │  │  └ loginApi.ts
│  │  └ index.ts
│  │
│  └ add-to-cart
│     ├ ui
│     │  └ AddToCartButton.tsx
│     ├ model
│     │  └ cartStore.ts
│     ├ api
│     │  └ addCartApi.ts
│     └ index.ts
│
├ entities
│  ├ user
│  │  ├ ui
│  │  │  └ UserAvatar.tsx
│  │  ├ model
│  │  │  └ userStore.ts
│  │  ├ api
│  │  │  └ userApi.ts
│  │  └ index.ts
│  │
│  └ product
│     ├ ui
│     │  └ ProductCard.tsx
│     ├ model
│     │  └ productTypes.ts
│     ├ api
│     │  └ productApi.ts
│     └ index.ts
│
├ shared
│  ├ ui
│  │  ├ Button
│  │  │  └ Button.tsx
│  │  └ Input
│  │     └ Input.tsx
│  │
│  ├ lib
│  │  └ formatDate.ts
│  │
│  ├ api
│  │  └ baseApi.ts
│  │
│  └ config
│     └ env.ts
│
└ main.tsx

FSD의 장점과 단점

장점

1. 프로젝트 구조가 통일됩니다.

모든 기능이 같은 구조를 사용하기 때문에 코드가 훨씬 일관성 있게 정리됩니다.

새로운 개발자가 프로젝트에 투입되어도 어디에 코드가 있고, 어디를 수정해야 하는지 빠르게 이해할 수 있습니다.

2. 변경과 리펙토링이 쉬워집니다.

위에서 설명한 FSD의 계층별 규칙(레이어, 슬라이스)을 통해 한 기능을 수정해도 다른 기능에 영향을 줄 가능성이 줄어듭니다.

3. 유지 보수성이 향상됩니다.

어떤 코드는 여러 곳에서 재사용해야 하고, 어떤 코드는 특정 기능에서만 사용해야 합니다.

FSD 아키텍쳐를 사용하면 공유 코드는 shared, 특정 기능 코드는 feature처럼 재사용 범위를 자연스럽게 나눌 수 있습니다.

4. 비즈니스 중심 구조가 됩니다.

폴더 이름을 비즈니스 용어로 만들기 때문에 실제 서비스 개념과 코드 구조가 맞춰집니다.

개발자는 프로젝트 전체를 완벽하게 이해하지 않아도 자신이 맡은 기능을 개발할 수 있게 됩니다.

즉, 신규 입사자의 온보딩 속도가 빨라지겠죠 !

단점

1. 초기 구조가 복잡하다.

레이어, 슬라이스, 세그먼트로 분리하기 때문에 폴더 구조가 꽤 많아집니다.

따라서 작은 프로젝트에는 오히려 오버 엔지니어링이 될 수 있습니다.

이런 경우에는 공식 문서에서 소개하는 점진적 도입을 참고하세요.

2. 러닝 커브

FSD는 일반적인 React 폴더 구조와 다르고, 각 계층의 규칙이 존재하기 때문에 처음 접하는 개발자에게는 이해하기 어려울 수 있습니다.

3. 규칙이 중요하다.

FSD는 정해진 규칙도 있고, 유연하게 팀에서 만든 규칙을 적용할 수도 있습니다.

하지만 규칙을 잘 정하고 잘 지키지 않으면 FSD의 구조가 망가지게 됩니다.

(같은 팀에서 같은 컨벤션도 지키기 힘든데 잘 지켜지는 회사의 모습이 궁금하네요 )

참고 문헌:

https://feature-sliced.design/kr/docs/get-started/overview

https://tech.kakaopay.com/post/fsd/

[Next.js] AI 에이전트가 Vercel 엔지니어처럼 코드 리뷰를 해준다면? (프론트엔드 성능 최적화 가이드, react-best-practices)

현기 — Thu, 29 Jan 2026 17:37:32 +0900

들어가며

클로드 코드를 처음 사용하고 3달이 지난 2026년 현재, 개발하는 방식이 또 완전히 달라졌습니다.

챗GPT에게 질문하고 답변을 받아 직접 코딩하던 ‘AI 어시스턴트’ 방식에서

커서나 클로드 코드 같이 스스로 판단하고 행동하며 작업을 자율적으로 수행하는 ‘AI 에이전트 방식’으로 발전했습니다.

많은 기업과 개발자들이 AI 에이전트에 관심을 갖고, 실제 업무에 적극적으로 도입하고 있습니다.

실제로 AI를 잘 다루는 개발자와 그렇지 않은 개발자의 생산성 차이는 매우 큽니다.

저는 앞으로 “코딩을 얼마나 잘하는가?”보다, “AI 에이전트를 얼마나 더 잘 다루고 활용할 수 있는가?”가

중요한 핵심 역량이 될 것이라고 생각합니다.

최근 Vercel에서 React/Next.js 개발 10년의 노하우가 담긴 react-best-practices를 공개했습니다.

뭐 특별한 프로그램이 아니라 실제 코드 사례가 담긴 마크다운 문서입니다.

그냥 읽어도 큰 도움이 되지만, 클로드 코드 같은 AI 에이전트에게 Skill로 주입해서 사용하면

프론트엔드 레전드 시니어 개발자에게 코드 리뷰를 무한대로 요청할 수 있게 됩니다. (물론 토큰 내에서요)

함께 알아봅시다.

프론트엔드의 성능 최적화에 대해서

출처: https://imgflip.com/i/6ck6k5

‘성능 최적화’는 프론트엔드 개발자에게 있어 아마도 골치 아픈 주제입니다.

앱이 느린데 왜 느린지 모르겠고 성능 개선을 위해 코드 스플리팅, 이미지 & 폰트 최적화, memo와 useCallback 등 다양한 방법을 동원해봅니다.

하지만 정작 들인 노력에 비해 웹 바이탈 점수는 크게 좋아지지 않는 경우도 많습니다.

결국 밀려오는 다음 일감을 처리하기 위해 성능 개선은 뒤로 미룹니다.

바로 이런 골치아픈 ‘성능 최적화’ 문제를 AI 에이전트와 함께 검토하고 빠르게 개선해볼 수 있습니다.

React Best Practices

https://vercel.com/blog/introducing-react-best-practices

Introducing: React Best Practices - Vercel

We've encapsulated 10+ years of React and Next.js optimization knowledge into react-best-practices, a structured repository optimized for AI agents and LLMs.

vercel.com

React의 성능 최적화 작업은 대개 사후 대응적입니다.
앱이 출시되고 나면 앱 속도가 느려진 것처럼 느껴지고 그제서야 팀은 원인을 찾기 시작합니다.
우리는 10년 넘게 운영 중인 코드베이스 전반에서 동일한 근본 원인을 목격해 왔습니다.
-Vercel

핵심 아이디어: 순서 정하기

대부분의 성능 개선 작업은 너무 낮은 단계에서 시작하기 때문에 실패합니다.

요청 워터폴 때문에 대기 시간이 600ms 증가한다면, 최적화가 아무리 잘 되어 있어도 소용 없습니다.

따라서 최적화 우선순위에 따라서 높은 단계에서 아래 단계로 순서로 진행해야 합니다.

1. 워터폴을 제거합니다.
2. 번들 크기를 줄입니다.
...
~ 8.

주요 카테고리 및 최적화 우선순위

우선순위	카테고리 (Category)	영향도 (Impact)	접두사 (Prefix)	번역 및 설명
1	Eliminating Waterfalls	CRITICAL (치명적)	async-	워터폴(연쇄 지연) 제거: 데이터 요청이 꼬리에 꼬리를 물고 늦어지는 현상 방지
2	Bundle Size Optimization	CRITICAL (치명적)	bundle-	번들 크기 최적화: 자바스크립트 파일 용량을 줄여 초기 로딩 속도 개선
3	Server-Side Performance	HIGH (높음)	server-	서버 사이드 성능: SSR이나 API 응답 등 서버 측 처리 효율화
4	Client-Side Data Fetching	MEDIUM-HIGH (중상)	client-	클라이언트 데이터 페칭: 브라우저에서 데이터를 가져오는 방식 최적화
5	Re-render Optimization	MEDIUM (보통)	rerender-	리렌더링 최적화: 불필요한 컴포넌트 재그리기를 방지하여 반응성 향상
6	Rendering Performance	MEDIUM (보통)	rendering-	렌더링 성능: 브라우저가 화면을 그리는 과정(Layout/Paint)의 효율성
7	JavaScript Performance	LOW-MEDIUM (중하)	js-	자바스크립트 성능: 순수 로직 및 알고리즘 실행 속도 개선
8	Advanced Patterns	LOW (낮음)	advanced-	고급 패턴: 코드의 구조나 확장성을 위한 심화 설계 방식

성능 개선의 영향도에 따라 CRITICAL 단계부터 LOW 단계까지 8개 카테고리로 분류됩니다.

현재 8개의 카테고리 속에 57개의 규칙이 존재합니다.

react-best-practices/rules/async-api-routes.md

각 항목별 자세한 내용은 깃허브 레포에 있는 마크다운 문서를 직접 읽어보는 것을 추천합니다.

클로드 스킬(Claude Skills)로 사용하기

설치 방법

# 설치
npx add-skill vercel-labs/agent-skills

명령어 입력 시 4가지 스킬 선택 화면이 나옵니다.

1. vercel-composition-patterns : 컴포넌트 간의 의존성 복잡도를 깔끔하게 정리하는 방법을 제공합니다.
2. vercel-react-best-practices : 리액트 최적의 실무 관행
3. vercel-react-native-skills : 리액트 네이티브(앱)을 위한 기술 모음
4. web-design-guidelines : UI/UX를 만드는 기준

저희는 2번을 선택할 거지만, 다른 스킬들도 굉장히 매력적이네요. 다음에 기회가 된다면 사용해 보고 포스팅하겠습니다.

/skills

폴더에 저장 됨

설치가 완료되면 /skills 명령어를 통해 클로드 스킬을 확인할 수 있습니다.

물론 컴퓨터에 마크다운 파일이 설치된 것이기 때문에, 폴더에서도 확인 가능합니다.

코드 리뷰 요청하기

(컴포넌트 태그) vercel-react-best-practices 코드 리뷰

이렇게 명시적으로 스킬 이름을 적어주면 클로드 코드가 SKILL.md 상단의 YAML 프론트 메터를 참조하여 계획을 세우고 작업을 실행합니다.

* YAML 프론트 메터 예시
---
name: my-skill
description: 이 기술이 하는 것
disable-model-invocation: true
allowed-tools: Read, Grep
---

코드 리뷰 결과 확인하기

위에서 언급한 성능 최적화 우선순위에 따라 솔루션을 제안합니다.

클로드 코드가 Vercel 시니어 엔지니어로 거듭난 순간입니다.

❯ 1번 2번 적용하고, 전후 측정 결과 얼마나 개선되었는지 알려줘

하나의 컴포넌트만 태그해서 테스트한 건데, 번들 크기를 14.8%나 개선할 수 있었습니다.

무엇을, 어떻게, 왜 수정했는지 추가적으로 질문하면 더 좋습니다.

참고로 결과 측정은 약 13분이 걸렸는데, 토큰도 아깝고 CLI나 툴을 따로 사용해 직접 측정하는 것이 좋아 보입니다.

이제 시니어 개발자의 코드 리뷰를 눈치 보지 않고 토큰이 허용하는 내에서 무한대로 받아볼 수 있게 되었습니다 !

마치며

MCP부터 클로드 스킬까지 요즘 LLM을 더 다양하게, 더 잘 활용하는 방법이 굉장히 빠르게 나오고 있습니다.

불과 1~2년 사이에 AI의 발전 속도가 정말 말이 안 되는데요

저는 개인적으로 밥그릇 뺏길까 봐 걱정인 건 당연히 있지만, (이미 뺏긴 것 같습니다.)

한편으로는 기술의 경계가 사라지고 아이디어만 있어도 러닝 커브 없이 빠르게 뭔가를 만들 수 있다는 게

설렘으로 다가오는 것 같습니다.

여러분은 어떠신가요?!

참고 문헌:

https://vercel.com/blog/introducing-react-best-practices

[FE] Next.js 로컬 개발환경에서 HTTPS 적용하기 (mkcert, 서브도메인 쿠키 공유)

현기 — Wed, 28 Jan 2026 23:23:09 +0900

출처: https://www.descope.com/learn/post/enterprise-sso

1. 문제 상황

로컬 개발 환경에서 SSO(Single Sign-On) 로직을 구현하고 있었습니다.

여러 서비스가 동일한 서브도메인 형태로 분리된 구조고, 인증은 하나의 인증 서버에서 담당합니다.

흐름

(A 사이트) 로그인 -> (B 사이트 SSO 담당) 로그인 페이지 -> 로그인 및 쿠키 저장 -> (A 사이트) 쿠키 기반 인증 처리

개발 환경

프론트엔드: HTTP (로컬)
인증 서버: HTTPS
인증 쿠키 옵션:
Secure=true SameSite=None
서브도메인 기반 SSO 구조

문제 현상

로그인은 성공
쿠키는 저장된 것처럼 보임
다른 서브도메인에서는 쿠키가 전달되지 않음
결과적으로 SSO 실패

문제의 원인은 쿠키의 Secure 옵션입니다.

브라우저 보안 정책상 이 옵션이 설정된 쿠키는 HTTPS에서만 동작하며,

HTTP 사이트가 HTTPS 사이트의 쿠키를 읽거나 공유하는 것을 차단합니다.

2. mkcert로 로컬 HTTPS 환경 구성

mkcert란?

mkcert는 복잡한 설정 없이 로컬 개발용으로 SSL 인증서를 만들어주는 간단한 도구입니다.

로컬 CA 생성 및 OS에 등록
운영 환경과 거의 동일한 HTTPS 조건 구성 가능

설치하기

# 1. 터미널 명령어 실행 (Mac 기준)
brew install mkcert                                                                                                                                                                                                              
mkcert -install                                                                                                                                                                                                                  

# 2. React/Next 프로젝트 루트에 인증서 생성
cd /Users/hyunki/Desktop/project/my-proj
mkcert "*.example.io"

로컬 호스트를 특정한 도메인으로 변경하는 방법 (선택)

서브도메인 기반 쿠키 공유를 하려면, 도메인이 있어야겠죠? 로컬 호스트에서도 가능합니다.

아래와 같이 host를 추가해 주면 내부적으로는 로컬 호스트지만 도메인을 사용할 수 있습니다.

sudo nano /etc/hosts

* 추가
127.0.0.1 auth.example.com

* 종료
!wq

package.json 스크립트 수정해서 실행하기

{
  "scripts": {
    // 기존 스크립트 예시
    "dev:auth": "next dev --turbopack --hostname auth.example.com --port 3000",
    
    // HTTPS 실행 스크립트
    "dev:auth:https": "next dev --turbopack --hostname auth.example.com --port 3000 --experimental-https --experimental-https-key ./_wildcard.example.com-key.pem --experimental-https-cert ./_wildcard.example.com.pem"
  }
}

스크립트를 추가해서 프로젝트를 실행하면 간편합니다.

Next.js 실행 스크립트 속성 설명

속성	설명
--experimental-https	Next.js에게 "이제 HTTP가 아니라 HTTPS 프로토콜로 서버를 열어줘"라고 명령하는 핵심 스위치입니다.
--experimental-https-key	mkcert로 생성한 파일 중 개인키(-key.pem) 파일의 경로를 지정합니다. 서버가 데이터를 암호화할 때 사용합니다.
--experimental-https-cert	mkcert로 생성한 인증서(.pem) 파일의 경로를 지정합니다. 브라우저에게 "이 서버는 신뢰할 수 있어"라고 증명하는 신분증 역할을 합니다.

3. 결과

HTTPS로 실행된 로컬호스트

로컬 호스트가 HTTPS로 실행 가능하게 되었고,

쿠키의 Secure 옵션 때문에 서브도메인간 쿠키 공유가 되지 않던 이슈도 해결되었습니다.

4. 주의 사항

- mkcert는 로컬 개발용입니다 !

- rootCA-key.pem이 유출되지 않도록 조심하세요 !

+ 약간의 소개

원래 제가 포스팅하던 형식은 머릿글에 중앙 정렬하고 조금 이쁘장하게 전달하려는 의도가 있었는데,

트러블슈팅이나 오늘처럼 간단한 포스팅은 요런 간결한 velog 스타일로 작성해보려고 합니다

[AI] Vercel v0을 활용한 10분만에 개발자 포트폴리오 만들기

현기 — Tue, 23 Dec 2025 23:00:56 +0900

Vercel의 v0으로 개발된 포트폴리오 사이트

안녕하세요

오늘은 프론트엔드 생태계를 이끌고 있는 Vercel에서

출시한 흥미로운 서비스인 v0에 대해서 소개해드리려고 합니다.

v0는 우리가 잘 아는 ChatGPT나 제미나이처럼 프롬프트를 입력하면,

그 결과물로 즉시 사용 가능한 UI 컴포넌트 코드를 생성해 주는 도구입니다.

살짝 찍어먹어 본 후기를 공유하고자 합니다.

함께 알아봅시다.

v0이란?

https://v0.app/docs/introduction

What is v0? | v0 Docs

v0 is an AI-powered development platform that turns ideas into production-ready, full-stack web apps.

v0.app

⦁개요

v0은 아이디어를 실제 사용 가능한 풀스택 웹 애플리케이션으로 구현해 주는 AI 기반 플랫폼입니다.

프롬프트를 통해 원하는 것을 설명하면 지능형 에이전트가 구현해 줍니다. (딸깍)

Next.js를 만든 Vercel에서 개발했기 때문에 구현 결과물은 React/Next.js + Shadcn + Tailwind CSS입니다.

요즘 가장 트렌디한 조합이죠?

⦁ 특징 1. 자연어 기반 이미지 생성

텍스트 설명뿐만 아니라, 스케치나 스크린샷을 통해서도 코드로 변환할 수 있습니다.

⦁ 특징 2. 반복 수정 및 버전 관리

결과물이 마음에 들지 않으면 질문 반복을 통해 실시간으로 수정할 수 있습니다.

이 수정사항은 버전이 기록되어 쉽게 롤백이 가능합니다.

⦁ 특징 3. 깃허브 연동 !

깃허브 계정을 연동하고 권한을 주면, 새 레포를 생성하고 push하는 등의 작업도 수행해 줍니다.

이게 굉장히 편리했습니다.

⦁ 가격 정보

v0 가격 정보

처음에 출시했을 때는 대기 명단을 등록하고 기다려야 했지만,

현재는 하루 7개의 메시지를 무료로 사용할 수 있습니다.

아직 많이 사용해 보지는 않았지만 저는 20달러라면 클로드 코드를 결제할 것 같긴 합니다.

우선 무료 플랜으로 체험해 보시는 것을 추천드립니다.

개발자 포트폴리오 만들기

https://v0.app/templates

v0 Templates - v0 by Vercel

Your collaborative AI assistant to design, iterate, and scale full-stack applications for the web.

v0.app

우선 채팅으로 직접 만들기 전에, Templates 탭을 한번 둘러 보시는 것을 추천드립니다.

다른 사용자가 만들어 둔 멋있는 예제들을 볼 수 있어요. ☺️

⦁질문 릴레이

여기서는 질문을 막 던졌지만, 제미나이나 GPT에게 프롬프트 생성을 요청하면 더 효율적입니다.

# 프롬프트
v0에 입력할 프롬프트 생성해줘
요구사항 
1. ~~
2. ~~
3. ~~

⦁ 각 질문 버전 확인 방법

우측 상단 Latest 클릭 시 이전 버전 변경 가능

손 쉽게 이전 채팅의 코드로 돌아갈 수 있어서 UX가 참 좋았습니다.

⦁ 결과물 템플릿 !

https://v0.app/templates/aSh4U6MpBRp

v0 - Developer portfolio - v0 by Vercel

A modern developer portfolio featuring a glassmorphism design with soft blur effects.

v0.app

결과물은 v0에 템플릿으로 공개했습니다.

어디서 많이 보던 디자인 같기는 하지만

이 정도면 제 눈에는 굉장히 예뻐 보입니다.

( v0 사용 10분 포스팅 2시간 )

참고 문헌 :

https://v0.app/docs/introduction

[AI] 클로드 코드 직접 사용해보기 (CLAUDE.md, 자주 쓰이는 명령어, 프롬프트)

현기 — Mon, 17 Nov 2025 21:30:44 +0900

https://hyunki99.tistory.com/131

[AI] 클로드 코드 설치 방법 + 가격 정보 (feat. 인텔리제이에서 실행하기)

요즘 생성형 AI를 활용한 바이브 코딩이 뜨거운 주제인 것 같습니다. 저는 시간이 날 때마다 IT 칼럼을 즐겨보는데,클로드 코드에 대해서 아주 많은 칼럼들이 보입니다. 운이 좋게도 회사에서 클

hyunki99.tistory.com

지난 글에서 클로드 코드를 설치하고 IDE에 통합까지 완료했습니다.

이제 직접 사용해봐야겠죠?

어디에 먼저 사용해볼까 고민하다가

예전에 만들어두고 방치한 제 개인 보일러플레이트 프로젝트인

nextjs-shadcn-boilerplate에 적용해보기로 했습니다.

클로드 코드 사용하는 방법 함께 알아봅시다.

프로젝트 정보 저장하기 (CLAUDE.md 생성)

⦁CLAUDE.md 파일이란?

클로드 코드는 마크다운 파일에 AI와 협업하기 위한 문서를 작성할 수 있습니다.

이곳에 프로젝트 정보, 기술 스택 버전, 코딩 컨벤션 등의 정보를 작성하면 클로드 코드가 이를 참고한 답변을 생성해 줍니다.

간단하게 /init 명령어를 통해 생성하고 필요한 부분을 수정해 보세요.

프롬프트를 통해서도 생성 및 수정이 가능합니다.

이 문서 그 자체로도 프로젝트를 설명할 수 있는 좋은 문서가 되기도 합니다.

프롬프트 예시) 프로젝트 분석해서 CLAUDE.md 생성. package.json 및 주요 컴포넌트 참고해서 기술 스택, 프로젝트 구조 포함

⦁ CLAUDE.md 잘 작성하는 방법

1. 기술 스택 및 버전 명시

클로드는 프로젝트의 코드를 탐색하는 과정을 통해 라이브러리의 버전을 추론합니다.

이대로도 크게 문제는 발생하지 않지만, 추론이 틀렸을 경우 LTS 버전으로 코드를 작성해 주기 때문에

문제가 발생할 수 있습니다.

특히나 라이브러리 버전에 민감한 프론트엔드 생태계에서는 기술 스택의 버전을 명시하는 것이 좋겠죠?

* Claude Code의 버전 처리 방식
CLAUDE.md 파일에는 프로젝트의 도구와 버전을 선언해야 합니다. (예: Tailwind CSS 4.1)
이를 통해 Claude Code가 프로젝트 컨텍스트를 이해합니다

* 버전이 명시되지 않았을 경우에는?
다음과 같은 순서로 판단합니다.
1. package.json / requirements.txt 등 확인 프로젝트의 의존성 파일을 먼저 읽음 실제 설치된 버전 확인

2. 코드 패턴 분석 코드 작성 스타일로 버전 추론 예: async/await 사용 → 최신 Node.js

3. 최신 안정 버전 가정 명시가 없으면 일반적으로 최신 LTS 버전 사용 -> ⚠️ 위험성 존재

- 클로드 코드 product-self-knowledge/SKILL.md

예시)

## Tech Stack
Next.js ^15.4.7 with App Router
React ^19.1.0
TypeScript ^5
Tailwind CSS ^4.1.4
shadcn/ui with Radix UI primitives
next-themes ^0.4.4 for dark mode
lucide-react ^0.477.0 for icons
ESLint ^8 + Prettier ^3.5.2

2. 프로젝트 아키텍쳐, 폴더 구조 명시

CLAUDE.md -> 폴더 구조

폴더 구조를 명시해 놓았더니, 컴포넌트를 생성할 때 규칙에 맞는 폴더로 파일이 생성되었습니다.

이거 보고 깜짝 놀랐습니다.

이 외에도 많은 내용이 있지만 직접 만들어보고 점점 개선해 나가는 방법을 추천드립니다.

여러분의 방법도 공유해 주세요 !

⦁ CLAUDE.md 전체 예제

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Next.js 15+ boilerplate with Tailwind CSS v4.1 and shadcn/ui components. It uses TypeScript and includes a pre-configured setup with dark mode support using next-themes.

## Tech Stack

- **Next.js** ^15.4.7 with App Router
- **React** ^19.1.0
- **TypeScript** ^5
- **Tailwind CSS** ^4.1.4
- **shadcn/ui** with Radix UI primitives
- **next-themes** ^0.4.4 for dark mode
- **lucide-react** ^0.477.0 for icons
- **ESLint** ^8 + **Prettier** ^3.5.2

## Development Commands

### Development

```bash
yarn dev        # Start development server
yarn build      # Build production bundle
yarn start      # Start production server
yarn lint       # Run ESLint
yarn prettier   # Check code formatting with Prettier
```

## Architecture

### Directory Structure

- **`src/app/`** - Next.js App Router pages and layouts
  - **`(Main)/`** - Route group with MainLayout wrapper
  - Uses route groups for shared layouts without affecting URL structure
- **`src/components/`** - React components organized by category
  - **`ui/`** - shadcn/ui components (button, dropdown-menu, etc.)
  - **`layouts/`** - Layout components (Header, Footer, MainLayout)
  - **`theme/`** - Theme-related components (ThemeProvider, ModeToggle)
  - **`common/`** - Common/shared components
- **`src/constants/`** - Application constants including routes
- **`src/lib/`** - Utility functions (includes `cn()` for Tailwind class merging)
- **`src/hooks/`** - Custom React hooks
- **`src/css/`** - Global styles and Tailwind configuration
- **`src/api/`** - API-related code

### Path Aliases

TypeScript paths are configured with `@/*` pointing to `src/*`:

```typescript
import { cn } from '@/lib/utils';
import { Header } from '@/components/layouts/Header';
```

### Layout System

The app uses a nested layout structure:

1. **Root Layout** (`src/app/layout.tsx`) - Wraps everything with ThemeProvider
2. **Main Layout** (`src/app/(Main)/layout.tsx`) - Applies MainLayout component to pages in the (Main) route group
3. **MainLayout Component** (`src/components/layouts/MainLayout.tsx`) - Contains Header, main content area, and Footer with predefined spacing

### Theming

- Uses **next-themes** with class-based dark mode (`attribute="class"`)
- Theme toggles between light/dark/system modes
- Custom color tokens defined in `src/css/globals.css` using OKLCH color space
- CSS variables for layout dimensions:
  - `--header-height: 64px`
  - `--container-max-width: 1200px`
  - `--container-px: 16px`

### Styling Approach

- **Tailwind CSS v4.1** with native CSS imports (`@import 'tailwindcss'`)
- Uses Pretendard font loaded from CDN
- `cn()` utility function combines clsx and tailwind-merge for conditional classes
- Prettier with `prettier-plugin-tailwindcss` automatically sorts Tailwind classes

### shadcn/ui Configuration

The project uses shadcn/ui with the following config (from `components.json`):

- **Style**: default
- **Base color**: zinc
- **CSS Variables**: enabled
- **Icon library**: lucide-react
- **RSC**: enabled (React Server Components)

To add new shadcn/ui components, the config expects:

- Components in `@/components` (mapped to `src/components/`)
- UI components in `@/components/ui`
- Utils in `@/lib/utils`

### Code Style

ESLint and Prettier are configured:

- Extends `next/core-web-vitals` and `prettier`
- Single quotes, semicolons, 2-space indentation
- Trailing commas for ES5
- 80 character line width

### Navigation

Navigation routes are centralized in `src/constants/routes.ts` as `NAV_LIST` array with `name` and `href` properties.

명령어 & 프롬프트

https://docs.claude.com/en/resources/prompt-library/library

Prompt Library - Claude Docs

Responses are generated using AI and may contain mistakes.

docs.claude.com

공식 문서에도 참고할 수 있는 다양한 프롬프트 예시를 제공합니다.

게임 만들기같이 재밌는 것도 있더라고요. 한번쯤 둘러보시는 것을 추천드립니다.

⦁자주 쓰이는 명령어

/clear	대화 기록을 컨텍스트 윈도우에서 제거
/explain	선택한 코드의 동작을 자세히 설명
/edit	선택한 코드 블록을 특정 요구사항에 맞게 수정
/test	유닛 테스트 코드 자동 생성
/refactor	가독성/성능 개선을 위한 코드 리팩토링 제안
/comment	코드에 주석 자동 추가
/doc	함수/컴포넌트 문서화
/commit	커밋 메시지를 생성하거나 변경 요약 작성
/review	현재 변경된 코드 리뷰
/run	현재 실행 가능한 명령어나 스크립트 실행 요청

이건 작은 팁인데, 토큰 사용량을 줄이기 위해서는 /clear를 주기적으로 실행해야 합니다.

새로운 작업을 시작할 경우 한 번씩 컨텍스트를 초기화 해주세요!

컨텍스트가 많이 쌓이면 질문 한번에 사용량 20%씩도 소모하더라고요

⦁자주 쓰이는 프롬프트 예시

코드 설명 요청
이 코드가 어떤 역할을 하는지 간단히 설명

코드 리팩토링
이 코드의 중복을 줄이고, 더 모듈화된 형태로 리팩토링

테스트 생성
이 함수에 대한 Jest 테스트 코드 생성

문서화
이 React 컴포넌트에 대한 JSDoc 주석 생성

성능 개선
이 코드의 렌더링 최적화를 위한 개선 방안 제안

새로운 기능 추가
이 컴포넌트에 검색 필터 기능을 추가

리뷰 요청
이 변경사항에 대한 코드 리뷰

❗️프롬프트가 길어질 수록 사용하는 토큰이 늘어날 수 있으니, 간결하고 명확하게 프롬프팅하는 것을 추천드립니다.

실제 사용기

깃허브링크

GitHub - HongHyunKi/nextjs-shadcn-boilerplate

Contribute to HongHyunKi/nextjs-shadcn-boilerplate development by creating an account on GitHub.

github.com

프롬프트 : 이 프로젝트는 보일러 플레이트 프로젝트야. 개선점을 찾고 모던하게 코드 변경

클로드 코드의 작업 리뷰

✅ 프롬프트 한줄에 엄청난 양의 작업을 해냈습니다. 헐랭

프롬프트 : Next.js + tailwind + shadcn 보일러 플레이트에 맞는 메인페이지 꾸며서 만들어줘 완벽한 반응형으로 세련되게

✅ 프로젝트 세팅은 되었으니, 샘플 페이지를 부탁해 보았습니다.

next.js 공식 문서 같은 디자인의 UI가 뚝딱 완성되었습니다.

결과는 여기에서 확인하실 수 있습니다.

패딩 값 같은 디테일한 조정은 잘 못 하더라고요.

약 10번의 질문 이후 사용량

30분 정도 사용했고, 프로젝트 전체에 걸친 코드 수정이 몇번 발생해서, Pro 플랜 사용량의 약 30%를 사용했습니다.

그래도 5시간마다 세션이 초기화 돼서 아직까지 엄청 부족하다는 느낌은 못받았습니다.

사용 후기

최근까지는 적절히 코드 조각을 잘라 붙여

ChatGPT에게 질문하는 방식으로 AI를 사용해왔습니다.

클로드 코드는 코드 조각을 직접 입력할 필요 없이

프로젝트 전체를 컨텍스트로 사용할 수 있고,

심지어 직접 파일까지 제어 할 수 있기 때문에

더욱 강력한 생산성을 체감했습니다.

현재 회사에서는 두가지 방법을 적절히 섞어가며

업무에 AI를 사용하고 있습니다.

이제는 확실히 AI 없이 개발하던 시절로는

점점 더 돌아가기 힘들어 질 것 같습니다.

이길 수 없다면 합류하라!

개발자 여러분 모두 화이팅입니다.

(추가) 클로드는 코딩만 하자

클로드가 생성한 - 개발자가 의자에 누워서 바이브 코딩하는 밈 이미지 생성

참고 문헌 :

[AI] 클로드 코드 설치 방법 + 가격 정보 (feat. 인텔리제이에서 실행하기)

현기 — Mon, 27 Oct 2025 21:00:10 +0900

30분만에 완성된 샘플 페이지

요즘 생성형 AI를 활용한 바이브 코딩이 뜨거운 주제인 것 같습니다.

저는 시간이 날 때마다 IT 칼럼을 즐겨보는데,

클로드 코드에 대해서 아주 많은 칼럼들이 보입니다.

운이 좋게도 회사에서 클로드 코드 연간 구독권을 지원받아

직접 한번 사용해 봤습니다.

(이 녀석 아주 물건입니다.)

함께 알아봅시다.

클로드 코드 가격

https://www.claude.com/pricing

Pricing | Claude

Explore Claude pricing plans and API costs. Choose from Free, Pro, Max, Team, or Enterprise options to get started with Claude.

www.claude.com

Free, Pro, Max

⦁개인

* Free : $0
- 사용량이 금방 부족해짐

* Pro : 연간 구독 $17, 월별 구독 $20
- Free 대비 약 5배 더 많은 사용량 제공

* Max : 월 $100 부터 시작
- Pro 대비 5배 또는 20배 많은 사용량 선택 가능

사용량에 따라 가격이 달라지는 플랜을 선택하는 구조입니다.

클로드 코드가 처음이시라면, Free로 체험해 보고 괜찮다 싶으면 Pro를 한두 달 정도 체험해 보시는 것을 추천드립니다.

직접 사용해보니 일을 좀 많이 시키면 Pro도 금방 세션 사용량을 초과할 것 같더라고요.

세션은 5시간마다 초기화 됩니다.

설치 및 실행 방법

https://docs.claude.com/en/docs/claude-code/overview

Claude Code overview - Claude Docs

Learn about Claude Code, Anthropic's agentic coding tool that lives in your terminal and helps you turn ideas into code faster than ever before.

docs.claude.com

✅ 공식문서에 정리가 잘 되어있으니 한번 읽어보시는 것을 추천드립니다.

⦁터미널 입력

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# 프로젝트 폴더 이동
cd your-awesome-project

# 클로드 코드 실행
claude

✅ 처음 실행 시 아주 귀여운 도트와 함께 테마를 선택하라는 UI가 표시됩니다.

이후 로그인까지 진행하면 바로 클로드 코드를 사용할 수 있습니다.

저는 이런 도트 감성이 좋더라구요.

클로드 코드를 개발한 Anthropic은 사내에서 다양한 개발 환경을 사용하고 있는

개발자들이 모두 사용할 수 있도록 CLI를 선택했다고 합니다.

VSCode || 인텔리제이에서 클로드 코드 사용하기

⦁VS Code

https://docs.claude.com/en/docs/claude-code/vs-code

Visual Studio Code - Claude Docs

Use Claude Code with Visual Studio Code through our native extension or CLI integration

docs.claude.com

저는 인텔리제이를 사용하기 때문에 VSCode는 해당 글을 참고해주세요!

⦁JetBrains IDE (인텔리제이)

https://docs.claude.com/en/docs/claude-code/jetbrains

JetBrains IDEs - Claude Docs

Use Claude Code with JetBrains IDEs including IntelliJ, PyCharm, WebStorm, and more

docs.claude.com

✅ 인텔리제이 내부에서 클로드 코드를 사용하기 위해서는, 플러그인을 설치해야합니다.

IDE 버전이 낮다는 경고 메시지

해당 플로그인을 사용하기 위해서는 최소 2025.2.3 버전의 인텔리제이가 필요합니다.

인텔리제이 업데이트 하는 방법 (mac)

미뤄왔던 IDE 업데이트를 이번 기회에 진행했습니다.

웹에서 설치할 필요 없이 인텔리제이의 Check for Updates 기능을 통해 쉽게 업데이트 할 수 있었습니다.

플러그인을 설치했다면,

이제 cmd + ESC 혹은 상단 클로드 버튼 클릭을 통해서 IDE 내부에서 클로드 코드 실행이 가능합니다.

인텔리제이 클로드 코드 터미널

작성하다 보니, 내용이 길어져서

다음 글에는 클로드 코드의 활용 방법과

사용해 본 후기로 찾아뵙겠습니다.

참고 문헌 :

https://claude.com/product/claude-code

[Next.js] 이전 페이지 뒤로 가기 구현하기 (세션 스토리지, 히스토리 스택)

현기 — Mon, 25 Aug 2025 19:06:12 +0900

문제 상황

Next.js 14버전을 사용하던 중

router.back() 함수에서 이슈가 발생했습니다.

<ArrowBackIosNewIcon
  onClick={() => {
    router.back(); // 문제 코드 !
  }}
>

router.back()은 그냥 사용하면 문제없이 동작하지만

새로고침 후 실행되면 RSC가 무한히 pending 되면서 결국 웹사이트가 터져버렸습니다.

무한 pending ...

router.back()을 계속 사용하면서,

해결할 수 있는 방법은 없나 찾아봤지만 마땅한 방법을 찾지 못했습니다.

저희 프로젝트만 그런가요?? 댓글로 알려주세요

그래서 결국 세션 스토리지에 히스토리를 직접 저장하고

goBack() 함수를 구현하기로 했습니다.

해결 방법

⦁1. 히스토리 저장을 위한 HistoryTracker 컴포넌트

const STORAGE_KEY = 'pageHistory';

/**
 * HistoryTracker
 * - 루트에 한 번만 마운트
 * - pathname 변화 시 세션스토리지에 기록
 */
export const HistoryTracker = () => {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    // 쿼리스트링 포함
    const fullPath = searchParams
      ? `${pathname}?${searchParams.toString()}`
      : pathname;
    const history = JSON.parse(sessionStorage.getItem(STORAGE_KEY) || '[]');

    // 중복 방지
    if (history[history.length - 1] !== fullPath) {
      history.push(fullPath);
      sessionStorage.setItem(STORAGE_KEY, JSON.stringify(history));
    }
  }, [pathname, searchParams]);

  return null;
};

// 선택사항입니다 ! -> 필요하면 suspense를 감싸서 사용하세요.
/**
 * SuspenseWrapper
 */
export const SuspenseHistoryTracker = () => (
  <Suspense fallback={null}>
    <HistoryTracker />
  </Suspense>
);


// 루트 컨테이너 등에서 한번만 렌더링
<SWRConfig>
	...
    <SuspenseHistoryTracker />

트래커는 언마운트 되지 않고 계속 유지되면서 path를 저장해야 하기 때문에 Provider를 넣는 곳에 위치시켜주었습니다.

이제 path가 변경되면 세션 스토리지에 배열로 저장됩니다.

⦁2. useHistory : 저장된 히스토리 관련 유틸 함수 모음 훅

/**
 * useHistory
 * - goBack(): 페이지 뒤로가기
 */
export const useHistory = (fallbackPath = '/') => {
  const router = useRouter();

  const goBack = useCallback(() => {
    const history = JSON.parse(sessionStorage.getItem(STORAGE_KEY) || '[]');

    if (history.length > 1) {
      history.pop(); // 현재 페이지 제거
      const prev = history.pop(); // 이전 페이지
      sessionStorage.setItem(STORAGE_KEY, JSON.stringify(history));

      if (prev) {
        router.replace(prev);
        return;
      }
    }

    router.replace(fallbackPath);
  }, [router, fallbackPath]);

  return { goBack };
};

저는 재사용성을 위해 커스텀 훅으로 구현했습니다.

지금은 goBack밖에 없지만, 히스토리와 관련된 함수를 추가할 경우

이곳에 작성하고 return만 해주면 되기 때문에 확장성도 좋습니다.

이제 새로고침해도 세션스토리지에 남아있는 path는 휘발되지 않기 때문에

정상적으로 뒤로 가기가 동작합니다 !

+ 09/05 추가 :

신규 프로젝트에서 Next.js 15.4.5 사용하는데, router.back() 함수가 잘 동작하네요 뭐지

+ 09/23 추가 :

문제가 발생한 프로젝트는 Next.js v14.2.29를 사용하고 있었고,

router.back()뿐만 아니라 브라우저 뒤로가기 시 간헐적으로 RSC가 무한 대기 상태가 되며 앱이 터지는 현상이 있었습니다.
Next.js를 최신 버전인 v15.5.3으로 마이그레이션하니 문제는 해결되었습니다.

참고 문헌 :

[CSS] Pretendard 숫자 데이터 고정폭 적용하기

현기 — Wed, 7 May 2025 20:20:21 +0900

사내 백오피스 프로젝트에서 숫자의 단위가 같은데

폰트의 크기가 달라 가독성이 떨어진다는 요구사항을 받았습니다.

이 프로젝트는 특성상 가격 데이터를 많이 다루기 때문에

숫자의 가독성이 중요했습니다.

해결방법 함께 알아봅시다.

문제 상황

https://en.wikipedia.org/wiki/Monospaced_font

⦁가변폭 폰트 vs 고정폭 폰트

해당 현상이 발생한 이유는 사용중인 Pretendard 폰트가 가변폭 폰트이기 때문입니다.

⦁ 가변폭 폰트 (Proportional Font)
글자마다 너비가 서로 다르게 설정된 폰트입니다. 예를 들어 i는 좁고, m은 넓게 표시됩니다.

- 일반적인 본문에 사용

⦁ 고정폭 폰트 (monospaced font, fixed-pitch, fixed-width, non-proportional font)
모든 글자와 기호가 동일한 너비를 가지는 폰트입니다. i, m, 1, W가 모두 같은 폭을 차지합니다.

- 숫자가 나란히 보여야 할 때
- 시계나 타이머 (ex. 12:34:56)
- 가격 리스트 (ex. ₩1,000 / ₩10,000 / ₩100,000)
- 회계나 통계 관련 표

해결 방법

https://github.com/orioncactus/pretendard/discussions/110

✅ Pretendard는 고정폭 숫자 기능을 지원합니다. 사용하는 폰트가 고정폭 숫자를 지원하는지 확인해보세요 !

// globlas.css
body {
  font-family: 'Pretendard', sans-serif;
  /* 
   font-variant-numeric: 숫자(0~9)의 스타일을 조절하는 CSS 속성입니다.
   tabular-nums: 숫자들을 같은 폭으로 출력하도록 지정합니다. 
  */
  font-variant-numeric: tabular-nums;
}

폰트 자체를 고정폭 폰트로 바꾸는 방법도 있지만 숫자에만 적용하고 싶을 경우

font-variant-numeric를 사용할 수 있습니다.

⦁적용 결과

숫자의 폰트 크기가 고정되어 가독성이 훨씬 개선되었습니다 !

참고 문헌 :

https://en.wikipedia.org/wiki/Monospaced_font

https://velog.io/@aneb/css-%EA%B0%80%EB%B3%80%ED%8F%AD-%ED%8F%B0%ED%8A%B8%EB%A5%BC-%EA%B3%A0%EC%A0%95%ED%8F%AD-%ED%8F%B0%ED%8A%B8%EB%A1%9C-%EB%B0%94%EA%BE%B8%EB%8A%94-%EB%B0%A9%EB%B2%95

[Next.js] next-intl 자바스크립트 프로젝트에서 다국어 메시지 자동완성 구현하기 (부분 타입스크립트 활용)

현기 — Fri, 11 Apr 2025 21:30:11 +0900

meme-arsenal

신규 프로젝트의 다국어 적용을 마치고

기존 프로젝트에도 다국어 적용이 필요한 상황이었습니다.

하지만 문제는 기존 프로젝트는 자바스크립트 프로젝트라는 것입니다.

사라져버린 다국어 메시지 자동완성

신규 프로젝트는 타입스크립트로 진행했기 때문에

어려움 없이 자동완성의 혜택을 누릴 수 있었지만,

자바스크립트 프로젝트에서는 다국어 메시지 자동완성이 불가능했습니다.

자동완성 없이 다국어 메시지를 적용한다고?

이건 여러모로 좋지 않을 것 같아서

방법을 찾아봤습니다.

JavaScript 프로젝트에서 .d.ts 파일 생성하기

⦁1. 타입스크립트를 devDependencies로 설치

yarn add -D typescript

.d.ts 파일을 생성하기 위해선 타입스크립트를 설치해야 합니다.

-D는 --dev의 줄임말로, 개발에만 필요한 패키지를 설치할 때 사용합니다.

typescript는 우리가 작성한 JS 코드에 타입 자동완성을 위한 도구일 뿐, 실제 빌드나 배포에는 포함되지 않습니다.

⦁2. .d.ts 파일이란?

- 코드의 구현 없이 타입만 정의되어 있습니다.
- JS 파일에서도 사용할 수 있어, 자동완성과 타입 체크를 가능하게 해줍니다.
- 특히 다국어 JSON 메시지 같은 구조화된 데이터를 다룰 때, 키 자동완성에 매우 유용합니다.

.d.ts 파일은 타입스크립트의 타입 선언 파일(declaration file) 입니다.

저희는 i18n.d.ts 파일을 생성해서, 다국어 메시지 자동완성을 구현할 거예요

JS 프로젝트에서 프로젝트 전체를 TS로 마이그레이션 하지 않아도 부분적으로 타입의 혜택을 누릴 수 있습니다.

⦁3. jsconfig는 그대로 유지하세요!

타입스크립트를 설치했다고 해서, jsconfig.json을 tsconfig.json으로 변경할 필요는 없습니다.

오히려 JS 기반 프로젝트라면 tsconfig.json으로 전환하면 에러가 너무 많이 생기고, 설정의 충돌이 발생할 수 있습니다.

따라서 jsconfig를 유지한 채 타입 보강만 하는 것을 추천드립니다.

// jsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    },
    "checkJs": true, // 이거랑
    "resolveJsonModule": true // 이거만 추가해주세요
  },
  "include": ["src"]
}

2가지 옵션 정도는 추가해 주셔야 합니다.

- checkJs : JSDoc 사용하기 위함

- resolveJsonModule : JSON 파일을 import 하기 위해 필요 (다국어 메시지는 JSON이니까요)

필요한 파일 생성

✅ next-intl을 세팅했다면 위와 같이 i18n 폴더에 파일들이 있을 겁니다.

** 3월 12일에 @4버전으로 올라가면서 라우팅 관련 래핑 컴포넌트를 export 하는 곳이

navigation으로 분리되었습니다. 참고하세요 !

⦁1. i18n.d.ts

// i18n.d.ts

import en from '../../messages/en.json';

type Messages = typeof en;

/* 중첩 객체 자동 완성을 위한 코드 */
type NestedKeyOf<T> = {
  [K in keyof T & string]: T[K] extends object
    ? `${K}.${NestedKeyOf<T[K]>}`
    : K;
}[keyof T & string];

declare global {
  type TKey = NestedKeyOf<Messages>;
}

타입스크립트 프로젝트에서는, 메시지의 typeof만 넘겼을 때에도 정상적으로 자동완성이 되었지만,

자바스크립트 프로젝트에서는 NestedKeyOf 처럼 타입을 만들어줘야 자동완성을 사용할 수 있더라고요.

⦁2. useT() 커스텀 훅 생성

/**
 * @typedef {import('./i18n').TKey} TKey
 */
import { useTranslations } from 'next-intl';

/**
 * @returns {(key: TKey) => string}
 */
export function useT() {
  const t = useTranslations();

  /**
   * @param {TKey} key
   */
  return function (key) {
    return t(key);
  };
}

useTranslations을 래핑한 커스텀 훅을 생성합니다.

JSDoc를 사용해서 JS에서도 타입 추론과 자동 완성을 제공합니다!

⦁3. 사용해보기

import { useT } from '@/i18n/useT';

function Home() {
  const t = useT();
  
  ...
  
  {t('Common.action')}

JS 프로젝트에서 다국어 메시지 자동완성 구현하기 끝 !

+ 4/15 추가

JSDoc을 사용해 타입을 정의했을 때, 타입 추론 속도가 느린지 자동완성이 불안정한 문제가 발생했습니다.
결국 useT() 훅을 JSDoc 대신 TypeScript로 전환하여 문제를 해결했습니다.

JSDoc 써보고 싶었는데 아쉽네요

// 1. i18n.d.ts 파일 제거
// 2. useT.js -> useT.ts 타입스크립트로 변환 및 타입 직접 사용

// useT.ts
import { useTranslations } from 'next-intl';
import en from '../../messages/en.json';

/* 다국어 메세지 타입 정의 */
type Messages = typeof en;

type NestedKeyOf<T> = {
  [K in keyof T & string]: T[K] extends object
    ? `${K}.${NestedKeyOf<T[K]>}`
    : K;
}[keyof T & string];

type TKey = NestedKeyOf<Messages>;

/* useTranslations 래핑 커스텀 훅 */
export function useT() {
  const t = useTranslations();

  return (key: TKey): string => t(key);
}

마치면서

프로젝트 전체를 타입스크립트로 마이그레이션할 수 있으면

좋겠지만, 현실적으로 쉽지 않은 상황이 있을 수 있습니다.

사내 신규 프로젝트에 타입스크립트를 도입하길 정말 다행인 것 같습니다.

이럴 땐 이 방법처럼 부분적으로만

타입스크립트를 적용하는 것도 좋은 방법인 것 같습니다.

참고 문헌 :

[Next.js] 구글 스프레드시트로 i18n 메시지 관리하기 (Apps Script json 추출)

현기 — Thu, 13 Mar 2025 22:00:24 +0900

https://ifunny.co/tags/i18n

https://hyunki99.tistory.com/124

[Next.js] Next 15 국제화라이브러리 비교 + 적용하기 (i18n, next-intl)

요즘의 모던하고 글로벌한 웹에는 국제화(i18n)와 지역화(i10n)라는 개념이 등장합니다.쉽게 정리하면 다음과 같습니다.✅ 국제화(i18n, Internationalization): → 다국어 지원을 위해 코드 구조를 준비

hyunki99.tistory.com

지난 시간에 next-intl 라이브러리를 사용해서

다국어 지원을 구현했습니다.

이제 더 중요한 숙제가 남았는데요, 바로 다국어 메시지 관리입니다.

프로젝트의 규모가 커지고 지원하는 언어가 늘어나면

다국어 메시지를 관리하기 복잡해집니다.

코드를 수정할 때마다 각각의 언어 파일의 Json을 찾아 수정하고

반복하면 번거롭겠죠? 이는 개발자가 실수할 확률도 높습니다.

개발팀 내부, 외부에서 다국어 메시지를 관리하고 공유할 수 있는

문서가 있으면 의사소통 비용이 줄고 생산성이 좋아질 것 같다는 생각에

구글 스프레드시트를 활용하기로 했습니다.

데이터 설계 & 작업 흐름

⦁JSON 데이터 (원하는 데이터)

// messages/en.json
{
  "LoginPage": {
    "login": "Log in",
    "logout": "Log out",
    "placeholder": {
      "account": "Account",
      "password": "Password",
      "referralCode": "Referral Code (6 digits)"
    }
  },
}

next-intl의 메시지 파일입니다. placeholder는 중첩된 객체구조입니다.

선택적으로 활용하면 메시지를 체계적인 구조로 사용할 수 있습니다. (더 복잡해지지 않도록 주의하세요)

⦁스프레드 시트

시트로 표현하면 위와 같습니다. 중첩된 객체는 . 으로 구분합니다.

필터같은 엑셀의 데이터 관련 부가 기능을 사용할 수 있는 장점도 있습니다.

⦁작업 흐름

이제 저희가 원하는 작업 흐름은 다음과 같습니다.

1. 다국어 메시지를 스프레드시트에 작성한다.

2. 포맷팅 함수를 동작시켜 원하는 형식의 json을 얻는다.

3. 복사 후 messages에 편리하게 붙여넣고 배포한다.

3번 같은 경우는 프로젝트 환경에 따라 많이 달라집니다.

S3에 json을 업데이트하는 방식도 있고 스프레드시트의 Api를 활용해 배포하는 방법도 있습니다.

저는 간단하게 시트에서 json만 추출해서 메시지에 바로 복사 붙여넣기를 할 수 있도록 구현했습니다. (반자동입니다)

Apps Script 활용 Json 추출

⦁시트 상단 확장 프로그램 -> Apps Script

간단한 기능 때문에 Node 프로젝트를 하나 생성해야 하나 고민했는데,

시트 확장 프로그램에 신기하게 함수를 만들 수 있는 기능이 있더라고요

바로 사용해 봤습니다.

⦁소스코드

function generateTranslationsJson() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  const data = sheet.getDataRange().getValues();
  
  // 첫 번째 행은 헤더이므로 두 번째 행부터 시작
  const translationsEn = {};
  const translationsJp = {};

  // 데이터를 순회하며 en과 jp 값을 각각 분리
  for (let i = 1; i < data.length; i++) {
    const [section, key, en, jp] = data[i];

    // section이 '.'을 포함하면 중첩된 구조로 처리
    const sectionKeys = section.split('.');

    let currentEn = translationsEn;
    let currentJp = translationsJp;

    // sectionKeys를 순회하며 중첩된 객체를 만듦
    sectionKeys.forEach((keyPart, index) => {
      if (!currentEn[keyPart]) {
        currentEn[keyPart] = index === sectionKeys.length - 1 ? {} : {};
        currentJp[keyPart] = index === sectionKeys.length - 1 ? {} : {};
      }

      if (index === sectionKeys.length - 1) {
        // 마지막 부분이라면 값을 넣어줌
        currentEn[keyPart][key] = en;
        currentJp[keyPart][key] = jp;
      } else {
        // 중간 단계는 객체를 계속 내려가며 만듦
        currentEn = currentEn[keyPart];
        currentJp = currentJp[keyPart];
      }
    });
  }

  // 결과를 JSON 형식으로 출력
  const jsonEn = JSON.stringify(translationsEn, null, 2);
  const jsonJp = JSON.stringify(translationsJp, null, 2);
  
  // 잘못된 "" 두 번 문제를 해결하기 위한 추가 처리
  const correctedJsonEn = jsonEn.replace(/""/g, '"');
  const correctedJsonJp = jsonJp.replace(/""/g, '"');
  
  Logger.log("English JSON:\n" + correctedJsonEn);
  Logger.log("Japanese JSON:\n" + correctedJsonJp);

  // 예시로 스프레드시트에 결과를 붙여넣기 (옵션)
  const resultSheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Results');
  if (!resultSheet) {
    resultSheet = SpreadsheetApp.getActiveSpreadsheet().insertSheet('Results');
  }
  resultSheet.getRange(1, 1).setValue("English JSON:");
  resultSheet.getRange(2, 1).setValue(correctedJsonEn);
  resultSheet.getRange(10, 1).setValue("Japanese JSON:");
  resultSheet.getRange(11, 1).setValue(correctedJsonJp);
}

⦁결과

프로젝트 이동할 필요 없이 간단하게 원하는 언어의 messages Json이 잘 추출 되었습니다.

프로젝트가 커진다면 namespace 칼럼을 시트로 구분하는 것도 좋은 방법일 것 같습니다.

여러분은 다국어의 Key값을 어떻게 구분하고 관리하는지 댓글로 알려주세요 !

+ 4/11일 추가

key 같은 경우에는 개발자가 직접 만드는 것보다

프로그램이 일정한 규칙에 따라 생성하는 것이 빠르고 일관적이기 때문에 좋겠죠?

그럴 땐 시트에 함수를 넣어서 자동으로 생성되게 할 수 있습니다.

1. Apps Script에 유틸 함수 추가

/**
 * Converts a sentence to camelCase, removing punctuation like commas, periods, and quotes.
 *
 * @param {string} text The input text.
 * @param {number} [maxWords] Optional. Max number of words to include.
 * @return {string} The camelCase version of the text.
 * @customfunction
 */
function TO_CAMEL_CASE(text, maxWords=4) {
  if (typeof text !== 'string') return '';

  // 구두점 및 스마트 따옴표 제거
  const cleanText = text.replace(/[.,\/#!$%\^&\*;:{}=\-_`~()'"’‘”“]/g, '');

  // 단어 분리 및 제한
  const words = cleanText.trim().split(/\s+/);
  const limited = maxWords && maxWords > 0 ? words.slice(0, maxWords) : words;

  // camelCase 변환
  return limited
    .map((word, i) => {
      word = word.toLowerCase();
      return i === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1);
    })
    .join('');
}

저는 조금의 특수문자를 제거한 후, 4단어 까지만 카멜케이스로 변환하는 함수를 작성했습니다.

이건 회사의 정책에 맞게 수정해서 사용하세요

2. 셀에 사용

이제 셀에 함수를 입력해서 사용하면 됩니다.

200개 정도의 다국어가 시트에 생성되었는데, 1초만에 key를 다 입력했네요

참고 문헌 :