innes.log

[자료구조] Set 자료구조 알아보기

Tue, 19 Aug 2025 06:26:27 GMT

1. `set` 자료구조란 무엇인가

set은 수학의 집합 개념을 기반으로 하는 자료구조입니다. 가장 중요한 특징은 중복된 요소를 허용하지 않는다는 점입니다. {} 중괄호를 사용하여 선언하며, 키(Key)와 값(Value)의 쌍으로 이루어진 딕셔너리와는 구분됩니다.

# set은 중복을 허용하지 않습니다.
unique_set = {1, 2, 2, 3, 4}
print(unique_set)
# 결과: {1, 2, 3, 4}

참고: 빈 set은 my_set = set()으로 선언해야 합니다. {}는 빈 딕셔너리로 인식됩니다.

2. `set`을 사용해야 하는 이유: 성능

set은 시간 효율성 측면에서 리스트보다 우수한 성능을 제공합니다. 이는 set이 내부적으로 해시 테이블을 사용하여 데이터를 관리하기 때문입니다.

리스트: 특정 요소의 존재 여부를 확인하기 위해 첫 번째 요소부터 순차적으로 탐색합니다. (시간 복잡도: O(N))
set: 해시 테이블을 통해 요소의 위치를 즉시 찾아냅니다. (시간 복잡도: O(1))

따라서 in 연산을 통한 데이터 존재 여부 확인이 빈번하게 발생하는 알고리즘 문제에서 set은 압도적인 속도를 보여줍니다.

3. `set` 자료구조의 주요 활용법

set은 주로 데이터의 중복을 제거하거나, 빠른 검색이 필요할 때 활용됩니다. 다음은 set의 주요 사용 예시입니다.

A. 리스트의 중복 제거

가장 보편적인 활용법입니다. 리스트를 set으로 변환하기만 하면 중복이 자동으로 제거됩니다.

my_list = [1, 2, 3, 2, 4, 1]
# 리스트를 set으로 변환하여 중복 제거
unique_elements = set(my_list)
print(unique_elements)
# 결과: {1, 2, 3, 4}

B. 요소 추가 및 삭제

set에 요소를 추가하거나 삭제할 때는 add()와 remove() 메서드를 사용합니다.

my_set = {1, 2, 3}
my_set.add(4)
print(my_set)
# 결과: {1, 2, 3, 4}

my_set.remove(1)
print(my_set)
# 결과: {2, 3, 4}

C. 정렬된 리스트로 변환

set은 순서가 없기 때문에 정렬이 필요한 경우, sorted() 함수를 사용하여 list로 변환해야 합니다.

unique_elements = {1, 3, 2}
# sorted() 함수는 정렬된 리스트를 반환합니다.
sorted_list = sorted(list(unique_elements))
print(sorted_list)
# 결과: [1, 2, 3]

결론

set은 코딩 테스트에서 중복 제거 및 빠른 검색을 위한 핵심 자료구조입니다. 리스트와 딕셔너리처럼 자유롭게 다룰 수 있도록 연습한다면, 복잡한 문제도 효율적으로 해결하는 통찰력을 기를 수 있을 것입니다.

[Side Project] Expo Web 500 에러 해결기: Babel 플러그인 호환성 문제

Mon, 18 Aug 2025 15:43:49 GMT

🚨 Expo Web 500 에러 해결기: Babel 플러그인 호환성 문제

TL;DR: Expo Web에서 발생하는 500 에러는 react-native-reanimated/plugin과 Expo SDK 53 간의 호환성 문제였습니다. Babel 플러그인을 제거하여 해결했습니다.

📱 문제 상황

React Native 모노레포(Turborepo)에서 Expo 앱을 개발 중이었습니다. 앱은 모바일에서는 정상 작동했지만, Expo Web에서 500 에러가 계속 발생했습니다.

🔍 에러 메시지

[Reanimated] Seems like you are using a Babel plugin `react-native-reanimated/plugin`.
It was moved to `react-native-worklets` package. Please use `react-native-worklets/plugin` instead.

ERROR index.ts: [BABEL] .plugins is not a valid Plugin property

🌐 실패하는 요청

...bundle?platform=web&...transform.routerRoot=app... returns 500 and JSON MIME type

🕵️ 문제 진단 과정

1단계: 일반적인 원인들 확인

처음에는 다음과 같은 일반적인 문제들을 의심했습니다:

expo-router 설정 문제
Metro 번들러 설정 문제
모노레포 구조 문제
웹 번들러 설정 문제

2단계: 설정 파일 분석

백업된 코드와 현재 코드를 비교 분석한 결과:

설정 파일	문제 상태	정상 상태
`babel.config.js`	`plugins: ['nativewind/babel', 'react-native-reanimated/plugin']`	`plugins: []`
`package.json`	복잡한 의존성 (nativewind, reanimated, tailwind)	간단한 기본 의존성
`metro.config.js`	모노레포 설정 있음	없음
`app.json`	`"bundler": "webpack"`	기본 웹 설정

3단계: 진짜 원인 발견

에러의 진짜 원인은 react-native-reanimated/plugin이었습니다!

🎯 문제의 핵심

Babel 플러그인 호환성 문제

Reanimated v3.17.4와 Expo SDK 53 간의 호환성 문제
에러 메시지의 react-native-worklets 가이드는 잘못된 정보였음
Reanimated v3.x에서는 여전히 react-native-reanimated/plugin 사용해야 함

잘못된 가이드의 함정

[Reanimated] Seems like you are using a Babel plugin `react-native-reanimated/plugin`.
It was moved to `react-native-worklets` package.

이 메시지는 오해의 소지가 있었습니다. 실제로는:

Reanimated v4+에서만 react-native-worklets/plugin 사용
Reanimated v3.x에서는 기존 플러그인 유지
하지만 Expo SDK 53과의 호환성 문제 존재

🔧 해결 방법

방법 1: Babel 플러그인 제거 (추천)

// babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: [], // Reanimated 플러그인 제거
  };
};

방법 2: Reanimated 버전 업그레이드

# Reanimated v4+로 업그레이드
npx expo install react-native-reanimated@^4.0.0

# babel.config.js 수정
plugins: [
  'nativewind/babel',
  'react-native-worklets/plugin', // v4+용
]

방법 3: Expo SDK 다운그레이드

# Reanimated v3와 호환되는 Expo SDK로 다운그레이드
npx expo install expo@~52.0.0

📚 교훈 및 인사이트

1. 에러 메시지 신중하게 해석하기

공식 에러 메시지도 항상 정확하지 않을 수 있음
버전별로 다른 해결책이 필요할 수 있음
컨텍스트를 고려한 분석이 중요

2. 단계별 문제 해결의 중요성

복잡한 문제는 하나씩 제거하며 접근
설정 파일들을 하나씩 비교하며 분석
백업과 비교를 통한 정확한 진단

3. 모노레포에서의 주의사항

각 앱의 설정이 독립적으로 작동해야 함
공유 패키지와의 의존성 관리 중요
캐시 정리가 문제 해결의 핵심

🚀 예방 방법

1. 의존성 버전 관리

{
  "dependencies": {
    "expo": "~53.0.20",
    "react-native-reanimated": "~4.0.0" // 최신 버전 사용
  }
}

2. Babel 설정 최소화

// 필요한 플러그인만 사용
plugins: [
  'nativewind/babel', // NativeWind 사용 시에만
  // Reanimated는 필요할 때만 추가
];

3. 정기적인 업데이트

# 정기적으로 의존성 업데이트
npx expo install --fix
npm update

🔍 디버깅 체크리스트

500 에러가 발생할 때 다음을 확인하세요:

Babel 플러그인 설정 확인
Reanimated 버전과 Expo SDK 호환성 확인
Metro 캐시 정리 (npx expo start -c)
node_modules 재설치
설정 파일들 비교 분석
백업과 현재 상태 비교

💡 결론

이번 트러블슈팅을 통해 Babel 플러그인 호환성이 Expo Web 에러의 주요 원인임을 확인했습니다.

