스타일링 이원화 전략 정리 글 ( ▶이동 )

먼저 스타일의 우선순위 선정이 필요했습니다.

이번 글은 스타일링 우선순위 선정을 주제로 아래 목차 순으로 진행해보겠습니다~

목차

1. 문제 상황 ( ▶이동 )

2. CSS Cascade Layer 개념 ( ▶이동 )

3. Tailwind layer 개념 ( ▶이동 )

4. 해결 전략 : Emotion Unlayered 설정 ( ▶이동 )

5. 환경별 세팅 ( ▶이동 )

6. 활용하기 위해 알아야 하는 개념들 ( ▶이동 )

0. Intro

Tailwind CSS(유틸리티 클래스)와 Emotion(CSS-in-JS)를 함께 사용하면 아래와 같은 장점들을 가져갈 수 있다.

• Tailwind : 빠른 레이아웃 구현, 간격, 반응형 처리
• Emotion : 컴포넌트 단위 스타일 캡슐화, 디자인 토큰 기반 스타일링, 상태 기반 동적 스타일링

하지만, 두 라이브러리를 함께 사용할 때 CSS 우선 순위 충돌 문제가 발생할 수 있다. 발생 원인과 CSS Cascade Layer를 활용한 해결 방법을 정리해본다.

1. 왜 스타일 충돌이 발생할까?

1-1. CSS 기본 우선 순위 규칙

CSS는 아래와 같은 세 가지 기준으로 우선 순위를 정한다.