핵심 교훈:

에러 메시지를 맹신하지 말고 컨텍스트를 고려하라
복잡한 문제는 단계별로 접근하라
백업과 비교를 통한 정확한 진단이 중요하다
불필요한 Babel 플러그인은 제거하는 것이 안전하다

이 경험이 비슷한 문제를 겪는 개발자들에게 도움이 되길 바랍니다! 🎉

바이브코딩으로 초기 세팅할 때의 꿀팁! 초기 세팅에서 계속 에러가 난다면, 해당 라이브러리의 공식 문서를 첨부하면서 공식문서 검토 후 다시 작업 진행하도록 시키면 훨씬 정확도가 높아진다!

[Side Project] React Native 찐초보의 UI 실행 방법 알아보기!

Mon, 18 Aug 2025 14:05:25 GMT

React 웹만 하다가 React Native 해보니까 환경부터가 완전 다른 세상이구만...?! 신기하다...!!

✅ React Native 실행 정리

1. 🌐 웹에서 확인

npm run web

→ 바로 브라우저에서 확인 (CRA처럼 동작)
npx expo start --tunnel 후 DevTools에서 Run in web browser 버튼 클릭

→ 이것도 가능하지만 그냥 npm run web이 더 직관적임

2. 📱 폰에서 확인 (Expo Go)

npm expo start

→ 같은 와이파이 환경에서 QR 찍으면 됨 (하지만 가끔 연결 문제 발생 가능)
npx expo start --tunnel

→ 네트워크 문제 있을 때 확실히 연결됨 (QR 찍고 바로 들어갈 수 있음)

3. 💻 iOS 시뮬레이터에서 확인 (Xcode 필요)

expo 서버(npm expo start) 열려 있는 터미널에서 i 입력

→ iOS 시뮬레이터 실행됨
npm expo run:ios

→ 네이티브 빌드해서 시뮬레이터 실행 (조금 무거움, Expo Go 없이 직접 빌드)

4. 💻 Android 시뮬레이터에서 확인 (Android Studio 필요)

Android Studio는 IDE 역할도 한다!

📌 결론

웹 확인 → npm run web
폰에서 확인 → npx expo start --tunnel (이게 가장 안정적)
시뮬레이터에서 확인 → 서버 켠 터미널에서 i

[트러블슈팅] GitLab Pages에서 React Router 새로고침 시 404 에러 해결기

Tue, 05 Aug 2025 09:41:42 GMT

회사 프로젝트를 진행하면서 React + Tailwind 프로젝트를 GitLab Pages에 배포했는데,
라우팅과 관련된 문제가 발생했다. 로컬 개발 서버에서는 문제가 없었지만, 배포된 페이지에서 새로고침 시 404 에러가 뜨는 상황이었다.
이 글에서는 내가 겪은 문제 상황과 원인 분석, 해결책 비교, 그리고 최종적으로 HashRouter로 임시 해결한 과정을 정리한다.

1. 문제 상황

React 프로젝트를 GitLab Pages로 배포
라우팅에 BrowserRouter 사용
로컬 개발 서버에서는 라우팅 및 새로고침 모두 정상 동작
문제: GitLab Pages 배포 후 특정 URL 직접 접근 또는 새로고침 시 GitLab 기본 404 페이지가 표시됨

증상

/dashboard 같은 URL을 직접 입력하면 GitLab의 404 UI 표시
페이지 내에서 클릭으로 이동하면 UI 정상 작동
이동 후 새로고침하면 다시 메인 페이지(/)로 리다이렉트됨
URL은 바뀌지만 React Router에서 페이지를 렌더링하지 못함

2. 원인 분석

GitLab Pages는 정적 호스팅으로 동작
서버 측 라우팅 설정 불가 → 존재하지 않는 경로 요청 시 404 반환
React Router의 BrowserRouter는 HTML5 History API를 사용
따라서 새로고침 시 서버에 직접 요청 → 서버는 해당 경로의 정적 파일 없음 → 404 발생

dist 폴더를 확인해보자. index.html 하나만 있는걸 봐도 알 수 있다. gitlab pages는 정적 호스팅이기 때문에 링크를 전달해서 요청하면 배포주소는 index.html하나만 바라보고 있어서 '전달받은 링크같은 그런 파일은 없는데..?'라고 생각하고 404를 뱉어버리는 것이다.

3. 시도한 해결 방법들

방법 1: 404.html + sessionStorage 복원

404.html에서 현재 경로를 sessionStorage에 저장
/로 리다이렉트 후 App.tsx에서 sessionStorage 값을 읽어 원래 경로로 복원

장점

URL 깔끔하게 유지 (/dashboard 그대로 사용)
React Router 그대로 사용 가능

단점

존재하지 않는 URL도 메인 페이지로 리다이렉트 → SEO 문제
GitLab Pages의 404 응답이 항상 200으로 변환 → 에러 구분 불가
sessionStorage 복원 로직이 복잡하고 유지보수 어려움

방법 2: 404.html → index.html 유사 내용으로 처리 (sessionStorage 사용 안 함)

404.html을 index.html과 동일한 React 앱으로 구성
사용자가 잘못된 URL을 직접 입력하면 404.html이 로드되고, React Router가 즉시 실행되어 해당 경로를 해석
존재하지 않는 경로는 NotFoundPage로 처리, 존재하는 경로는 정상 라우팅

장점

sessionStorage 없이 자연스럽게 동작
클릭/새로고침/직접 접근 모두 정상 작동

단점

잘못된 URL도 200 상태로 서빙되어 SEO 문제
GitLab Pages 특성상 서버 측 404 구분 불가

방법 3: GitLab Pages CI 수정 (모든 경로 index.html로 fallback)

GitLab CI 설정에서 모든 요청을 index.html로 리다이렉트하도록 설정
404.html 활용 없이 서버 레벨에서 우회

장점

URL 깔끔 유지
별도 복원 로직 불필요

단점

GitLab Pages는 커스텀 리라이트 규칙을 지원하지 않음 (불가능에 가까움)
결국 404.html 방식과 유사한 효과만 기대 가능

방법 4: HashRouter 사용

React Router에서 BrowserRouter → HashRouter로 변경
URL이 /#/dashboard 형태로 변경됨
서버는 # 이후 경로를 무시하므로 항상 index.html 반환
클라이언트 라우팅은 해시 기반으로 정상 작동

장점

가장 단순하고 빠른 해결책
GitLab Pages 특성과 100% 호환
별도 서버 설정, 404.html 필요 없음
새로고침, 직접 접근 모두 문제 없이 동작

단점

URL에 # 포함 → SEO에 불리
HTTP 상태 코드와 무관하게 항상 200 응답

4. 최종 선택: HashRouter

선택 이유

빠른 배포 필요
- 회사 프로젝트이고 GitLab Group 비공개 레포
- Vercel/Netlify는 그룹 비공개 레포 무료 연결 불가
- 유료 서비스 사용 불가한 상황
임시 배포
- 최종적으로는 AWS 등 서버 기반 배포로 이관 예정
- SEO 문제는 이후 서버 배포 시 BrowserRouter로 복원하며 해결 가능
적용 난이도 최소
- BrowserRouter → HashRouter 변경만으로 문제 해결
- 404.html 및 복원 로직 제거 가능

5. 적용 방법

1) main.tsx 수정

import { HashRouter } from 'react-router-dom';

ReactDOM.createRoot(document.getElementById('root')!).render(
  
    
      
    
  
);

React + Tailwind CSS 다크모드 구현 시 발생하는 문제들과 해결방법

Fri, 18 Jul 2025 07:14:19 GMT

Tailwind 설정에서 직접 색상 클래스 누락

// ❌ 문제: bg-bg, text-text 등의 클래스가 정의되지 않음
colors: {
  primary: "var(--color-primary)",
  secondary: "var(--color-secondary)",
  // bg-bg, text-text 등이 없어서 클래스가 작동하지 않음
}

// ✅ 해결: 직접적인 색상 클래스들 추가
colors: {
  // 직접 색상 클래스들
  bg: "var(--color-bg)",
  "bg-card": "var(--color-bg-card)",
  "bg-input": "var(--color-bg-input)",
  "bg-alt": "var(--color-bg-alt)",
  text: "var(--color-text)",
  "text-muted": "var(--color-text-muted)",
  border: "var(--color-border)",
  "border-divider": "var(--color-border-divider)",

  // 기존 색상들
  primary: "var(--color-primary)",
  secondary: "var(--color-secondary)",
  // ... 기타 색상들
}

(styles/themes/dark, light/variables.css 에서 컬러 변수를 선언하고 있음) ex)

:root[data-theme="dark"] {
  /* Background Colors */
  --color-bg: #0a0a0a;
  --color-bg-card: #111111;
  --color-bg-input: #1a1a1a;
  --color-bg-alt: #1f1f1f;

  /* Border Colors */
  --color-border: #222222;
  --color-border-divider: #333333;
  ...

CSS 변수 로딩 순서 문제

/* ❌ 문제: Tailwind가 CSS 변수보다 먼저 로드됨 */
@tailwind base;
@tailwind components;
@tailwind utilities;
@import '../themes/dark/variables.css';

/* ✅ 해결: CSS 변수를 먼저 import */
@import '../themes/dark/variables.css';
@import '../themes/light/variables.css';
@tailwind base;
@tailwind components;
@tailwind utilities;

테마 전환 시 CSS 변수 적용 지연

// ❌ 문제: CSS 변수가 즉시 적용되지 않음
setTheme(theme) {
  const root = document.documentElement;
  root.setAttribute('data-theme', theme);
  // reflow가 없어서 CSS 변수 적용이 지연됨
}

// ✅ 해결: 강제 reflow 추가
setTheme(theme) {
  const root = document.documentElement;
  root.setAttribute('data-theme', theme);
  root.offsetHeight; // 강제 reflow로 즉시 적용
}

Next.js와 React(Vite)에서 Tailwind CSS, @layer, @apply 사용 시 발생하는 차이점과 디자인 시스템 적용 문제

Wed, 16 Jul 2025 07:11:25 GMT

최근에 Next.js로 개발된 디자인 시스템을 React(Vite) 프로젝트로 옮기는 과정에서 예상치 못한 문제가 발생했습니다. Next.js에서는 잘 동작하던 Tailwind CSS 기반의 커스텀 유틸리티와 @layer, @apply 조합이 Vite 기반 React 프로젝트에서는 제대로 적용되지 않는 현상이었습니다. 이 글에서는 그 원인과 해결 과정을 정리했습니다.

문제 상황

Next.js 프로젝트(fofood-origin)에서 디자인 시스템을 개발할 때,

globals.css(또는 index.css)에

@layer utilities {
  .text-body-2-medium {
    @apply font-figtree text-base font-medium leading-none tracking-[-0.04em];
  }
}

와 같이 커스텀 유틸리티 클래스를 정의하고,

버튼 등 컴포넌트 스타일을
```
.btn-yellow-solid {
  @apply text-body-2-medium ...;
}
```
처럼 @apply로 재사용하는 방식이 잘 동작했습니다.

이 디자인 시스템을 Vite 기반의 React 프로젝트(design-test)로 그대로 가져와 적용했을 때, 아래와 같은 에러가 발생했습니다.

Error: Cannot apply unknown utility class `text-body-2-medium`.

원인 분석

1. Next.js와 Vite(React)의 Tailwind 빌드 파이프라인 차이

Next.js는 Tailwind와 PostCSS, 글로벌 CSS를 통합적으로 처리하면서, @layer utilities에서 정의한 커스텀 유틸리티를 @apply로 사용할 때도 “일반 CSS 클래스”로 인식하여 에러 없이 빌드가 진행되는 경우가 많았습니다.
Vite(React)는 Tailwind의 JIT 엔진이 모든 CSS를 직접 처리합니다. 이때 @apply 안에 들어가는 클래스는 반드시 Tailwind가 “자신이 생성한 유틸리티”여야 하며, 그렇지 않으면 빌드 에러가 발생합니다.

2. Tailwind의 공식 정책

Tailwind 공식 문서에서는

“@apply는 Tailwind가 생성한 유틸리티 클래스에만 사용할 수 있습니다. @layer에서 정의한 커스텀 유틸리티는 @apply로 사용할 수 없습니다.”

라고 명시하고 있습니다.

즉, Next.js에서만 “운 좋게” 동작했던 것이고, Vite(React)에서는 공식 정책대로 엄격하게 동작한 것입니다.

해결 과정

1. tailwind.config.js의 content 경로 확인

src 디렉토리 전체가 포함되어야 Tailwind가 유틸리티를 생성합니다.

2. 커스텀 유틸리티를 theme.extend에 등록

fontSize, colors, fontFamily 등 필요한 값을 tailwind.config.js에 추가했습니다.

3. @apply에서 커스텀 유틸리티 사용 금지

@apply에서는 반드시 Tailwind 기본 유틸리티만 사용하도록 코드를 수정했습니다.

예를 들어,

   .btn-yellow-solid {
     @apply font-figtree text-base font-medium ...;
   }

처럼 직접 유틸리티 조합을 사용했습니다.

결론

Next.js와 Vite(React)에서 Tailwind CSS의 @layer, @apply, 커스텀 유틸리티 처리 방식이 다릅니다.
Next.js에서는 PostCSS 처리 순서 등으로 인해 커스텀 유틸리티를 @apply로 써도 동작할 수 있지만, Vite(React)에서는 반드시 Tailwind가 생성한 유틸리티만 @apply에서 사용할 수 있습니다.
디자인 시스템을 여러 환경에서 재사용하려면, Tailwind의 공식 정책에 맞게 커스텀 유틸리티를 관리하고, @apply에서는 기본 유틸리티만 사용하는 것이 안전합니다.

이 경험을 통해, 프로젝트 환경에 따라 Tailwind CSS의 동작 방식이 달라질 수 있음을 알게 되었고, 공식 문서의 정책을 항상 준수하는 것이 중요하다는 점을 다시 한 번 깨달았습니다.

[Design system] 디자인 시스템 제작하기

Mon, 30 Jun 2025 05:19:36 GMT

🎨 디자인 시스템 제대로 만들기: 토큰 기반 중앙 관리부터 Tailwind 연동까지

프로젝트를 진행하다 보면 디자인이 계속 바뀌는데, 그때마다 색상, 폰트, 간격 등을 일일이 수정하는 일이 번거로웠다.

브랜드 컬러 하나만 바꿔도 앱 전체가 한 번에 바뀌고, 버튼의 둥글기를 바꾸면 전부 반영되며, 폰트를 바꿔도 전역에서 따라오도록 만들고 싶었다.

이걸 해결하기 위해 디자인 시스템을 중앙 관리하는 구조를 설계했고, 그 과정을 정리해보았다.

✅ 1️⃣ 디자인 토큰 객체 만들기

먼저 디자인 토큰(Design Token)이 뭔지 간단히 설명하면,

디자인의 결정값을 의미 있는 이름으로 변수화해서 코드로 관리하는 방식이다.

예를 들어 브랜드 메인 색을 그냥 #FF4D8D로 박아 넣는 대신:

export const Colors = {
  brandPrimary: '#FF4D8D',
};

이렇게 변수로 관리하면 이 변수만 바꿨을 때 전역에서 색이 모두 바뀌도록 만들 수 있었다.

✅ 장점

중앙 관리가 가능했다. 한 군데서 정의하면 앱 전체에 반영됐다.

의미가 명확했다. brandPrimary라는 이름만 봐도 쓰임새를 알 수 있었다.

팀 작업에서 일관성을 유지할 수 있었다.

✅ 단점

런타임 변수라서 CSS 클래스에서 직접 못 썼다.

인라인 스타일이나 styled-components 같은 데서는 바로 쓸 수 있었지만

Tailwind 유틸리티 클래스에서는 적용이 안 됐다.

실수로 하드코딩된 색상값을 넣을 가능성이 있었다.

코드리뷰나 규칙으로 강제해야 했다.

✅ 2️⃣ 단점 보완: Tailwind Config에 연동하기

이 방식의 가장 큰 문제는

“변수 기반으로 중앙 관리하면 좋은데, Tailwind 클래스에서는 못 쓰잖아?”

라는 부분이었다.

이를 해결하기 위해 Tailwind의 tailwind.config.js에서 토큰 객체를 불러와서 확장하도록 만들었다.

// tailwind.config.js
const { Colors } = require('./design-system/tokens/colors');

module.exports = {
  theme: {
    extend: {
      colors: Colors,
    },
  },
};

이렇게 하면:

Tailwind가 Colors 객체를 읽어서

bg-brandPrimary, text-brandPrimary 같은 유틸리티 클래스를 자동으로 생성하고

CSS 빌드 시 포함하게 만들었다.

✅ 런타임 이슈가 해결되는 이유

Tailwind는 빌드타임에 config를 읽고 → CSS 클래스를 생성한다.

JS 변수를 config에 넣으면 → 변수 기반으로 클래스를 미리 생성한다.

빌드된 CSS에는 단순히 클래스 이름과 색상값만 들어간다.

브라우저가 읽을 때는 변수 참조가 필요 없다.

결국

“JS 변수 기반 중앙 관리하면서도, Tailwind 클래스화 → 퍼포먼스 최적화 + 일관성 유지”

를 달성할 수 있었다.

👩🏻‍💻 심화 : tailwind plugin api 사용하기

보통은 tailwind.config.js의 extend.colors에 넣으면 bg-primary, text-primary 같은 클래스가 생긴다. 이 정도면 색상을 유틸리티로 쓰기에 충분하다.

문제: ring-color, outline-color는 자동 생성이 안 된다

그런데 디자인 시스템 명세가 이렇게 오면 곤란하다.

버튼 border는 primary, ring-color도 primary, outline-color도 primary로 맞춰주세요.

Tailwind가 기본적으로 ring-primary나 outline-primary는 만들어주지 않는다. bg, text, border까지만 지원하고 ring-color는 따로 지정해줘야 한다.

이렇게 되면 다음 문제를 만나게 된다.

✅ colors에는 primary가 정의되어 있는데 ❌ ring-primary 클래스는 존재하지 않는다.

해결책: Plugin API로 커스텀 유틸리티 생성

이 문제를 해결하기 위해 Tailwind의 Plugin API를 활용했다.

Tailwind의 plugin 함수에서 addUtilities를 쓰면, 원하는 규칙을 따라 유틸리티 클래스를 추가할 수 있다.

아래는 디자인 토큰의 색상을 border, ring-color 유틸리티로 변환해주는 플러그인 예시 코드다.

import plugin from 'tailwindcss/plugin';
import { colors } from './design-system/tokens/colors.js';

export default {
  theme: {
    extend: {
      colors,
    },
  },
  plugins: [
    plugin(({ addUtilities }) => {
      const colorUtilities = Object.entries(colors).reduce((acc, [name, value]) => {
        acc[`.border-${name}`] = { borderColor: value };
        acc[`.ring-${name}`] = { '--tw-ring-color': value };
        return acc;
      }, {});

      addUtilities(colorUtilities);
    }),
  ],
}

이 코드가 하는 일

colors.js에 아래처럼 디자인 시스템 토큰을 정의했다고 가정했다.

export const colors = {
  primary: '#4F46E5',
  secondary: '#7C3AED',
  error: '#EF4444',
};

Tailwind의 기본 확장으로는 이런 클래스만 만들어진다.

✅ bg-primary ✅ text-primary ✅ border-primary

하지만 ring-color 유틸리티는 없다.

플러그인 코드가 실행되면:

✅ .border-primary → border-color: #4F46E5 ✅ .ring-primary → --tw-ring-color: #4F46E5

이런 규칙을 자동으로 생성해준다.

결과적으로 얻은 것

디자인 토큰을 바꾸면 Tailwind 유틸리티가 한 번에 바뀐다. ring, border 등 모든 상태에서 디자인 시스템 색상을 일관되게 사용할 수 있게 됐다.

이제 버튼을 이렇게 쓰면 된다.

✅ 디자인 시스템의 색상이 수정되면 버튼의 border와 ring도 전부 바뀐다.

한 단계 더 확장하기

원한다면 outline, focus-visible 같은 상태까지 지원할 수도 있다. 예를 들어 아래처럼 규칙을 추가하면 된다.

acc[`.outline-${name}`] = { outlineColor: value };
acc[`.focus-visible-${name}`] = { outlineColor: value };

이렇게 하면:

✅ .outline-primary ✅ .focus-visible-primary

클래스도 자동 생성된다.

Tailwind CSS는 기본적으로 bg, text, border 색상 유틸리티만 토큰을 반영한다. 하지만 디자인 시스템에서는 ring, outline 같은 다양한 상태색상도 통일해야 할 때가 많다.

이걸 해결하기 위해 Plugin API를 써서 addUtilities로 규칙을 생성할 수 있다. 이 방법으로 디자인 토큰 변경이 Tailwind 전역 유틸리티 클래스에 일괄 반영되도록 만들 수 있다.

디자인 시스템을 코드화하고, 색상 토큰의 일관된 사용을 강제하고 싶다면 Tailwind Plugin 커스텀화를 고려해볼 만하다.

✅ 3️⃣ 폴더 구조 예시

디자인 시스템은 아예 별도 폴더로 관리하도록 설계했다.

design-system/
  ├── tokens/
  │     ├── colors.ts
  │     ├── typography.ts
  │     ├── spacing.ts
  │     └── ...
  ├── themes/
  │     └── light.ts
  ├── components/
  │     ├── Button.tsx
  │     └── ...
  └── index.ts

✅ tokens: 디자인 결정값 (색상, 간격, 폰트) → 싱글 소스 오브 트루스로 관리했다. ✅ themes: tokens을 조합해 테마를 정의했다. ✅ components: 반드시 tokens/테마에서 값을 가져와서 스타일을 적용하도록 했다.

✅ 4️⃣ 싱글 소스 오브 트루스(Single Source of Truth)

이게 디자인 시스템 설계에서 진짜 핵심이었다.

“디자인 결정값을 한 군데서만 관리하고, 거기가 바뀌면 앱 전체가 바뀌도록 한다.”

색상 팔레트가 바뀌면 → Colors.ts만 수정했다.

폰트 크기를 바꾸면 → Typography.ts만 수정했다.

Spacing 단위를 변경하면 → Spacing.ts만 수정했다.

결국 토큰이 디자인의 "진실의 원천(=Single Source of Truth)"이 되었다.

✅ 다른 말로는 디자인 토큰 저장소

디자인 시스템 변수

디자인 정의 계층

어떻게 부르든 중요한 건 → 중앙에서만 관리한다는 점이었다.

✅ 5️⃣ 결과적으로 얻은 이점

✔ 브랜드 리디자인이 필요하면 → 토큰 파일만 수정하면 됐다. ✔ 팀원들이 각자 색상을 새로 정의하지 못하게 강제할 수 있었다. ✔ 다크모드 / 라이트모드 테마 전환이 훨씬 쉽도록 설계할 수 있었다. ✔ Tailwind 유틸리티를 그대로 써서 → 퍼포먼스 최적화, Purge도 가능했다.

✅ 6️⃣ 최종 정리

내가 권장하는 방식은:

✅ 디자인 토큰을 TypeScript 객체로 관리했다. ✅ design-system 폴더에서 모든 디자인 결정을 중앙 관리했다. ✅ tailwind.config.js에서 이 토큰을 import해 → Tailwind 클래스 생성까지 자동화했다. ✅ 앱 컴포넌트에서는 클래스와 변수 둘 다 자유롭게 활용했다.

결국

"변수 기반 중앙 관리"와 "Tailwind의 퍼포먼스와 편의성"을 둘 다 잡을 수 있었다.

✅ 마무리

이 구조를 만들면서 나도 처음에는

그냥 colors.ts 하나 만들어서 변수만 쓰면 될 줄 알았다 → Tailwind에서 못 썼다.

tailwind.config.js만 쓰자 → JS 코드에서 못 썼다.

둘 다 유지보수는 어떻게 하지?

이런 고민을 거쳤다.

결국 “토큰 → Tailwind config 연동” 이 가장 깔끔하고 표준적인 해법이었다.

[i18n] i18n 영어 번역시 트러블슈팅

Thu, 26 Jun 2025 09:17:44 GMT

🛠️ i18n 영어 번역시 트러블슈팅

키값이 그대로 노출되는 문제 완벽 해결법

다국어 웹 서비스를 개발하다 보면, 영어 번역을 추가할 때 번역 키값이 그대로 화면에 노출되는 황당한 경험을 하게 됩니다. 예를 들어, t('leads.dashboard.period')를 호출했는데 화면에 leads.dashboard.period가 그대로 뜨는 현상입니다. 이 글에서는 왜 이런 일이 발생하는지, 한 번만 세팅하면 앞으로 다시는 이런 문제가 생기지 않게 만드는 방법을 실전 코드와 함께 정리합니다.

1. 문제의 원인

i18next(react-i18next)에서 번역 키가 번역 파일에 없을 때, 기본적으로 키값 자체를 반환합니다.

영어 번역 파일(en/translation.json)에 "leads.dashboard.period": "Period"가 없으면 t('leads.dashboard.period') 호출 시 화면에 leads.dashboard.period가 그대로 노출됨

이 현상은 번역 파일 관리가 조금만 소홀해도 자주 발생합니다.

2. 근본적인 해결책

(1) i18n 설정에서 키값 노출 방지 옵션 추가 i18n 초기화 시 아래 옵션을 추가하세요.

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    lng: 'ko',
    returnNull: false,         // 키가 없을 때 null 반환 방지
    returnEmptyString: false,  // 키가 없을 때 빈 문자열 반환 방지
    saveMissing: process.env.NODE_ENV === 'development', // 개발환경에서 누락 키 추적
    // ...기타 설정...
  })