1. Specificity : 선택자 구체성(#id > .class > tag)
2. Source Order : 나중에 선언된 스타일이 우선
3. !important : 모든 규칙을 무시하고 적용

1-2. Tailwind와 Emotion 충돌 지점

먼저 각각 생성 스타일을 살펴보겠다.

Emotion 생성 스타일

.css-abc123 { padding: 16px }

Tailwind 생성 스타일

.p-4 { padding: 1rem }

두 스타일 모드 클래스 선택자(.로 시작) 1개이므로 Specificity가 동일하다. 이 경우 Source Order(선언 순서)로 우선순위가 결정된다.

문제는 이 경우에 발생한다. 빌드 환경 A : Tailwind가 나중에 삽입 → Tailwind 승 빌드 환경 B : Emotion이 나중에 삽입 → Emotion 승

동일한 출력물도 빌드 환경, 번들러 설정, 청크 분할 방식에 따라 CSS 삽입 순서가 달라지므로 결과를 예측할 수 없다.

참고

• 빌드 환경 : React, Next.js 등
• 번들러 설정 : Vite, Webpack, Turbopack 등
• 청크 분할이란? : 하나의 큰 번들을 여러 개의 작은 파일(chunk)로 나누는 것

2. CSS Cascade Layer란?

2-1. @layer 개념

CSS Cascading and Inheritance Level 5 스펙에서 도입된 우선순위 그룹화 메커니즘이다.

@layer base, components, utilities;

@layer base {
    /* 가장 낮은 우선 순위 */
}

@layer utilities {
    /* 가장 높은 우선 순위 */
}

2-2. @layer 핵심 규칙

1. 선언 순서 === 우선 순위

@layer A, B, C에서 C가 우선 순위가 가장 높다. → Source Order

2. Layer > Specificity

상위 layer의 .class가 하위 layer의 #id를 이김 (#id > .class > tag )

3. Unlayered > Layered

@layer 밖의 스타일이 모든 layer보다 우선

2-3. 시각화

정리(핵심)

Layer를 사용하면 CSS 삽입 순서와 무관하게 우선순위가 고정된다!

3. Tailwind v4의 Layer 구조

3-1. Tailwind 기본 layer 구조

layer는 다음과 같이 4개의 layer로 구성된다.

• theme : CSS 변수, 테마 토큰
• base : Preflight(브라우저 초기화)
• components : @apply 기반 컴포넌트 스타일
• utilities : 유틸리티 클래스(p-4, mt-2 등)

3-2. Preflight란?

Tailwind에 내장된 브라우저 초기화 스타일이다. modern-normalize를 기반으로 하며, base layer에 포함된다.

주요 초기화 내용

• margin/padding 제거 : 모든 요소의 기본 여백 초기화
• border 리셋 : border: 0 solid;로 통일
• heading 스타일 제거 : h1~h6의 font-size, font-weight 상속
• list 스타일 제거 : ul, ol의 bullet/number 제거
• img block 처리 : 이미지를 display:block으로 설정

초기화 내용이 좀 익숙하였다.

*그렇다. reset.css와 중복된다. *

3-3. Tailwind v4 import 문법

Tailwind v4에서는 간결한 import 문법을 사용한다

@layer theme, base, components, utilities;

@import 'tailwindcss';

이 한 줄로 theme, preflight, utilities가 모두 포함된다.

만약 개별 import가 필요한 경우라면 아래와 같이 진행한다.

@layer theme, base, components, utilities

@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/preflight.css' layer(base);
@import 'tailwindcss/utilities.css' layer(utilities)

4. 해결 전략 : Emotion Unlayered 설정

4-1. 전략 선택 이유

Emotion에서 @layer를 직접 지원하는 방법을 검토했다.(with 클로드)

1. stylis 플러그인 커스텀 : Emotion 출력을 @layer로 감싸기 → 실용성 낮음. 불안정
2. CSS 후처리 : 런타임에서 style 태그 수정 → 실용성 낮음. 성능 이슈(런타임 비용 증가)
3. Unlayered로 유지 : Emotion을 layer 밖에 두기 → 실용성 높음. 안정적

Emotion v11이 현재 @layer를 네이티브로 지원하지 않는다. 커스텀 플러그인이나 후처리 방식은 복잡도가 높고, 안정성이 떨어진다.

결론

Emotion을 Unlayered로 두는 전략이 가장 실용적이다.

4-2. 최종 우선 순위

CSS 스펙 규칙상 Unlayered 스타일은 모든 Layered 스타일보다 우선한다.

따라서 Emotion 스타일이 항상 Tailwind보다 높은 우선순위를 가진다.

Tailwind로 레이아웃 → Emotion으로 컴포넌트 스타일링 순서가 자연스럽게 보장된다.

4-3. 설정 방법

1. globals.css

2. reset.css 삭제

Tailwind Preflight가 브라우저 초기화를 담당한다. 그러므로 기존 reset.css는 삭제한다. 중복 선언을 방지하고 유지보수를 단순화 할 수 있다.

4-4. 유틸리티 오버라이드가 필요한 경우

현재 전략은 Emotion이 Tailwind utilities보다 우선순위가 높다. 만약 특정 상황에서 Tailwind 유틸리티로 Emotion 스타일을 덮어써야 한다면 ! 접두사를 이용한다.

참고 !접두사는 해당 유틸리티에 !important를 추가한다. 남용은 하지말고..꼭 필요한 경우에만 사용하자..!

5. 환경별 설정 가이드

현재 나는 동시에 참여 중인 React, Next.js에서 모두 이원화 전략을 사용하고 있다. 맞다..그래서 2번의 세팅을 진행했다..( 주여.. )

5-1. React + Vite

1. globals.css

2. main.tsx

globals.css import만 하면 끝!!

5-2. Next.js(App Router)

Next.js에서 App Router에서 Emotion을 사용할 때는 SSR 대응을 위한 추가 설정이 필요하다.

1. app/globals.css

React와 동일하게 globals.css를 설정한다.

2. app/EmotionCacheProvider.tsx

참고 Emotion Hydration 해결 ( ▶이동 ) Emotion HTML 삽입 ( ▶이동 )

3. app/layout.tsx

5-3. 공통 확인 사항

• @layer 선언 위치 : CSS 파일 최상단에 위치하는 지
• 빌드 테스트 : dev/prod 환경에서 동일하게 동작하는지
• 브라우저 확인 : 개발자 도구에서 Computed 탭에서 적용된 스타일 확인

6. 알아야 하는 개념들

6-1. CSS

Cascade Layer(@layer)

• CSS 우선순위를 그룹 단위로 관리하는 메커니즘
• 삽입 순서와 무관하게 선언된 순서대로 우선순위 설정
• 나중에 선언된 layer가 높은 우선순위

Specificity vs Source Order

• Specificity : 선택자의 구체성(#id > .class > tag)
• Source Order : 동일 Specificity인 경우 나중에 선언된 스타일 우선
• @layer 사용 시 Layer 우선순위가 Specificity보다 먼저 적용됨

Unlayered vs Layered

• Unlayered : @layer 밖에 선언된 스타일
• Layered : @layer 안에 선언된 스타일

  우선 순위 : Unlayered > Layered

우선 순위 정리

Unlayered > Layered ( Layer > Source Order > *Specificity(#id > .class > tag) ) *

6-2. Tailwind

Preflight

• tailwind 내장 브라우저 초기화 스타일
• modern-normalize 기반
• base layer에 포함

layer 구조

• theme : CSS 변수, 테마 토큰
• base : Preflight, 기본 스타일
• components : @apply 기반 컴포넌트
• utilities : 유틸리티 클래스

  우선순위

  theme → base → components → utilities

v4 import 문법

• @import "tailwindcss"; 한줄로 전체 import
• 개별 import 시 layer( )함수로 맵핑

  여기서 주의해야할 점은,

  위에서 언급한 Preflight는 layer 개념으로 "tailwindcss"에 내장되어 있다.
  그래서 @layer를 사용할 경우 무조건@layer를 최상단에 선언한 뒤, @import "tailwindcss";를 위치시켜야 한다.
  @layer 선언 전에 @import "tailwindcss";를 진행한다면,이후 @layer 선언이 기존 구조를 덮어쓰거나 무시될 수 있다.

Tailwind 우선순위 선정 단계는 다음과 같다.

1. @layer 선언 : (theme→ base → components → utilities 순으로 렌더) 스타일시트 처리 시점에서 layer 우선순위 구조 확정
2. @import "tailwindcss"; : 이미 선언된 layer 안에 스타일 배치
3. @config(optional) : Tailwind 설정(tailwind.config.ts) 설정 적용

참고 Tailwind v4부터는 tailwind.config.ts를 사용하지 않는다. 다만, 나는 스타일링 이원화에 따른 중앙 관리형 타이포시스템 사용을 위해 추가로 설정했다.

6-3. Emotion 관련

런타임 스타일 생성

• 컴포넌트 렌더링 시점에 <style> 태그 동적 삽입
• 빌드타임에 CSS 파일을 생성하지 않음

cacheProvider와 createCache

• Emotion 스타일 캐싱 관리 : className 캐싱-중복 선언 방지를 위해
• key : 생성되는 클래스명 접두사(prefix)
• prepend : <style>태그 삽입 위치
  • true : head 최상단

prepend 옵션 주의

• prepend : true → head 최상단에 삽입 → 우선순위 낮아짐.
• @layer 사용 시 prepend 설정은 의미가 없음. layer 우선순위가 결정되기 때문에.

6-4. Next.js (App Router)

SSR과 CSS 삽입

• 서버에서 HTML 렌더링 시 스타일도 함께 추출
• 클라이언트 하이드레이션 후에도 스타일 유지 필요

Emotion Cache 패턴

• useServerInsertedHTML로 SSR시 스타일 삽입
• CacheProvider로 클라이언트 스타일 관리

7. 마무리

7-1. 핵심 요약

• 문제 상황 : Tailwind + Emotion 동일 속성 충돌, 빌드마다 출력되는 결과 다름
• 원인 : CSS 삽입 순서에 따른 Source Order 의존
• 해결 : CSS Cascade Layer로 명시적 우선순위 설정
• 전략 : Emotion을 Unlayered로 유지(최상위 우선순위)
• 오버라이드 : 필요 시 !접두사 사용

7-2. 체크리스트

1. globals.css 에 @layer 선언
2. reset.css 삭제(tailwind preflight로 대체)
3. Next.js 경우 EmotionCache 설정
4. dev/prod 빌드 테스트

( 이렇게 또 이슈 상황에서 살아남았다..! ) 내가 판 무덤같은 이원화 전략이지만, 이왕 선택한 김에 제대로 활용해보고 싶다. 언젠간 만날 클린 코드를 기다리며..글을 마칩니당~

참고 자료 Tailwind Preflight 공식 문서 MDN @layer Emotion Server Side Rendering 공식 문서 CSS Cascading and Inheritance Level 5

0. Intro

0-1. 자동 저장이란?

사용자가 직접 저장 버튼을 누르지 않아도, 데이터 변경이 감지되면 자동으로 서버에 저장되는 기능

대표적으로 Google Docs, Notion, Figma처럼 타이핑하는 순간 자동으로 저장되는 기능이 대표적이다.

0-2. 왜 필요할까?

Next.js 환경에서 그래픽 에디터 기능을 개발하면서 자동 저장의 필요성을 느꼈다.

에디터에서는 아래와 같이 작고 큰 다양한 변경들이 끊임 없이 발생했다.

• 작은 단위 변경 : 요소 1px 이동, 컬러 해시값 변경, 요소 내 컨텐츠 한 글자 변경 등
• 큰 단위 변경 : 작업물의 한 페이지 삭제 및 추가, n개 이상의 요소의 그룹을 복사 등

이 과정에서 브라우저 종료, 새로고침, 네트워크 끊김 등 예상하지 못한 상황이 발생하면, 작업 내역이 모두 날아갈 수 있다. 그리고 실제로 기능 테스트를 진행하면서 브라우저 새로고침이 일어나면, 모든 데이터가 날라가는 상황에서 많이 짜증이 나기도 했다..ㅎㅎ ( 디자인과 출신으로서 정말 그냥 죽고 싶은 순간 1위 )

사용자가 매번 저장 버튼을 누르는 것도 불편하고, 깜빡하면 데이터 손실로 이어진다.

자동 저장은 이런 문제를 해결하기 위해 구현해보기로 했다.

0-3. 구현 전략 : debounce + useMutation 조합

자동 저장은 아래 두 가지 핵심 전략을 사용했다.

• useMutation : 에디터 내부 작업물 데이터를 서버에 저장하는 요청 담당(▶ 이동하기)
• debounce : 불필요한 네트워크 요청을 줄이는 요청 제어 담당

둘을 조합하면 아래와 같은 흐름을 만들 수 있다.

1. 에디터 작업물 변경
2. debounce 대기
3. 일정 시간 후 useMutation 실행
4. 서버 저장
5. 걱정 없이 행복한 에디터 작업 진행

1. debounce란?

1-1. debounce 정의

연속된 이벤트 중 마지막 이벤트만 실행되도록 지연시키는 기법

만약 타이핑 중이라면, 타이핑을 멈추고(끝나고) n초 후에 실행한다고 이해하면 된다.

1-2. 자동 저장에서 debounce가 필요한 이유

만약, debounce 없이 자동 저장을 구현한다면, 어떤 상황이 발생할 수 있을까?

예시 상황 : input 창에 "안녕하세요" 타이핑

debounce 적용 전 - 총 5번의 API 요청이 일어난다. 1. "안" 입력 → API 요청 2. "녕" 입력 → API 요청 3. "하" 입력 → API 요청 4. "세" 입력 → API 요청 5. "요" 입력 → API 요청

debounce 적용 후 - 적용 전과 다르게 1번의 API 요청만 발생한다. 1. "안녕하세요" 입력 → 1초 대기 → API 요청

정리하자면, debounce를 통해 자동 저장을 구현하면 불필요한 네트워크 요청을 최소화하여 서버 부하를 줄이고, 통신 비용을 낮춰 앱 성능을 높일 수 있다.

2. Next.js App Router 환경 세팅

2-1. QueryClientProvider 세팅(App Router 기준)

Next.js App Router에서 QueryClientProvider를 사용하려면 별도의 클라이언트 컴포넌트가 필요하다. QueryClientProvider는 말그대로 Client Provider이기에 React Context 기반이기 때문이다. 즉, 서버 컴포넌트에서는 직접 사용할 수 없다.

'use client';를 사용하여 클라이언트 컴포넌트로 선언하여 Provider를 생성한다.

참고 useState로 QueryClient를 생성하는 이유는 매 렌더링마다 새 인스턴스가 생성되는 것을 방지하기 위함이다.

서버 컴포넌트인 RootLayout에서 Context를 전달할 자식 요소(children)를 생성한 Provider로 감싼다. 이러면 이제 Next.js환경에서 Tanstak Query 세팅이 끝난다.

참고 Tanstack Query 공식 문서

2-2. API 데이터 구조 설계

자동 저장 구현 전, API 요청 body와 Zustand store(CanvasState)를 동일한 JSON 구조로 설계했다.

구조를 동일하게 맞추면 별도 변환 없이 mutate(canvasState)으로 바로 넘길 수 있기때문이다. 백엔드와 응답 포맷을 사전에 조율한 덕분에 불필요한 작업 비용을 줄일 수 있었다.

3. 자동 저장 구현

3-1. 에디터 client 상태 관리(Zustand)

에디터의 클라이언트 상태는 Zustand store로 관리한다. CanvasState가 최상위 계층이며, 모든 에디터 데이터가 여기에 저장된다.

컴포넌트는 아래와 같이 store를 구독한다.

canvasState가 변경될 때마다 자동 저장이 트리거 된다.

3-2. useMutation으로 저장 요청 연동

3-3. debounce 적용 - 불필요한 네트워크 요청 최소화

useRef로 타이머를 관리하여 debounce를 구현했다. useRef를 사용하는 이유는 타이머가 리렌더링 시에도 초기화되지 않고, 유지되어야 하기 때문이다.

참고 clearTimeout(timerRef.current)는 컴포넌트가 언마운트될 때 대기 중인 타이머를 취소한다. 호출하지 않으면 언마운트 후에도 뒤늦게 API 요청이 발생할 수 있다.

이번 프로젝트에서는 debounce를 3분으로 정하였다.

판단 기준은 지극히 개인적이긴하다. (개발자 실격 포인트) 1분으로 설정하면 너무 많은 통신 비용이 발생할 것 같고, 생각보다 1분동안 많은 작업양이 발생하지 않았다. 그렇지만, 5분동안은 생각보다 작업양이 많았다. 만약 자동저장이 안되어서 데이터를 날리더라도 타격이 없고, 통신 비용이 많지 않은 범위는 '3분'이 적당하다고 판단했다.

( just one 3 minutes..내 것이 되는 시간..순진한..작동에 기뻐 우는 유저들.. )

3-4. 저장 상태 UI 표시

isPending, isError, isSuccess를 활용하여 저장 상태를 UI에 적용했다. 스타일링은 emotion/styled 기반으로 구현했다.

4. 전체 코드

자동 저장 컴포넌트 코드는 아래와 같다.

스타일링은 emotion/styled의 css helper를 활용하여 구현했다.(▶ 이동하기)

5. 마무리..

이번 글을 정리하면 다음과 같다.

• debounce로 연속된 상태 변경 이벤트를 제어하여 불필요한 네트워크 요청을 최소화한다.
• Next.js App Router에서 QueryClientProvider는 'use client' 컴포넌트로 분리하여 세팅한다.
• Zustand store(CanvasState)와 API 스키마를 동일한 JSON구조로 설계하면 별도 변환 없이 mutate(canvasState)로 바로 요청할 수 있다.
• useRef + setTimeout 조합으로 리렌더링 시에도 타이머를 유지하며 debounce를 구현한다.
• isPending / isError / isSuccess로 저장 상태를 UI에 표시 한다.

이번 기회에 Tanstack Query의 공식 문서를 제대로 살펴보게 되었다. 그곳은 노다지다..끝나지 않은 배움의 축복이...눈물이 살짝 고인다(행복의 눈물..ㅎㅎ)

0. Intro

1편의 이론을 간단히 정리하면 아래와 같습니다. ▶ 1편 이동하기

• useQuery : 서버 데이터를 "읽을 때" 사용하는 훅 (▶ 이동하기)
• QueryKey : 캐시를 식별하는 기준점(▶ 이동하기)
• staleTime/gcTime : 캐시의 신선도와 수명을 제어하는 옵션(▶ 이동하기)
  

이번 편에서는 데이터를 직접 쓰고(POST), 제어(수정(PUT,PATCH), 삭제(DELETE))하는 방식에 대해 알아보겠다.

• useMutation : 서버 데이터를 "쓸 때" 사용하는 훅 (▶ 1. useMutation이란?)
• useQueryClient : 캐시를 직접 제어하는 훅 (▶ 2. useQueryClient란?)

추가적으로 아래 요소들도 함께 다뤄보겠다.

• 에러 핸들링 : mutation 실패 시 처리 방법 (▶ 3. 에러 핸들링)
• 낙관적 업데이트 : 응답을 기다리지 않고 UI를 먼저 바꾸는 패턴 (▶ 4-1. 낙관적 업데이트)

1. useMutation이란?

서버 데이터를 생성(POST), 수정(PUT, PATCH), 삭제(DELETE)할 때 사용하는 훅 즉, 데이터를 "쓰는" 훅이다.

1-1. useQuery와 차이점

useQuery는 컴포넌트가 렌더링되면 자동으로 실행된다. 하지만, useMutation은 버튼 클릭, 폼 제출처럼 "특정 이벤트가 발생했을 때" 실행된다.

1-2. useMutation 기본 구조

• mutationFn : 실제 API 요청을 담당하는 함수. Promise를 반환하면 된다.
• onSuccess : 요청이 성공했을 때 실행되는 콜백. 응답 데이터(data)를 인자로 받는다.
• onError : 요청이 실패했을 때 실행되는 콜백. 에러 객체(error)를 인자로 받는다.
• onSettled : 성공/실패 여부와 상관 없이 항상 실행되는 콜백. try-catch의 finally와 동일 개념

참고 Tanstack Query 공식 문서

1-3. useMutation 반환값

useMutation이 반환하는 주요 값들은 아래와 같다.

• mutate : mutation을 실행하는 함수. 이벤트 핸들러에서 호출한다.
• isPending : 요청 진행 중 여부 (boolean값)
• isError : 에러 발생 여부 (boolean값)
• error : 에러가 발생한 객체

반환값 사용 방식은 두 가지이다. 상황에 맞게 편한 방식을 선택하여 사용하면 된다.

참고 mutate와 mutateAsync 두가지가 있다.

• mutate : 콜백(onSuccess, onError) 방식으로 결과 처리
• mutateAsync : Promise를 반환하여 async/await으로 결과 처리
  [Tanstack Query 공식 문서](https://tanstack.com/query/latest/docs/framework/react/guides/mutations#promises)

useMutation 선언과 반환값의 전체 코드는 다음과 같다.

1-4. 예제 코드

게시글을 작성하는 POST 요청 예제이다. 위의 예시코드의 작동 화면이다.

2. useQueryClient란?

QueryClient 인스턴스에 접근하여 캐시를 직접 제어하는 훅

지난 글에서 QueryClient는 모든 캐시를 저장하는 핵심 인스턴스라고 설명했다. useQueryClient는 해당 인스턴스에 접근하여 캐시를 읽거나 수정할 수 있게 해준다.

use로 시작하니, React의 Hook개념이 베이스인거 잊지말기!

위와 같은 방식으로 선언하여 사용한다.

참고 Tanstack Query 공식 문서

2-1. invalidateQueries : 캐시 무효화

특정 Query Key의 캐시를 "오래된 것(stale)"으로 표시하여 자동으로 재요청 유발

mutation으로 데이터를 변경했을 때, 기존 캐시가 최신 데이터를 반영하지 못하는 상황이 발생한다. invalidateQueries를 호출하면, 해당 캐시를 stale 처리하고, 화면에서 사용 중인 경우 자동으로 재요청하여 최신 데이터로 갱신한다.

참고 Tanstack Query 공식 문서

2-2. setQueryData : 캐시 직접 수정

특정 Query Key의 캐시 데이터를 직접 수정. API 재요청 없이 캐시를 업데이트 할 때 사용한다.

invalidateQueries는 서버에 재요청하여 최신 데이터를 받아오는 방식이라면, setQueryData는 서버 요청 없이 캐시만 직접 수정한다.

주로 낙관적 업데이트(4. 낙관적 업데이트)에서 사용된다.

참고 Tanstack Query 공식 문서

2-3. 예제 코드

게시글 작성 후 목록 캐시를 갱신하는 실제 코드이다. onSuccess에서 invalidateQueries를 호출하면, 게시글 작성 성공 후 자동으로 목록을 다시 불러온다.

3. 에러 핸들링

3-1. onError 콜백

mutation 실패 시 onError 콜백에서 에러를 처리할 수 있다.

참고 onSettled는 mutation 상태(성공, 실패)와 무관하게 모두 실행된다. 캐시 무효화처럼 결과에 관계없이 항상 실행해야 하는 로직은 onSettled에 두는 것이 좋다.

3-2. isError/error 반환값 활용

isError와 error를 활용하면, UI에서 직접 에러 상태를 표시할 수 있다.

위의 예시코드를 구현한 화면이다.

4. useMutation + useQueryClient 함께 사용하는 패턴

4-1. 낙관적 업데이트(Optimistic Update)란?

서버 응답을 기다리지 않고, 요청이 성공할 것이라 '낙관'하고 UI를 먼저 업데이트 하는 패턴

일반적인 요청 흐름과 비교한다면 다음과 같다.

일반적인 흐름

요청 → (대기) → 서버 응답 → UI 업데이트

낙관적 업데이트 흐름

요청 → UI 즉시 업데이트 → 서버 응답 → (실패 시 rollback)

서버 응답을 기다리는 동안 UI가 멈춰있지 않기 때문에 사용자 경험(UX)이 향상된다. 인스타그램의 좋아요 버튼이 대표적인 예시이다. 버튼을 누르는 즉시 하트가 채워지고, 실패 시에만 원래대로 돌아온다.

4-2. onMutate + onError rollback 흐름

낙관적 업데이트는 onMutate, onError, onSettled 세 콜백을 조합하여 구현한다.

• onMutate : 요청 직전. 현재 캐시를 백업하고, UI를 먼저 업데이트
• onError : 요청 실패. 백업해둔 캐시로 rollback
• onSettled : 요청 완료 후. 서버 데이터와 최종 동기화(invalidateQueries)

4-3. 예제 코드

실제 게시글 스크랩 버튼 기능을 낙관적 업데이트로 구현한 코드이다.

참고 cancelQueries란? (onMutate 내 await 부분) 진행 중인 refetch 요청을 취소한다. 낙관적 업데이트 직전에 호출하지 않으면, 진행 중이던 refetch 응답이 낙관적으로 업데이트한 캐시를 덮어쓸 수 있다.

해당 코드를 실제로 구현하면 아래와 같이 작동한다.

5. 마무리..

이번 글에서 다룬 내용을 정리하면 아래와 같다.

• useMutation 으로 서버 데이터를 생성, 수정, 삭제한다.
• onSuccess, onError, onSettled 콜백으로 요청의 성공, 실패, 완료 시점을 처리한다.
• useQueryClient의 invalidateQueries로 캐시를 무효화하여 목록을 자동 갱신한다.
• useQueryClient의 setQueryData로 서버 요청 없이 캐시를 직접 수정한다.
• onMutate + onError rollback 패턴으로 낙관적 업데이트를 구현한다.

이제 Tanstack Query의 핵심은 파악했다! ( 하지만 배움의 축복은 끝나지 않는다... 공식 문서에 축복들이 잔뜩 있다.. )

다음편에서는 지금까지의 이론을 바탕으로 Next.js 환경에서 자동 저장 기능을 직접 구현한 과정을 작성해 볼 예정이다.

참고 ▶ 🔗 Tanstack Query 공식 문서

0. Intro

0-1. 상태 관리란?

상태(State)란, "컴포넌트가 기억하는 값"이다. 버튼을 "클릭 했는지", 모달이 "열려있는지", 입력창에 "뭘 썼는지" 등 이런 "값"들을 관리하는 것이 상태 관리이다.

상태는 크게 두 종류로 나뉜다. 위에서 언급한 것 처럼 UI와 관련된 상태가 있고, 그와 별개로 서버에서 가져오는 데이터가 있다. 그렇다면, 서버 데이터의 상태란 뭘까?

0-2. 서버 상태 관리란?

게시글 목록, 유저 프로필, 상품 정보처럼 API를 호출해서 받아오는 데이터가 바로 서버 상태다. 이 데이터를 '언제 가져오고', '언제 다시 가져오고', '어떻게 저장할지' 관리하는 것이 서버 상태 관리다.

0-3. 클라이언트(client) 상태 VS 서버(server) 상태

두 환경의 상태 차이를 표로 정리하자면 아래와 같다.

클라이언트(client) 상태는 내가 완전히 제어할 수 있다.

하지만, 서버(server) 상태는 아래와 같다.

• 제어할 수 없거나, 소유하지 않은 원격 위치에 저장된다.
• 데이터 가져오기 및 업데이트를 위해 비동기 API가 필요하다.
• 데이터를 다른 사람이 나의 동의 없이 변경할 수 있다.
• 어플리케이션에서 최신화되지 않은 데이터가 표시될 수 있다.

정리하자면, 서버(server) 상태는 서버가 언제든 바뀔 수 있고, 내 앱은 그걸 가져다 쓰는 입장이다. 즉, 내가 완전히 제어 "불가능"한 상태이다.

서버 상태 정의 참고 문헌

0-4. 서버 상태 관리가 어려운 이유

fetch + useState 만으로 서버 데이터를 다룰때, 주로 아래와 같은 코드를 작성했다. 데이터를 하나 가져오는데, state가 3개다. ( 🤢 🤮 ) 그리고 이 방식은 아래와 같은 한계들이 있다

• 캐시(Cache)가 없다. : 페이지를 이동했다 돌아오면, 다시 요청해야한다.
• 중복 요청을 막기 어렵다. : 같은 데이터를 여러 컴포넌트에서 각자 요청한다.
• 데이터가 오래됐는지 모른다. : 서버가 바뀌어도 내 화면은 그대로다.
• 보일러플레이트가 많다. : 매번 로딩/에러 상태(state)를 직접 만든다.

위의 한계들을 해결하기 위해 나온 것이 Tanstack Query(React Query)이다.

1. Tanstack Query(React Query)란?

공식 문서의 표현을 가져오면 아래와 같다.

서버 상태를 fetching, caching, synchronizing, updating하는 라이브러리 참고

Tanstack Query 라이브러리는 "서버 데이터를 가져오고, 캐싱하고, 최신 상태로 유지해주는 도구"이다.

참고로 원래 이름은 React Query였다. React 외의 다양한 프레임워크(Vue, Angular, Svelte 등)를 지원하면서 Tanstack Query로 이름을 바꾸었다.

React 환경에서 사용시 @tanstack/react-query를 설치하여 사용하면 된다.

참고 취준시 JD에 Tanstack Query과 React Query를 혼용해서 작성되는 경우가 많다. 같은 라이브러리이지만, 혹시 모르니 JD 요구 기술 스택에 맞게 서류를 꼼꼼히 수정하자..!

이제부터 Tanstack Query 사용법을 알아보겠다.

1-1. QueryClient / QueryClientProvider

Tanstack Query를 사용하려면, 먼저 앱 전체를 QueryClientProvider로 감싸야한다.

QueryClient

캐시를 관리하는 핵심 인스턴스. 모든 쿼리의 데이터가 여기에 저장된다.

QueryClientProvider

QueryClient를 Context로 앱 전체에 전달한다. React의 Context API와 동일한 방식이다.

참고 Context란? React에서 컴포넌트 간 데이터를 공유하기 위한 객체다. createContext()로 생성하며, Provider로 감싼 하위 컴포넌트 어디서든 해당 데이터에 접근할 수 있다.
React의 Context API란? React의 컴포넌트 트리 전체에 데이터를 전달하는 기능이다. 일반적으로 props는 부모 → 자식으로만 데이터를 전달할 수 있지만(props drilling 발생), Context를 사용하면 중간 컴포넌트를 거치지 않고 원하는 컴포넌트에 바로 데이터를 전달할 수 있다.

1-2. Query Key

캐시의 기준점

Tanstack Query는 모든 캐시를 Query Key를 기준으로 "식별"한다. Query Key가 같으면 같은 데이터로 취급한다.

Query Key는 "배열 형태"로 작성한다. 예시 이미지를 보면 키의 형식이 2가지이다.

단순한 키

고정된 값이다. 항상 동일한 데이터를 가져올 때 사용한다.

동적인 키

변하는 값이 포함된 키이다. 특정 데이터를 하나씩 식별할 때 사용한다.

이미지 속 예시 코드인 ['posts', 1]과 ['posts', 2]는 서로 다른 캐시이다. ** **queryKey는 동일하지만, 배열의 두번째 요소(id)가 다르기 때문이다.

동적인 키가 필요한 이유는 다음과 같다.

• 고정된 값인 게시글 목록(['posts'])은 하나지만,
• 게시글 목록 안 특정 데이터인 게시글 상세(['posts', 1], ['posts', 2])는 id마다 데이터가 다르다.

즉, id별로 캐시를 따로 관리해야 하므로, 배열에 유니크한 값인 id를 추가해 키를 구분한다.

React의 useEffect 의존성 배열과 비슷한 개념이라 생각하면 된다. postId가 바뀌면 Query Key도 바뀌고, 이를 기반으로 Tanstack Query가 자동으로 새 데이터를 요청한다.

Query Key 덕분에 같은 데이터를 여러 컴포넌트에서 요청해도 실제 API 호출은 한 번만 일어난다.

1-3. staleTime/gcTime

데이터를 얼마나 믿을건지

캐시된 데이터를 언제까지 "신선하다"고 볼건지, "언제 지울 건지"를 제어하는 두가지 옵션이다. 표로 표현하자면 아래와 같다.

참고 gcTime은 v4까지 cacheTime이라는 이름이었다. v5에서 gcTime으로 변경되었다.

staleTime를 5분으로 설정하면, 같은 쿼리를 5분 안에 다시 호출해도 API 요청 없이 캐시 데이터를 바로 반환한다.

각 모듈의 작동 흐름은 아래와 같다.

⌛ 예시 상황 : 게시글 목록 페이지에 진입했다가, 10분 후 다시 돌아온 경우

1. 첫 진입

• 1-1. queryFn 실행 (API 요청)
• 1-2. 데이터 캐시에 저장
• 1-3. staleTime 5분 타이머 시작
  

  2-1. [ staleTime ] 5분 이내 재진입

• API 요청 없음 → 캐시 데이터 그대로 사용 (fresh 상태)
  

  2-2. [ staleTime ] 5분 이후 재진입

• *⭐ "핵심" 캐시 데이터를 먼저 보여줌 (stale 상태) *
• 백그라운드에서 queryFn 재실행 (API 재요청) → 새 데이터로 교체
  2-2번은 핵심 동작이다. stale 상태여도 빈 화면이 아니라 기존 캐시를 먼저 보여주면서 백그라운드에서 갱신한다. 사용자 입장에선 로딩 없이 바로 데이터가 보이기에 UX가 향상된다.
  

  3. [ gcTime ] 10분 동안 해당 쿼리를 아무도 사용하지 않으면

• gcTime 만료 → 캐시 메모리에서 삭제
• 다음 진입 시 queryFn 재실행

자 이제 기본 작동 원리는 파악이 됐다. 이제 useQuery에 대해 설명해보겠다.

2. useQuery 기본 사용법

2-1. useQuery란?

Tanstack Query에서 데이터를 가져올 때 사용하는 핵심 훅(Hook)
참고 훅(Hook)이란?

• 함수 컴포넌트에서 React의 state, lifecycle 등을 사용할 수 있게 해주는 함수.
• React의 state, lifecycle을 사용하면 클래스 컴포넌트 없이 함수 컴포넌트만으로 구현이 가능하다. 클래스 컴포넌트는 this, constructor 등 보일러플레이트가 많고 코드가 복잡해지는 단점이 있었지만, 훅의 등장으로 함수 컴포넌트로 동일한 기능을 구현하고, 코드가 간결해졌다.
• use로 시작하는 컨벤션이 있다.(useState, useEffect, useQuery ...)

• queryKey : 캐시 키.
• queryFn : 데이터를 가져오는 비동기 함수. fetch, axios 상관 없이 Promise를 반환하면 된다.

2-2. 반환값 읽기

useQuery가 반환하는 주요 값들을 예시 코드로 작성해보았다.

• data : 성공적으로 가져온 데이터
• isLoading(isPending) : 최초 로딩 중 여부(boolean값)
• isError : 에러 발생 여부(boolean값)
• error : 발생한 에러 객체

참고 v5에서 isLoading이 isPending으로 변경되었다. 두 이름이 혼용되는 글들이 많다!

2-3. 예제 코드

실제로 사용 예정인 '게시글 목록을 불러오는 기능' 예제 코드다.

게시글 목록 : Feed 게시글 : Post
1 Feed : N Post

먼저 feed의 api 메소드 코드 예시이다.

다음은 api 메소드를 queryFn에 넣은 실제 컴포넌트 코드 예시이다.

위에서 fetch + useState 예시(0-4)보다 코드가 훨씬 짧아지고, Tanstack Query가 캐싱과 중복 요청 방지를 알아서 처리해준다.

3. 마무리..

이번 글에서 다룬 내용을 정리하면 아래와 같다.

• 서버 상태는 클라이언트 상태와 의미가 다르다. 서버 상태는 서버가 주도권을 갖는 데이터다.
• Tanstack Query는 서버 상태를 불러오고, 캐싱하고, 정합성을 유지한다.
• QueryClient가 캐시를 관리하고, QueryKey가 캐시를 식별한다.
• staleTime, gcTime으로 캐시의 신선도와 수명을 제어한다.
• useQuery로 데이터를 가져오고, data/isLoading/isError로 상태를 다룬다.

참고 정합성이란? 서버와 클라이언트(혹은 DB) 간의 데이터가 서로 일치하고 모순이 없는 상태를 의미한다.

이제 Tanstack Query를 제대로 활용하기 위해 데이터를 변경할 때 사용하는 useMutation, 캐시를 직접 건드리는 useQueryClient를 다뤄볼 예정이다.

참고 ▶ 🔗 Tanstack Query 공식 문서

이전 해커톤 후기 글에 스타일링 이원화 전략에 대해 짧게 정리했었다. Emotion은 _상태 변화가 빈번한 컴포넌트_에, Tailwind는 _정적 레이아웃 영역_에 사용했다.

당시에는 각자의 장점만 골라쓰자는 관점에서 결정했고, 실제로 개발하면서 나쁘지 않다고 느꼈었다. 그런데 아래와 같은 의문점들이 생기기 시작했다.

• 이 기준이 이론적으로도 맞는 선택일까?
• 실제로 경계가 모호해지는 순간에 어떻게 해야할까?
• 어떤 상황에서 이 전략이 잘 작동하고, 어떤 상황에서 삐걱거릴까?

이런 의문점들을 해결해보기 위해 조금 더 깊게 접근해보았다.

1. Tailwind VS Emotion 차이

먼저 두 라이브러리가 "어떤 문제"를 "어떻게 해결"하는지를 비교해본다.

1-1. Tailwind

" 빌드 타임 유틸리티 클래스 "

Tailwind는 미리 정의된 유틸리티 클래스를 HTML에 직접 붙이는 방식이다

유틸리티(Utility)란? 하나의 목적만 수행하는 도구. 단일 기능에 집중된 작은 단위. 복잡한 일을 하는 게 아니라, 한 가지 일을 명확하게 처리하는 것이 목적이다.

즉, Tailwind에서 유틸리티 클래스란 'CSS 속성 하나' == '클래스 하나'를 의미한다.

Tailwind는 스타일을 빌드 타임에 처리한다.

빌드 타임이란? " 컴파일 → 빌드 → 런타임 "

• 컴파일 : 소스코드를 브라우저가 이해할 수 있는 형태로 변환 (TS → JS, JSX → JS)
• 빌드 : 컴파일 + 번들링 + 최적화까지 포함한 전체 과정 (npm run build)
• 런타임 : 브라우저에서 실제로 실행되는 시점

브라우저가 페이지를 렌더링할 때 Tailwind가 하는 일은 없습니다. 런타임에 스타일을 계산하거나 삽입하지 않는다.

즉, 런타임 비용이 없다. Tailwind의 가장 큰 장점이다.

1-2. Emotion

" 런타임 CSS-in-JS "

Emotion은 JavaScript 안에서 스타일을 작성하고, 런타임에 CSS를 생성해 DOM에 삽입한다.

props를 받아서 그 값에 따라 스타일을 동적으로 계산한다. 이 계산은 컴포넌트가 렌더링될 때마다 발생한다.

1-3. 런타임 VS 빌드 타임

두 라이브러리를 표로 비교했다.

2. 이원화 전략 기준선

두 라이브러리의 특성을 파악했으니, 이제 어떤 스타일을 누가 담당할지 기준을 잡아봤다.

2-1. Tailwind 담당 영역

" 정적 레이아웃 "

Tailwind는 상태와 무관하게 고정된 스타일에 강하다.

• 페이지 레이아웃 : flex, grid, gap, padding 등
• 반응형 브레이크 포인트 : md:, lg:
• 고정된 색상, 테두리, 그림자
• spacing 시스템 기반의 여백

이 영역은 런타임에 바뀔 일이 없다. Tailwind가 빌드 타임에 처리하고 끝내는게 최적이다.

2-2. Emotion 담당 영역:상태 기반 동적 스타일링

" 상태 기반 동적 스타일링 "

Emotion은 JS 상태가 스타일에 직접 영향을 주는 영역에서 진가를 발휘한다고 생각한다.

• 상태에 따라 색상, 크기, 형태가 달라지는 컴포넌트
• 디자인 토큰 기반 theme 연동
• 여러 variant를 객체로 관리하는 UI 컴포넌트
• **인터랙션(hover, focus)이 JS 상태와 연동되는 경우
• *

2-3. 경계가 모호한 케이스

" 어떤 라이브러리로 구현해야할까? "

실제로 라이브러리 선택이 모호할 때, 나는 아래 기준으로 선정했다.

1. JS 변수(상태, props)가 스타일 값 자체에 직접 영향을 주는가?

• YES → Emotion
• No → Tailwind ( 단순히 클래스 2개 토글 수준 )

  2. variant가 3개 이상이거나 앞으로 늘어날 가능성이 있는가?

  : Tailwind의 조건부 클래스 조합은 variant가 늘어날수록 관리가 어려움 → Emotion

  3. 테마 토큰(디자인 시스템 변수)을 참조해야하는가?

• → Emotion*

  4. 스타일을 별도 파일로 분리하여 관리하는가?

  (ui.tsx / style.ts / type.ts로 나누고 page에서 조합하는 구조)
• YES → Emotion (style.ts에서 styled component로 관리 )
• No → Tailwind ( 마크업 안에서 바로 처리 )

단순 토글 정도라면 Tailwind의 조건부 클래스로 처리해도 충분하다. 복잡도가 올라가는 순간 Emotion으로 가져오는 것이 유지보수에 유리하다 생각한다.

3. 실제 예시

실제로 내가 어떻게 사용했는지 코드를 살짝 공개해보겠다.

3-1. Tailwind로 레이아웃 작업

레이아웃 골격은 Tailwind로 빠르게 잡았다. 별도의 파일 없이 마크업 안에서 즉시 확인이 가능하다.

3-2. Emotion으로 상태 스타일 작업

variant가 늘어나도 토큰만 추가하면 된다. 만약 이걸 Tailwind 조건부 클래스로 구현했다면, className 문자열 복잡도가 빠르게 증가했을 것이다.

3-3. 같은 컴포넌트 안에서 공존

Tailwind와 Emotion이 같은 파일 안에 있다. 처음에는 조금 어색했지만, 고정된 것은 className, 달라지는 것은 emotion이라는 규칙을 잡으면 읽기에 어렵지 않다.

4.이 전략의 트레이드오프

저번 프로젝트에서는 빠르고 동적인 스타일 구현에만 초점을 두고 구현했지만, 앞으로는 아래 요소들을 고려하여 선택을 진행하려고 한다.

4-1. 번들&런타임 비용

Tailwind의 가장 큰 장점 중 하나는 런타임 비용이 0(Zero)라는 점이다. 반면, Emotion은 컴포넌트가 렌더링될 때마다 스타일을 직렬화하는 비용이 발생한다.

두 라이브러리를 함께 쓰면 Tailwind가 커버하는 영역에서의 런타임 절약은 의미가 있다. 다만 Emotion 쪽의 런타임 비용은 그대로 남는다.

그러므로, 빠른 구현과 반응형 레이아웃이라는 이점만을 챙기고 싶다면 이번 이원화 전략은 좋은 선택이지만, 런타임 비용 최적화가 필요한 상황이라면 필요 없는 전략이다.

4-2. 경계가 흐려질 때 생기는 일

초반엔 명확한 경계_( 정적 레이아웃 VS 상태 기반 동적 컴포넌트 )_가 존재했지만, 점점 경계가 모호해지는 순간들이 발생할 수 있다.

예를 들면 아래와 같은 순간들이다.

const Button = styled.button`
  display: flex;        // ← 이건 Tailwind로 가야 하지 않았나?
  align-items: center;  // ← 이것도
  gap: 8px;             // ← 이것도
  background: ${({ isActive }) => isActive ? '#1BCBA3' : '#e5e7eb'};
`;

레이아웃 스타일 _( flex, grid, gap, padding )_이 emotion안으로 침범하는 순간들이 생긴다. 이러한 순간이 점점 많아진다면, 결국 두 라이브러리의 역할 구분이 섞이고, 이원화의 의미가 없어진다.

해결책으로는 명확한 기준을 문서화하는 것을 추천한다.

나는 아래와 같은 기준을 세우고 작업을 진행했었다. 뷰포트 조건(반응형)에 따른 스타일 변화는 Tailwind, JS 상태에 따른 스타일 변화(state, props)는 Emotion을 선택하였다.

4-3. SSR 환경에서의 주의점(Next.js 기준)

Tailwind는 SSR에서 아무런 추가 설정이 필요없다. 하지만, Emotion은 추가 설정이 필요하다.

짧게 설명해보자면, Next.js App Router 환경에서 Emotion을 별도 설정 없이 사용한다면 Hydration 불일치 에러가 발생할 수 있다. 서버에서 생성한 스타일과 클라이언트에서 생성한 스타일이 달라지기 때문이다. 자세한 설명은 이전에 작성한 글을 참고하길 바란다.

만약, Next.js에서 이원화 전략을 선택한다면 설정이 제대로 되어있는지 확인해야한다.

5. 마치며..

이번 글을 작성하며 어떤 프로젝트에서 맞는 전략인가에 대해 깊게 고민해보았다.

Emotion을 이미 써야할 이유가 있다면(동적 컴포넌트, 디자인 시스템), Tailwind를 레이아웃 전담으로 병용하는 건 합리적인 선택이다. 단, 경계를 명확하게 문서화해두고 사용해야한다.

만약 성능이 최우선인 프로젝트라면 Emotion의 런타임 비용을 구체적으로 측정한 뒤 판단해봐야 한다. 그리고 신규 팀원이 자주 합류한다면, 스타일링 온보딩 비용을 고려해봐야 할 것 같다.

처음엔 직관적으로 선택한 전략이었는데, 다시 들여다보니 나름 이론적 근거가 있었다. 물론 "경계를 유지하는 비용"이라는 약점도 분명하게 존재하지만, 현재 참여 중인 프로젝트에서는 그 비용보다 동적 스타일의 유지보수 편의성이 더 중요한 고려사항이라 판단되어 다시한번 이원화 전략에 대해 선택했다.

특히 프로젝트 폴더구조 설계 능력이 생각 이상으로 더 중요한데요! 개발 전 구조 정책을 잘 설정해두지 않으면, 후반부로 갈수록 더 고생길이 열립니다.. ( 알고 싶지 않던...고생길 루트... )

거기다 Cursor, Copilot 같은 AI 코딩 도구를 쓰면서 느낀 건, 구조가 잡혀있지 않으면 AI한테 좋은 명령도 못 내린다는 거였어요. 설계 능력의 중요성이 두 배로 와닿았습니다...

사실 전 FSD를 실제 프로젝트에 도입해봤지만, 제대로 이해하지 못한 채로 프로젝트가 끝난 아쉬운 경험이 있습니다.. 뇌가 딱 감을 잡기 직전에 흐름이 끊어져서, 날을 잡고 FSD를 다시 제대로 공부하다보니 비교 대상으로 프랙탈 구조도 알게 되었습니다!! ( 1+1? 나이스~ )

공부한 내용을 정리하지 않으면 머리에 남지 않을 것 같아 기록을 남깁니다!

시작하기 앞서.. 갑작스러운 문체 변경은... 이해해 주세요..두뇌 풀가동하면서 쓰느라 그렇답니다..

Intro

처음 HTML, CSS, JavaScript로 프로젝트를 처음 시작할 때는 파일 구조를 크게 신경쓰지 않았었다. 그리고 React를 처음 시작했을 때도, public/, src/ 정도만 알고, 그 안에 components/, pages/, utils/ 폴더 몇 개 만들어 파일 네이밍 규칙을 지키며 코드 구현에만 열중하는 상황을 1년 넘게 보내왔다.

그런데 창업 프로젝트에 들어가게되며 프로젝트 규모가 점점 커졌고, 이런 상황이 자주 발생했다.

• "이 컴포넌트, 어느 폴더에 넣어야 하지?"
• "components/ 폴더에 파일이 너무 많은데?"
• "이 유틸함수는 어디서 쓰지? 지금도 쓰는건가?"

파일 구조는 단순한 취향 문제가 아니라, 나와 팀(과 ai)이 코드를 읽고, 찾고, 유지하는 속도에 직접적인 영향을 미친다는 것을 느끼게 되었다.

이 글은 먼저 프랙탈 구조를 살펴본 뒤, 한계를 극복하기 위해 등장한 FSD(Feature-Sliced Design)로 흘러가보겠다.

1. 프랙탈 구조(Fractal Structure)

1-1. 프랙탈(Fractal)이란?

작은 구조가 전체 구조와 닮은 형태로 끝없이 되풀이되는 구조이다.

글로 풀어서 작성해본다면, ❶ 자신의 작은 부분에 자신과 닮은 모습이 나타나고 ❷ 그 안의 작은 부분에도 자신과 닮은 모습이 무한히 반복되어 나타나는 구조이다.

이걸 프론트엔드 구조로 다시 작성해본다면, ❶ A폴더의 작은 부분인 하위 폴더 B폴더 안에 A폴더와 유사한 구조가 나타나고 ❷ B폴더의 하위 폴더인 C폴더에도 동일한 구조가 반복되어 나타나는 형식을 말한다.

마지막으로 정의해보면, 폴더 구조에서 각 폴더가 동일한 내부 구조를 반복하는 구조이다.

예를 들어, 최상위 src/ 폴더에 components/, hooks/, utils/가 있다면, feature 폴더 안에도 동일하게 components/, hooks/, utils/가 존재한다.

1-2. 프랙탈 구조의 핵심 규칙

1. 기능 단위로 폴더를 나눈다.

파일 타입(components, hooks)이 아닌, 기능(auth, dashboard)이 최상위 분류 기준이다.

참고 이미지 속 📁auth/, 📁dashboard/ 폴더를 보면 Lv.1에서 반복된 요소가 Lv.3에서 다시 반복되는 걸 확인할 수 있다.
이런 성질을 자기 유사성(Self-similarity)이라고 한다.

2. 각 기능 폴더는 독립적이다.

한 기능을 삭제할 때 해당 폴더만 지우면 된다.

3. 공통 코드는 최상위에 둔다

여러 기능에서 공유되는 코드는src/ 바로 아래에 위치한다.

1-3. 프랙탈 구조의 장점

1. 직관적이다.

기능 이름으로 폴더를 찾으면 되기 때문에 진입장벽이 낮다. ex. 📁auth/, 📁dashboard/

2. 로컬 응집성이 높다.

관련 파일이 한 폴더에 모여 있어 맥락을 파악하기 쉽다.

여기서, 응집성이란 뭘까?

응집성(응집도/Cohesion)란?
_" 연관된 코드가 얼마나 한 곳(폴더)에 모여 있는가 "_를 나타냅니다. 응집도가 높을 수록 관련 코드를 찾기 쉽고, 수정할 때 영향 범위도 예측하기 쉽습니다.
첨부한 이미지 기반으로 설명하자면, 로그인 관련 components, hooks, utils이 📁auth/폴더 하나에 모여있는 걸 응집도가 높다고 표현합니다. ▶ 참고 링크

3. 독립성이 좋다.

기능 폴더를 통째로 복사하거나 삭제할 수 있다.

4. 별도의 학습이 필요 없다.

구조 자체가 설명적이다.

1-4. 프랙탈 구조의 단점

1. 기능 간 참조를 구조적으로 제한할 수 없다

📁auth/가 📁dashboard/를 참조해도 구조상 막을 방법이 없다.

2. 공통 코드의 경계가 모호하다.

"이 코드, 공통으로 올려야할지, 기능 폴더에 둬야 할지" 결정하기 어려워진다.

3. 규모가 커지면 혼란스러워 진다.

기능이 20개를 넘어가면 📁features/폴더 자체가 복잡해진다.

4. 팀마다 해석이 다르다.

명확한 표준이 없어 팀원마다 구조를 다르게 적용할 수 있다. 이를 보완하기 위해 팀 내 파일 구조 컨벤션이 필요하거나, 구조 자체가 규칙을 강제하는 방식을 도입하게 된다.

1-5. 프랙탈 구조의 문제 상황

프랙탈 구조는 소규모 프로젝트에서 잘 작동한다. 그런데 팀이 커지고 기능이 늘어나면 두 가지 문제가 반복적으로 등장한다.

1. 의존성 방향이 뒤섞인다.

A 기능이 B를 참조하고, B가 다시 A를 참조하는 순환 참조가 일어나게 된다.

2. 코드의 위치 결정이 주관적이다.

개발자마다 파일을 다른 위치에 넣는다.. ( 파일 구조 컨벤션이 없다면, 일어나는 아찔한 상황.. )

이를 FSD의 레이어(Layer)개념으로 해결할 수 있다.

2. FSD 구조(Feature-Sliced Design)

레이어를 정의하고, 상위 레이어만 하위 레이어를 참조할 수 있게 강제한다.

2-1. 레이어 설명

FSD는 코드를 주로 6개의 레이어(Layers)로 나눈다. 위로 갈 수록 "더 구체적인 기능", 아래로 갈수록 "더 범용적인 코드"이다.

• app : 앱 초기화, 라우팅 설정, 전역 Provider
• pages : 라우트에 대응하는 페이지 컴포넌트
• widgets : 여러 features를 조합한 독립적인 UI 블록
• features : 사용자 시나리오(행동) 단위의 기능 (로그인, 장바구니 담기 등)
• entities : 비즈니스 도메인 단위(User, Product, Order 등). 데이터 모델
• shared : 재사용 가능한 UI 컴포넌트, 유틸, API 클라이언트

참고 사실 레이어는 7개이다. app 다음에 processes가 있지만, 실제로 잘 사용되지는 않는다.

2-2. 레이어의 참조 규칙

각 레이어는 자신보다 아래 레이어만 참조할 수 있다.

app

• 참조 가능 : pages, widgets, features, entities, shared
• 참조 불가능 : X

  pages

• 참조 가능 : widgets, features, entities, shared
• 참조 불가능 : app

  widgets

• 참조 가능 : features, entities, shared
• 참조 불가능 : app, pages

  features

• 참조 가능 : entities, shared
• 참조 불가능 : app, pages, widgets

  entities

• 참조 가능 : shared
• 참조 불가능 : app, pages, widgets, features

  shared

• 참조 가능 : X
• 참조 불가능 : app, pages, widgets, features, entities, shared

2-3. 레이어의 핵심 규칙

1. 단방향 의존성(Unidirectional Dependencies)

레이어 간 참조는 항상 위에서 아래 방향으로만 흐른다. 바로 2-2. 참조 규칙 기반으로만 가능하다.

2. Slice와 Segment

레이어 안에서는 2가지 단위가 있다.

• Slice : 각 레이어 안에서 코드를 나누는 단위
• Segment : slice 안에서 역할별로 나누는 단위

사진과 같이 단위에 맞게 자르면 된다. 추가적으로 설명을 더 남겨보자면 아래와 같다.

📁features : 레이어
├📁auth : 기능 단위 슬라이스 (Slice)
│   ├ 📁ui : UI 컴포넌트 시그먼트 (Segment)
│   ├ 📁model : 상태, 비즈니스 로직 시그먼트 (Segment)
│   └ 📁api : API 호출 시그먼트 (Segment)

슬라이스(Slice)은 프로젝트별 네이밍 컨벤션이 필요하다. Slice 네이밍은 도메인(명사)기준이 표준이므로, 프로젝트 컨벤션에 따라 자유롭게 정하되, 시그먼트 이름은 FSD 표준 명칭(ui, model, api, lib, config)을 따르는 것을 권장한다.

FSD 사용하는 실제 프로젝트 구조 ** 기능 : post 생성 / post 삭제
📁 **features/ ├── 📁 post-create/ : Post 생성 │ ├── 📁 ui/ : 생성에 필요한 UI 컴포넌트 │ ├── 📁 model/ : Post 생성 관련 상태 관리, 비즈니스 로직 │ └── 📁 api/ : Post 생성 요청 (POST) └── 📁 post-delete/ : Post 삭제 │ ├── 📁 ui/ : 삭제에 필요한 UI 컴포넌트 │ ├── 📁 model/ : Post 삭제 관련 상태 관리, 비즈니스 로직 │ └── 📁 api/ : Post 삭제 요청 (DELETE) 📁 entities/ └── 📁 post/ │ ├── 📁 ui/ : PostCard, PostPreview 등 순수 UI │ ├── 📁 model/ : Post 타입 정의 │ └── 📁 api/ : Post 데이터 조회 (GET)

3. Public API(index.ts)

각 slice는 index.ts를 통해 외부에 노출할 코드를 명시적으로 선언한다. 외부에서는 slice 내부 파일을 직접 참조하지 않고, 반드시 index.ts를 통해 접근한다.

2-4. FSD 구조의 장점

• 의존성이 명확하다. 레이어 규칙 덕분에 순환 참조가 구조적으로 불가능하다.
• 코드 위치 결정이 객관적이다. " 이 코드는 어느 레이어인가? " 위치가 결정된다.
• 대규모 팀에서 강하다. 여러 팀이 서로 다른 레이어를 맡아 병렬로 작업할 수 있다.
• eslint 플러그인으로 자동 강제할 수 있다. eslint-plugin-fsd

2-5. FSD 구조의 단점

• 학습 곡선이 있다. 6개 레이어와 각 규칙을 이해하는 데 시간이 필요하다. ( 지금의 나에요.. )
• 소규모 프로젝트엔 과하다. 기능이 5개 미만이면 구조가 오히려 복잡하게 느껴진다.
• 초기 설정 비용이 있다. alias 설정, eslint 규칙 등 사전 설정이 필요하다.
• widgets 레이어가 모호하게 느껴질 수 있다. pages와 features의 중간 개념이라 처음엔 구분이 어렵다.

3. 프랙탈 → FSD, 왜 발전했는가??

두 구조의 철학을 (ai가) 비교한 표를 먼저 봐보자.

각각의 성격은 알겠다. 이제 어떤 상황에서 어떤 구조를 선택해야 할까?

1. 프랙탈 구조가 적합한 경우

• 혼자 개발하거나, 팀이 2~3명인 경우
• MVP나 사이드 프로젝트처럼 빠른 초기 개발이 중요한 경우
• 기능이 10개 이하로 유지될 것으로 예상되는 경우

  2. FSD가 적합한 경우

• 팀이 5명 이상이거나 앞으로 커질 예정인 경우
• 장기적으로 유지보수할 서비스인 경우
• 도메인이 복잡하고 기능 간 의존성 관리가 중요한 경우

프랙탈이 FSD로 발전했다에서 간혹 프랙탈 구조가 틀렸다고 생각할 수 있지만, 프랙탈 구조가 틀린건 아니다!!

프랙탈은 "파일을 어디에 둘 것인가"라는 목적에 집중했고, FSD는 한 발 더 나아가 "코드가 서로 어떻게 참조해야 하는가"라는 목적에도 집중했다.

4. 마치며..

좋은 파일 구조란 "현재 팀과 프로젝트 규모에 맞는 구조"라 생각한다.

소규모로 시작할 때는 프랙탈로 빠르게 시작하고, 규모가 커지는 시점에 FSD 마이그레이션을 검토하는 것이 좋을 것 같다는 판단이다. ( 하지만 전 소규모 플젝도 공부를 위해 FSD를 선택했어요..! 프론트 혼자일때의 장점이랄까요 후후.. )

그리고 AI_(Cursor, Claude Code, Codex 등)_를 사용하여 코드를 작성해본 결과, FSD가 AI에게도 좋은 선택이라 판단이 든다.

AI는 코드를 생성하는 속도는 빠르지만, 구조를 제대로 판단하지는 않는 것으로 보인다. 이전 FSD를 사용한 프로젝트에서 명확한 FSD 구조 설계 없이 진행하였더니, 점점 파일 구조가 붕괴되는 경험을 했었다.

요구사항에 대해 .md를 제대로 설정하지 않고, 너무 모호한 명령을 내려서 그럴수도 있지만, AI는 코드 생성 속도를 빠르게 높이는 것에 중점을 두고, 구조의 붕괴는 따로 요청 혹은 설정이 없다면 신경쓰지 않는다는 걸 알게되었다.

그래서 이번에는 FSD를 사람도, AI도 더 명확하게 이해할 수 있는 "좌표계"로 사용해보고자 한다. AI는 기능 구현과 보일러플레이트를, 사람은 설계와 리스크 검토를 담당하는 방식으로 진행해보고자 한다. ( 제발 구조 붕괴 없이 잘 마무리되길...!!! )

결론은, AI는 "무엇을 만들지" 를 도와주지만, "어디에 어떻게 놓을지" 는 여전히 사람과 구조가 결정해야 한다고 생각한다.

AI는 "지금 잘 동작하는 코드" 를 만들고, FSD는 "나중에도 읽히는 구조" 를 만든다.

참고 ▶ 🔗 FSD 공식 문서 ▶ 🔗 토스 Frontend Fundamentals 공식 문서 ▶ 프랙탈 구조란?

대부분은 SSR 환경에서 CSS-in-JS가 동작하는 방식이 원인입니다.. (나 자신!) 이제 SSR 환경의 작동 원리를 다시 이해해보자!

SSR 환경에서 Emotion의 문제점

1. CSS-in-JS의 SSR 동작 원리

Emotion은 기본적으로 런타임에 스타일을 생성한다.

런타임 : 컴파일 후 코드가 실제로 실행되는 순간/환경

컴포넌트가 랜더링될 때 스타일을 계산하고, 해당 스타일을 <style> 태그로 DOM에 동적으로 삽입하는 방식이다.

CSR 환경에서는 이 방식이 문제가 없다. 브라우저에서 JS가 실행되면서 스타일도 함께 삽입되기 때문이다.

그런데, SSR에선 문제가 발생한다. 서버에서는 HTML 문자열을 만들어 응답하는데, 기본 설정에는 Emotion이 생성한 스타일이 해당 HTML에 포함되지 않는다. ( 당연하다! JS가 실행되기 전이니 포함이 안된다! )

그 결과 브라우저는 스타일이 없는 HTML을 먼저 받아 화면에 그리고, 이후 JS가 실행되며 뒤늦게 스타일이 적용된다.

2. Critical CSS 누락 문제 - FOUC

위의 상황은 실제 사용자에게 '스타일이 없는 날것의 HTML'이 순간적으로 노출된다. 이를 FOUC(Flash of Unstyled Content)라고 한다. ( 완전...밤티 이미지... )

JS 번들이 로드되고 Hydration이 완료되기 전까지, 사용자는 레이아웃이 깨진 화면을 보게 된다. 네트워크가 느릴수록 이 현상은 더 두드러진다.

그런데, Hydration? 얘는 또뭘까?

3. Hydration

SSR 환경에서 React가 동작하는 방식을 이해하려면 Hydration 개념이 필수다.

3-1. Hydration 개념 정의

" React가 SSR로 생성된 HTML을 재사용하기 위해 서버에서 생성된 DOM과 클라이언트에서 렌더링한 결과가 일치하는지 검증하는 과정 "

SSR은 서버에서 완성된 HTML을 만들어 브라우저에 전달한다. 덕분에 사용자는 JS가 실행되기 전에도 화면을 볼 수 있다. 그런데, 이 HTML은 정적인 문자열일 뿐이다. 버튼을 눌러도 반응이 없고, 상태도 없다.

이후 JS 번들이 로드되면 React가 개입한다. React는 서버에서 받은 HTML을 버리고 새로 그리는게 아니라, 기존 DOM에 이벤트 핸들러와 상태를 붙여 App으로 만든다.

이 과정을 수화, Hydration이라고 한다.

3-2. Hydration 성립 조건

서버가 만든 HTML과 클라이언트 React가 렌더링하는 결과가 100% 일치해야 한다.

React는 둘을 비교하여 검증하기 때문이다.

조금이라도 다르면, React는 경고를 띄우거나, 아예 SSR 결과를 버리고 클라이언트에서 전체를 다시 렌더링한다.

이 전제 조건 때문에 Emotion 같은 CSS-in-JS에서 className 불일치 문제가 발생한다.

4. Hydration 불일치 문제

Hydration 불일치는 FOUC보다 더 심각한 문제이다. FOUC는 UI가 추후 제대로 작동하지만, Hydration은 React가 SSR 결과물을 아예 폐기하고 클라이언트에서 전체를 다시 렌더링하여서 SSR을 선택하는 장점 자체가 사라지는 셈이다!

에러 발생 원인

Emotion은 스타일을 기반으로 className 해시값을 런타임에 생성한다.

해시값(Hash Value) 임의의 데이터를 고정된 길이의 문자열로 변환한 결과값 ex. css-abc123 에서 abc123이 해시값이다.

별도의 설정이 없으면 서버와 클라이언트가 각자 독립적인 카운터로 해시를 계산하는데, 렌더링 순서나 타이밍에 따라 동일한 스타일이더라도 서로 다른 className이 나올 수 있다.

    Warning: Prop `className` did not match.
    Server: "css-abc123" Client: "css-xyz789"

이 에러가 콘솔에 출력되면, (심한 경우)React가 SSR 결과물을 버리고 전체를 클라이언트에서 다시 렌더링한다.

원인은 크게 두 가지다.

원인1. 캐시 인스턴스 따로 증가

"서버와 클라이언트가 각자 해시값을 만드는 문제"

Emotion은 스타일을 만들 때마다 고유한 이름표(className)을 붙인다. css-1, css-2, css-3 이런식으로, 만들어진 순서대로 번호가 올라간다.

이 번호를 관리하는 장부가 바로 캐시(Cache)이다. 쉽게 말해 "나는 지금까지 몇 번째 스타일까지 만들었다"를 기억하는 메모장이다.

문제는 SSR 환경에서 캐시(메모장)가 서버용, 클라이언트용 따로따로 존재한다는 점이다.

클라이언트에서만 추가로 렌더링 되는 스타일이 끼어들면(ex. 'use client' 사용한 컴포넌트 스타일) 번호가 어긋나기 시작한다. ( 문제 발생 시작!! )

서버는 헤더에 css-1이라고 붙여 HTML을 만들어도, 클라이언트가 헤더에 css-2라고 알고 있는 상황이다. React가 둘을 비교하면, 에러를 낸다.

정리하면, 공유된 하나의 캐시(메모장)를 같이 보지 않고, 각자 처음부터 번호를 새로 매기기 떄문에 생기는 문제다.

이를 해결하려면 1. *서버에서 만든 메모장의 상태를 *2. 클라이언트에 그대로 전달하여 *3. *클라이언트가 이어서 번호를 매기도록 만들어야 한다.

원인2. @emotion/babel-plugin 미적용

className이 렌더링 순서에 따라 결정되는 숫자 해시라는 점이 근본 원인이다.

플러그인 없이 빌드하면 클래스명에 안정적인 식별자가 붙지 않아 순서에만 의존하게 된다. 조건부 렌더링이나 동적 스타일이 있을 때 특히 불일치가 잘 발생한다.

5. Hydration 에러 해결하기

원인이 두 가지였으니, 해결책도 그에 맞게 맞춰 작성해봅니당~

5-1. @emotion/cache로 캐시 분리

@emotion/cache는 Emotion이 스타일을 저장하고 관리하는 인스턴스다.

기본적으로 전역 단일 인스턴스를 사용하는데, SSR 환경에서는 요청마다 독립된 캐시 인스턴스를 생성해야한다.

그렇지 않으면 이전 요청의 스타일이 다음 요청에 오염되는 문제가 생긴다.

오염을 방지 하기 위해 key 옵션을 사용하면 된다. key는 생성되는 className의 접두사(prefix)가 된다. (css-abc123에서 css 부분) 이로 인해 요청마다 안정되고 독립된 캐시 인스턴스를 생성할 수 있게 된다.

여러 캐시 인스턴스를 구분해야 하는 경우 key를 다르게 지정하면 된다. ( 좋은 전략 방법! )

추가 설정 " prepend: true로 스타일 삽입 순서 제어 하기!! " prepend:true를 설정하면 Emotion이 생성한 <style> 태그를 <head>의 맨 앞에 삽입한다. 이렇게 설정해두면 전역 CSS나 다른 라이브러리 스타일보다 Emotion의 스타일이 먼저 선언되어, *나중에 선언된 스타일이 덮어쓸 수있는 구조가 만들어진다. * 스타일 우선순위를 예측 가능하게 유지하는 데 도움이 된다!!!

5-2. @emotion/babel-plugin/SWC로 클래스명 안정화

Hydration 불일치의 근본 원인 중 하나는 className이 렌더링 순서에 따라 결정되는 숫자, 해시라는 점이다.

빌드 타임에 '각 스타일에 컴포넌트 이름 + 파일 경로 기반의 안정적인 레이블'을 추가한다.

서버와 클라이언트가 동일한 컴포넌트를 렌더링하면 항상 같은 className을 생성하게 되어 Hydration 불일치가 해소된다.

    // 플러그인 없음 — 순서에 의존
    css-1, css-2, css-3 ...

    // 플러그인 적용 후 — 안정적인 식별자
    css-Button-abc123, css-Header-xyz789 ...

Babel을 사용하는 경우

@emotion/babel-plugin을 사용하면 이 문제를 해결할 수 있다.

Next.js에서 SWC 컴파일러를 사용하는 경우

Babel 대신 next.config.js에서 설정한다.

SWC 컴파일러란? 컴파일러 : 사람이 작성한 코드를 브라우저가 읽을 수 있게 변환해주는 도구
우리가 작성한 코드(TypeScript,.jsx, .tsx)는 브라우저가 바로 이해하지 못한다. 브라우저는 순수한 JavaScript만 읽을 수 있기 때문에, 작성한 코드를 브라우저가 읽을 수 있는 JavaScript로 변환하는 과정이 필요하다. 변환을 해주는 도구를 컴파일러 라고 부른다. 기존에는 이 역할을 Babel이 담당했다. 그런데, Babel은 JavaScript로 만들어져 있어 변환 속도가 느리다는 단점이 있다.
SWC는 이 Babel을 대체하기 위해 만들어진 컴파일러이다. Rust로 작성되어 있어 Babel보다 훨씬 빠르다. Next.js 12부터 기본 컴파일러로 채택됬다.
@emotion/babel-plugin은 말그대로 Babel 전용 플러그인이다. 프로젝트가 SWC를 사용하고 있으면, 이 플러그인을 그대로 쓸 수 없고, 대신 next.config.js에서 SWC용 Emotion 옵션을 따로 설정해줘야 한다.

5-3. App Router : useServerInsertedHTML로 스타일 동기화

App Router에서는 _document.tsx 방식을 사용할 수 없다. 대신 React 18에서 추가된 useServerInsertedHTML 훅을 활용한다.

useServerInsertedHTML : 서버 렌더링 중 생성된 스타일을 HTML에 직접 삽입할 수 있게 해준다.

흐름을 정리하면 아래와 같다.

1. 서버 렌더링 시작
2. EmotionCacheProvider가 캐시 인스턴스 생성
3. 컴포넌트 트리 렌더링 ( 스타일이 cache.inserted에 누적 )
4. useServerInsertedHTML 콜백 실행
5. 누적된 스타일을 <style> 태그로 HTML에 삽입
6. 브라우저에 스타일이 포함된 HTML 전달
7. Hydration 시 서버/클라이언트 className 일치

6. SSR + Emotion 설정 순서

일단 심호흡 한번 하자... 이 글을 정리하며 당시 에러 상황이 생각나서 너무 호흡이 딸렸다..

다시는 이런 아찔상황을 겪지 않기 위해 아래 순서대로 설정을 진행하는 걸 잊지 말자. ( 컨시컨브 편하게 하기 위해 이미지가 아닌 점.. 참고 부탁드립니다..^0^~ )

6-1. 패키지 설치

npm install @emotion/react @emotion/styled @emotion/cache @emotion/server

6-2. 컴파일러 설정 - SWC(Next.js 기본)

// next.config.js
const nextConfig = {
    compiler: {
        emotion:true, // 클래스명 안정화
    },
};

module.exports = nextConfig;

6-3. 캐시 생성 유틸 작성

// lib/emotionCache.ts
import createCache from '@emotion/cache';

export function createEmotionCache() {
    return createCache({ key:'css', prepend:true });
}

파일 주소는 임의로 저렇게 적어놨는데, 파일 구조 형식에 맞게 위치하면 됩니다~

6-4. EmotionCacheProvider 작성(App Router)

// lib/EmotionCacheProvider.tsx
'use client';

import { useServerInsertedHTML } from 'next/navigation';
import { CacheProvider } from '@emotion/react';
import { createEmotionCache } from './emotionCache';
import { useState } from 'react';

export default function EmotionCacheProvider({ children} : { children:React.ReactNode}) {
    const [cache] = useState(()=>{
        const c = createEmotionCache();
        c.compat = true;
        return c;
    });

    useServerInsertedHTML(()=>(
        <style 
            data-emotion={`${cache.key} ${Object.keys(cache.inserted).join(' ')}`}
            dangerouslySetInnerHTML={{__html:Object.values(cache.inserted).join(' ')}}
        />
    ));

    return <CacheProvider value={cache}>{children}</CacheProvider>
}

6-5. layout.tsx 적용

// app/layout.tsx
import EmotionCacheProvider from '@/lib/EmotionCacheProvider';

export default function RootLayout({ children }:{ children: React.ReactNode}) {
    return(
        <html>
            <body>
                <EmotionCacheProvider>{children}</EmotionCacheProvider>
            </body>
        </html>
    );
}

설정을 완료한다면, 아래와 같은 흐름으로 동작한다. ( 그래도 에러 해결이 안된다면...다시 검토해보자 )

1. 서버 렌더링 시작
2. EmotionCacheProvider가 캐시 인스턴스 생성
3. 컴포넌트 트리 렌더링 (스타일이 cache.inserted에 누적)
4. useServerInsertedHTML 콜백 실행
5. 누적된 스타일을 <style> 태그로 HTML에 삽입
6. 브라우저에 스타일이 포함된 HTML 전달
7. Hydration 시 서버/클라이언트 className 일치

7. 흔히 겪는 Hydration 에러 사례 및 디버깅

7-1. @emotion/babel-plugin 미적용

가장 흔한 원인. 플러그인 없이 사용하면, className이 렌더링 순서에 의존하게 되어 조건부 렌더링이나 동적 스타일이 있을 때 불일치가 발생한다.

→@emotion/babel-plugin or SWC emotion 옵션 적용으로 해결.

7-2. 캐시 인스턴스가 요청 간 공유됨

createEmotionCache()를 모듈 최상단에서 한 번만 호출하면, 모든 요청이 같은 캐시를 공유한다. 이전 요청의 스타일이 섞여 들어온다.

→ 요청마다 새 인스턴스를 생성하도록 수정.

7-3. App Router에서 useServerInsertedHTML 미적용

EmotionCacheProvider 없이 사용하면 서버에서 생성된 스타일이 HTML에 포함되지 않아 Hydration 시 className은 일치해도 스타일이 없는 상태로 시작된다. → 6. SSR + Emotion 설정 순서를 다시 적용해보자.

디버깅 방법

1. 브라우저 콘솔에서 className did not match 에러 확인
2. 서버 응답 HTML(view-source:)에서 <style data-emotion> 태그 존재 여부 확인
3. React DevTools에서 Hydration 에러 컴포넌트 추적.

오늘도 긴 글 읽어주셔서 정말 감사드립니다... 방전된 저는 이만..

피그마 dev 모드 → 복사 → 붙여넣기 → 또 복사 → 또 붙여넣기...

타이포그래피 컴포넌트가 20개라면, 이 과정을 20번 반복해야 했습니다. 결과물은 아래와 같은 구조였는데요.

(왼쪽) 피그마 코드를 그대로 객체로 정의 / (오른쪽) 컴포넌트 오버라이딩 한 코드

타이포 객체를 정의해두고, 실제 사용 컴포넌트에서는 color 같은 가변 요소만 styled(컴포넌트) 형식으로 오버라이딩해서 쓰는 방식이었습니다.

ctrl+c, ctrl+v. ** 행동 자체는 단순했지만, **유지보수가 문제였습니다. 시스템 변경이 생기면 20개의 객체를 전부 찾아서 고쳐야 했고, 코드는 점점 더 지저분해졌습니다.

' 좀 더 효율적인 방식이 없을까? '

그래서 직접 설계해봤습니다..!

이번 구현 방식은 @emotion/styled 이론 지식 기반입니다! 공식 문서를 먼저 읽어 보신 뒤, 기록을 읽어주시면 더욱 이해가 잘 될거에요! ▶ 🔗 공식 문서 이동 링크 ▶ 🔗 @emotion/styled 정리 글

0. intro

먼저 '공통적으로 사용되는 요소들은 Token으로 정의하고, 이를 기반으로 베이스를 만들어서 활용하자!'로 시작했습니다. 피그마 dev 모드로 전환시 타이포그라피 요소는 위와 같은 형태로 코드가 출력됩니다. 참여한 서비스 내 타이포 시스템은 아래와 같은 특징을 가지고 있었습니다.

1. 불변 요소(빨간 부분) : font-family, font-style 2. 가변 요소 : font-size, font-weight, font-height, color

다음으로 저는 2가지 문제 상황을 해결해보고자 했습니다.

0-1. 문자열로 표현된 font-weight를 내부적으로 숫자로 풀어내자.

퍼블리싱 작업 중에 간혹 디자인 시스템에 정의되지 않은 타이포 요소를 확인할 수 있었는데요! 그럴 경우 font-weight (초록색 부분)가 숫자값이 아닌 문자열로 표현이 되어 해당 시스템 요소의 weight 값이 헷갈리는 경우가 있었습니다. 이런 경우에_ '리터럴로 작성하여도 내부적으로 자동 변환이 되면 편하겠다.'_ 라는 생각이 들었습니다.

0-2. 불변요소들은 외부로 노출되지 않게 표현해보자.

피그마의 Variables 표현 방식처럼 ' color를 제외한 가변요소(노랑색, 하늘색)만 표현하고, 그 외의 요소는 숨겨보자!' 라는 목표로 삼고 디자인 시스템을 리팩토링했습니다.

이 두 가지 문제를 해결하기 위해 @emotion/styled 기반의 레이어 구조를 설계했습니다. 각 레이어가 다음 레이어의 재료가 되는 구조로, 아래 순서로 구현했어요.

원시값(Token) → 재사용 조각(Mixins) → 공통 기본값(Base) → 조합기(Builder) → 자동 생성기(Factory)

1. import

@emotion/styled 패키지는 내부적으로 @emotion/react를 래핑하고 있어서, 2개의 패키지를 함께 설치 후 사용해주셔야 합니다! ▶🔗 관련 정리 글

먼저 타이포 시스템 파일 상단에 import문을 작성했습니다.

1-1. @emotion/styled

styled 컴포넌트 자동 생성(7. Factory) 기능에 활용

1-2. @emotion/react

• css() : 객체로 스타일을 정의
• CSSObject : TypeScript 환경에서 Emotion의 자동완성 및 타입 추론

2. token

" 폰트 상수 정의 "

시스템 전체에서 사용할 원시값인 Token을 정의했습니다.

2-1. $typoFont

$typoFont 객체는 아래 2가지 목적을 가지고 있습니다.

1. family 정의 : font-family를 한 곳에서 관리합니다. 2. weight 값 리터럴 맵핑 : 피그마에서는 font-weight를 숫자가 아닌 문자열(Regular, SemiBold 등)으로 표기하는데요, 이를 보고 바로 코드에 적용 가능하기 위해 리터럴 타입으로 매핑했습니다. ( 0-1 문제 해결 !! )

2-2. $lh

$lh 함수는 행간을 배수로 입력받아 '%문자열'로 변환해주는 유틸입니다.

$lh(1.4) → "140%"

2글자 타이핑이라도 줄여보자는 마음으로 작성했는데, 만족스럽습니다!

2-3. etc

$ prefix에 대해 Sass $ *변수 선언 컨벤션에서 영감을 받아 붙여봤습니다. 문법적으로는 의미가 없지만, 코드를 보면 *스타일 토큰이라는 것을 바로 인식할 수 있어서 꽤 만족스럽습니다!

as const를 사용해 리터럴 타입으로 좁혀주었기 때문에, 컴파일 단계에서 잘못된 키 접근을 바로 잡아줍니다!

3. Mixins

" 재사용 스타일 조각 "

여러 곳에서 반복되는 스타일 묶음을 clampLines()함수로 추출하였습니다.

3-1. clampLines

텍스트를 n줄까지만 보여주고, 초과하면 말줄임표(...)로 자르는 함수

• display: -webkit-box; : 박스를 webkit flex box로 설정
• -webkit-box-orient: vertical; : 박스 방향을 세로로 설정
• -webkit-line-clamp: ${n}; : n줄까지만 표시
• overflow: hidden; : n줄 초과 텍스트 숨김
• text-overflow: ellipsis; : 잘린 부분을 ...으로 표시

clampLines(2)를 호출하면 2줄 이상은 말줄임표 처리하는 CSS를 반환합니다. 특정 타이포 컴포넌트에 clamp 옵션이 있을 때 이 믹스인이 자동으로 주입됩니다! ( 5.Styled Builder 참고 )

clampLines는 현재 구현에서 사용한 예시이며, 프로젝트 필요에 따라 믹스인 레이어에 자유롭게 함수를 추가해 확장할 수 있습니다!

4. Base

" 공통 기본 스타일 "

모든 타이포 컴포넌트에 공통으로 깔리는 베이스 스타일입니다. CSSObject 타입으로 정의하여 Object Style의 자동완성과 타입 검사가 동작하게 했습니다! ( Object Style의 장점! )

BASE_TYPO는 상수임을 명시하기 위해 UPPER_SNAKE_CASE로 작성했습니다.

• UPPER_SNAKE_CASE : 수정하지 않을 것임을 명시하는 '네이밍 컨벤션'

4-1. fontFamily

2.Token에서 정의한 토큰$typoFont을 참조합니다.

4-2. 폰트 렌더링 속성

폰트 렌더링을 부드럽게 처리하기 위해 아래 속성들을 추가했습니다.

아래 두 속성은 함께 써야 Chrome, Safari, *Firefox *환경 모두에서 동일하게 부드러운 폰트 렌더링을 보장할 수 있어요.

WebkitFontSmoothing: 'antialiased'

• 적용 환경 : macOS + Chrome/Safari (webkit 계열)
• 역할 : 폰트 렌더링 방식을 안티앨리어싱으로 설정
• 효과 : 폰트 외곽선을 부드럽게 처리해서 얇고 선명하게 보임

MozOsxFontSmoothing: 'grayscale'

• 적용 환경 : macOS + Firefox (Moz 계열)
• 역할 : Firefox에서 macOS 폰트 스무딩을 그레이스케일 방식으로 설정
• 효과 : webkit과 동일한 부드러운 렌더링 효과를 Firefox에서도 구현

그외 추가적으로 설정하고자 하는 요소들을 붙여줍니다!!

5. Styled Builder

_" 스타일 배열 조합기 " _

TypoConfig 객체를 받아 스타일 배열을 반환하는 함수입니다.

5-1. TypoConfig

• 필수값 : size(string), weight(number), lh(string / line-height)
• 선택값 : clamp(number / line-clamp), extra(CSSObject)

5-2. styleOf( )

@emotion/styled는 스타일 인자로 배열을 받을 수 있습니다. 배열 내부를 순서대로 순회하며 병합해주고, null은 자동으로 무시해요.

객체 방식이라면 조건부 스타일을 추가할 때마다 spread 연산자(...)가 필요하지만, 배열 방식은 조건부 결과를 요소로 넣기만 하면 Emotion이 알아서 처리해줍니다!!! ( 최고다...!!!! ) 덕분에 BASE_TYPO, 개별 값, clamp, extra 같은 스타일 레이어를 독립적으로 깔끔하게 조합할 수 있었습니다.

styleOf 함수 흐름을 정리하자면, 다음과 같습니다.

1. styleOf 함수가 TypoConfig 타입의 객체를 인자로 받아 구조 분해
2. BASE_TYPO(공통 기본값)를 배열 첫 번째 요소로 추가
3. fontSize / fontWeight / lineHeight 개별 값을 객체로 묶어 추가
4. clamp가 있으면clampLines(clamp), 없으면 null — 삼항 연산자로 조건부 추가
5. extra가 있으면 그대로, 없으면 null — ?? 연산자로 조건부 추가

6. Config Map

" 타이포 스펙 명세 "

타입별 스펙을 한곳에 모아 정의하는 명세서입니다!

6-1. $typoFont.weight.sb 참조

숫자 대신 토큰을 참조해서 의미를 명확하게 했습니다.

피그마에서 "SemiBold"를 확인하고 바로 $typoFont.weight.sb로 작성할 수 있게 되어 0-1 문제가 해결됐습니다!

6-2 가변 요소만 노출($lh 유틸, size )

intro에서 세운 목표를 다시 떠올려볼게요. " color를 제외한 가변요소만 표현하고, 불변요소는 숨기자 "

Config Map을 보면 size, weight, lh — 타입별로 달라지는 가변요소만 명세되어 있어요. font-family, font-style 같은 불변요소는 Config Map 어디에도 없습니다. 불변요소는 4. Base의 BASE_TYPO에서 처리했기 때문에 Config Map에서는 신경 쓸 필요가 없거든요!

color 역시 Config Map에 없어요. 사용하는 쪽에서 오버라이딩으로 처리하기 때문이에요.

결과적으로 Config Map은 딱 "바뀌는 것만" 보이는 명세서가 됐습니다. 0-2 문제 해결!!!

6-3. satisfies Record<string, TypoConfig>

각 항목이 5-1. TypoConfig 타입을 만족하는지 컴파일 단계에서 검사하며, 각 키의 정확한 타입 추론을 유지할 수 있습니다.

6-4. extra

Caption, Button 타입처럼 필요한 개별 속성을 추가할 수 있습니다.

이미지에는 flexShrink:0 추가함!

7. Factory

" styled 컴포넌트 자동 생성 "

Config Map을 순회하며 styled.span 컴포넌트를 자동 생성하는 함수입니다.

핵심은 styled.span(styleOf(map[key])) 한 줄이에요.

1. Config Map의 각 키
2. styleOf( )로 스타일 배열 생성
3. styled.span( )에 주입
4. styled 컴포넌트 반환

제네릭 T를 활용하여 반환 타입이 Record<keyof T, StyledSpan>으로 추론됩니다. 즉, T에 없는 키로 접근하면, TypeScript가 바로 에러를 반환해요!

7-1. StyledSpan

type StyledSpan = ReturnType<typeof styled.span>; styled.span이 반환하는 타입을 추출해서 별도 타입으로 정의한 것입니다. ReturnType<typeof styled.span>을 직접 쓰면 너무 길고 가독성이 떨어지기 때문에, StyledSpan이라는 이름으로 추출해서 재사용할 수 있게 했습니다.

📝 용어 정리 ReturnType : TypeScript 유틸리티 타입으로, 함수 T의 반환 타입을 추출해줍니다. ReturnType<typeof styled.span> → styled.span()이 반환하는 타입을 그대로 가져옴

7-2. createTypo

function createTypo<T extends Record<string, TypoConfig>>(
  map: T
): Record<keyof T, StyledSpan>

Config Map을 받아 styled.span 컴포넌트를 자동으로 생성해주는 팩토리 함수입니다. 제네릭 T를 활용한 덕분에 두 가지 이점이 생겨요.

1. 타입 안전성 T는 Record<string, TypoConfig>를 확장해야 하므로, TypoConfig 형태에 맞지 않는 값을 넘기면 컴파일 단계에서 바로 에러가 발생합니다.

2. 반환 타입 자동 추론 반환 타입이 Record<keyof T, StyledSpan>으로 추론되기 때문에, T에 없는 키로 접근하면 TypeScript가 바로 잡아줘요.

const T = createTypo(CONFIGS);

T.Headline1  // ✅ 정상
T.존재하지않는키  // ❌ TypeScript 에러

6. Config Map에서 정의한 CONFIGS를 인자로 넘기면, 각 키에 해당하는 styled.span 컴포넌트가 자동으로 생성됩니다.

8. Build / Named Export

" 외부 노출 "

마지막으로 createTypo(CONFIGS)를 실행해 전체 컴포넌트를 생성하고, Named Export로 하나씩 내보냅니다.

import { Headline1, Body2 } from '@/styles/typo';

Named Export를 사용하면 사용하는 쪽에서 필요한 컴포넌트만 골라서 import할 수 있어요. 야호!! 사용 방식은 그대로 유지하되, 내부 로직만 변경 성공이에요!! 마치 젠가 가운데 블럭을 뺀 것 같이..내부 로직만 수정 변경한게 너무 짜릿하지 않나요!!!

9. 적용 예시 및 결과

프로젝트 보안상 실제 적용 화면 첨부가 어렵지만, 아래는 실제 사용 예시 코드입니다!

(왼쪽) 타이포 컴포넌트를 오버라이딩해서 사용 / (오른쪽) 실제 사용 예시

기존에 타이포 시스템을 사용하던 방식(export/import, 오버라이딩)은 그대로 유지하되, 타이포 시스템 구축 자체는 훨씬 효율적인 구조로 개선되었습니다!

결과

이제 시스템 변경이 필요하면, 6. Config Map와 8. export 문만 추가/수정하면 됩니다.

실제 커밋 기록을 보면, 1개 파일에서 304줄이 제거되고 213줄로 재작성되었습니다.

약 100줄 이상의 코드를 줄이고, 재사용 가능한 구조를 만들 수 있었어요. ( 코드양 약 33% 감소!! )

각 레이어별 역할이 분리되어 있어서, 폰트 자체를 변경하더라도 Token 한 줄만 고치면 전체에 반영됩니다!!

언젠간 지금보다 더 나은 방식으로 발전시킬 수 있겠죠? 야호~ 이렇게 기분좋게 기록 마무리합니다~ ^0^~

🔗 참고 Emotion 공식 문서 : https://emotion.sh/docs/styled

이번 글은 @emotion/styled 공식 문서 기반입니다! 기본 개념은 ▶ 🔗 1편을 먼저 읽어 보신 뒤 읽어주시면 더욱 이해가 잘 될거에요!
▶ 🔗 공식 문서 이동 링크

1. props 기반 동적 스타일링

@emotion/styled 의 강점. 바로 props를 받아서 스타일을 동적으로 변경할 수 있다는 점입니다.

1-1. 기본 props 사용 방식

백틱 안에서 ${} 을 사용해 props에 접근이 가능합니다. ${} 안에 함수를 넣으면 props를 인자로 받습니다. 함수가 반환하는 값이 그대로 CSS 값으로 적용됩니다!

Object Style 방식도 동일하게 사용해요.

1-2. TypeScript 환경에서 props 타입 정의

TypeScript 환경에서는 props 타입을 제네릭으로 정의해야해요. 저는 이 제네릭 부분이 참 헷갈렸는데요!! 참고용으로 아래 헷갈릴만한 이론을 정리해뒀습니다!

📝참고용

• () : props의 값을 받는 곳 ( ex. ( props ) => ... )
• <> : 타입을 주입하는 제네릭 문법. styled에서는 props의 타입을 주입하는 데 사용

   _( ex. **```<```**{ active?: boolean }**```>```** )_

• <> 안의 내용 : 주입하는 타입 ( ex. { active?: boolean } )

타입을 정의하면 잘못된 props 전달을 컴파일 단계에서 바로 잡아줍니다!

2. shouldForwardProp

props 기반 스타일링을 하다 보면 아래와 같은 경고를 마주칠 수 있다고 합니다..! ( 흐음..전 만나본 기억은 없어용.. )

Warning: Received 'true' for a non-boolean attribute 'primary'
HTML 표준 속성이 아닌 커스텀 props가 DOM에 전달되면 발생하는 경고입니다. HTML 표준 속성이 아닌 props는 DOM에 전달되면 안되거든요!

이를 해결하는 것이 바로 shouldForwardProp입니다.

2-1.기본 사용법

shouldForwardProp이 false를 반환하는 prop은 DOM에 전달되지 않고 스타일링에만 사용됩니다.

2-2. isPropValid 활용

커스텀 props가 많아질수록 하나씩 제외하는 방식은 번거롭습니다. @emotion/is-prop-valid 패키지를 활용하면 HTML 표준 속성인지 자동 판별을 해줍니다. isPropValid는 속성들에 대해 아래와 같이 반환합니다.

• HTML 표준 속성(id, className, onClick 등) : true
• 커스텀 속성(primary, active 등) : false

특정 커스텀 props만 추가로 제외하고 싶다면, 아래와 같이 조합이 가능합니다.

shouldForwardProp: (prop) => isPropValid(prop) && prop !== 'primary'

저는 커스텀 속성은 Sass에서 영감을 받은 $ prefix를 사용하여 표시하곤 합니다!! $가 붙은 props는 HTML 표준 속성이 아니라는 게 한눈에 보여서, shouldForwardProp 설정 없이도 의도를 명확하게 전달할 수 있어요.
단, 실제로 $ prefix만으로는 DOM 전달을 막을 수 없고 shouldForwardProp은 여전히 필요해요!!!

3. 오버라이딩

3-1. styled( )로 컴포넌트 확장

styled(컴포넌트) 방식으로 기존 스타일을 확장할 수 있습니다. BaseButton의 공통 스타일은 유지하되, 각각 다른 스타일만 추가했습니다.

변형이 많은 컴포넌트를 만들 때 중복을 줄이는 핵심 패턴이에요!!

실제로 제가 정말 많이 애용하는 패턴입니다! 디자인 시스템 만들때 좋아요!

단, styled(컴포넌트) 방식은 해당 컴포넌트가 className prop을 받을 수 있어야 합니다. Emotion이 내부적으로 생성한 클래스명을 className으로 전달하는 방식이기 때문이에요!

3-2. as prop으로 렌더링 태그 변경

스타일은 그대로 유지하면서 렌더링되는 HTML 태그만 변경하고 싶을 때 as prop을 사용해요. ( 사실 저는 한번도 사용해보지 않았습니다..! )

아직 실무에서 직접 써볼 기회가 없었는데요, 버튼 컴포넌트를 <a> 태그로 렌더링해야 할 때나, 시맨틱 마크업(의미 있는 HTML 태그 사용)이 중요한 상황에서 유용할 것 같아요. 언젠가 써먹을 날이 오겠죠...? 아무튼 무척 편리한 방식이에요! 천재만재 개발자들!!

4. 실무에서 자주 사용되는 패턴

4-1. css helper로 동적 스타일 분리

props 기반 스타일이 복잡해질수록 백틱 안이 지저분해집니다. css helper를 활용해 동적 스타일을 별도 변수로 분리하면 훨씬 깔끔해져요. 스타일 변형이 많은 디자인 시스템 컴포넌트에서 자주 사용합니다!! ( 강추 강추 강강추~ )

4-2. 조건부 스타일링 패턴

실제로 제가 가장 자주 쓰는 조건부 패턴들입니다!

삼항 연산자

: 2가지 중 한가지 선택 시

&& 연산자

: 조건이 true인 경우에만, 스타일 블록 전체를 적용할 때

객체 스프레드

: Object Style에서 조건부 속성을 추가할 때

아래 상황에 맞게 패턴을 선택해서 사용하면 된답니다!

• 적용할 스타일이 1~2개 : 삼항 연산자
• 여러 속성을 한 번에 적용 : && 연산자 or 객체 스프레드

저는 3가지의 스타일링 패턴 중 삼항 연산자와 && 연산자를 css helper와 함께 자주 사용합니다!

Tailwind도 좋지만, 전 여전히 이 매력둥이에게 푹 빠져있답니다..❤️

다음 글은 @emotion/styled 기반으로 구현한 타이포 시스템 구현으로 돌아올게요!!

🔗 참고 Emotion 공식 문서 : https://emotion.sh/docs/styled

풀어봅니다. 저의 사랑.

Emotion이란?

" JavaScript로 CSS를 작성하게 해주는 스타일링 라이브러리 "

styled-component와 CSS-in-JS 진영의 양대산맥 중 하나로, styled-component에 영감을 받아 개발했다고 공식 문서에서 직접 밝히고 있다.

즉, Emotion은 styled-components의 오마주라 생각하면 된다.

이번 글은 아래 목차 순으로 작성 예정이다.

목차

1. CSS-in-JS 장점
2. Emotion 작동 원리
3. Emotion 스타일 작성 방식(2가지)
4. @emotion/css VS @emotion/react VS @emotion/styled 비교

그런데 여기서 의문이 드는 건, '왜 굳이 CSS 파일 대신 JS로 스타일을 작성할까?' 이다.

CSS-in-JS의 장점을 보면 이해할 수 있다.

1. CSS-in-JS 장점

1. 스코프 격리 : 클래스명 충돌 걱정이 없이 컴포넌트 단위로 스타일 관리 가능 2. 동적 스타일링 : JS변수, props, state 값을 스타일에 직접 반영 가능 3. Dead Code 제거 : 컴포넌트 삭제 시, 스타일도 함께 삭제.

이러한 장점에 Emotion은 DX(Developer Experience) 향상을 위해 아래 요소를 추가로 제공한다.

1-1. Source maps

"변환된 코드 - 원본 코드를 연결해주는 지도"

빌드 후 브라우저에서 실행되는 코드는 압축/변환되어 있기에, 에러가 발생해도 "어느 파일, 몇 번째 줄에서 발생" 했는지 추적이 어렵다. 이를 해결하는 것이 Source maps이다. 개발자 도구를 통해 어떤 컴포넌트의 어느 줄에서 해당 스타일이 바로 왔는지 확인 가능하다.

1-2. Labels

Emotion이 생성하는 클래스명은 기본적으로 "해시값"(ex.css-abc123)이라 사람이 읽기 어렵다. @emotion/babel-plugin을 사용하면, 자동으로 컴포넌트/변수이름을 클래스명에 붙여줘서 어떤 스타일인지 바로 파악이 가능하다.

// label이 없을 때
class = "css-abc123"

//label이 있을 때
class = "css-Button-abc123" // Button 컴포넌트의 스타일임을 바로 인식 가능

직접 label 옵션을 붙일 수도 있다.

const style = css`
    label : this-is-label-example;
    color : hotpink;
`

// class = "css-this-is-label-example-abc123"

디버깅 시 브라우저 DevTools를 보면 css-this-is-label-example-abc123과 같은 형태를 볼 수 있다.

1-3. Testing utilties

@emotion/jest 패키지를 통해 Jest 스냅샷 테스트에서 실제 CSS 스타일이 어떻게 적용됐는지 확인할 수 있다. 일반 Jest 스냅샷은 클래스명(css-abc123) 만 찍히는데, Emotion의 테스트 유틸리티를 쓰면 클래스명이 아닌 실제 스타일 내용이 스냅샷에 포함된다.

// 일반 스냅샷
<button class="css-abc123">클릭</button>

// @emotion/jest 적용 후
.css-abc123 {
    color:hotpink;
    font-size:16px;
}

<button class="css-abc123">클릭</button>

스타일이 의도치 않게 변경된 경우, 테스트로 바로 잡아낼 수 있어 스타일 회귀 방지에 유용하다.

(오호..Jest 사용 시 적용해봐야겠다)

2. 작동 원리

Emotion은 내부적으로 돌아가는 방식 중 핵심 아래와 같다.

" 런타임 에 클래스명을 생성 한다 "

📝 용어 정리 컴파일(Compile) : 코드를 실행 하기 전 변환하는 과정 ( 사람 말을 컴퓨터 말로 번역 ) *런타임(RunTime) *: 코드가 실제로 실행되는 순간/환경 ( 번역된 코드가 실제로 돌아가는 순간 )

예시 코드를 @emotion/css로 작성해보았다

import { css } from '@emotion/css';

const ExampleStyle01 = css`
    color : hotpink;
    font-size : 24px;
`

해당 예시 코드는 개발자 모드로 확인하면, 'css-abc123'과 같은 "고유" 클래스명 문자열을 반환한다.

emotion은

1. 스타일 코드를 받아서
2. 해시 기반의 고유 클래스명을 생성하고, 해당 CSS 규칙을
3. <style>태그에 동적으로 주입한다.

이 모든 과정은 @emotion/cache가 담당한다.

3. Emotion 스타일 작성 방식(2가지)

emotion은 2가지 스타일 작성 방식을 제공한다.

3-1. Tagged Template Literal

" CSS 문법 그대로 사용"

const ExampleStyle02 = css`
  background-color : hotpink;
  color:white;

  &:hover{
      color:${myColor}; // JS 변수로 사용 가능
  }
  `

css키워드+백틱(`)을 사용하여 백틱(`) 안에 일반 CSS를 쓰듯 작성한다. 내부적으로 css 함수가 Tagged Template Literal을 파싱 해 처리한다.

📝 용어 정리 파싱(parsing) : 텍스트(문자열)을 읽은 뒤 컴퓨터가 다룰 수 있는 구조로 변환하는 과정. 즉, 글자 덩어리를 의미 있는 구조로 해석하는 것.

3-2. Object Style

" JS 객체로 스타일 표현 "

평소 프로젝트 시 역할별 분리를 좋아하는 나에게는 정말 사랑스러운 표현 방식이다. 이 방식보다는 추후 등장할 @emotion/styled가 정말 압도적이다. ( DX 향상의 길. )

  const ExampleStyle03 = css({
      backgroundColor : 'hotpink',
      color : 'white',
      '&:hover':{
          color:myColor, // JS 변수
      }
  })

해당 표현 방식은 CSS 프로퍼티 명이 camelCase로 바뀌는 것만 주의하면 된다. 또한 TypeScript 환경에서 자동완성이 더 잘된다는 이점이 있다.

TS에서 자동완성이 더 잘되는 이유
" CSS 속성명이 JS 객체의 키(Key)이기 때문 "
그러므로 1. Tagged Template Literal의 경우 TS 관점에서 백틱 안은 그냥 문자열이다. 오타가 나도 타입 에러가 발생하지 않고, 자동 완성도 되지 않는다.
2.Object Style의 경우 css( )함수는 인자 타입으로 CSSObject(React의 CSSProperties 기반)를 받는다.
JS객체의 키로 CSS 속성을 사용하기에 TS가 타입 검사를 할 수 있다.
이로 인해 아래와 같은 편리함이 생긴다.

• 자동 완성 : back 입력 시, backgroundColor 등 후보 목록이 뜸
• 오타 감지 : 존재하지 않는 속성명에 빨간 줄이 생김
• 값 타입 검사 : font-size:'abc' 처럼 잘못된 값 타입을 잡아줌
  정리하자면, _" **Template Literal 안은 TypeScript가 '문자열'**로 보고, **Object Style은 TypeScript가 '타입이 있는 객체'**로 본다. "_

@emotion/cache와 스타일 캐싱에 대해 짧게 먼저 소개를 해보자면,

Emotion은 같은 스타일이 중복으로 삽입되지 않도록 내부적으로 캐시를 사용한다. 동일한 스타일 문자열은 동일한 클래스명을 반환하고, 이미 <style>태그에 존재하면 다시 삽입하지 않는다. 성능 최적화가 내장된 셈이다. ( 최고다...!!!! )

4. @emotion/css VS @emotion/react VS @emotion/styled 비교

그렇다면, 이제 뭘 써야할까? 라고 할땐 React 기반이라면 개인적으로는 @emotion/styled를 추천한다.

3가지 패키지를 표로 비교를 해보자면 다음과 같다.

4-1. @emotion/css

_" 프레임워크 무관, 가장 심플한 진입점 " _

import { css, cx } from '@emotion/css'

const ExampleStyle04 = css`
    color : hotpink;
`

<div className={ExampleStyle04}> @emotion/css 예시 코드 </div>

• Babel 설정이 전혀 필요 없다. npm install 후 바로 사용 가능
• css( ) 함수가 클래스명 문자열을 반환(핵심!!)
• 클래스를 합성 시, cx( ) 함수를 사용
• SSR 적용 시 추가 설정이 필요하고, 테마 시스템이 없다.

참고 : 공식 문서 예시 출력 화면(🔗 문서 이동)

이런 경우에 선택하는 걸 추천한다.

1. React가 아닌 환경(Vue, Svelte, Vanilla JS 등)에서 Emotion을 사용해야 할 때
2. Babel 커스터마이징이 불가능한 환경(CRA 기본 설정 등)에서 가장 빠르게 시작하고 싶을 때

4-2. @emotion/react

_" React 유저의 메인 선택지 " _

/** @jsxImportSource @emotion/react */
import { css } from '@emotion/react'

const ExampleStyle05 = 'hotpink'

<div css={css`color:${ExampleStyle05};`}> @emotion/react 예시 코드 </div>

• HTML 요소에 직접 css prop를 붙일 수 있음. styled API 없이도 컴포넌트에 바로 스타일을 입힐 수 있어서 보일러플레이트가 줄어든다.

  📝 용어 정리

• 보일러플레이트(Boilerplate) * " 기능은 없지만, 꼭 써야하는 의례적인 코드. 매번 반복해서 써야하는 틀에 박힌 코드 덩어리 "
  뭔가를 만들기 위해 실제 내용과 상관 없이 항상 작성해야하는 코드. 다다익손. 많으면 피로도와 실수가 증가함

보일러플레이터가 줄어든다를 더 잘 이해하기 위한 비교 예시 코드

// ========== @emotion/react 코드 ========== 
// 📄 Button.tsx
/** @jsxImportSource @emotion/react */
import { css } from '@emotion/react'

const Button = () => {
    <button css={css`
        background : pink;
        color : white;
    `}>예시 버튼</button>
}

//  ===== CSS Module 방식 : 항상 2개의 파일 필요. 반복 작업 증가 ===== 
// 📄 button.module.css
.button {
    background : pink;
    color : white ;
}

// 📄 Button.tsx
import styles from './button.module.css' // 매번 import 해야함

const Button = () => {
    <button className={styles.button}>css module 버튼</button> // className 연결
}

• @emotion/css와 달리 css( )함수가 클래스명 문자열이 아닌 내부 스타일 객체를 반환. 이 객체는 Emotion이 저레벨에서 해석해 다른 스타일과 조합 가능.
• SSR이 별도 설정 없이 지원. ThemeProvider를 통해 테마 시스템 사용 가능.
• 단, JSX Pragma 또는 Babel 설정이 반드시 필요.

참고 : 공식 문서 예시 출력 화면(🔗 문서 이동)

이런 경우에 사용하는 걸 추천한다.

1. React 프로젝트에서 Babel 설정을 커스터마이징 가능
2. styled 컴포넌트를 매번 만들지 않고 요소에 직접 스타일을 적용하고 싶을때
3. 테마와 SSR이 중요한 프로젝트

4-3. @emotion/styled

" styled-components에서 갈아타는 사람들의 선택 (마이럽💕)"

styled 패키지는 내부적으로 @emotion/react를 래핑한 API이다. 그래서 @emotion/react의 모든 기능을 포함한다. 래핑 패키지이기에 무조건 @emotion/react가 의존성으로 함께 설치되어야한다. ( 공식 문서 작성된 install 문을 보면 더 와닫는다. )

styled-components와 API가 거의 동일하여 마이그레이션 비용이 낮다. props 기반 동적 스타일링이 직관적이다. 'as' prop으로 렌더링 태그를 바꾸거나, shouldForwardProp으로 props 전달을 제어하는 등 고급 기능이 포함되어 있다.

참고 : 공식 문서 예시 출력 화면(🔗 문서 이동)

개인적으로 정말 추천한다. 이런 경우에 사용하는 걸 추천한다.

1. 팀이 styled-components 스타일 API에 익숙 + 마이그레이션 필요
2. 스타일을 독립된 컴포넌트 단위로 분리해서 재사용성을 높이고 싶을 때.

4-4. 비교 결론

실무에서는 @emotion/react와 @emotion/styled를 함께 쓰는경우가 많다고 합니다. _(클로드 피셜. 아니라면 독자분이 맞아요) _

재사용 컴포넌트는 styled로 만들고, 일회성 스타일 조정은 css prop으로 처리하는 식이다. 심지어 둘은 내부적으로 같은 캐시를 공유하므로 동시에 사용해도 충돌도 없다..!!

설명을 통해서도 선택하기가 어려우면 아래 단계를 따라 선택하면 된다.

Q1. React 프로젝트인가?

NO : @emotion/css YES : Q2 이동

Q2. Babel 설정이 가능한가?

NO : @emotion/css (제한이 있지만 가능) YES : Q3 이동

Q3. CSS prop VS styled API 중 선호 방식은?

CSS props: @emotion/react styled API : @emotion/styled

결론

Emotion은 " CSS를 JS답게 사용하고 싶다 " + " 그래도 CSS 문법은 익숙한게 좋다 " 를 만족하기 위해 만들어진 라이브러리다.

3개의 패키지 차이를 알고나면, 프로젝트 성격에 맞게 골라 쓰는게 점점 익숙해질 것이다. _( 이렇게 쓰고 난 @emotion/styled를 주로 사용한다. 헿~ ) _

*🔗 참고 * Emotion 공식 문서 : https://emotion.sh/docs/introduction

2주차 키워드 : 취업 사진 촬영, 멘토링, MVP 완성

1/12(6일차)

추가 기획 논의 및 개발 세팅 진행, 스타일링 이원화

첫 데일리 스크럼입니다!

저번주 백로그 기반으로 개발 시작 전 마지막으로 다듬는 시간을 가졌습니다. ( 못 알아 보실 것 알아서 블러 처리는 따로 안했어요!헤헿~ ) 이 과정에서 추가 기획이 생겼어요..( ..ㅠㅠ ) 빠른 배포를 목표로 MVP만 설정했지만, 다시 봐도 살 떨리는 양이긴했어요..

저 표정으로 크게 숨 한번 쉬면 진짜 갑자기 몸에 도파민이 싹돌아요. 추천합니다~ ^_^b 오랜만에 달릴 준비하니까 참..보람차구 힘이 납니다..(p)

아무래도 개발자라..개발 모먼트들도 함께 기록해봅니다!

📝 개발 기록 : 스타일링 전략

이번 프로젝트에서는 스타일링 전략을 조금 색다르게 가져가봤어요! 바로바로 Emotion + Tailwind 조합으로 이원화를 했답니다!!

굳이 이원화를 선택한 이유는.. 다양한 상태 변화와 빠른 구현, 두 가지 목표를 달성하기 위해 라이브러리 선정에서 고민이 많았어요. 그러다 각자의 장점만 골라서 쓰면 오히려 목적에 딱 맞겠다는 판단이 들었습니다! 저는 아래 기준으로 라이브러리를 사용했답니다~

Emotion : 상태 변화가 빈번하고 인터랙션이 많은 컴포넌트 구현

• props 기반 조건부 스타일링으로 상태에 따른 동적 스타일 처리
• 디자인 토큰 기반 theme 설정으로 추후 기업 연계 시 확장성 확보
• 다수의 상태 기반 변형 구조를 객체화된 스타일로 관리해 유지보수 용이

  Tailwind : 상태와 무관한 정적 레이아웃 영역 구현

• 정적 영역에서 CSS-in-JS 런타임 오버헤드 제거로 성능 최적화
• spacing, flex 정렬 등 반복 스타일을 유틸리티 클래스로 빠르게 구현
• 별도 스타일 파일 없이 마크업 내에서 즉시 레이아웃 구성 가능

이원화 덕분에 동적 UI의 표현력 + 정적 레이아웃의 생산성, 두 마리 토끼를 모두 잡을 수 있었어요~🐇🐇 앞으로 반복되는 Tailwind 클래스를 더 효율적으로 재사용하는 방법도 틈틈이 공부해봐야겠습니다!

오늘의 개발 기록 끝!

오늘의 점심은 각자 배달시켜먹었슴다! 포케 러버는 포케를 시켜먹었는데요!! 제가 먹었던 포케 중 가장 양이 많고 맛있는 곳 맛있는 곳을 찾았어요..💗 포케 러버분께 너무 추천해요~ ( 건강하고 돼람직한 메뉴 선택이었다. )

1/13(7일차)

취업 사진 촬영 (팀별로 사진 촬영 일정 다름)

오늘의 팀 이벤트는 조금은 널널했어요~ 저희 팀은 취업 사진을 가장 처음 찍게 되었는데요!! 카메라 앞에서 엄청난 뚝딱 로봇이 되는 사람이라 정말 긴장 많이했지만, 촬영팀 스태프분들이 너무나 즐겁게 도와주셔서 활짝 웃는 취업사진을 얻을 수 있었답니다!! ( 돌잔치 체험 덕분에 자연스러운 웃음 GET )

기초화장(피부+쉐도우)을 하고 가면, 빠르게 추가 메이크업과 헤어 스타일링을 해주십니다! 장점만 살리는 메이크업을 엄청 빨리 해주셔서 당황스러울 정도로 신기했어요.. 헤메 다하는 데 (기억상) 10분..?15분..?걸렸어요..! ( 이때 수정해주신 부분 기억 못하는게 너무 한스러울 뿐. )

다들 깔쌈한 얼굴로 개발 논의를 마저 진행했답니다~ ( 핸섬앤프리티 너디 최고다. ✨ 🤓 💗 )

추억 강박증 환자는 오늘 같은 🎀pretty event🎀, 놓칠 수 없어요. 바로 옆에 있는 포토이즘으로 이동합니다.

📸 추억을 추억하는 사진 찍기를 도촬당한 사진 ( 추추사사.아줌마 의미 없는 별다줄 좋아해요.. )

팀 컨지 첫 단체사진!!( 최고다 팀컨지! )

개인적으로 프로그램 초반에 프로필 사진 촬영해서 좋았습니다!! 더 바쁠때 찍었다면, 프로필 촬영에 신경도 못 쓰구, 프로젝트 흐름이 많이 깨졌을 것 같아요!

이렇게 즐거운 추억 저장 후 다시 본업으로 돌아왔습니다..😇

오늘의 데일리 스크럼이에요! 프론트는 백업이 없으니..그동안의 개발 지식을 총동원해 '확장 가능한 구조로 MVP 구현하기'를 목표로 잡고 달렸습니다. 그리고 해냈어요.

1/14(8일차)

멘토링

오늘은 두 번째 멘토링이 있는 날이었어요! 개인적으로 아쉬운 점은 멘토분들이 개발과 디자인 멘토가 아닌 전략, 마케팅, 투자 멘토 셨다는 점이에요.

물론 멘토링 시간들이 너무나 도움되는 시간들이었지만, 파트별 멘토링을 통해 실무에 가까운 역량을 쌓고 싶던 저는 많이 아쉬웠어요..ㅠㅠ

오늘의 데일리 스크럼입니다~

그동안 에디터 개발만 하다가 오랜만에 카카오 SDK 사용하니까 조금 신이 났어요~~

우리의 👑Queen_👑, 매주 금요일 제출인 운영 문서화를 간편하게 작성하기 위해 영수증 정산 서비스를 만들었어요.. 덕분에 저희 팀은 운영쪽에서 힘을 빼고 프로젝트에 더 집중할 수 있었답니다!! _( 진짜 개발자, 퀸수👑 )

개발 공부를 하면 할수록 느끼는 건데요.. 성장 속도보다 의무적으로 알아야하는 지식들이 더 많아지는 것 같아요..특히 요즘엔 더.. 아휴! 솔직히 개발 왤케 할게 끝이 없을까요!!증말!! ( 당연함. 기술파트라 그럼. )

1/15(9일차)

플로우 개발

오늘은 잔잔한 Day 시작이에요~

그리고 와글와글 오늘의 데일리 스크럼입니다. ㅎ..나자신 화이팅!!

다들 2주차 후반부 오니까 힘든가봐요.. 저만 그런줄 알았는데, 모두가 힘들지만 열심히 일하는 거 보고 다시 힘을 얻어요..!! 빡집중해서 개발하는데, 저의 늙은 노트북은...벌써 2번의 블루 스크린이 떴어요.. 이제 곧 보내줄 때가 됐나봅니다.. ( 죽어도 못 보내.. ) 깜빡했는데, 신한에서 정말 빠르게 피드백을 잘 반영해주십니다!! 듀얼 모니터, AI 구독료 등 여러 방면으로 최대한 많이 지원해주셨답니다!! 제가 참여했던 대외 활동 중 가장 소통이 잘 되는 프로그램이었어요👍👍

플로우 하나 구현 완료했어요~ ( 뿌듯뿌듯~ )

이제 영역 전개 구현으로 들어갑니다. ( 팀 컨지를 향한 하트. 받으세요.💟 )

1/16(10일차)

긴급 기획 회의 & 서류 제출

오늘은 이슈 파티 데이에요~🎉 저희 팀은 하나의 큰 목표를 위해 3개의 서비스가 단계별로 필요한 상황이었는데, 그 중 2번째 서비스에서 이슈 상황이 발생했어요!

능력자들이 모인 저희 팀, 회의 한번으로 해결했답니다!! ( 그냥 박수갈채👏👏👏👏👏 )

오늘은 제가 사랑니 이슈로 아침 조퇴를 했는데요! 생각보다..출혈이 멈추지 않아서, MVP 구현은 주말 내에 완성하기로 하고 푹 쉬었답니다! 내 몸이 내 마음을 이해한 순간. 이렇게 기쁠 수가 없어요.. 광대 잔뜩 올라간 상태로 푹 휴식했답니다~ ( 하지만 이러고 다음날 응급 내원했어요..🦷🩸🩸 )

어느정도 회복 후 다시 작업에 들어갔습니다! 1주차 깃허브 이슈는 총 14개였습니다! 6일만에 MVP 구현...이게 정말 될 줄 몰랐어요..! 전에 7일 안에 MVP 구현을 했었는데, 이번에 하루 줄였어요!! 이렇게 인생 업적에 하나 또 추가합니다~ ( 룰루랄라~ )

이번 플젝을 통해 새로운 습관이 하나 생겼습니다! 자잘한 이슈 파악이 아니라면, 디버깅을 위한 컴포넌트를 구현해서 화면에서 바로 디버깅을 하는 습관이 생겼어요! 사진은 웹소켓 통신을 바로바로 확인할 수 있게 컴포넌트를 구현한 화면이랍니다~ 다음에도 이 방식으로 빠르게 상태 파악하고 릴리즈때 삭제해야겠어요~

2주차 활동은 자존감을 회복할 수 있던 행복하고 뜻깊은 시간들이었습니다! 앞으로 또 얼마나 회복하고 성장할 수 있을지 기대를 한아름 안고, 2주차 기록 끝!!

사진 출처 팀컨지 (진짜 곧) 인플루언서님의 블로그 줍줍..아자스..아이시떼루..

1/5(1일차)

킥오프(OT)

기본 스케줄은 9:30~17:30까지지만, 오늘은 오후 1시부터 시작했어요!! 6주 동안 이렇게 여유로운 스케줄은 당분간 없겠죠..아좌잣! (나자신)_화이팅..!! 킥오프 장소에 도착하니까 '이제 진짜 시작이구나' 싶어서 심장이 두근두근 했답니다!! _( 원래 심장은 두근두근함. 그냥 귀엽게 시작해봄 ) 1주차는 지하 라운지?에서 활동한다고 합니다! 춥지 않고 참 따뜻했어요! 다만, 노트북 충전이 어려워서 늙은 노트북을 가진 저는 조금 힘들었어요ㅠ_ㅠ

일찍 도착해서 짐 놓고 바로 옆 명동교자로 점심을 먹으러 갔습니당~ 사실 몇번 먹어봐서 이젠 엄청 맛있다?는 잘 모르겠는데, 빨리 나와서 좋았어요~

이름표를 받고 임시로 원하는 자리에 착석했답니다!

간단하게 OT가 끝나고, 레크레이션을 시작했는데요, 좀 새로운 레크레이션이 많아서 시간이 빨리 갔어요. ( 대문자 I인간에게는 힘들었음...흑흑 ) 힘들었지만 짧은 시간 동안 같은 테이블 팀원분들과 가까워졌답니다! 레크레이션에서는 맞은편 팀원의 얼굴을 종이를 보지 않고, 얼굴만 보고 그리는 시간도 가졌는데요? 저는 금손 디자인 팀원분이 그려주셔서 사람 얼굴이 나왔답니다!! 1분?정도 짧은 시간이었는데, 저렇게 디테일하게 그리시다니..역시 금손이에요

해커톤에 참여하면 신한의 이달의 희망이 될 수 있답니다? ( 일석이조 미쳤다...진짜 미쳤다..아..😫 ) 킥오프 때 같은 테이블이었던 팀원분들과 추억을 남기지 못한게 아쉬웠는데, 이렇게 박제되어서 반가웠어요~ ( 많은 얘기를 나눠보지는 못했지만, 너무나 좋은 분들이었습니다!! 뒤늦게 몰래 전해보는 속마음이에요..🫶 )

이렇게 1일차 킥오프가 끝나고 과제가 생겼어요. 다음날 발표할 자기 pr 준비하기 에요.. 자기 PR은 팀빌딩에 꼭 필요한 시간이긴 하지만, 항상 부끄럽더군요.. 제가 어떤 사람인지, 함께 하고 싶은 팀원상을 (기억상) 3분이라는 짧은 시간 내에 전달하고자 수정을 무한반복 하다보니, 어느덧 새벽 3시에요...

전 여기서부터 느꼈어요.

이 해커톤...생각보다 더 바쁘겠다..

( 이런 과제는 사전에 공지해주셨다면, 촉박하지 않게 준비할 수 있었을 것 같아요! )

1/6(2일차)

자기 PR & 기업 소개 1차

오늘은 자기 PR 1차날이에요! 총 49명이 발표했고, 백엔드>프론트>디자인 순이었어요!

역시나 대단하신 분들 가득이었어요.. 개인적으로 대외활동을 하면 할수록 제가 우물 안 개구리였구나를 느낍니다! 오늘도 우물 밖 세상을 맛보았어요!!! 긍정적 자극 많이 받아요. 아 오늘 도움 많이 된다.

그런데...

ㄹㅈㄷ개큰 사고... 저는 프론트 협업을 꿈꾸며 들어온건데, 팀당 프론트가 1명이래요... (프론트 아예 없는 1팀도 있어요..)

매니저님 말씀으로는 프백 비율을 맞추기 위해 총점이 높은 지원자분들을 불합격시키는 건 형평성에 맞지 않다고 판단되어 비율 생각하지 않고 총점 순으로 뽑으셨다고 하셨지만... 팀에서 프론트가 나 혼자라니...!!혼자라니...!!! 일단 좋은 팀원들 만나고 싶어서 털린 멘탈은 미래의 나에게 일단 토스해봐요.

긴장 가득한 저의 발표... 어떠셨을까요..? 저도 제가 이렇게 많이 떨줄 몰랐어요..다들 좋게 봐주셨기를 기도했답니다..🙏🙏

오늘은 오전부터 시작한 스케줄이라 중간에 점심시간이 있었는데요! 매니저님이 맘스터치 햄버거를 사주셨어요~ 맛있다! 내일부터는 팀원분들과 먹는데요!! 아직 팀빌딩도 안했지만, 벌써 기대되는 첫 회식?이에요!!!

오후까지 자기 PR을 마무리한 뒤, 팀빌딩을 진행했답니다! 2기 팀빌딩은 개발자는 한팀에 최대 3명, 팀 전체 최대 인원은 5명까지 가능했어요. 2기 기준으로 가장 이상적인 팀 비율은 백엔드 2 : 프론트 1 : 디자인 2 이었습니다!

팀빌딩은 뭐 따로 시간을 주시지는 않고, 그냥 닌자에 빙의해서 자기 pr로 얻을 수 있는 정보로 각자 원하는 분들에게 연락했답니다! 그래서 다들 PR 시간 후반부가 될수록 핸드폰과 노트북으로 바쁘게 연락하셨어요! ( 아닐수도..저만 그런거일수도.. )

저희 팀은 조금 빠르게 팀빌딩이 완료되었습니다!( 속도감 호감. ) 훌륭한 개발자분들과 디자이너분들이 많았지만, 어떤 분들과 협업핏이 맞을지 자기 PR내내 메모를 남겼다가 자기 PR이 끝나자마자 바로 연락을 드렸어요~💌 조금 빠르게 움직여서 원하던 팀원분들을 다 모셔올 수 있었어요!! ( 사랑해 팀 컨지!🫶 )

우리의 첫 추억...✨ 팀 컨지 빌딩 완료!!!

1/7(3일차)

기업 소개 2차

오늘부터는 팀별로 점심시간을 가지게 되었답니다~( 두근두근 팀 활동!! ) 오늘의 타임테이블입니다. 총 8개의 기업이 참여하다보니, 기업 소개에 1.5일을 사용할 수 밖에 없었어요..!! ( 지치지?않아?요... )

팀 컨지의 첫 회식은 베트남 음식이었답니다!

꼭 기억하십쇼.

꾸에흐엉. 볶음밥. 해물비빔면.

저에게 명동은 정말 많이 온 곳이지만, 맛집을 발견할 수 없는 곳이었는데요... 꾸에흐엉 진짜 맛있어요...이제라도 알아서 너무 좋아요..

팀원분이 근처에 위치한 헤이티가 맛있다고 해서 트라이해봤는데요!! 저 치즈폼 처음 먹어보는데 사랑에 빠졌어요...포도와 치즈의 만남 최고다..

밥먹고 아직은 어색한 팀컨지의 모습이 도촬당했답니다! 아쉽게도 저희 팀원 분 한분이 일정이 있어 같이 도촬당하지 못한게 아쉬워요~

사진을 남기지는 못했지만, 저희 팀은 기획안 작성을 위해 오후 20:30까지 야근?을 하고 집에갔답니다.. 오늘 불참했던 팀원분은 일정을 끝내고 다시 명동으로 출근해서 같이 회의를 진행했어요!! 열정가득걸들...( 성별은 다수결 따름 ) 덕분에 저희는 하루 만에 기업 선정과 메인 기획에 대한 큰 틀을 잡을 수 있었답니다!

1/8(4일차)

팀빌딩 & 특강

오늘은 팀별로 연계할 기업에 대해 논의하는 시간과 특강을 들었어요!

오전 오후에 한타임씩 특강을 들었습니다. 특강해주신 두분 다 너무 본받을 점이 많은 멘토분들이셨어요! 현재의 제가 가진 고민과, 미래의 제가 가질 수 있는 고민들에 대해 많은 인사이트를 얻을 수 있는 특강들이었습니다! 특강 내용을 참고하며 어떤 기업을 선정하는게 좋을지 고민했어요~

오늘 드디어 팀명을 정했습니다!!! ( 개인적으로 팀 활동에서 가장 중요한 부분이라 생각합니다. ) 여러 아이디어 중 마음이 움직이는 네이밍이 나오지 않아 고민하던 찰나 나왔어요!! 'Ctrl+G'가 나왔어요!!! '그룹화' 기능 단축키라는 뜻이 디발자(디자이너+개발자)에게 너무나 매력적인거에요~ 그래서 이렇게 Team.Ctrl+G(컨트롤지)가 되었답니다! ( 다시 봐도 호감. )

그 뒤 기업 선정에 있어서 저희팀은 꽤 다이나믹한 의견 변경이 있었는데요! 이 과정이 참 즐거웠어요!!

팀 구성안 및 기업 선정 제출 형식과 취업 컨설팅 일정을 공유해주셨어요!!

오늘은 명동교자에서 비빔국수를 먹었습니다! 먹으면서 ㄹㅈㄷ 빌런 팀원 썰 들어서 입도, 귀도 매운 흥미진진한 시간이었어요!!

1/9(5일차)

기업 선정과 기획안 작성 및 제출

기업 선정과 기획안 문서는 팀원 소개와 희망 기업을 작성한 뒤, 해당 기업별 기획안을 제출하는 방식이었습니다. 저희는 어제 1지망 기업의 기획안을 어느정도 진행해서 그런지, 조금은 수월하게 문서를 작성한뒤 제출했어요!

어제 집중해서 기획안을 완성해서 그런지, 오늘은 제출 형식에만 힘을 썼어요!

기획안 제출 후 공정한 자리뽑기를 시작했어요! 진짜 그냥 운에 맡긴 뽑기였어요! 앞으로 6주 동안 보낼 공간이라 다들 도파민과 긴장 그 사이 어딘가의 상태로 화면만 쳐다봤답니다..

두둥탁탁..ㅠㅠ 10팀 중 저희가 마지막 순서로 뽑히게 되어서 선택권이 없었답니다ㅠㅠ

자리가 어떻게 구성되어있는지 미리 전달받은 내용이 없어서 '이미 좋은 자리는 다 나가겠다ㅠㅠ'라는 아쉬움을 가지고 처음으로 활동 구역으로 올라갔습니다! 6주 동안 이 쾌적한 공간에서 생활한다니갑자기 취직 한 것 같아서 두근두근했어요

그런데 자리가 너무 좋은거에요!! 사실 어느 자리든 다 좋았을 것 같긴한데, 저희 팀원 모두 "넓은 공간 선호"걸들이어서 선택권 없이 배정된 자리가 오히려 좋았습니다! 앞으로 이름표 없이 활동해서, 네트워킹을 위해 종이 명패를 만들어서 각자 자리에 붙여놨답니다! ( like 무한상사..헿~우리팀 벌써부터 재밌다 )

팀 구역에 자리를 풀고 저희가 넘..신나버렸는지 게임을 진심으로 해버렸어욥..ㅎㅎ 그래서 매니저님께 '금쪽이'타이틀을 얻었답니다! ( 사실 저희팀 금쪽이 타이틀 좋아했어요..팀 ctrl금쪽이들..ㅎㅎ ) 매니저님의 새로운 네이밍 덕분에 닉값하는 팀이 되었답니다! 헿 0_<~

잠시 휴식을 즐겼다가 다시 본업으로 돌아왔어요.

첫 주의 마지막 날은 협업 환경 구성하고, 다음 주 할일을 정했습니다! 팀 노션을 호다닥 만들고, 다들 경력직답게 빠르게 노션 템플릿을 만들었어요!

저희 팀은 이번 프로젝트에서 '스크럼'방식을 진행하기로 했어요!

이말은 뭐냐, 6주 동안 아주 바쁜 일상을 보낸다는 말이었어요...!!! 항상 워터폴에 가까운 방식으로 프로젝트를 진행해왔기에 이번 협업 방식이 무척 기대되었답니다!( 걱정 한스푼 아니 한컵과 함께... )

저희 팀이 정한 스크럼 방식은 아래와 같습니다!

• 사용자 니즈에 가까운 산출물을 만들기 위해, 주별 목표를 정하고 매주 MVP 배포를 진행한다.
• 매일 아침 일과 시작 전 약 5분정도 모든 팀원들과 진행 상황과 이슈를 공유하는 데일리 스크럼을 가진다.
• 매주 금요일은 다음 주 일정을 위해 스프린트 회의를 진행한다.

저희 팀은 노션 캘린더에 각각의 이벤트를 해당 일자 속 페이지를 만들어서 공유했습니다! 각자 다른 취업 패키지 일정(사진 촬영, 자소서 컨설팅, 모의 면접)과 그 외의 이슈(조퇴, 결석 등)를 캘린더에 미리 다 작성한 뒤 큰 계획을 잡기 시작했어요! 짜잔!오늘 해야할 일이랍니다!

현업에 가까운 협업 환경을 위해 메신저로 슬랙을 선택했어요! 빠르게 슬랙도 판 뒤, 규칙 기반 채널들을 생성했답니다~

이렇게 협업 환경을 구성 후 이제 본격적인 업무를 시작했습니다! 스크럼 방식을 선택하였기에 저희는 다음 주 할 일을 오늘 다 구성해 놨어야 했습니다. 약 3시간 동안 논의를 통해 백로그 정의 후 우선순위 기반으로 MVP 선정 후 다음 주 목표를 정하였답니다..! ( 나혼자..프론트...다시봐도 까마득했던 순간이 기억납니다..)

사실 저는 엄청난 추억 강박증 환자인데요 소소한 재미를 남기고 싶어서 노션에 daily.log를 만들었어요!! 그냥 별건 없고 각자 남기고 싶은 아무말 대잔치 공간이었어요~

이렇게 본격적이고 재미있는 해커톤이 시작되었답니다!!

쾌조의 스타트, 1주차 기록 끝!!

** 사진 출처**

신한금융희망재단 블로그에서 추억 몇개 가져왔습니다..아자스..👍 팀컨지 (곧) 인플루언서님의 블로그에서 줍줍해왔습니다..아자스2..👍

지원 동기

취준 1시즌을 보내며 성과 없이 열심히만 하는 생활이 반복되다보니, 자기 효능감과 의욕을 잃었다.

의욕을 잃어버린 것에는 두가지 이유가 있다 생각했다.

1. 개발 커리어에서 가장 큰 의욕을 얻고 있던 프로젝트가 점점 부담으로 느껴짐
2. 반복되는 탈락으로 인한 자신감 하락

그래서 극약처방인 "환경 바꾸기"에 들어갔다. 지금와서 들어갈 수 있는 동아리나, 그런 여건도 되지 않았기에 조금은 막막하던 찰나 신한 스퀘어브릿지 청년 해커톤을 알게되었다.

고민하고 있던 도메인 중 핀테크도 포함되어있고, 해커톤 연계 기업으로 참여하는 기업들이 매력적이었기에 현재 필요한 환경 바꾸기에 최적화된 활동이라 생각했다.

약 1주일이 남은 시점에 발견하여 지원서를 급하게 작성하기 시작했다.

서류 작성(지원서+포트폴리오)

총 4개의 문항이 있었다.

1. 지원 동기 2. 지원 동기와 관련된 경험 3. 나의 보유 스킬 및 역량 4. 해커톤을 통해 이루고 싶은 목표와 기대하는 점

위의 문항들에 대해 각각 300~1000자 이내로 작성해야 했다. 여기서 나의 고질병인, "좀만더병"이 발생되버렸다. 난 첫번째 문항에서 6일을 써버렸다.

하고싶은 말은 많고, 깔끔하게 나의 지원동기와 내가 어떤 사람인지 표현하고 싶어서 계속 다듬다가 선택사항으로 제출해야하는 포트폴리오도 미쳐 다 다듬지 못했다!!! ( J 실격이다 )

취준 시즌에 가장 어려운 점은 나 자신을 스스로 파악하는 것이 어렵다고 생각한다. 당연하다고 느껴지는게 나의 특징이라 그 당연한걸 캐치하는 게 너무 어려웠다. 그래서 6일동안 너무 당연하다 생각해서 작성하지 않았던 나의 특징들을 뒤늦게 특징으로 정의한 뒤 고쳐나갔다. 그 작업을 하고 나니, 나머지 세 문항에서 필요한 소스들을 얻어 5시간 만에 나머지 문항 완성이라는 기적이 일어났다.✨ ( 하지만, 다시는 이러지 않을 것. J 실격 2 )

마감 당일 제출을 먼저한 뒤, 포트폴리오 작업을 시작했다. ( 선택 사항인 포트폴리오는 이메일 제출이었다. 선택이지만, 필수입니다✨ )

기존에 만들어둔 오리진 포트폴리오가 있어서 추가로 디자인과 내용을 다듬었는데, 제출하고 나서 보니 내용 실수가 2개나 있었다... 아찔했지만, 이미 늦음.

그렇게 4일 뒤, 문자가 왔다.

면접(대면)

면접은 오래 준비하지 못했다. 이유는 정확히 기억나지 않지만, 무언가로 인해 무척 바빠서 전날 겨우 시작한 게 전부였다. 자기소개와 기술 면접 준비만 간신히 챙긴 채 명동으로 향했다.

면접장에 들어가니 출석 체크 후 이름표(스티커)를 받고, 면접 조 뽑기가 진행되었다. 기억상 4번째 조였나... 첫 번째와 마지막은 아니었는데, 갑자기 우리 조가 첫 번째로 면접에 들어간다는 거 아닌가요..???? ( 당황했지만, 오히려 좋아. 매도 먼저 맞는 게 낫지. 그래도 좀 당황스러운 건 어쩔 수 없었다 )

4인 1팀으로 약 15분간 팀 면접이 진행되었다. 면접 문항은 총 3개였고, 답변에 따라 짧은 꼬리 질문이 몇 개 이어졌다.

1. 자기소개
2. 최근에 관심있게 본 빅테크 기업이나 스타트업
3. 개발하면서 팀으로 어떤 상황이 가장 저하되는 요인인지, 그리고 개발자로서 나의 단점이 무엇인지

개발 파트 지원이라 기술 면접이 있을거라 긴장했는데, 인성 면접 위주여서 한결 편하게 임할 수 있었다.

면접관들은 총 4분이셨다. 해커톤이 끝난 시점에서 돌아보니, 해커톤 사업 담당 대리님과 팀장님, 그리고 멘토님 2분이셨던 것 같다.

면접 분위기는 무척 좋았다. 짧지만 따뜻한 아이스브레이킹이 있고, 공격적인 질문은 전혀 없었다. 아쉬웠던 건 면접 시간이 너무 짧아서 '나'라는 사람을 다 보여주지 못한 느낌이었다는 것. 이렇게 짧은 시간 안에 사람을 어떻게 평가할 수 있을까, 라는 의문이 남는 면접이었다.

면접을 나쁘지 않게 보긴 했지만, 크게 임팩트 있는 지원자는 아니었다고 판단되었다. 서류와 짧고 임팩트 없는 면접으로 과연 내가 뽑힐 수 있을까, 솔직히 탈락을 50%쯤 예상하고 있었다. ( 면접 후 정신 없던거 티냈던 사람. 명동에 제 이름 자랑하고 다녔어요~ )

결과

그렇게 2주 뒤, 붙었다..! 최종 합격이다!!!

최종 합격 후에는 기한 내에 제출해야 하는 서류가 2가지 있었다. ( 제출하지 않으면 탈락이다. ) 프로그램 내 취업 역량 강화를 위한 취업 패키지의 일환으로, 자소서 멘토링과 모의 면접 멘토링에서 사용할 이력서와 자기소개서였다.

이미 취준 1시즌을 보낸 덕분에 준비된 서류가 있었고, 조금만 다듬어 제출하면 됐기에 크게 어렵지는 않았다.

다만 한 가지 아쉬운 점이 있다면, 자소서 제출 형식이 따로 정해져 있지 않아서 희망 기업 지원 동기를 1,000자 정도만 작성해 제출했는데, 막상 자소서 멘토링을 받고 나니 _여러 문항을 더 작성해서 낼걸 _ 싶은 후회가 남았다.

자세한 이야기는 다음 후기에서.. ✨

합격이라는 글자에 설레면서도, 앞으로 만날 6주가 살짝 두렵기도 했다.

지난 2년은 고난과 시련을 파도타기하듯 '아 즐겨~🤩' 하는 마인드로 버텼는데, 요즘 들어서는 그냥 파도에 휩쓸리며 '살려주세요..😢' 하면서 겨우겨우 헤쳐나가고 있었다.

이번 합격이, 그 마인드를 다시 장착하는 데 꽤 큰 도움이 됐다. 😎

앞으로 어떤 고난과 시련과 성장이 기다리고 있을지 모르겠지만,

덤벼.