returnNull: false, returnEmptyString: false → 키가 없을 때 null/빈문자열이 아닌 fallback 언어(예: 한국어)로 자동 대체 → 키값이 그대로 노출되는 현상 방지 saveMissing: true → 개발 환경에서 누락된 키를 자동으로 기록(콘솔, 서버, 파일 등) → 번역 누락을 빠르게 추적 가능

(2) 번역 파일 자동 동기화(권장) 모든 언어의 번역 파일에 동일한 키가 항상 존재하도록 자동화 스크립트(i18next-scanner, custom node script 등)로 관리 새 키가 추가되면 모든 언어 파일에 자동으로 추가(미번역은 빈 문자열 또는 "TODO" 등으로 표시) CI(빌드) 단계에서 누락된 키가 있으면 에러로 처리

3. 실전 적용 예시

i18n.ts 설정 예시

i18n
.use(LanguageDetector)
.use(initReactI18next)
.init({
  resources,
  fallbackLng: 'en',
  lng: 'ko',
  returnNull: false,
  returnEmptyString: false,
  saveMissing: process.env.NODE_ENV === 'development',
  // ...기타 설정...
})

번역 파일 예시 (en/translation.json)

{
"leads": {
  "dashboard": {
    "period": "Period"
  }
}
}

4. 앞으로의 번역 관리 팁

번역 파일에 키가 없을 때 화면에 키값이 그대로 뜨는 문제는 위 설정만 하면 더 이상 발생하지 않습니다. 개발 환경에서는 누락된 키를 자동으로 추적할 수 있어, 번역 누락도 빠르게 보완할 수 있습니다. 번역 파일만 잘 관리하면, 추가 작업 없이 안전하게 다국어 지원이 가능합니다.

5. 결론

i18n의 옵션 몇 줄만 추가해도, 영어 번역 추가 시 키값이 그대로 노출되는 문제를 완벽하게 예방할 수 있습니다. 한 번만 세팅해두면, 앞으로는 번역 파일만 잘 관리하면 되고, 키값 노출로 인한 당황스러운 상황이 반복되는 걸 방지할 수 있습니다.

[gitlab pages] gitlab pages로 배포하기

Thu, 26 Jun 2025 04:57:13 GMT

GitLab Pages로 React 프로젝트 배포하기

🎯 배포의 필요성

React + Vite로 개발한 mpi-skeleton 프로젝트를 GitLab Pages로 배포하기로 결정했습니다. GitHub Pages가 아닌 GitLab Pages를 선택한 이유는 프로젝트가 GitLab에서 관리되고 있었기 때문입니다.

또한 처음엔 vercel로 배포를 시도했으나, 회사 vercel 계정이 아직 무료 플랜었는데 gitlab 프로젝트는 그룹 내에 비공개 프로젝트로 위치해있어 무료버전으로는 배포가 불가능했습니다.

따라서 gitlab의 장점인 CI/CD 편리성을 활용해보고자 gitlab pages를 선택했습니다.

🛠️ 초기 설정과 첫 번째 시도

커스텀 도메인을 사용하지 않는 기본 배포 과정을 정리하였습니다.

GitLab CI/CD 설정 파일 생성 프로젝트 루트에 .gitlab-ci.yml 파일을 생성했습니다:

image: node:20.19.1
// node:latest 로 해도 되지만, 혹시 모를 node 버전 충돌을 막고자 특정 버전을 지정함

cache: paths: - node_modules/

pages: stage: deploy script: - npm ci - npm run build - cp -r dist/* public/ artifacts: paths: - public only: - main


2. Vite 설정 수정
`vite.config.ts` 파일 수정
```ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from "path";

export default defineConfig({
  base : '/',
  plugins: [react()],
  resolve: {
    alias: {
      "@": "/src",
    },
  },
  build: {
    outDir: path.resolve(import.meta.dirname, "dist"),
    emptyOutDir: true,
  },
})

추가 - 커스텀 도메인 사용하는 경우

.gitlab-ci.yml 파일 맨 아래에 variables 추가
```
variables:
CUSTOM_DOMAIN: "<커스텀 도메인>" 
```
public 폴더 내 CNAME 파일 추가 CNAME 파일 안에는 커스텀 도메인만 작성해둡니다.

public > .well-known > acme-challenge 폴더 생성 폴더 안에 .gitkeep 파일 생성 및 아래 내용 작성

 # 이 파일은 디렉토리 구조를 유지하기 위한 것입니다.
 # Let's Encrypt와 같은 SSL 인증서 발급 서비스가 acme-challenge 파일을 이 디렉토리에 저장합니다.

🚨 트러블 슈팅

1. 첫 번째 실패: TypeScript 컴파일 에러

src/App.tsx(46,7): error TS6133: 'LOARequestsPage' is declared but its value is never read.
src/components/mpi/ClaimsUnderReviewTable.tsx(195,36): error TS7053: Element implicitly has an 'any' type...

문제 : 사용되지 않는 변수 및 함수들, type 에러 등의 문제
해결 과정: 사용되지 않는 import들 제거 STATUS_CONFIG에 누락된 상태들 추가 (approved, rejected, cancelled) 타입 안전성을 위한 null 체크 구현 등

2. 두 번째 실패: public 폴더 없음 에러

cp: target 'public/': No such file or directory

문제 : 로컬에서는 분명 public 폴더가 있는데 build만 하면 public폴더가 없다고 한다. public폴더 내부에 아무 파일도 없어서 생긴 문제인 것 같았습니다.

해결책: .gitlab-ci.yml에 폴더 생성 명령어 추가

script:
- npm ci
- npm run build
- mkdir -p public  # 추가
- cp -r dist/* public/

3. 세 번째 실패: 배포 사이트 최초 접속시 뜨는 Redirecting 메시지

배포는 성공했지만 브라우저에서 접속 시 'Redirecting : ...' 라는 불필요한 리다이렉팅 화면이 떴습니다.

문제 : 배포 사이트의 접근 권한이 설정되어 있었기 때문!
해결 : ⭐️ 마지막엔 Setting > General > Visibility, project features, permissions > Pages 에서 배포 사이트 접근 권한을 전체공개로 바꿔줘야함! (기본 : only project members)

-> Redirecting 링크가 뜨고나서 사이트 접속되는걸 막고, 모두가 배포 사이트에 접속 가능하도록 설정하는 과정입니다.

🎉 배포 성공!!

배포에 성공했다면, 배포 주소를 확인해봅시다. 배포 링크는 Deploy > Pages에서 확인이 가능합니다.

main 브랜치를 배포했기 때문에, main 브랜치에 push혹은 merge를 하면 바로 재배포가 실행됩니다.

👍 총 정리

1단계: .gitlab-ci.yml 생성
2단계: Vite 설정 최적화
3단계: 로컬에서 오류 등 미리 해결
4단계: 배포 실행
5단계: 배포 확인 GitLab 프로젝트 → CI/CD → Pipelines에서 진행 상황 확인

💡 핵심 포인트 및 주의사항

.gitlab-ci.yml은 반드시 커밋: CI/CD가 작동하려면 저장소에 포함되어야 함

🔧 트러블슈팅 팁

404 에러 발생 시: base path 설정 재확인
빌드 실패 시: TypeScript 에러와 lint 에러 우선 해결
파일 경로 에러: public 폴더 생성 여부 확인

[Middleware] 임시 로그인 로직 리팩토링(local storage → httpOnly 쿠키)

Sun, 22 Jun 2025 11:10:06 GMT

임시 로그인 로직 리팩토링 과정 (local storage → httpOnly 쿠키)

📝 백엔드로부터 로그인 api를 받기 전, 프론트에서 권한 별 페이지 접근 제어를 해야 해서 임시 로그인을 구현하게 되었다. 처음에는 local storage로 임시 키를 넣었다 빼는 로직이 간편하니까 그렇게 진행했는데, 이후 미들웨어를 사용하면서 문제가 생겼다. 아래는 local storage에서 httpOnly 쿠키로 임시 로그인 로직을 리팩토링한 과정을 작성해보았다.

기술 스택

Next.js 프로젝트라서 httpOnly 쿠키를 주고 받는 백엔드 api를 임시로 작성할 수 있었다.

리팩토링 과정

처음엔 local storage에 값을 넣었다 뺐다 하는게 쉬우니까 그걸로 임시 로그인 로직을 구현해놨었음

사이드바 만들다보니 어쩔수없이(?) 인증 상태별 접근권한 설정이 필요해 구현

로그인 상태일때만 사이드바, 각 메뉴별 페이지가 보이도록 만들어야 했음
local storage, zustand로 로그인 상태 판별
‘/’, dashboard, login, layout.tsx, RootPage 에서 각자 로그인 상태 확인해서 리다이렉트 시켜주는 아주 복잡하고 파악안되는 거미줄이 되어버림
→ 미들웨어를 써서 컴포넌트 책임분리 및 가독성 향상 등등등을 노려야겠군!

사이드바 및 기본 인증 시스템 구현 (구 버전) SPRINT5.md

  # SPRINT 5: 사이드바 및 기본 인증 시스템 구현

  ## 주요 목표

  - Figma 디자인 기반의 사이드바 UI 컴포넌트 개발
  - 임시 로그인/로그아웃 기능 및 전역 상태 관리 시스템 구축
  - 사용자의 인증 상태에 따라 동적으로 라우팅 및 레이아웃을 제어하는 로직 구현

  ---

  ## ✅ 완료된 작업

  ### 1. 사이드바 UI 및 기능 구현

  - **Figma 분석 및 아이콘 에셋 추출**:
    - Figma 디자인을 분석하여 사이드바 레이아웃과 메뉴 구조를 파악했습니다.
    - 메뉴에 필요한 모든 아이콘을 SVG 형식으로 추출하여 `src/assets/svg/sidebar` 디렉토리에 저장했습니다.
    - `svgr` 라이브러리를 설정하여 SVG 아이콘을 React 컴포넌트로 직접 불러와 사용했습니다.

  - **`Sidebar` 컴포넌트 개발 (`src/components/layout/Sidebar.tsx`)**:
    - `usePathname` 훅을 활용하여 현재 URL 경로를 감지하고, 활성화된 메뉴 항목에 동적으로 하이라이트 스타일(배경색 변경)을 적용하는 클라이언트 컴포넌트를 생성했습니다.
    - 메뉴 항목들을 `Main`, `Workflows`, `Other` 등 논리적 그룹으로 나누어 구조화하여 코드의 가독성과 유지보수성을 향상시켰습니다.

  ### 2. 임시 인증 시스템 구축

  - **Zustand를 이용한 전역 상태 관리 (`src/store/useAuthStore.ts`)**:
    - `isLoggedIn` (로그인 여부), `isLoading` (인증 상태 확인 중) 상태와 `login`, `logout`, `checkAuth` 액션을 포함하는 전역 스토어를 생성했습니다.
    - `localStorage`를 사용하여 브라우저를 새로고침해도 로그인 상태가 유지되도록 구현했습니다.

  - **인증 관련 유틸리티 컴포넌트 개발 (`src/components/auth/`)**:
    - `AuthInitializer.tsx`: 앱이 처음 로드될 때 `localStorage`를 확인하여 전역 스토어의 인증 상태를 초기화하는 컴포넌트입니다.
    - `AuthButton.tsx`: 개발 및 테스트 편의를 위해 UI에 영향을 주지 않는 임시 '로그인'/'로그아웃' 토글 버튼을 추가했습니다.

  ### 3. 인증 기반 동적 라우팅 및 레이아웃 적용

  - **인증된 사용자 전용 레이아웃 분리 (`src/app/(authenticated)/`)**:
    - Next.js의 Route Group 기능을 사용하여 URL에 영향을 주지 않는 `(authenticated)` 그룹을 생성했습니다.
    - `(authenticated)/layout.tsx`: 해당 그룹에 속한 페이지들을 위한 공통 레이아웃을 생성했습니다.
      - 이 레이아웃은 사용자가 로그인 상태일 때만 `Sidebar`와 페이지 콘텐츠를 보여줍니다.
      - 로그인되어 있지 않은 사용자가 접근할 경우, 자동으로 로그인 페이지(`/login`)로 리다이렉트 시키는 보호 로직을 구현했습니다.
    - `(authenticated)/dashboard/page.tsx`: 로그인 후 가장 먼저 보게 될 대시보드 페이지를 생성하여 보호된 라우트 그룹 내에 배치했습니다.

  - **페이지별 접근 제어 로직 구현**:
    - **루트 페이지 (`/`)**: 사용자의 인증 상태를 확인하여 `/dashboard` 또는 `/login`으로 자동 리다이렉트 시키는 역할로 변경했습니다.
    - **로그인 페이지 (`/login`)**: 이미 로그인한 사용자가 접근할 경우, 불필요한 로그인 과정을 생략하고 즉시 `/dashboard`로 이동시키는 로직을 추가했습니다.

  ## ⚙️ 기술 스택 변경 및 추가

  - **`zustand`**: 전역 상태 관리를 위해 도입
  - **`clsx`**: 조건부 스타일링의 가독성 향상을 위해 사용

  ## 💭 회고

  이번 스프린트를 통해 어드민 시스템의 핵심 기능인 사이드바와 인증 기반의 페이지 접근 제어 시스템의 기반을 마련했습니다. 특히 Zustand와 Next.js의 Route Group을 활용하여 효율적이고 확장 가능한 구조를 설계하는 데 집중했습니다. 현재 인증은 `localStorage`를 이용한 임시 방식이므로, 다음 스프린트에서는 실제 백엔드 API와 연동하여 안전한 인증 시스템을 구축하는 작업이 필요합니다.

그래서 미들웨어로 접근권한 관리를 통일하려니까 갑자기 js-cookie인가 그 라이브러리를 설치해야된다그랬음
미들웨어는 서버에서 쓰는건데 local storage는 브라우저에서만 접근이 가능해서 해당 라이브러리로 로그인 확인을 해야된다고 했음
어차피 나중에 로그인 로직 백엔드랑 연결하면서 local storage도 안쓸거고, 아마 httpOnly 쿠키로 refresh token 갱신식으로 전달해주는 로직으로 전달해줄것 같은데, 그럴거면 이 임시 로그인 로직때문에 js-cookie 라이브러리까지 다운받아야된다고? 그건 안되지
그래서 임시 로그인 로직 자체를 바꾸는 방향으로 노선을 틀었음
1. next.js는 백엔드 api 로직 구현도 가능해서 좋다! httpOnly 쿠키에 값 넣었다 뺐다 하는 서버 api들을 만듦
2. zustand store에서 fetch로 httpOnly 쿠키에 접근하는 api에 연결하여 로그인 상태 확인하는 로직 구현!
AuthInitializer.tsx까지 만들어서 앱 처음 로드시 서버 실제 쿠키 상태와 클라이언트의 useAuthStore를 일치시키는 ‘최초 동기화’ 작업 수행하도록 추가

인증 로직 리팩토링 및 미들웨어 도입 SPRINT6.md

  # SPRINT 6: 인증 시스템 리팩토링 및 미들웨어 도입

  ## 주요 목표

  -   여러 컴포넌트에 흩어져 있던 인증 및 페이지 이동 로직을 **리팩토링**하여 중앙에서 관리
  -   Next.js 미들웨어를 도입하여 요청 단계에서 접근 제어를 처리하는 효율적이고 안전한 구조 구축
  -   `localStorage` 기반의 임시 인증을 `httpOnly` 쿠키 기반으로 변경하여 실제 백엔드 연동에 가까운 구조로 개선

  ---

  ## ✅ 완료된 작업: 인증 로직 리팩토링

  이번 스프린트는 새로운 기능 개발보다는, 기존에 구현했던 임시 인증 시스템의 구조적 문제점을 개선하는 **리팩토링**에 집중했습니다.

  ### 1. 인증 방식 변경: `localStorage`에서 `httpOnly` 쿠키로

  -   **문제점**: 기존 방식은 클라이언트 측 `localStorage`에 의존하여 미들웨어에서 접근이 불가능했고, 실제 프로덕션 인증 방식과 구조적 차이가 컸습니다.
  -   **리팩토링**:
      -   인증 상태를 관리하기 위한 임시 백엔드 API 라우트를 생성했습니다.
          -   `POST /api/auth/login`: 로그인 요청 시 `httpOnly` 속성을 가진 인증 쿠키를 생성합니다.
          -   `POST /api/auth/logout`: 인증 쿠키를 삭제합니다.
          -   `GET /api/auth/status`: 현재 쿠키 유무를 통해 로그인 상태를 반환합니다.
      -   `useAuthStore` (Zustand 스토어)가 `localStorage`를 직접 조작하는 대신, 위 API들을 `fetch`로 호출하도록 로직을 전면 수정했습니다.

  ### 2. 중앙 집중 제어: 미들웨어 도입 (`src/middleware.ts`)

  -   **문제점**: 로그인/로그아웃 상태에 따른 페이지 이동(리다이렉션) 로직이 `(authenticated)/layout.tsx`, `login/page.tsx`, `page.tsx` 등 여러 파일에 흩어져 있어 유지보수가 어려웠습니다.
  -   **리팩토링**:
      -   프로젝트 루트에 `middleware.ts` 파일을 생성하여 모든 접근 제어 로직을 통합했습니다.
      -   미들웨어는 사용자의 모든 페이지 요청을 가로채, 요청에 포함된 `auth-token` 쿠키의 유무를 확인합니다.
      -   인증 상태와 접근하려는 경로(공개/보호)를 비교하여, 서버단에서 직접 적절한 페이지로 리다이렉트 시킵니다.
      -   `matcher` 설정을 통해 API나 정적 파일 등 불필요한 경로에서는 미들웨어가 실행되지 않도록 최적화했습니다.

  ### 3. 컴포넌트 코드 단순화

  -   **문제점**: 여러 컴포넌트들이 인증 상태를 확인하고 페이지를 이동시키는 책임을 함께 가지고 있어 코드가 복잡했습니다.
  -   **리팩토링**:
      -   미들웨어가 모든 접근 제어를 담당하게 되면서, 각 페이지 컴포넌트에 있던 `useEffect` 기반의 리다이렉션 로직을 모두 제거했습니다.
      -   이를 통해 각 컴포넌트는 본래의 목적인 UI 렌더링에만 집중하게 되어, 코드가 훨씬 간결하고 명확해졌습니다.

  ## 🏁 리팩토링 결과 및 기대효과

  -   **유지보수성 향상**: 인증 관련 정책이 변경될 경우, 이제 `middleware.ts` 파일 하나만 수정하면 되므로 관리가 매우 용이해졌습니다.
  -   **구조적 개선**: 실제 프로덕션 환경에서 사용될 `httpOnly` 쿠키 기반 인증과 거의 동일한 아키텍처를 갖추게 되어, 향후 실제 백엔드 API와 연동 시 코드 변경을 최소화할 수 있습니다.
  -   **성능 및 안정성**: 클라이언트 측에서 여러 번 실행되던 리다이렉션 로직이 서버 요청 단계에서 한 번만 실행되므로, 불필요한 렌더링이나 화면 깜빡임 현상이 사라져 사용자 경험이 개선됩니다.

  ---

  ## 📝 아키텍처 변경에 따른 주요 컴포넌트 역할 재정의

  이번 리팩토링으로 인해 기존 컴포넌트들의 역할이 다음과 같이 명확하게 재정의되었습니다.

  -   **`middleware.ts`**: **페이지 접근 제어 담당**
      -   서버 요청 단계에서 쿠키를 검사하여, 허용되지 않은 페이지 접근을 막고 올바른 경로로 리다이렉트 시키는 **'경비원'** 역할을 전담합니다.

  -   **`useAuthStore` (Zustand 스토어)**: **클라이언트 UI 상태 관리 담당**
      -   페이지 이동 로직은 미들웨어에 위임하고, 이제 '로그인'/'로그아웃' 버튼 텍스트 변경이나 사용자 프로필 표시 등 **사용자에게 보여지는 UI를 제어하는 '상태 표시판'** 역할을 합니다.
      -   사용자가 '로그인' 버튼을 클릭했을 때, `/api/auth/login` API를 호출하는 액션을 트리거합니다.

  -   **`AuthInitializer.tsx`**: **서버-클라이언트 상태 동기화 담당**
      -   앱이 처음 로드될 때, `/api/auth/status` API를 호출하여 **서버의 실제 쿠키 상태를 클라이언트의 `useAuthStore` 상태와 일치시키는 '최초 동기화'** 작업을 수행합니다.
      -   이 과정을 통해 사용자가 로그인 상태임에도 불구하고 UI가 잠시 로그아웃 상태로 보이는 등의 깜빡임(flickering) 현상을 방지합니다.

[디자인 시스템] typography design system 구축 과정

Fri, 13 Jun 2025 02:04:13 GMT

typography 디자인 시스템 구축 과정

💬 타이틀, 서브 텍스트 등과 같이 모든 페이지에서 동일한 글꼴 크기, 색상, 굵기를 사용하고 있음에도 매번 css를 각각 직접 지정해주고 있었다. 공통된 텍스트 css를 매번 새로 지정하고 있는 비효율을 없애고, 동일한 글꼴 크기, 색상, 굵기를 사용하는 곳이라면 한 번에 가져와 사용할 수 있게 만들고 싶어서 typography design system을 구축하게 되었다.

기술스택

⚙️ next.js, tailwind css, postcss 기술스택에서 타이포그래피 디자인 시스템 구축 - tailwind만 쓰고 postcss는 결합되어있지 않았다면 @apply로 묶어서 디자인 시스템을 구축하는 방식을 사용하지 못함. > @apply는 Tailwind CSS에서 유틸리티 클래스들을 CSS 안에서 재사용 가능하게 해주는 문법 입니다. PostCSS가 있어야 @apply가 동작합니다. (@apply는 CSS의 표준 문법이 아니라 Tailwind가 PostCSS 플러그인을 통해 확장한 기능이기 때문입니다.) ➡️ 예전에 인턴할 때도 타이포그래피 속성을 묶고싶었는데, 그때도 tailwind를 쓰고있었으나 PostCSS를 결합하지 않고 기본 Tailwind CSS만 사용했기 때문에 @apply 문법 적용이 안돼서 실패한 기억이 있어 이번 프로젝트에서는 처음부터 Tailwind를 PostCSS와 함께 설치했다.

내가 원했던 것 ex)
- h1에 해당하는 사이즈, 폰트 굵기, 줄간격 등을 하나의 분류로 묶고 싶었음
- 반응형 적용할 수 있도록 하고 싶었음 (ex. 같은 h1임에도 모바일에서는 크기 몇, 데스크탑에서는 크기 몇 이런 식으로)
내가 적용한 방식
- app> styles> globals.css, typography.css (globals.css는 기본적으로 root에 있고 layout.tsx에서 import하고 있으므로, styles폴더로 옮길 경우 layout.tsx에서 import 경로 수정 필수!)
- globals.css에서 typography.css를 import
```
  @import "tailwindcss";
  @import "tw-animate-css";

  @import "./typography.css";
```
- typography.css 작성
  - 주의 : tailwind css import하는건 globals.css에서만 해야함 (typography.css에서는 @layer base { } 만 작성해야 함
```
@import "tailwindcss";
@import "tw-animate-css";
```
  - 예시
```
@layer base {
  /* Headings */
  .h1 {
    @apply text-[32px] font-bold leading-[1.31em];
  }

  .h2 {
    @apply text-[30px] font-bold leading-[1.4em];
  }

  .h3 {
    @apply text-2xl font-semibold leading-tight;
  }
}
```

[다국어 지원 의사결정] i18next와 react-intl 비교

Wed, 30 Apr 2025 07:56:28 GMT

💬 배경

필리핀 거래처 사이트를 제작하게 되어 다국어 지원을 알아보게 되었다. 사이트 기본 제공 언어는 영어이지만, 필리핀어(타갈로그어)와 한국어도 함께 지원하면 좋겠다는 생각이 들어 다국어 지원 기능을 알아보게 되었다.

이 프로젝트의 다국어 지원에서 중요한 점으로 아래의 3가지가 있었기에 이 점을 유의하여 비교 및 결정했다.

필리핀어(타갈로그어) 지원 여부
사이트 특성 상 통화 포맷 정확도 중요
next.js 기반 적용하기 때문에 플리커 랭귀지(flickering language) 현상 없어야 함

✨ i18next와 react-intl 비교

항목	🟦 i18next (+ next-i18next)	🟧 react-intl (FormatJS)
🧩 기본 개념	key-value 기반 번역 관리 (JSON)	메시지 ID 기반 포맷 + ICU 문법
✅ Next.js 호환성	`next-i18next`로 App Router/SSR 완전 지원	수동 설정 필요. App Router 지원 제한적
⚙️ 설정 난이도	상대적으로 쉬움 (자동 라우팅, 서버 전송 자동화 등)	복잡 (Provider 직접 설정, 수동 번역 로딩 필요)
💡 런타임 언어 변경 (클라이언트 전환)	`i18n.changeLanguage()`로 간단	상태 관리 및 Provider 교체 필요
📁 다국어 리소스 관리	언어별 JSON 파일 사용 (구조화 쉬움)	코드 내 메시지 ID로 직접 관리 (분산됨)
📉 플리커 방지 (SSR)	✅ `serverSideTranslations`로 완전 방지 가능	⚠️ 직접 설정 잘못하면 깜빡임 발생 가능
💬 복잡한 메시지 (성별, 복수형 등)	별도 플러그인 필요	✅ ICU 문법 기본 지원
💰 통화 / 날짜 / 숫자 포맷	`Intl.NumberFormat`, `Intl.DateTimeFormat` 직접 사용	✅ 내장 포맷 지원 (통화, 시간, 상대시간 등)
🌍 번역 SaaS 연동 (Lokalise 등)	연동 잘 됨	제한적, 직접 변환 필요
🔧 커스터마이징	namespace, fallbackLng 등 유연함	설정 제한적
🧱 커뮤니티 및 생태계	매우 크고 오래된 생태계	Facebook이 만든 안정적 프로젝트지만 규모는 작음
📦 패키지 크기	약간 더 무거움	상대적으로 가벼움

👉🏻 둘 중 i18next가 맘에 들었던 핵심적인 이유

App Router/SSR 자동 지원 (추가적인 설정 필요 X)
런타임 언어 변경 용이
플리커 방지 쉬움
next.js의 이점을 잘 살리면서 UX를 해치지 않는 라이브러리로, 도입의 결정적 계기!
커뮤니티 활성화가 잘 되어 있음 (다국어 지원 기능을 처음 도입하는 본인에게는 플러스 요인이 됨)

✅ i18next + next-i18next + Intl.NumberFormat 조합의 장단점

항목	장점 👍	단점 👎
🈂️ 다국어 지원	- JSON 기반 key-value 방식으로 관리 쉬움 - 필리핀어(`tl`), 영어(`en`), 한국어(`ko`) 지원에 문제 없음	- JSON 키가 많아지면 관리 복잡해질 수 있음
🔁 실시간 언어 전환	- 클라이언트에서 `i18n.changeLanguage()`로 즉시 언어 변경 가능 - 자동 쿠키 저장 기능으로 재방문 시 언어 유지	- SSR 시 초기 언어 설정 신경 써야 함 (기본값 정확히 세팅 필요)
📄 SSR / RSC 호환성	- `next-i18next`가 `getStaticProps` / `getServerSideProps`에서 SSR 최적화 처리 - App Router도 공식 지원	- 설정 파일 많아짐 (`i18n.js`, `next-i18next.config.js` 등)
⚠️ Flickering Language (플리커 방지)	✅ 서버사이드에서 언어별 번역 JSON을 미리 주입하기 때문에 깜빡임 없음	- 잘못된 `fallbackLng` 설정 시 혼란 발생 가능
💰 통화 / 숫자 포맷	- `Intl.NumberFormat` 으로 KRW, USD, PHP 등 정확한 통화 포맷 가능 예: `₩1,000`, `$1,000.00`, `₱1,000`	- 별도 포맷 함수 만들어야 함 (`i18next` 기본 기능 아님)
🛠 커스터마이징	- namespace, fallback, 로딩 전략 등 유연한 설정 가능	- 너무 세세한 설정은 초심자에게 부담될 수 있음
🌍 SaaS 연동 (Lokalise, Phrase 등)	- i18next와 연동 매우 잘됨 → 다국어 번역 관리 용이	- 사용 안 하면 무관
📦 생태계 및 유지보수	- 인기 많고 업데이트 활발함 - Next.js와 잘 맞음	- 설정 구조가 초반에 약간 번거로움

🧠 결론

✅ 다국어(필리핀어 포함) 지원이 안정적이고,

✅ SSR 기반이라 플리커 방지도 자동 해결되고,

✅ 통화 포맷 처리까지 Intl.NumberFormat으로 확실하게 관리 가능

✅ RSC(App Router)와의 궁합도 좋음

따라서, 이번 프로젝트처럼 통화 포맷 + 다국어 라우팅 + SSR 깔끔한 적용이 중요한 경우 👉 i18next + next-i18next + Intl.NumberFormat 조합이 가장 현실적이고 안정적인 선택!

[스타일링 방식 의사결정] CSS-in-JS와 tailwind css 비교

Wed, 30 Apr 2025 07:03:59 GMT