프론트 서버 한대가 죽었다는 알림이었는데요. 트래픽이 몰리거나 메모리 문제 혹은 DDoS 공격 등으로 인해 간헐적으로 발생하던 문제였기 때문에 메뉴얼대로 처리하고 원인에 대해서는 월요일에 파악하자고 하면 마무리되는 듯 했습니다. 그런데 한 10분 정도 지났을까요? 또 다시 서버 한대가 죽었다는 AWS 메일이 왔습니다.

뭔가 잘못됐다는 것을 느꼈고, 몇일 전 Next.js 보안 이슈가 발표됐다는 것 알게되었습니다. 이번 이슈는 단순 라이브러리 경고 수준이 아닌, 구조적으로 서버 코드 실행까지 이어질 수 있는 취약점이었기 때문에 실제 운영 관점에서 많은 점을 다시 점검하게 된 계기였습니다.

이 글에서는 취약점이 어떤 문제였는지, 서비스에 어떤 영향을 줄 수 있었는지, 어떻게 대응했는지 경험을 바탕으로 정리했습니다.

React2Shell 이 뭔데?

React2Shell(CVE-2025-55182) 은 React Server Components의 RSC 프로토콜에서 발견된 취약점으로, CVSS 점수가 10.0인 최고 등급의 보안 취약점입니다. React 19의 react-server 패키지가 RSC Flight 프로토콜 처리 과정에서 안전하지 않은 역직렬화로 인해 악의적인 HTTP 요청을 통해 서버에 임의의 코드를 실행 할 수 있는 문제입니다.

이 취약점이 특히 심각한 이유는 다음과 같습니다.

1. 기본 설정만으로 취약

create-next-app 으로 만든 기본 프로젝트도 공격 대상이 됩니다. Next.js 15의 App Router는 RSC를 기본으로 사용하는데, 바로 이 구조 자체에 취약점이 있었습니다.

2. 인증 없는 원격 코드 실행

공격자는 인증 없이 단 하나의 조작된 HTTP 요청만으로 서버에서 코드를 실행할 수 있습니다.

3. 광범위한 영향

React 사용자의 82%, 클라우드 환경의 39%가 취약한 버전을 사용 중이었습니다. 수많은 서비스가 잠재적인 공격 대상이었던 것입니다.

4. 빠른 무기화

취약점 공개 후 불과 몇 시간 만에 실제 공격이 시작되었다고 합니다. 중국 국가 지원 해킹 그룹을 포함한 여러 공각자들이 즉각 움지였고, 저희 서비스 또한 그 표적이 되었던 것입니다.

문제가 발생한 이유는?

상황

RSC를 사용하는 곳에 직렬화하는 부분에서 의도적으로 조작된 URL이 들어오게 되었습니다. 그 URL은 사실상 서비스에서 제공하지 않는 비정상적인 요청이었는데도 불구하고 Next.js에서 정상적인 요청으로 받아들였습니다.

여기서 문제는 Next.js가 next-action 헤더가 포함된 요청을 받으면 개발자가 실제로 서버 액션을 작성했는지 여부와 상관없이 무조건 해당 요청의 데이터를 처리하려고 시도한다는 점이었습니다. 공격자는 이 점을 악용해 next-action 헤어만 붙여서 악성 코드를 서버로 전송할 수 있었습니다.

문제

그 조작된 요청은 중국 암호화폐 채굴 스크립트를 실행하는 URL이었고, 그 공격으로 인해 CPU 사용률이 급격히 증가하면서 서버가 계속해서 다운되는 현상이 발생했습니다.

공격이 성공하면 서버에서는

• cpu 사용률 급증
• 외부 중국 서버로 지속적인 네트워크 연결 시도
• 헬스체크 실패로 인스턴스 종료
• 오토 스케일링으로 새 인스턴스 생성 -> 다시 공격 -> 반복

처음에는 한두대였지만, 몇 분 간격으로 추가적으로 서버가 다운되면서 상황은 심각해졌습니다.

원인

React2Shell(CVE-2025-55182)의 핵심 원인은 안전하지 않은 역직렬화(Unsafe Deserialization) 문제입니다.

React Server Components는 클라이언트와 서버가 데이터를 주고받을 때 Flight 프로토콜이라는 방식을 사용합니다. 이 과정에서 데이터를 "직렬화(문자열로 변환)" → "전송" → "역직렬화(다시 객체로 복원)" 하는데, 바로 이 역직렬화 과정에서 보안 검증이 부족했습니다.

1. 공격자가 겉으로 보기엔 정상적인 데이터를 전송
2. Next.js 서버가 이 데이터를 받아서 처리하기 시작
3. 숨겨진 특수 속성들이 Javascript의 핵심 기능에 접근
4. 공격자가 서버에서 원하는 코드를 실행

Next.js는 받은 데이터가 이상한 속성이 포함되어 있는지, 위험 코드가 실행될 수 있는지 등을 제대로 확인하지 않았습니다. 이 취약점이 특히 위험한 이유는 인증이 불필요하고 기본 설정으로도 취약하며 공격 성공률이 거의 100%에 달했기 때문입니다.

어떻게 해결했지?

1. 버전 업데이트

가장 우선적으로 수행한 작업은 Next.js 버전 업데이트였습니다. 또한 Next.js 버전 업데이트와 관련된 다른 라이브러리 버전 또한 체크하여 업데이트 진행했습니다.

공식 권장 패치 버전 Next.js 15.0.x → 15.0.7 Next.js 15.1.x → 15.1.11 Next.js 15.2.x → 15.2.8 Next.js 15.3.x → 15.3.8 Next.js 15.4.x → 15.4.10 Next.js 15.5.x → 15.5.9 Next.js 16.0.x → 16.0.10

2. 긴급 재배포

패치 버전으로 업데이트한 후 즉시 프로덕션 환경에 재배포했습니다. 주말이었음에도 불구하고 밤늦게까지 고생한 동료들에게 너무 감사합니다😭

3. 보안 키 점검

패치된 버전으로 업데이트를 진행하면서 서비스에서 사용중인 시크릿을 점검했습니다. 공격자가 이미 환경 변수나 시크릿에 접근했을 가능성을 배제할 수 없었기 때문입니다.

4. 외부 방화벽 도입

또한 앞으로 이런 일을 예방하기 위해 내년 초 웹 방화벽 도입을 검토 중에 있습니다. 방화벽 도입 시 서비스에 도달하기 전 네트워크 레벨에서 비정상적인 요청 패턴을 차단할 수 있어 프레임워크 취약점이 발견되더라도 한 단계 더 안전한 방어막을 구축할 수 있습니다.

느낌점

이번 React2Shell 취약점 대응을 겪어보면서 보안에 대한 인식이 많이 달라졌습니다.

평소 Next.js 블로그나 커뮤니티에서 올라오는 버전 업데이트 공지를 무심하게 지나쳤던 것을 많이 반성하게 되었습니다. "major 버전만 올리면 되지 않을까?", "보안 패치는 급하지 않겠지" 하는 안일한 생각이 얼마나 위험했던 것인지 반성하게 되었습니다.

이번 일을 계기로 Next.js의 보안 이슈 및 소식에 대해 Slack으로 즉시 알림을 받을 수 있도록 설정했습니다. 보안 패치는 공개된 순간부터 공격이 시작될 수 있기 때문에, 커뮤니티의 소식을 빠르게 캐치하는 것이 첫 번째 방어선이라는 것을 깨달았습니다.

또한 AWS 알림의 중요성도 절실히 느꼈습니다. 만약 AWS에서 메일이 오지 않았다면 서버가 다운되는 것을 훨씬 늦게 발견했을 것이고 그만큼 서비스 장애 시간도 길어졌을 것입니다. 토요일 아침이라 모니터링 대시보드를 능동적으로 확인하지 않았던 상황에서, 실시간 알림이 즉각적인 대응을 가능하게 해주었습니다. 서버 상태, 리소스 사용률, 비정상 패턴 등을 실시간으로 모니터링하고 즉각 알림받을 수 있는 시스템 구축이 얼마나 중요한지 실감했습니다.

React2Shell 취약점은 현대 웹 개발 생태계에서 얼마나 빠르게 보안 위협이 확산될 수 있는지를 깨닫게 해주었습니다. 단순히 기술적인 문제를 넘어서, 조직의 보안 대응 체계, 모니터링 시스템, 그리고 개발자의 보안 의식까지 전반적으로 점검하게 만든 계기였습니다.

우리 모두 정기적으로 확인하는 습관을 가지면 좋을 것 같습니다 🙌🏻

// 프로젝트에 설치된 npm 패키지들의 보안 취약점을 검사하는 명령어
pnpm audit

📚 참고 자료

• Next.js Security Advisory: CVE-2025-66478
• AWS Security Blog: China-nexus cyber threat groups rapidly exploit React2Shell
• pnpm audit

이때 디자인 시스템 패키지에는 TailwindCSS를 설치하지 않고, 각 프로젝트에 설치된 Tailwind가 내부 className을 스캔해 스타일을 생성해줄 것이라 기대했습니다.

하지만 동일한 컴포넌트를 사용하는 두 프로젝트에서 한쪽은 정상적으로 스타일이 적용되었고, 다른 한쪽에서는 Tailwind 클래스가 누락되는 문제가 발생했습니다. 이 예상치 못한 차이를 분석하는 과정에서 여러 원인과 구조적인 제약을 확인하게 되었고, 제가 겪었던 경험에 대해서 정리해보고자 합니다!

1. 프로젝트 구조

모노레포는 다음과 같은 형태로 구성되어 있습니다! (이해를 돕기 위한 참고용 구조입니다.)

├─ apps
│  ├─ project-a
│  ├─ project-b
│  └─ ...
│
└─ packages
   ├─ design-system
   ├─ components
   ├─ hooks
   └─ utils

각 프로젝트는 apps 디렉토리 아래에 위치하며, packages에는 여러 프로젝트에서 공통으로 사용할 수 있는 패키지들(components, hooks, utils 등) 이 존재하는 구조입니다.

이 중 디자인 시스템은 다음과 같은 형태로 구성되어 있는데요. 빌드 결과물은 dist로 생성되며, 각 컴포넌트는 반드시 index.ts에서 export 해주어야합니다.

dist 란?

• 빌드된 결과물이 담기는 디렉토리를 말합니다.
• 개발 시 작성하는 토드틑 src 내부에 있지만 이 코드를 그대로 다른 프로젝트에서 사용하기 어렵습니다. (Typescrip, JSX, 내부 경로 등 그대로는 브라우저나 외부 프로젝트가 이해하지 못합니다ㅠ)
• 그래서 빌드 도구(tsup) 을 통해 JS로 변환하고 번들링한 최종 산출물을 생성하는데, 이 최종 산출물이 저장되는 폴더가 dist입니다!
• 즉, 외부 프로젝트에서 실제 가져다 쓰는 배포용 코드가 담긴 폴더 라고 할 수 있습니다

packages
└─ design-system
   ├─ dist
   ├─ node_modules
   ├─ src
   │  ├─ component
   │  ├─ contents
   │  ├─ theme
   │  ├─ types
   │  ├─ index.ts
   │  └─ index.css
   ├─ package.json
   ├─ tsconfig.json
   └─ tsup.config.ts

2. 문제

디자인 시스템을 적용하고 발생한 문제는 동일한 컴포넌트를 사용했는데 프로젝트마다 TailwindCSS 클래스 적용 결과가 다르게 나타난다 는 점이었습니다.

A 프로젝트에서는 디자인 시스템에서 정의한 Tailwind 클래스가 문제없이 적용되었지만, B 프로젝트에서는 동일한 컴포넌트임에도 일부 클래스가 누락 되어 스타일이 깨지는 현상이 발생했습니다.

A 프로젝트(적용 O)	B 프로젝트(적용 X)

같은 디자인 시스템을 import하여 사용하는데도 불구하고 특정 클래스만 적용되지 않는 상황이 반복되었습니다...😭

처음에는 Tailwind 설정 문제로 추측했지만 두 프로젝트 모두 동일한 설정을 가지고 있었기 때문에 단순한 설정 이슈로는 보이지 않았습니다. 겉으로 보기에는 환경 구성도 동일했기 때문에 문제의 원인을 바로 파악하기 어려웠습니다.

3. 액션

문제의 원인을 파악하기 위해 여러 방향에서 하나씩 검증을 진행했습니다. 처음에는 단순한 설정 문제라고 생각했지만 확인 과정이 반복될수록 디자인 시스템 패키지와 tailwind의 동작 방식이 예상과 다르다는 점을 알 수 있었습니다!

첫번째 시도: tailwind.config.js 경로 확인 ( ❌ )

GPT의 도움을 받아 가장 처음 수정했던 부분은 tailwind의 content 설정이었습니다. content는 해당 경로에 존재하는 파일을 스캔하여 className을 추출하고 그 결과를 기반으로 최종 CSS를 생성합니다.

따라서, 디자인 시스템 내부 파일이 스캔 대상에서 누락되고 있다면 일부 클래스가 생성되지 않는 문제가 발생할 수 있겠다는 가설이었고, 디자인 시스템 컴포넌트가 있는 경로를 아래와 같이 추가해주었습니다.

content: [
'./app/**/*.{jsx,tsx,mdx}', 
'./components/**/*.{jsx,tsx,mdx}'
// 디자인 시스템 경로 추가
'../packages/design-system/components/**/*.{js,ts,jsx,tsx}'
],
...

하지만 결과는 동일했습니다. 애초에 설정 자체는 두 프로젝트 모두 동일하게 되어있었기 때문에 단순히 content 범위 오류로 발생한 문제는 아니었습니다.

(그리고 모노레포 구조 특성상 app 디렉토리 밖으로 나가면 이론상 프로젝트를 벗어나가는건데 packages에 접근이 가능한지도 정확하지 않았습니다 😇)

두번째 시도: next.js 버전 ( ❌ )

다음으로 확인한 부분은 두 프로젝트가 사용하고 있는 Next.js 버전 차이었습니다. A프로젝트는 15.3.5, B프로젝트는 15.5.5 버전을 사용하고 있었고 혹시나 두 버전 사이에 TailwindCSS 처리 방식이 달라졌을 가능성을 의심했습니다.

테스트를 위한 신규 프로젝트를 15.3.5 버전으로 설치한 결과 동일하게 디자인 시스템 스타일이 깨지는 문제가 발생하는 것을 확인할 수 있었습니다. 따라서 Next.js 자체의 문제는 아니라는 결론을 내릴 수 있었습니다.

즉, 문제의 핵심은 버전이나 설정 문제가 아닌 tailwind의 스캔 범위 또는 빌드 타이닝에 있다는 방향으로 좁혀졌습니다.

세번째 시도: tailwindCSS 빌드 타이밍 ( ✅ )

문제의 원인을 보다 명확히 확인하기 위해 TailwindCSS가 실제로 어떤 클래스를 빌드하는지 직접 확인했습니다. Next.js는 빌드 시 Tailwind가 스캔한 className을 기반으로 최종 CSS 파일 (layout.css) 을 생성 하는데, 만약 디자인 시스템 컴포넌트가 스캔되지 않았다면 해당 클래스는 layout.css에 생성되지 않을 것입니다.

이를 확인하기 위해 A 프로젝트와 B 프로젝트 각각의 빌드 결과물을 비교했습니다. 그 결과 다음과 같은 사실을 확인했습니다.

A 프로젝트	B 프로젝트

• A 프로젝트의 layout.css에는 mt-7, text-4xl 등 디자인 시스템에서 사용한 클래스가 모두 존재했습니다.
• B 프로젝트의 layout.css에는 일부 클래스가 아예 존재하지 않았습니다. (즉, Tailwind가 스캔하지 못했고 CSS 생성 자체가 되지 않은 상태)

이 차이를 확인하면서 문제의 원인은 더욱 명확해졌습니다. 디자인 시스템 패키지 내부의 파일이 Tailwind 스캔 대상에 포함되지 않았기 때문에, 프로젝트마다 생성되는 CSS가 달라지고, 그 결과 컴포넌트가 정상적으로 렌더링되지 않는 구조적 문제 가 발생한 것입니다.

4. 원인과 해결 방법

원인

결론적으로 문제의 핵심은 TailwindCSS가 스타일을 생성하는 시점에 packages/design-system 내부의 className을 스캔하지 못한다는 것이었습니다.

TailwindCSS는 content 옵션에 포함된 경로만 기준으로 실제 사용된 className을 스캔해 layout.css 에 필요한 유틸리티 클래스를 생성합니다. 하지만 monorepo 구조에서 프로젝트 밖의 패키지(packages/design-system)는 content 스캔 범위에 포함되지 않는다 는 것을 알 수 있었습니다.

정리하자면,

• 디자인 시스템 컴포넌트 내부에서 사용한 Tailwind 클래스는 스캔 대상에 포함되지 않음
• 빌드된 CSS(layout.css)에 해당 클래스가 생성되지 않음
• A 프로젝트 → 우연히 동일한 유틸리티 클래스를 자체적으로 사용하고 있어 정상 노출
• B 프로젝트 → 해당 클래스가 프로젝트 내부에서 사용되지 않아 CSS가 생성되지 않았고, 스타일이 누락됨

즉, 특정 프로젝트만 깨진 것이 아니라, Tailwind가 아예 해당 클래스를 빌드하지 않았기 때문에 발생한 구조적 문제였습니다.

해결 방법

지금의 문제를 해결할 수 있는 방법은 3가지로 추릴 수 있었습니다.

1. CSS 사용 ➡️ TailwindCSS 의존도를 낮추고 디자인 시스템 패키지 내부에서 직접 CSS를 정의해 제공하는 방법입니다. 이렇게 하면 각 프로젝트의 Tailwind 스캠 여부와 무관하에 안정적으로 스타일이 적용되기 때문에 가장 확실한 해결책이라고 할 수 있습니다. 다만, CSS 파일 관리에 대해서 팀원들과 충분한 대화가 필요합니다. (컨벤션 등...)

2. tailwind.config.js content 경로 추가 ➡️ Tailwind 가 스타일을 생성하려면 해당 경로에 있는 파일들을 스캔할 수 있어야하기 때문에 가장 논리적인 정석 방법이라고 할 수 있습니다. 하지만, 모노레포 구조에서 어떻게 적용해야하는지 그 방법에 대해서 찾아야하고 프로젝트마다 설정을 관리해야한다는 부담이 있습니다.

3. 디자인 시스템에 tailwindCSS 라이브러리 설치 ➡️ 디자인 시스템이 자체적으로 Tailwind를 기반으로 스타일을 빌드할 수 있어 프로젝트 환경에 의존하지 않아도 된다는 장점이 있지만, 프로젝트에서 사용할 때 결국 Tailwind 라이브러리가 중복으로 로드된다는 점, 스타일이 충돌될 수 있다는 점에서 위험 부담이 있습니다.

마무리

쉽게 해결할 수 있는 문제인 줄 알았는데 꼬박 하루 걸려 원인을 발견할 수 있었습니다 😅 지금 와서 다시 돌이켜보면 처음부터 tailwind의 빌드 구조와 스캔 방식 같은 근본적인 원리를 짚고 들어갔다면 훨씬 빠르게 해결할 수 있지 않았을까 하는 생각이 들었습니다. 그래도 덕분에 평소 당연하게 사용하던 tailwind 가 어떤 식으로 동작하는지 깊에 이해할 수 있었던 좋은 경험이었습니다.

만약 저처럼 모노레포에서 tailwind기반의 디자인 시스템을 구축하며 비슷한 문제를 겪은 분이 있다면 경험이나 해결 과정을 함께 공유해봐요🙌 🏻

그런데 만약, 클라이언트 컴포넌트안에서 서버 컴포넌트를 import 하면, 다음과 같은 에러가 발생합니다.

평소처럼 개발하던 중 문득, "왜 클라이언트 컴포넌트안에서는 서버 컴포넌트를 import 할 수 없는걸까?" 하는 의문이 생겼고 그 이유에 대해 알아봤습니다.

🤔 원인 및 이유

React Server Components의 렌더링 구조

React의 RSC 아키텍처는 단방향 렌더링 을 따릅니다.

🔄 렌더링 순서

1. 서버 단계 • React가 서버 컴포넌트를 렌더링 • RSC payload 생성 (직렬화된 컴포넌트 트리) • Next.js가 HTML과 함께 클라이언트로 전송

2. 클라이언트 단계 • 브라우저에서 HTML 표시 • React가 hydration 및 reconciliation(재조정) 수행 • 클라이언트 컴포넌트 활성화

React는 화면을 만들 때 서버에서 먼저 컴포넌트를 실행하고, 그 다음에 클라이언트에서 이어서 처리하는 구조를 가지고 있습니다. 즉, 클라이언트 컴포넌트는 서버가 미리 만들어준 결과만 사용할 수 있고, 서버에서만 실행 가능한 컴포넌트 함수는 직접 실행할 수 없습니다.

실행 환경 차이

클라이언트 컴포넌트가 서버 컴포넌트를 import한다는 건 브라우저 코드 안에서 Node.js 전용 코드를 실행하려는 시도가 되기 때문에, Next.js가 이를 감지하고 에러가 발생합니다.

브라우저 코드 안에서 Node.js 코드가 실행되지 않는 이유는? ➡️ 브라우저와 Node.js는 사용할 수 있는 API가 다르기 떄문입니다. 브라우저에는 파일 시스템, 데이터베이스, Node 전용 모듈이 없어서 서버 코드를 실행할 수 없어요!

컴포넌트 트리 구조의 제약

React는 다음과 같은 구조로 컴포넌트 트리를 렌더링합니다.

React.createElement(ClientWrapper, {}, React.createElement(ServerContent))

이 코드의 의미는 “ServerContent를 먼저 렌더링한 결과를 ClientWrapper의 children으로 전달한다” 입니다. 즉, 서버 컴포넌트는 이미 서버 단계에서 렌더링을 끝낸 후, 그 결과 (JSX Element)가 클라이언트 컴포넌트에 children으로 전달됩니다. 이때 중요한 점은 클라이언트 컴포넌트는 "컴포넌트 함수" 가 아니라, "렌더링된 결과(React Element)"를 받는다는 것입니다.

💡 올바른 컴포넌트 전달 과정

1단계: 서버에서 먼저 ServerContent 렌더링

// 서버에서 ServerContent가 실행되어 JSX 결과물 생성
const serverResult = {
  type: 'div',
  props: {
    children: 'Hello from server!'
  }

서버 컴포넌트는 서버에서 먼저 실행되어 JSX 결과물을 생성합니다.

2단계: 렌더링 결과를 RSC payload로 직렬화

{
  "type": "div",
  "props": {
    "children": "Hello from server!"
  }
}

서버에서 렌더링된 결과는 RSC payload로 직렬화됩니다.

3단계: 클라이언트로 전달

// 클라이언트에서는 이미 렌더링된 결과를 받음

function ClientWrapper({ children }) {
// children은 서버 컴포넌트가 아니라 렌더링된 React 엘리먼트
  console.log(children);
  // { type: 'div', props: { children: 'Hello from server!' } }

  return <div>{children}</div>
}

클라이언트 컴포넌트에서는 이미 렌더링된 React Element를 받습니다. 즉, 서버에서 만들어진 결과물을 그대로 표시합니다.

✨ 마무리

서버 컴포넌트를 클라이언트로 전달할 때 가장 중요한 점은 클라이언트는 결과물만 받을 수 있다 는 것입니다.

❌ 직접 import (불가능)

'use client'

import ServerComponent from './ServerComponent'
// 컴포넌트 함수 자체를 가져오려고 함

export default function ClientComponent() {
  return <ServerComponent />
  // 클라이언트에서 서버 컴포넌트 함수를 실행하려고 함
}

클라이언트에서 서버 컴포넌트 함수를 실행하려고 하면, 브라우저가 Node.js 전용 코드를 실행하려는 시도이기 때문에 에러가 발생합니다.

✅ Props로 전달 (가능)

// 서버에서
<ClientWrapper>
  <ServerContent /> // 서버에서 실행되어 결과물 생성
</ClientWrapper>


// 클라이언트에서
'use client'
export default function ClientWrapper({ children }) {
// children은 이미 렌더링된 결과물 (React 엘리먼트)
  return <div>{children}</div>
}

서버에서 먼저 컴포넌트를 실행하여 렌더링 결과(JSX)를 만들고, 이를 클라이언트 컴포넌트의 props(children)로 전달하면 안전하게 사용할 수 있습니다.

쉽게 비유하자면, 직접 import하는 것은 고객이 주방에 들어가 직접 요리 하려고 하는 것이고, props로 전달하는 것은 주방에서 요리를 완성한 후 완성된 음식을 고객에서 가져다 주는 것 입니다. 즉, 클라이언트 컴포넌트는 "완성된 음식"(렌더링 결과) 은 받을 수 있지만, "레시피"(서버 컴포넌트 함수) 로 직접 요리할 수는 없습니다!

평소에는 당연하게 사용했던 개념에 대해서 자세히 알아보고 정리해보면서 Next.js에 대해서 좀 더 깊이 알게된 것 같아요! 새로운 내용을 배우는 것도 중요하지만 내가 알고 있는 내용을 정확하고 깊게 이해하고 넘어가는 것도 중요하다는 것을 다시 한번 깨달았습니다...ㅎㅎ 기본을 알면 나중에 스스로 응용도 할 수 있을 거라고 생각합니다 🙌

이때부터 저의 삽질은 시작됐습니다 😇

문제 상황

제가 구현한 기능은 공유하기 버튼을 누르면 shortURL을 발급받고, 그걸 클립보드에 복사하는 단순한 기능이었습니다.

await navigator.clipboard.writeText(text); // 🚨 Safari 첫 클릭에서만 에러!

혹시 몰라 fallback으로 document.execCommand('copy') 도 넣어두긴 했는데, Safari에서는 첫 클릭에서만 writeText 부분이 터지면서 에러 alert이 뜨는 상황이었습니다.

조금 더 전체 흐름을 보자면 이런 식이었습니다.

const { data: shortUrl, isLoading } = useGetShortUrl(currentId); // SWR shortURL API 통신

const shareItem = (id: number) => {
  if (currentId === id && shortUrl?.url && !isLoading) {
    handleShare(shortUrl.url);
    return;
  }
  setCurrentId(id);
};

const handleShare = (url: string) => {
  const shareData = { title: '공유하기 테스트', url };
  copyToClipboard(shareData.url); // 클립보드 복사
};

겉보기에는 큰 문제가 없어 보였지만, Safari에서는 첫 클릭시 에러가 발생했습니다.

삽질 과정

1. SWR 대신 직접 호출해보기

처음에는 “혹시 SWR 캐싱 때문에 응답이 늦게 들어와서 그런가?” 싶어서 아예 SWR을 걷어내고, 직접 API를 호출해서 응답을 받은 뒤 클립보드에 넣어봤습니다.

const handleShareClick = async () => {
  try {
    // ✅ API 직접 호출
    const res = await fetch(`/api/short-url?postId=${postId}`);
    const data = await res.json();

    // ✅ 응답 후 바로 clipboard 실행
    await navigator.clipboard.writeText(data.url);
    alert('공유 링크가 복사되었습니다');
  } catch (err) {
    alert('복사 실패');
  }
};

하지만 결과는 똑같이 실패했습니다. 즉, SWR 문제는 아니었습니다.

2. 동기 방식으로 강제 실행해보기

Clipboard API가 async 함수라 혹시 Safari가 “비동기라서 제스처 컨텍스트를 잃었다” 고 생각하나 싶어서, 클립보드 복사 부분을 동기 fallback 코드(execCommand)로 강제 실행해봤습니다.

const copyToClipboard = (text: string) => {
  if (!text) return;

  try {
    const textarea = document.createElement('textarea');
    textarea.value = text;

    textarea.style.position = 'absolute';
    textarea.style.left = '-9999px';
    document.body.appendChild(textarea);
    textarea.select();

    // ✅ 동기 방식으로 강제 실행
    document.execCommand('copy');
    document.body.removeChild(textarea);

    alert('공유 링크가 복사되었습니다');
  } catch (err) {
    alert('복사 실패');
  }
};

하지만 이 방식도 첫 클릭 실패는 여전했습니다. 단순히 비동기를 동기로 바꾼다고 해결되는 문제가 아니었습니다.

3. 클릭 안에서 끝까지 처리해보기

마지막으로, 사용자 클릭 → API 호출 → 응답 → clipboard 실행 이 흐름이 문제라면, 클릭 이벤트 안에서 끝까지 실행하면 괜찮지 않을까 싶었습니다.

const handleShareClick = () => {
  fetch(`/api/short-url?postId=${postId}`)
    .then(res => res.json())
    .then(data => {
      return navigator.clipboard.writeText(data.url);
    })
    .then(() => {
      alert('공유 링크가 복사되었습니다');
    })
    .catch(() => {
      alert('복사 실패');
    });
};;

하지만 역시 결과는 동일했습니다. Safari 입장에서는 API 호출 자체가 비동기이기 때문에, 이 방법 또한 이미 사용자 제스처 컨텍스트가 사라졌다고 판단한 것이었습니다.

진짜 원인

Safari의 보안 정책상 navigator.clipboard.writeText() 는 다음 조건에서만 허용됩니다.

1. 직접적인 사용자 제스처(클릭/터치) 안에서 호출
2. 동기적 호출 스택 안에서 실행
3. 한 번이라도 await, setTimeout, API 호출 같은 비동기 작업을 거치면 Safari는 “이건 더 이상 사용자 제스처랑 무관하다” 라고 판단 → 복사 거부

즉, 제가 만든 로직은 shortURL을 발급받기 위해 비동기 API 호출을 한 뒤 그 결과를 클립보드에 넣었기 때문에, Safari는 “이건 사용자가 누른 게 아니라 스크립트가 실행한 거야” 라고 보고 첫 클릭을 막아버린 겁니다.

두 번째부터는 shortURL이 이미 캐시/준비되어 있어서 곧바로 실행되니 정상 동작한 것이었고요.

해결 방법

저는 결국 Safari 전용 바텀시트 를 만들어서 문제를 해결했습니다. 진행 플로우는 이렇게 바뀌었습니다.

1. 공유하기 버튼 클릭 → 바텀시트 열림
2. 바텀시트가 열리면 shortURL을 API로 미리 요청
3. 사용자가 바텀시트에서 링크 복사하기 버튼을 누름
4. 이때 곧바로 navigator.clipboard.writeText() 실행 (사용자 제스처 안에서 호출)

// 클릭 시 모달 열고 shortURL 미리 요청
const onShareClick = async (itemId: number) => {
  setShowModal(true);
  setLoading(true);

  try {
    const res = await fetch(`/api/short-url?itemId=${itemId}`);
    const json = await res.json();
    setShortUrl(json.url); // shortURL 준비
  } finally {
    setLoading(false);
  }
};

// 바텀시트에서 "복사하기" 클릭 시
const onCopyClick = () => {
  if (!shortUrl) {
    alert('링크 준비 중입니다.');
    return;
  }

  navigator.clipboard.writeText(shortUrl)
    .then(() => alert('링크가 복사되었습니다'))
    .catch(() => alert('복사 실패'));
};

Safari에서는 클릭 이벤트 핸들러 안에서 즉시 실행 되는 코드만 허용하기 때문에, onCopyClick 안에서 바로 writeText() 를 호출하는 구조로 바꿔서 버그를 해결할 수 있었습니다.

마무리

결론적으로, Safari에서 발생한 이 버그는 코드 문제가 아니라 브라우저 정책 때문이었습니다. 생각보다 해결책은 단순했습니다. 비동기 작업으로 URL을 받아온 뒤 곧바로 복사하는 게 아니라, 사용자 클릭 시점에서 즉시 복사 동작을 실행 하도록 구조를 바꾸는 것!

결국 문제의 핵심은 “언제 클립보드 복사 동작을 실행하느냐”였습니다. 비동기 API 호출과 사용자 제스처 사이의 타이밍만 맞춰주면 Safari도 더 이상 문제를 일으키지 않습니다. 삽질은 길었지만, 덕분에 브라우저 호환성에 대해 깊이 이해할 수 있었습니다.😇

📚 참고 류쥰열의 기술 블로그 | 사파리에서 클립보드 복사 이슈

문제 상황

회사에서 개발 중인 서비스에서 HLS(HTTP Live Streaming) 방식으로 비디오를 재생하는 기능을 구현하고 있었습니다. 백엔드에서는 AWS S3에 업로드된 m3u8 파일과 ts 세그먼트들을 CloudFront를 통해 배포하고 있었고, 프론트엔드에서는 video.js 라이브러리를 사용해 이를 재생하려고 했습니다.

(이해를 돕기위한 코드로 참고용으로 봐주세요 🙇‍♀️)

import { useRef, useEffect } from 'react';
import videojs from 'video.js';
import 'video.js/dist/video-js.css';

interface VideoPlayerProps {
  src: string;
  options?: any;
}

export const VideoPlayer: React.FC<VideoPlayerProps> = ({ src, options }) => {
  const videoRef = useRef<HTMLVideoElement>(null);
  const playerRef = useRef<any>(null);

  useEffect(() => {
    if (videoRef.current) {
      playerRef.current = videojs(videoRef.current, {
        ...options,
        sources: [{
          src: src, // CloudFront URL: https://d1234567890.cloudfront.net/videos/sample.m3u8
          type: 'application/x-mpegURL'
        }]
      });
    }

    return () => {
      if (playerRef.current) {
        playerRef.current.dispose();
      }
    };
  }, [src, options]);

  return (
    <video
      ref={videoRef}
      className="video-js vjs-default-skin"
      controls
      preload="auto"
      data-setup="{}"
    />
  );
};

그런데 개발 환경에서 테스트해보니 CORS 에러가 발생해 동영상을 제대로 불러오지 못하고 있었습니다.

처음에는 "단순히 m3u8 파일을 가져오는 건데 왜 CORS 에러가 나지?" 라고 생각했습니다. 이후 원인에 대해 구글링을 해보다 Simple Request 와 Complex Request의 차이가 있다는 것을 알게 되었습니다.

Simple Request의 조건

CORS에서 Simple Request는 preflight 없이 바로 서버로 전송되는 요청으로, 조건이 생각보다 까다로웠습니다.

Simple Request가 되려면 다음 조건을 모두 만족해야 합니다.

1. HTTP 메서드

• GET
• POST

2. 허용되는 헤더만 사용

자동으로 설정되는 헤더 (User-Agent, Accept 등) 외에 수동으로 설정할 수 있는 헤더는 다음과 같이 제한됩니다.

• Accept
• Accept-Language
• Content-Language
• Content-Type (단, 특정 값으로 제한)
• Range ( ⬅️ 여기서 문제 발생! )

Complex Request의 조건

Simple Request 조건을 하나라도 벗어나면 Complex Request(복합 요청)가 됩니다.

1. Range 헤더 사용

비디오 스트리밍에서는 브라우저가 자동으로 Range 헤더를 추가합니다. 이는 비디오 파일의 특정 부분만 요청 하기 위한 헤더입니다.

GET /videos/sample.m3u8 HTTP/1.1
Host: d1234567890.cloudfront.net
Range: bytes=0-1023
Origin: http://localhost:3000

2. 커스텀 헤더들

video.js나 HLS 플레이어(내가 사용한 것) 들은 종종 다음과 같은 헤더들을 추가로 사용합니다.

• X-Requested-With
• X-Playback-Session-Id
• 기타 플레이어별 커스텀 헤더들

이런 헤더들이 하나라도 있으면 Complex Request가 되어 preflight가 필요 합니다.

Pre-flight 란?

pre-flight는 브라우저가 실제 요청을 보내기전에 이런 요청을 보내도 괜찮은지 서버에게 미리 확인하는 과정을 말합니다.

pre-flight 요청 과정

1. 브라우저가 OPTIONS 요청 발송

   OPTIONS /videos/sample.m3u8 HTTP/1.1
   Host: d1234567890.cloudfront.net
   Origin: http://localhost:3000
   Access-Control-Request-Method: GET
   Access-Control-Request-Headers: range
   

2. 서버가 허용 정보 응답
```http
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://localhost:3000
Access-Control-Allow-Methods: GET, HEAD, OPTIONS
Access-Control-Allow-Headers: range, content-type
Access-Control-Max-Age: 86400

3. 브라우저가 실제 요청 발송

   GET /videos/sample.m3u8 HTTP/1.1
   Host: d1234567890.cloudfront.net
   Origin: http://localhost:3000
   Range: bytes=0-1023
   

만약 preflight 단계에서 서버가 적절한 CORS 헤더를 반환하지 않으면, 브라우저는 실제 요청을 보내지 않고 CORS 에러를 발생시키게 되는 것입니다.


<br />


## 스트리밍 Video 요청시 CORS 에러가 발생했던 이유

#### 1. Range 헤더로 인한 Complex Request
비디오 스트리밍에서는 브라우저가 자동으로 `Range` 헤더를 사용합니다. 이는 **대용량 비디오 파일을 청크 단위로 나눠 받기 위함**인데 이 때문에 simple Request 조건을 벗어나 pre-flight 가 필요하게 됩니다.

```http
# 첫 1MB 요청 (초기 로딩)
Range: bytes=0-1048575

# 다음 1MB 요청 (스트리밍 계속)
Range: bytes=1048576-2097151

# 사용자가 건너뛰기 한 경우
Range: bytes=5242880-6291455

Range 헤더의 장점은 다음과 같습니다.

• 빠른 초기 로딩: 전체 파일이 아닌 필요한 부분만 먼저 다운로드
• 대역폭 절약: 시청하지 않는 부분은 다운로드하지 않음
• 사용자 경험 향상: 즉시 재생 시작, 구간 이동 가능

2. CloudFront의 CORS 정책 미설정

비디오 스트리밍은 Range 헤더 사용으로 인해 Complex Request가 되며, 이에 따라 브라우저는 사전에 preflight 요청(OPTIONS)을 전송하게 됩니다.

하지만 CloudFront에서 별도의 응답 헤더 정책(Response Headers Policy) 을 설정하지 않으면, 이러한 preflight 요청에 대해 적절한 CORS 허용 헤더를 포함하지 않게 됩니다.

즉, 브라우저는 CloudFront에서 오는 응답에 Access-Control-Allow-Origin, Access-Control-Allow-Headers, Access-Control-Allow-Methods 같은 CORS 관련 헤더가 포함되지 않은 것을 확인하고, CORS 에러를 발생시킵니다.

해결 방법

해결 방법은 간단했습니다. CloudFront 콘솔에서 응답 헤더 정책을 설정해줌으로써 브라우저가 요청을 정상적으로 처리할 수 있게 만들었습니다. CloudFront에서 다음과 같은 설정을 통해 문제를 해결할 수 있습니다.

1. CloudFront 콘솔 > 배포(Distribution) > 동작(Behaviors) 로 이동

2. 해당 동작을 선택 후 편집(Edit)

3. 응답 헤더 정책 변경

설정이 완료되면 브라우저가 OPTIONS 요청에 대해 유효한 응답을 받게 되어 CORS 에러 없이 정상적으로 스트리밍 요청이 처리됩니다.

📚 참고

• s3에 업로드된 m3u8 파일을 가져올때 cors 오류가 발생합니다
• Cloudfront에서 “요청된 리소스에 대한 '액세스 제어-허용-오리진' 헤더가 없습니다” 오류를 해결하려면 어떻게 해야 하나요?
• Preflight

제가 경험한 바로는 window.location.reload() 를 사용하면 의도한 대로 모든 모달이 닫혔지만, router.refresh() 를 사용하면 URL은 변경되었음에도 불구하고 화면 상의 모달은 여전히 남아있었습니다.

그래서 과연 두개의 차이는 무엇이면 각각 어떤 상황에서 사용해야하는지에 대해 알아보도록 하겠습니다.

window.location.reload()의 동작 원리

window.location.reload() 는 브라우저 네이티브 API로 전체 페이지를 완전히 새로고침하는 역할을 합니다. 이 메서드가 호출되면 다음과 같은 과정이 진행됩니다.

const handleHardReload = () => {
  window.location.reload();
};

1. 브라우저는 서버로부터 현재 페이지의 HTML을 다시 요청하고 받아옵니다. 이는 처음 페이지에 접속할 때와 동일한 과정입니다.
2. 모든 Javascript 상태가 완전히 초기화됩니다. 이는 React 컴포넌트 상태, 전역 상태, 그리고 메모리에 저장된 모든 변수들이 초기값으로 돌아가는 것을 의미합니다.
3. 캐시된 데이터가 모두 지워집니다. 브라우저는 임시로 저장해둔 데이터들이 모두 삭제하고 초기 상태에서 다시 시작하게됩니다.
4. 마지막으로, 컴포넌트가 완전히 새로 구성되고 기존에 렌더링된 모든 컴포넌트들이 언마운트 되며 새로운 컴포넌트들이 다시 마운트됩니다.

이러한 특성 때문에 window.location.reload() 는 완전한 초기화가 필요한 상황에서 확실한 해결책이 되지만, 사용자 경험 측면에서는 느리고 불편할 수 있습니다.

router.refresh()의 동작 원리

router.refresh() 는 Next.js의 App Router에서 제공하는 메서드로, 소프트 내비게이션(Soft Navigation) 방식으로 동작합니다.

• Hard Navigation: 브라우저가 완전히 새로운 페이지를 로드 (전체 새로고침)

• Soft Navigation: JavaScript로 필요한 컴포넌트만 교체 (부분 업데이트)

'use client';
import { useRouter } from 'next/navigation';

const RefreshButton = () => {
  const router = useRouter();

  const handleSoftRefresh = () => {
    router.refresh();
  };

  return (
    <button onClick={handleSoftRefresh}>
      데이터 새로고침
    </button>
  );
};

router.refresh() 가 호출되면, Next.js는 현재 경로에 해당하는 서버 컴포넌트의 데이터만 다시 가져옵니다. 이때 중요한 점은 페이지의 구조나 레이아웃은 그대로 유지한다는 것입니다. 이는 사용자가 입력한 폼 데이터나 스크롤 위치 같은 상태들이 유지된다는 것을 의미합니다.

또한, 클라이언트 상태도 보존됩니다. useState나 Zustand 같은 상태 관리 라이브러리의 상태들이 그대로 유지되어, 사용자가 설정한 값들이 사라지지 않습니다.

가장 중요한 특징은 라우팅 구조와 슬롯이 변경되지 않는다는 점입니다. 특히 패럴렐 라우트의 슬롯들은 기존 상태를 그대로 유지하게 됩니다.

이러한 특성으로 인해 router.refresh()는 사용자 경험을 해치지 않으면서도 최신 데이터를 가져올 수 있는 효율적인 방법이지만, 완전한 초기화가 필요한 상황에서는 한계가 있습니다.

패럴렐 라우트 모달

상황

패럴렐 라우트를 사용하여 모달을 구현할 때는 다음과 같은 구조를 가집니다.

이해를 돕기 위한 예시 코드로 내용 이해를 위한 참고용으로 봐주세요.

// app/layout.tsx
export default function RootLayout({
  children,
  modal,
}: {
  children: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <div>
          {children}
          {modal}
        </div>
      </body>
    </html>
  );
}

// app/page.tsx
export default function HomePage() {
  return (
    <div>
      <h1>메인 페이지</h1>
      <Link href="/products/1">
        상품 모달 열기
      </Link>
    </div>
  );
}

// app/@modal/products/[id]/page.tsx
export default function ProductModal({ params }: { params: { id: string } }) {

const handleModalClose = () => {
  window.history.pushState({}, '', '/');
  router.refresh();
};
  return (
    <div>
      <div>
        <h2>상품 {params.id} 상세</h2>
        <p>상품에 대한 자세한 정보입니다.</p>
          <button onClick={handleModalClose}>
            닫기
          </button>

      </div>
    </div>
  );
}

// app/@modal/default.tsx
export default function DefaultModal() {
  return null; // 모달이 없을 때는 null 반환
}

위와 같은 구조에서 이런 구조에서 products/1 경로로 이동하면 @modal 슬롯에 의해 모달이 화면에 표시됩니다. 만약 이때, 사용자가 닫기 버튼을 클릭했을 때, URL을 /로 변경하고 router.refresh()를 호출해도 화면상의 모달은 여전히 남아있게 됩니다.

원인

const handleModalClose = () => {
  // 1. URL을 '/'로 변경
  window.history.pushState({}, '', '/');
  // 2. router.refresh() 호출
  router.refresh();
};

router.refresh() 를 사용했을 때 패럴렐 라우트 모달이 닫히지 않는 원인은 Next.js의 패럴렐 라우트 슬롯 관리 방식 에 있습니다.

패럴렐 라우트에서** @modal 슬롯은 독립적인 렌더링 단위로 취급** 됩니다. router.refresh() 가 호출되면 Next.js는 현재 활성화된 모든 슬롯을 기준으로 데이터를 다시 가져오지만, 슬롯 자체의 구조는 변경하지 않습니다.

이는 Next.js가 성능 최적화를 위해 설계한 동작으로, router.refresh() 는 필요한 데이터만 새로 가져오고 기존 컴포넌트 구조는 최대한 보존하려고 하기 때문입니다. 구체적으로 설명하면, URL이 /로 변경되어도 Next.js는 이미 마운트된 @modal 슬롯의 컴포넌트들이 여전히 유효하다고 판단합니다. router.refresh() 는 단순히 서버에서 새로운 데이터를 가져와서 기존 컴포넌트에 전달할 뿐, 컴포넌트 자체를 언마운트하지는 않습니다.

반면, window.location.reload() 는 브라우저 레벨에서 완전한 새로고침을 수행하므로, 모든 슬롯과 컴포넌트가 처음부터 다시 생성되어 모달이 확실히 닫히게 됩니다.

해결 방안

router.push()를 사용한 명시적 경로 이동

가장 권장되는 방법은 모달이 없는 경로로 명시적으로 이동하는 것입니다.

'use client';
import { useRouter } from 'next/navigation';

const CloseModalButton = () => {
  const router = useRouter();

  const closeModal = () => {
    // 모달 슬롯이 매칭되지 않는 경로로 이동
    router.push('/');
  };

  return (
    <button 
      onClick={closeModal}
      className="bg-red-500 text-white px-4 py-2 rounded"
    >
      모달 닫기
    </button>
  );
};

router.back()을 사용한 이전 페이지 이동

사용자가 모달을 열기 전 페이지로 돌아가는 경우에 유용합니다.

const BackButton = () => {
  const router = useRouter();

  const goBack = () => {
    // 브라우저 히스토리에서 이전 페이지로 이동
    router.back();
  };

  return (
    <button onClick={goBack} className="bg-gray-500 text-white px-4 py-2 rounded">
      이전으로
    </button>
  );
};

이 밖에도 복잡한 모달 관리가 필요한 경우 zustand를 활용한 상태 관리 방식 및 인터셉팅 라우트를 활용한 방법도 고려해 볼 수 있습니다.

정리

이번 글을 작성하면서 패럴렐 라우트 모달 관리에 대한 이슈가 저뿐만 아니라 여러 개발자들이 공통적으로 겪고 있는 문제라는 것을 알게 되었습니다. 개발을 하다 보면 모달 관리는 언제나 고민거리였는데, 패럴렐 라우트가 이를 체계적이면서도 심플하게 해결해줄 수 있을 거라는 기대를 했지만 생각보다 쉽지 않더라고요 ... 😅

우선, 블로그를 정리하면서 느꼈던 것은 router.refresh()와 window.location.reload()의 차이점을 명확히 이해하는 것이었습니다.

router.refresh() 의 특징:

• 서버 데이터만 새로 가져오는 소프트 리프레시
• 기존의 레이아웃과 슬롯 구조를 그대로 유지
• 데이터 갱신이 목적일 때는 효율적이지만, 패럴렐 라우트 모달을 닫는 용도로는 부적합

window.location.reload() 의 특징:

• 브라우저 전체를 새로고침하여 모든 상태와 컴포넌트를 초기화
• 모달은 확실히 닫히지만, 사용자 경험 측면에서는 권장되지 않음

결론적으로, 패럴렐 라우트 모달을 올바르게 관리하려면 router.push() 나 router.back() 을 사용하여 적절한 경로로 이동하거나, 상태 관리 라이브러리를 활용한 조건부 렌더링 방식을 고려하는 것이 가장 적절한 해결책입니다.

패럴렐 라우트가 완벽한 해결책은 아니지만, 이러한 동작 원리와 차이점을 이해하고 상황에 맞는 적절한 방법을 선택한다면 Next.js에서 더욱 안정적이고 사용자 친화적인 모달 경험을 제공할 수 있을거라고 생각합니다~!

📚 참고 - Next.js의 고급 라우팅 패턴 - Next.js Parallel Routes 공식 문서 - GitHub Discussion - window.location.reload vs router.reload 차이점 - Creating Modals in Next.js 14: Using Parallel and Intercepting Routes

OOM(Out of Memory) 이란?

OOM 에러는 애플리케이션이 사용할 수 있는 메모리의 한계를 초과하려고 할 때 발생하는 에러입니다. 쉽게 말해, 더 이상 필요하지 않은 값들이 여전히 메모리 공간을 차지하고 있어 새로운 데이터를 저장할 공간이 부족해지는 상황이라고 이해할 수 있습니다.

이러한 문제가 발생하게 되면, 애플리케이션이 강제로 종료되거나, 전체 시스템 성능이 심각하게 저하되는 등의 문제가 발생할 수 있습니다. 특히 서버 환경에서는 OOM이 발생하는 순간 요청을 처리하지 못해 서비스 중단으로 이어질 수 있기 때문에 주의해야합니다.

원시 값과 참조 값의 메모리 관리 방식

자바스크립트에서 값은 크게 원시 값과 참고 값으로 나뉩니다. 이 두 종류의 값은 메모리에 저장되는 방식이 서로 다르며, 이로 인해 메모리 관리에도 차이가 생깁니다.

원시 값은 문자열,숫자,불리언,null,undefined 와 같은 값들입니다. 이들은 실행 컨텍스트가 생성되는 시점에 스택(stack) 이라는 메모리 공간에 저장되고, 함수가 종료되면 자동으로 메모리에서 제거 됩니다. 이처럼 원시 값은 사용이 끝나면 자연스럽게 정리되기 때문에 별도로 메모리를 수거할 필요가 없습니다.

반면, 참조 값 은 객체,배열,함수 등을 말합니다. 참조 값은 힙(Heap) 이라는 공간에 저장되며, 변수에는 해당 값의 실제 값이 아니라 그 값을 가리키는 메모리 주소가 저장됩니다. 힙은 스택과 달리 다양한 실행 컨텍스트에서 공유되기 때문에 참조 값이 여전히 다른 곳에서 사용되고 있는지 아닌지를 판단해 메모리를 해제 해야합니다. 이러한 역할을 해주는 것이 바로 가비지 컬렉션 입니다.

🤔 실행 컨텍스트 란?

• 실행 컨텍스트는 자바스크립트 코드가 실행될 때 생성되는 실행 환경을 의미합니다. 즉, 자바스크립트 엔진이 코드를 해석하고 실행하는 동안의 환경을 말하며, 함수 호출이나 코드 블록이 실행될 때 새로운 실행 컨텍스트를 생성합니다.
• 실행 컨텍스트의 구성 요소는 크게 렉시컬 환경, 변수 객체, this 값이 있습니다.
  • 렉시컬 환경 : 변수나 함수가 어디서 선언 되었는지를 기억하고 저장합니다.
  • 변수 객체 : 변수와 함수 선언이 포함된 객체로 함수 내에서 사용되는 변수들이 저장됩니다.
  • this : 함수가 어디서 실행되었는지에 따라서 동적으로 결정됩니다.

가비지 컬렉션

가비지 컬렉션은 자바스크립트 엔진이 불필요해진 메모리를 자동으로 해제해주는 기능입니다. 자바스크립트는 메모리를 자동으로 관리하기 때문에 가비지 컬렉션은 메모리 누수를 방지하는데 중요한 역할을 합니다.

가비지 컬렉션은 기본적으로 도달할 수 없는 값(unreachable value) 을 찾아서 메모리에서 제거합니다. 예를 들어 어떤 객체를 참조하던 변수가 null로 설정되거나, 함수 실행이 끝나면서 클로저 내부에서 참조하던 객체들이 더 이상 사용되지 않을 경우, 해당 객체는 더 이상 도달할 수 없는 상태가 됩니다.

대표적인 방식은 Mark-and-Sweep 방식 입니다. 이 방식은 먼저 전역 객체나 실행 중인 함수에서 시작해서 연결된 객체들을 모두 찾아 ‘도달 가능하다’고 표시한 뒤, 도달할 수 없는 객체들을 찾아내어 제거합니다. 하지만 모든 상황에서 완벽하게 작동하는 것은 아니며, 잘못된 참조나 불필요한 클로저 사용 등으로 인해 참조가 끊기지 않는 객체가 남아 있는 경우 , 메모리 누수가 발생할 수 있습니다.

OOM이 발생하는 원인

OOM은 여러 가지 이유로 발생할 수 있지만 일반적으로 아래와 같은 원인이 있습니다.

• 사용하지 않지만 참조가 해제되지 않은 객체 가 계속해서 메모리를 차지하고 있을 때 발생할 수 있습니다. 예를 들어 클로저 내부에서 참조되고 있거나, 전역 객체에 등록된 값이 제거되지 않은 경우 등이 이에 해당합니다.
• 대용량 데이터를 한꺼번에 메모리에 로드 하는 경우에 문제가 발생할 수 있습니다. 예를 들어 JSON데이터 수만 건을 메모리에 올려놓고 처리하거나, 이미지 파일 수백 개를 동시에 로딩하는 경우 OOM 위험이 높아집니다.
• 무한 루프나 재귀 호출 이 발생할 경우 메모리 사용량이 급격히 증가합니다.
• 서버 환경에서는 로그나 응답 데이터를 메모리에 계속 유지 하거나, 캐시 데이터를 수동으로 정리하지 않아 누적될 경우 문제가 발생할 수 있습니다.

Next.js 와 OOM

Next.js는 서버 기능을 포함하고 있기 때문에 Node.js 런타임에서 돌아가는 서버 측 코드가 존재합니다. getServerSideProps, API Routes, Server Actions 와 같은 기능이 그 예입니다. 따라서, Next.js에서도 서버 측에서 OOM이 발생할 수 있으며 서비스 중단으로 이어질 수 있습니다.

저는 최근 회사에서 Next.js 기반의 서비스에서 OOM 문제를 경험하게 되었습니다. 메모리가 초기화되지 않아 메모리 사용량이 점점 증가하다가 결국 한계치를 초과해 버리는 현상이었습니다. 실무에서 OOM 문제를 마주친건 처음이라 당황스럽기도 했지만, 우선 Next.js에서 OOM이 발생할 수 있는 원인 을 찾아봤습니다.

• 불필요하거나 과도한 데이터 캐싱 서버에서 응답 결과를 캐시에 저장하되, 이를 해제하지 않으면 메모리가 계속 누적될 수 있습니다.
• 대용량 데이터의 반복 패칭 또는 유지 한 번에 많은 양의 데이터를 패칭하거나, 이를 서버 메모리에 오래 유지할 경우 문제가 됩니다.
• 해제되지 않는 참조 클로저나 전역 변수 등으로 인해 객체 참조가 끊기지 않으면 가비지 컬렉션이 이를 수거하지 못합니다.
• 의도치 않은 무한 루프 또는 재귀 호출 반복되는 로직이 메모리를 점유하면서 해제되지 않아 문제가 될 수 있습니다.

Next.js의 캐시가 문제?

이 중에서도 가장 핵심적인 원인으로 판단한 것은 데이터 패칭 후 캐시에 저장된 데이터가 적절히 초기화되지 않는 문제 였습니다.

실제로 저희 서비스는 대부분의 페이지가 서버 컴포넌트 로 구성되어 있었고, 데이터를 Server Actions를 통해 데이터를 패칭 하고 있었습니다. 커머스 서비스의 특성상 무한스크롤 페이지가 많았고, 이미지나 상품 정보처럼 한 페이지에서 불러오는 데이터 양이 많다 보니 메모리 사용량이 빠르게 증가한 것으로 추측했습니다.

문제를 해결하기 위해 문제 해결을 위해 먼저 일부 페이지의 데이터 패칭 방식을 서버 → 클라이언트 로 전환했습니다. 클라이언트에서 데이터를 가져올 경우 서버 메모리에 직접 데이터를 유지하지 않기 때문에 일시적으로 메모리 사용량을 줄일 수 있었습니다.

💭 캐싱도 살리고 메모리도 지킬 수는 없을까?

클라이언트 패칭으로 변경하면서 들었던 생각은 "Next.js의 장점 중 하나가 데이터 캐싱인데 이 캐싱이 오히려 OOM의 원인이 되어 버린다면 과연 Next.js의 이점을 제대로 활용하고 있는 것일까?" 라는 의문이 들었습니다. 그렇다면, "Next.js의 데이터 캐싱 기능을 유지하면서도 OOM 문제를 해결할 수 있는 방법은 없을까?" 라는 생각이 들었고 아직 실무에 적용해보진 않았지만 다음과 같은 방법이 있다고 생각했습니다.

• 캐시의 만료 시간 설정
  • fetch()의 next.revalidate 옵션을 이용해 불필요한 데이터의 장기 보관을 피할 수 있습니다. 참고 ➡️ Next.js(v15) 에서 데이터 캐시하기
• 클라이언트 패칭과 서버 패칭 구분
  • 동적인 데이터와 정적인 데이터에 따라 적절한 패칭 방식을 선택한다.

번외) OOM 디버깅 방법

크롬의 개발자 도구를 통해서 메모리 디버깅을 진행할 수 있습니다.

1. Heap snapshot

• 현재 페이지의 힙 상태를 기록하고 분석할 수 있으며 성능 개선 전후로 스냅샷을 비교할 수 있습니다.

2. Allocation instrumentation timeline

• 메모리 누수가 의심되는 시나리오를 수행하여 메모리 상태를 기록할 수 있다. 기록이 진행하는 동안 타임라인에 메모리 할당과 해제가 그래프로 표시되어 이를 분석하여 메모리 누수를 디버깅할 수 있습니다.

3. Allocation sampling

• 메모리 할당을 함수 단위로 간단하게 기록할 수 있습니다.

자세한 디버깅 방법은 FEConf 2023 [B2] SSR 환경(Node.js) 메모리 누수 디버깅 가이드 를 참고해주세요!

크롬 개발자 도구의 Memory 탭을 활용해 메모리 누수의 원인을 찾아보려 했지만, 개인적으로는 직관적이지 않고 어려웠다고 느꼈습니다. 관련 블로그나 문서를 참고했지만 어떤 항목을 중점적으로 봐야 하는지 명확하지 않았고 각 지표가 무엇을 의미하는지도 쉽게 와닿지 않았던 것 같습니다. (익숙하지 않아서 더 그랬던 것일 수도...😅)

해당 탭에서 제가 파악할 수 있었던 건, 현재 페이지에서 메모리가 얼마나 사용되고 있는지, 메모리가 적절히 해제되고 있는지 여부 정도였던 것 같습니다. 실제 누수의 원인을 정확히 짚어내기에는 한계가 있었고, 프론트엔드 개발자가 실무에서 활용할 수 있는 메모리 디버깅 툴이나 라이브러리를 더 찾아봐야겠다는 생각이 들었습니다.

📚 참고 Visualizing memory management in V8 Engine Tìm hiểu về NextJS và build ứng dụng đơn giản kết hợp Firebase Next.js에서 메모리 누수 디버깅하기

작년 10월에 다니던 회사가 경영 악화로 갑작스럽게 문을 닫으면서 퇴사를 하게 됐고, 냅다 채용 시장에 던져졌습니다.ㅋㅋㅋㅋ 그후 약 5-6개월 이직 준비를 하게 됐는데요, "내가 다시 취업할 수 있을까?" 하는 생각에 불안할 때도 많았지만 지금 돌아보면 여유롭던 아침이 살짝 그리워지기도 합니다...ㅎㅎ

힘들었지만 어느 때보다 의미 있었던 이직 준비 과정을 돌아보면서 앞으로의 계획도 함께 정리해보려 합니다!

🤷🏻‍♀️ 왜 퇴사했나요?

면접에서 꼭 물어보는 질문 중 하나죠ㅎㅎ 저는 경영 악화로 인한 퇴사였기 때문에 설명이 복잡하진 않았습니다. (장점이라면 장점?ㅋㅋㅋ) 회사가 그렇게 하루 아침에 문을 닫게 될 줄은 몰라서 처음엔 그 상황이 웃겼던 것(?) 같습니다ㅋㅋㅋㅋ 이후에 실업급여 신청하고, 회사가 정리된 후에 이력서 쓰고 포폴 준비하면서 "아, 진짜 나 백수됐구나" 하면서 실감 나면서 걱정이 됐던 것 같습니다.

사실 회사를 2년 동안 다니면서 이직 생각을 안 했던 건 아닙니다. 중간중간 면접도 몇 번 봤습니다. 그런데 일을 하면서 이직을 준비하다보니 좋은 회사를 가고 싶은 욕심은 커지는데 시간과 에너지가 부족해서 쉽지 않았습니다. 그런 면에서, 이번에는 오히려 몰입해서 준비할 수 있었던 점이 장점이었던 것 같기도 합니다.

🏃‍♀️ 어떻게 준비했나요?

하루 루틴 만들기

저는 완전 J형 인간이라서 퇴사하고 제일 먼저 했던게 무의미하게 시간을 보내는 걸 예방하기 위해 노션 플래너를 만드는 것이었습니다. 오전에는 일단 아침에 눈뜨면 무조건 헬스장으로 갔습니다. 운동하는 습관은 제 인생 통틀어 가장 잘한 일이라고 생각하고 진심으로 모든 분들께 추천드립니다! 운동 다녀온 후에 아점을 간단히 먹고 채용 공고를 싹 훑어보고 지원했습니다. 그리고 면접 준비, 코테 준비를 하면서 워밍업을 한 후에 그 날의 계획에 맞게 코어 타임에는 공부를 했습니다. 주로 강의를 듣거나 블로그를 쓰거나 개인 프로젝트를 진행했습니다. 저녁을 먹은 후에 잠깐 쉬었다가 코어 타임에 다 끝내지 못했던 일을 하면서 하루를 마무리했습니다.

물론 하루 계획을 다 지키지 못하는 날도 있었지만 중요한 건 꾸준히 하는 거라고 생각했기 때문에 "아 망했네" 라고 생각하기 보다 "오늘 못했으니깐 내일 더 완벽히 하면 되겠다" 라고 긍정적으로 생각하려고 했던 것 같습니다.

이력서는 무조건 여러 번 써보기

위의 루틴은 거의 올해 1월부터 진행했었고 작년 11월~12월은 이력서 준비 + 피드백 반복의 연속이었습니다. 양식, 구성, 내용 등 뭐 하나 쉽게 느껴지는 게 없었고 정말 많이 시간을 쏟아서 고민했던 것 같습니다. 처음에 인프런과 왓에버에서 이력서 멘토링을 신청해서 피드백을 받으면서 틀을 잡았고, 이후에는 이력서를 넣어보면서 서류 결과에 따라서 또 조금씩 수정했습니다.

이력서를 여러 번 수정하면서 느꼈던 것은 결국 모두가 말하는 좋은 이력서는 단순히 무엇을 했는지 나열하기 보다 무엇을 어떻게 했는지를 설명해야하고 어떻게 했는지가 면접관에게 매력적으로 다가와야 한다는 것이었습니다. 이 말 또한 추상적이고 당연하게 느껴질 수 있지만ㅋㅋㅋ 계속 고치고 고민하다보면 스스로 감을 잡아가는 것 같습니다.

(+ 그리고 추가적으로 회사마다 뽑는 기준이 다 다르기 때문에 절대적으로 좋은 이력서는 없다는 것도 느꼈습니다. A회사에서는 떨어진 이력서가 B,C회사에서는 붙을 수도 있다는 점...)

알고리즘 & 면접 준비는 평소에 꾸준히

이 두 가지(알고리즘, 면접)는 사실 하루 아침에 되는게 아니기 때문에 평소에 준비하는게 중요하다고 생각했습니다.

알고리즘은 지금도 잘하진 않지만ㅋㅋㅋ 프로그래머스에서 LV0부터 차근차근 시작하면서 기초는 어느 정도 다졌다고 생각합니다. 문제를 읽고 해석할 수 있고, “여기선 이걸 써야겠다.” 판단할 수 있을 정도까진 된 것 같습니다.

면접은 크게 기술 질문, 이력서 기반 질문, 인성 질문 이렇게 나뉘는 것 같습니다. 3가지 유형 모두 평소에 준비해두는 게 중요하다고 느꼈습니다. (그래야 면접 때 어버버하지 않고 자연스럽게 말할 수 있더라구요😅) 기술 질문은 CS부분이 평소 부족하다고 느껴서 인프런의 CS 강의를 들으면서 기초 개념들을 정리했습니다. 프론트엔드 관련 지식(JS,TS,React,Next.js 등...) 은 인터넷에 돌아다니는 대표 질문들을 모두 정리했고 이후에는 매일메일 서비스 구독을 하며 준비했습니다.

기술 질문들을 정리할 때는 무작정 암기하기 보다는 원리를 이해하려고 했습니다. 그러면 억지로 외우려하지 않아도 자연스럽게 기억에 남았던 것 같습니다.

면접 복기

면접이 끝나면 그냥 멍하니 이불 킥 하면서 시간을 보내기 보다는 어떤 질문들이 나왔고 내가 어떤 것에 질문을 못하고 잘했는지를 정리하는게 중요한 것 같습니다. 실제로 "나 대답 좀 잘한거 같은데?" 싶은데 하나하나 복기해보면 대답 엉망으로 한것 도 있었고 "이게 맞나?" 싶은데 맞을 때도 있었습니다ㅋㅋㅋ (중요한 건 자신감일지도) 이 과정이 다음 면접 때 정말 많은 도움이 되기 때문에 떨어지더라도 얻어가는 게 많았습니다.

🏢 그래서 어떤 회사로 갔나요?

이번에 입사한 회사는 커머스 스타트업입니다.

스타트업이라는 특성상 빠르게 변화하고 끊임없이 도전해야 하는데, 여기에 커머스까지 더해지니 정말 공부할 게 많았습니다...ㅎㅎ 특히 커머스는 서비스 운영 상태가 매출과 직결되기 때문에 예민하고 빠르게 반응해야 한다는 것을 느꼈습니다.

입사 후 가장 인상 깊었던 건, 항상 큰 화면에 whatap으로 모두가 볼 수 있도록 실시간 모니터링을 하고 있다는 것이었습니다. 보면서 “지금 이 순간에도 누군가는 이 서비스를 사용하고 있구나” 라는 생각에 신기하기도 했고 실시간으로 서버 상태를 확인할 수 있어서 편리하다고 생각했습니다.

이 회사를 가고 싶다고 생각했던 이유 중 하나는 면접에서 정해진 기술 질문보다는 제 이력서를 기반으로 실제 경험에 대해 궁금해하는 느낌을 받아서 좋았습니다. 또, CTO님의 "커머스에서 다양한 경험을 할 수 있고 그만큼 개발자로 많이 성장할 수 있다" 는 말씀이 인상 깊었습니다. 물론 그 말은 곧 힘든 일도 많을 수 있다는 뜻이겠지만ㅋㅋㅋ 세상에 쉽게 얻어지는 건 없다고 생각해서 지금의 회사를 가게되었습니다.

✨ 앞으로의 계획은 무엇인가요?

1. 빠르게 적응하기

현재 회사의 업무 분위기, 개발 환경, 기술 스택에 빠르게 적응하는 게 가장 우선이라고 생각합니다. 예전엔 기능만 구현하면 끝이라고 생각했지만, 이젠 코드의 질과 성능까지 고민하는 개발자가 되고 싶습니다. 이런 이야기를 CTO님과의 1on1 시간에 나눴는데 도움 받을 수 있는 책을 4권이나 주셨습니다 🥹 (부지런히 공부해야겠죠?ㅎㅎ) 지금은 그중 첫 번째로 『대규모 시스템 설계 기초』 를 읽고 있습니다.

2. 공부를 습관화하기

회사에서 배운 것, 새롭게 알게 된 기술들은 개인 Notion, GitHub, 블로그에 정리하려고 합니다. 이번 주에도 기술 블로그를 쓰고 싶었지만 주제를 정하지 못해서 일단 회고 블로그부터 업로드 하기로 했습니다ㅋㅋㅋ 앞으로는 최소 월 1~2회 블로그 포스팅을 목표로 하고 있습니다.

3. 개인 블로그 개편

작년부터 계획만 세워두고 미뤄왔던 개인 블로그 개편도 올해 꼭 해내고 싶습니다ㅋㅋ 개인적으로 저만의 블로그를 만들고 싶은 로망(?)이 있어서 단순히 글만 올리는 게 아니라, 직접 블로그를 개발하고 CRUD 기능까지 구현해서 운영하는 게 목표입니다!

물론 지금 계획들은 단순하고 당연한 것 들일 수 있지만 회사를 다니면서 더 구체적인 목표들이 생길 거라고 생각합니다.

👋🏻 마무리

마지막으로 제가 준비하면서 힘들 때 chat GPT에게 상담을 했었는데요ㅋㅋㅋ 이게 생각보다 위로가 되더라구요. 혹시나 위로가 필요하신 분들이 계시다면 chat GPT에게 고민을 털어놓는 것도 방법이 될 것 같습니다!

제가 좋아하는 말 중에 "운을 이기는 것은 꾸준함이다." 라는 말이 있는데요. 어려운 시기이지만 목표를 이루기 위해 꾸준히 움직인다면 못할 건 없다고 생각합니다! 그러니 우리 모두 멈추지말고 킵고잉합시다.

이번 글에서는 서버 액션의 구체적인 활용 후기라기 보다는 서버 액션이 무엇이고 어떻게 동작하는지에 대한 이론적인 부분에 대해서 정리해보려고 합니다. 서버 액션의 구체적인 활용 방법에 대해서는 다음 글에서 만나요👋🏻

1️⃣ 서버 액션이란?

서버 액션은 클라이언트에서 호출할 수 있는 서버에서 실행되는 비동기 함수입니다.

기존에는 DB를 수정하려면 아래와 같은 플로우로 진행됩니다.

1. 백엔드에서 API 엔드 포인트 생성
2. 프론트엔드에서 해당 API를 호출

하지만 서버 액션을 사용하면 별도의 API 없이 Next.js 서버에서 실행되는 함수를 호출해 직접 DB를 수정할 수 있습니다.

2️⃣ 서버 액션 사용하기

export default function Page() {
    const saveName = async (formData: FormData) => {    
          "use server";

        const name = formData.get("name");
          console.log("name", name);

        // 실제 DB에 저장하려면 여기에 sql 와 같은 서버에서 실행되는 명령어를 추가하면 됩니다.
    }

    return (
        <form action={saveName}>
              <input name="name" placeholder="이름을 알려주세요..." />
            <button type="submit">제출</button>
          </form>
    )

}

위 코드는 클라이언트에서 form 태그를 통해 유저의 이름을 서버에 저장하기 위한 간단한 예제 입니다.

• saveName 함수
  • 함수 최상단에 "use server" 지시자를 통해 서버 액션 함수를 만들어 줍니다.
  • formData.get("name") 을 이용해 입력된 데이터를 가져옵니다.
• <form action={saveName}>
  • action 속성에 서버 액션을 전달하면 폼 제출 시 서버에서 해당 함수(saveName)가 실행됩니다.
  • 결과적으로 프론트에서 API 요청을 할 필요없이 서버 액션만으로 DB 수정이 가능하게 됩니다.

✔️ 서버 액션은 서버에서만 실행된다.

실제로 위 코드의 폼을 제출하게 되면 서버로 요청이 전송되며, 서버측 콘솔인 vscode 터미널에 console.log 가 출력 되는 것을 확인할 수 있습니다. 이는 서버 액션이 클라이언트에서 실행되는 것이 아니라 서버에서 실행되고 있음을 증명하는 요소입니다.

이를 통해 서버 액션을 호출하면 Next.js 서버에서 실행되는 함수로 요청이 전달되었고 해당 함수가 정상적으로 실행되었음을 확인할 수 있습니다.

✔️ Request Headers의 Next-Action 해시값

서버 액션이 실행될 때, 브라우저의 Network 탭에서 요청 정보를 확인하면** Request Headers에 Next-Action 해시값**이 포함된 것을 볼 수 있습니다.

Next.js는 서버 액션을 호출할 때 내부적으로 해당 액션을 실핸하는 API 엔드포인트를 자동으로 생성합니다. 이때, 각 서버 액션 함수는 고유한 해시값(Next-Action)과 연결되며 브라우저가 해당 함수를 실행할 때 Request Header의 Next-Action 필드에 이 해시값을 전달하게 됩니다.

즉, 이 해시값은 어떤 서버 액션을 실행할지 식별하는 역할을 하는 것입니다. 이를 통해 Next.js가 서버 액션을 특정 API 엔드 포인트로 변환하여 처리하게 됩니다.

💬 서버 액션의 동작 과정 정리

1. 서버 실행 시, 서버 액션을 해시값과 매핑

• Next.js가 빌드될 때, 서버 액션 함수마다 고유한 해시값을 생성하고 특정 API 엔드포인트로 변환합니다.

2. 클라이언트에서 서버 액션 호출 (폼 제출)

• 브라우저에서 <form> 을 제출하면 Next.js는 내부적으로 서버 액션을 실행하는 API 요청을 보냅니다.
• 이때, Request Headers에 Next-Action 해시값이 자동으로 포함됩니다.

3. Next.js 서버에서 요청 처리

• 서버는 요청 헤더에서 Next-Action 값을 확인하고, 해당 해시값과 매핑된 서버 액션을 실행합니다.

4. 서버 액션 실행 및 결과 반환

• 서버 액션이 실행되면서 DB 저장 등 필요한 작업을 수행하게 됩니다.

🚨 주의할 점

서버 액션에서 FormData를 사용할 때, formData.get("key") 메서드는 FormDataEntryValue | null 타입을 반환합니다.

• FormDataEntryValue: 이는 string 또는 File일 수 있습니다. 보통 텍스트 입력 필드에서는 string이 반환됩니다.
• null : 해당 키에 대응되는 값이 없을 경우 null이 반환됩니다.

따라서, formData.get("name") 의 결과값을 직접 사용할 때는 반드시 이를 처리해 주어야 합니다.

1. null 값이 올 경우를 대비한 처리
2. 결과값에 대한 string 처리

const name = formData.get("name")?.toString();

3️⃣ 서버 액션을 사용하는 이유

마지막으로 서버 액션을 왜 사용해야하면 어떨 때 사용해야 하는지에 대해 다음과 같이 정리해 보았습니다.

1. 코드가 간결하다.

• 기존 API Route 방식보다 짧고 직관적인 코드 작성이 가능합니다.

기존 API Route 방식

1. API Route 파일을 따로 생성 → pages/api 또는 app/api 경로에 서버 로직을 작성
2. 클라이언트에서 해당 API 엔드포인트를 호출 → fetch('/api/xxx') 또는 axios.post('/api/xxx') 사용

2. 보안성이 높다.

• 서버 액션은 클라이언트에서 실행되지 않고 서버에서만 실행되므로 API 엔드포인트가 노출되지 않습니다. 따라서, API 요청을 가로채거나 변조하는 보안 위협을 줄일 수 있습니다.

3. API 없이도 데이터 처리가 가능하다.

• 별도의 API를 만들 필요 없이 Next.js 내부에서 서버 액션을 실행하면 되기 때문에 단순한 CRUD 작업이라면 유지보수에 더 유리할 수 있습니다.

✨ 마무리

서버액션에 대해 정리하면서 Next.js에서 기존에 제공하던 API Route보다 훨씬 간편하게 사용할 수 있다는 점이 가장 인상적이었습니다.

API Route의 경우 서버 로직을 따로 작성한 뒤 클라이언트 에서 fetch로 또 해당 로직으로 불러와야했기 때문에 관리가 복잡하게 느껴졌었지만, 서버 액션을 사용하면 하나의 함수로 서버 로직을 관리하고 클라이언트에서 직접 호출할 수 있어 유지보수가 훨씬 쉽게 할 수 있겠다는 생각이 들었습니다. (풀스택 사프 SSAP가능..?😅)

하지만 복잡한 비즈니스 로직이 필요한 경우에는 서버 액션만으로 해결하기 어려운 부분이 반드시 있을거고 백엔드 API 설계를 완전히 대체 할 수는 없겠다는 생각이 들었습니다. 특히 프론트에서 DB를 다루기 위해서 필요한 sql 설정을 하는 것도 리소스가 필요하고 어쩌면 배보다 배꼽이 더 커지는 일이 발생할 수 도 있겠다는 생각이...ㅎㅎ 언제나 그렇듯 프로젝트의 규모와 요구 사항에 따라 사용하는게 가장 중요하겠죠?

1️⃣ 패럴렐 라우트

발음하기도 어려운(?) 패럴렐 라우트는 병렬 라우트를 뜻합니다. 즉, 하나의 화면 안에 여러 페이지 컴포넌트를 한번에 렌더링 시켜주는 패턴입니다. 주로 트위터와 같은 소셜 미디어, 어드민 대시보드 등 복잡한 구조에 사용됩니다.

Slot(슬롯)

패럴렐 라우트에는 슬롯 이라는 개념이 등장하는데요. 이는 병렬로 렌더링 될 페이지들을 보관하는 폴더 역할을 합니다. 원하는 페이지 폴더 아래 @ 를 붙여서 슬롯을 만들어 주면 됩니다. *이때, 생성된 슬롯은 라우트 그룹처럼 URL경로에는 아무런 영향을 주지 않습니다. *

슬롯의 특징에 대해서 몇가지 더 살펴보자면,

1. 부모 컴포넌트(layout.tsx)에 자동으로 props(슬롯에 생성한 컴포넌트)로 전달됩니다.

export default function Layout({
  children,
  sidebar,
  feed,
}: {
  children: React.ReactNode;
  sidebar: React.ReactNode;
  feed: React.ReactNode;
}) {
  return (
    <div>
      {feed}
      {sidebar}
      {children}
    </div>
  );
}

2. 개수 제한이 없습니다.

• 하나의 페이지 디렉토리 안에 여러 개의 스롯을 만들 수 있습니다.

3. 슬롯 안에서 새로운 페이지를 추가할 수 있습니다.

• 해당 슬롯 내부에서 페이지 전환이 가능하지만 바로 그 경로로 접근하거나 새로 고침을 하게되면 404페이지를 만나게 됩니다.

3번 특징에 대해 좀더 자세히 알아보겠습니다.

슬롯 안에서 새로운 페이지를 추가한 경우

@feed 슬롯 안에 setting 이라는 페이지 폴더를 생성한 뒤 layout.tsx 에 해당 페이지로 이동할 수 있는 테스트 경로를 추가했습니다.

// app/parallel/layout.tsx 

import Link from "next/link";

export default function Layout({
  children,
  sidebar,
  feed,
}: {
  children: React.ReactNode;
  sidebar: React.ReactNode;
  feed: React.ReactNode;
}) {
  return (
    <div>
      <div>
        <Link href={"/parallel"}>parallel</Link>
        &nbsp;
        <Link href={"/parallel/setting"}>parallel/setting</Link>
      </div>

      <br />
      {feed}
      {sidebar}
      {children}
    </div>
  );
}

1. <Link> 를 통해 진입한 경우

즉, 현재 layout.tsx가 유지된 상태에서 패럴렐 라우트 내부만 업데이트 되기 때문에 정상적으로 동작합니다.

2. 초기 진입 (새로 고침)한 경우

Next.js는 페이지 진입시 해당 페이지가 독립적인 페이지인지를 확인하는데 슬롯 안에 등록된 페이지는 직접 페이지로 등록하지 않기 때문에 존재하지 않는 경로라고 판단하는 것입니다.

즉, 페러렐 라우트 내부 페이지들은 기본적으로 단독으로 접근할 수 없고 반드시 상위 layout.tsx 가 존재해야 정상적으로 렌더링됩니다.

3. 해결 방법

위와 같은 오류를 해결하는 방법은 간단합니다. 페럴렐 라우트가 비어있을 때 기본적으로 보여줄 페이지인 default.tsx 를 만들어 주면 됩니다.

export default function Default() {
  return <div>/parallel/default</div>;
}

2️⃣ 인터셉팅 라우트

인터셉팅 라우트는 intercept 의 낚아채다 라는 뜻대로 경로를 낚아채는 것을 말합니다. 즉, 사용자가 동일한 경로로 접속하게 되더라고 특정 조건에 만족하면 다른 페이지를 렌더링하도록 설정하는 기술 을 말합니다.

그런데 여기서 말하는 조건은 개발자가 직접 설정할 수 있는 것은 아니고, Next.js 에서 지정된 조건으로 초기 접속이 아닐 때 를 말합니다. 예를 들면 클라이언트 사이드 렌더링 방식 으로 <Link> 혹은 Router.push() 을 말합니다.

설정 방법

1. app 폴더 아래 인터셉팅 라우트를 적용시킬 폴더를 만듭니다.
2. 해당 폴더 앞에 (.) 를 붙여줍니다.
   • () 뒤에 나오는 경로를 인터셉트 하라는 의미입니다.
   • . 은 상태 경로를 나타냅니다. (동일한 경로라는 뜻)
   • (..) 인터셉트를 적용시킬 페이지의 경로가 한 단계 위에 있을 때
   • (..)(..) 인터셉트를 적용시킬 페이지의 경로가 두 단계 위에 있을 때
   • (...) app폴더 바로 아래에 있는 페이지를 인터셉트하겠다는 의미 자세한 내용 보러가기

3️⃣ 패럴렐 라우트와 인터셉팅 라우트 함께 사용하기

이 두 가지 원리를 사용해서 인스타그램의 상세 페이지를 선택했을 때 동작하는 방식을 구현할 수 있습니다.

예시로 인스타그램(pc)에서 내 프로필에서 피드를 선택했을 때 피드 상세가 모달로 노출되지만, 다시 새로 고침을 하게되면 피드 상세 페이지로 보여지고 있습니다. 이와 같은 동작을 패럴렐 라우트와 인터셉팅 라우트를 사용해서 구현해 보도록 하겠습니다.

구현 동작

1. 메인 페이지에서 책을 클릭하면 모달 형태로 책 상세 정보가 나타난다.
2. 새로 고침하면 책 상세 페이지로 이동한다.

코드 구조

• app/page.tsx → 메인 페이지
• app/@modal/(.)book/[id]/page.tsx → 모달을 통한 책 상세 페이지
• app/book/[id]/page.tsx → 책 상세 페이지

// app/page.tsx
export default function Home() {
  return (
    <div className={style.container}>
      <section>
        <h3>지금 추천하는 도서</h3>
        <div>
          {recoBooks.map((book) => (
              <Link href={`/book/${id}`} className={style.container}>
                  ...
              </Link>
          ))}
        </div>
      </section>
    </div>
  );
}


// app/@modal/(.)book/[id]/page.tsx
import BookPage from "@/app/book/[id]/page";
import Modal from "@/components/modal";

export default function Page(props: any) {
  return (
    <Modal>
      <BookPage {...props} />
    </Modal>
  );
}

// app/book/[id]/page.tsx
export default function Page({ params }: { params: { id: string } }) {
  return (
    <div className={style.container}>
      <BookDetail bookId={params.id} />
      <ReviewEditor bookId={params.id} />
      <ReviewList bookId={params.id} />
    </div>
  );
}

정리

패럴렐 라우트와 인터셉팅 라우트를 함께 사용하면, 기존 페이지에서 모달을 띄우는 사용자 경험을 제공하면서도 새로 고침 시 개별 상세 페이지로 자연스럽게 이동하는 동작을 구현할 수 있습니다.

1. 메인 페이지에서 책을 클릭하면 모달이 열림 (인터셉팅 라우트)

• app/@modal/(.)book/[id]/page.tsx가 렌더링됩니다.
• 이 파일은 app/book/[id]/page.tsx를 불러와 <Modal> 로 감싸서 모달 형태로 표시됩니다.

2. 새로 고침하면 모달이 사라지고 책 상세 페이지로 이동 (패럴렐 라우트)

• /book/[id]로 직접 접근하는 형태가 되면 app/book/[id]/page.tsx가 단독 렌더링됩니다. 즉, 모달이 아닌 전체 페이지로 전환됩니다.

3. @modal 패럴렐 라우트와 default.tsx 역할

• / 로 접근하거나 /book/[id] 에 직접 접근했을 경우를 위해 default.tsx 을 만들어 줘야합니다.
• app/@modal/default.tsx는 기본적으로 null을 반환합니다. → 모달이 필요 없을 때 아무것도 렌더링하지 않는 역할을 합니다.

export default function Default() {
  return null;
}

📚 참고 한 입 크기로 잘라먹는 Next.js(v15)

이번 글에서는 Next.js 15 버전을 공부하면서 새롭게 알게된 스트리밍에 대해서 정리해보려고 합니다!🙂

1️⃣ 스트리밍이란?

스트리밍이란 서버에서 클라이언트로 매우 큰 용량의 데이터를 보낼 줄 때 데이터를 잘게 쪼개서 보내주는 것을 말합니다.

기존 SSR vs 스트리밍 SSR

• 기존 SSR (Server Side Rendering) : 서버에서 모든 데이터를 한꺼번에 준비한 후 클라이언트로 전달
• 스트리밍 SSR (Streaming SSR) : 준비된 데이터부터 즉시 전송하여 빠르게 화면 구성

기존 SSR 방식은 모든 데이터를 서버에서 처리한 후 한번에 클라이언트로 전송하지만, 스트리밍 기반 SSR은 서버에서 준비된 데이터부터 점진적으로 클라이언트에 전송하기 때문에 전체 데이터가 다 준비되지 않아도 준비된 부분부터 먼저 화면에 표시가 가능합니다.

결과적으로 사용자는 페이지 로딩을 기다리는 시간이 줄고 빠르게 화면을 볼 수 있게됩니다.

2️⃣ Next.js의 스트리밍

Next.js에서는 페이지 스트리밍과 컴포넌트 스트리밍을 지원합니다.먼저 렌더링된 컴포넌트(동기 작업)를 보여주고, 느리게 렌더링 되는 컴포넌트(비동기 작업)는 대체 UI를 보여주게 됩니다.

페이지 스트리밍

Next.js에서는 페이지 단위에서 스트리밍을 적용할 수 있습니다.

예를 들어 page.tsx에서 데이터를 불러오는 작업이 오래 걸리는 경우, 해당 디렉토리에 loading.tsx 파일을 함께 정의하면 해당 페이지가 로딩 중일 때 loading.tsx 에서 지정한 로딩 UI를 먼저 보여줄 수 있습니다.

// page.tsx
export default function Page({
  searchParams,
}: {
  searchParams: { q?: string };
}) {
  return (
    <div>
      <div>test</div>
      <SearchResult q={searchParams.q || ""} />
    </div>
  );
}

// loading.tsx
export default function Loading() {
  return <div>로딩 중...</div>;
}

위의 코드에서 SearchResult 컴포넌트가 API 호출을 통해 데이터를 받아와야 한다면, 해당 데이터가 준비될 때까지 아무것도 표시되지 않을 수 있습니다. 이를 해결하기 위해 동일한 경로에 loading.tsx 파일을 추가하면, SearchResult가 로딩되는 동안 대체 UI를 표시할 수 있습니다.

주의할 점

페이지 스트리밍 시에 몇 가지 주의해야할 점이 있습니다.

1. loading.tsx 는 현재 경로에 있는 page 컴포넌트 뿐만 아니라 마치 layout 처럼 해당 경로 아래에 있는 모든 비동기 page 컴포넌트를 스트리밍 되도록 만든다.

2. 스트리밍은 async가 적용된 비동기 페이지에서만 동작합니다. → page.tsx가 서버 컴포넌트이어야 합니다.

3. loading.tsx는 page.tsx에만 적용되며, layout.tsx나 일반 컴포넌트에서는 사용할 수 없습니다.

4. 쿼리 스트링 변경 시에는 loading.tsx가 트리거되지 않습니다. → URL의 쿼리 스트링만 바뀌는 경우에는 다시 로딩 상태로 돌아가지 않습니다.

그렇다면 만약 전체 페이지에 대한 스트리밍을 적용하지 않고, 특정 컴포넌트 혹은 클라이언트 컴포넌트에서 스트리밍하고 싶다면 어떻게 해야할까요? 그때 Suspense를 사용해서 해결할 수 있습니다.

3️⃣ Suspense란?

React의 Suspense는 비동기 컴포넌트가 로딩되는 동안 대체 UI를 제공하는 기능입니다. 즉, 비동기 작업이 완료될 때까지 사용자가 기다리지 않도록, 미리 준비된 UI를 보여주고 이후 데이터를 채워 넣을 수 있도록 도와줍니다.

대체 UI 표시

Suspense는 fallback 속성을 통해 비동기 작업이 끝날 때까지 대체 UI를 보여 줄 수 있습니다.

비동기 작업 완료 후 화면 업데이트

비동기 작업이 끝나게 되면 Suspense로 감싸고 있던 컴포넌트를 렌더링하여 보여주게 됩니다.

4️⃣ Suspense + 스트리밍 SSR

컴포넌트 스트리밍

페이지 스트리밍에서 부족했던 부분을 다음과 같은 보완할 수 있습니다.

export default function Page({
  searchParams,
}: {
  searchParams: { q?: string };
}) {
  return (
    <div>
      <div>test</div>
      <Suspense
        key={searchParams.q || ""}
        fallback={<BookListSkeleton count={3} />}
      >
        <SearchResult q={searchParams.q || ""} />
      </Suspense>
    </div>  
  );
}

1. 쿼리 스트링에 따른 UI 갱신

페이지 스트리밍에서는 쿼리 스트링 변경 시에는 loading.tsx가 트리거되지 않습니다. 하지만 쿼리 스티링이 바뀌면서 새로 데이터를 요청해야하는 경우가 있습니다. Suspense에서는 key 속성을 사용하여 컴포넌트가 리렌더링되도록 할 수 있습니다.

기본적으로 Suspense 컴포넌트는 최초로 한번 내부 컴포넌트 로딩이 완료된 이후로는 내부의 콘텐츠가 변경되어도 로딩 상태로 돌아가지 않습니다. 따라서 key 값을 동적으로 설정하여 key값이 변할 때마다 새로운 컴포넌트로 인식하게 하여 매번 로딩 상태를 보여주도록 합니다.

2. 전체 페이지가 아닌 일부분 스트리밍 적용

Suspense는 페이지 전체가 아닌 특정 컴포넌트에만 스트리밍을 적용할 수 있습니다. 페이지 내 여러 개의 컴포넌트 중 일부만 비동기적으로 데이터를 로딩할 때, 그 부분만 대체 UI를 보여줄 수 있습니다.

위 코드에서 <div>test</div> 영역은 바로 보여지고, <SearchResult /> 영역만 비동기 작업을 수행하는 동안 대체 UI안 BookListSkeleton를 보여주고 있습니다.

📚 참고 한 입 크기로 잘라먹는 Next.js(v15)

1️⃣ 클로저란?

클로저는 주변 상태(어휘적 환경)에 대한 참조와 함께 묶인 함수의 조합니다. 즉, 클로저는 내부 함수에서 외부 함수의 범위에 대한 접근을 제공합니다. Javascript에서 클로저는 함수 생성 시 함수가 생성될 때마다 생성됩니다. 출처-MDN

사실 우리는 코딩을 하면서 이미 클로저를 자주 사용해왔습니다. 클로저 구조는 다음과 같습니다.

function outer() {
  let x = 10;
  function inner() {
    console.log(x); 
  }
  return inner;
}

outer(); // 10

위 코드의 결과가 왜 10이 나올까요? 코드가 다음과 같이 실행되기 때문입니다.

• outer 함수 안에는 x라는 변수가 있고, inner라는 내부 함수가 x를 사용합니다.
• outer 함수가 실행되면 inner 함수를 반환하는데, 이때 inner 함수는 outer 함수의 변수 x를 기억하고 있습니다.
• 그래서 closureExample()을 호출하면 inner 함수가 실행되어 x를 출력하게 됩니다.

위 처럼 클로저란, 함수 안에 정의된 다른 함수가 외부 함수의 변수에 접근할 수 있게 해주는 구조입니다. 그렇다면 자바스크립트에서는 이런 클로저가 왜 가능한 걸까요?

2️⃣ 자바스크립트에서 클로저

자바스크립트에서 클로저가 가능한 이유는 렉시컬 환경(Lexical Environment) 과 실행 컨텍스트(Execution Context) 덕분입니다. 자바스크립트는 렉시컬 스코프를 따르기 때문에, 함수가 어디에 선언되었는지에 따라 변수의 유효 범위가 결정됩니다. 이를 기반으로 클로저가 형성됩니다.

렉시컬 스코프란? 함수의 선언 위치에 따라 변수의 유효 범위(스코프)가 정해지는 것을 말합니다. 즉, 함수 내에서 참조할 수 있는 변수들은 그 함수가 선언된 위치를 기준으로 결정됩니다.

렉시컬 환경

렉시컬 환경이란 변수나 함수가 어디서 정의되었는지를 기억하고 관리하는 개념입니다.

렉시컬 환경을 구성하는 두가지 요소가 있습니다.

1. 환경 레코드는 변수와 함수들이 실제로 저장되는 저장소를 말합니다. 함수안에서 선언된 변수나 함수들이 여기에 저장되고 변수의 값을 찾을 때 여기서부터 시작해서 찾게됩니다.
2. 상위 환경에 대한 참조는 해당 변수를 다른 곳에서 찾도록 해주는 역할을 합니다. 예를 들어 함수 안에서 외부 함수의 변수의 접근하려면 상위 환경을 찾아야하는데 이 때 이 참조가 필요하게 됩니다.

실행 컨텍스트

실행 컨텍스트는 자바스크립트 코드가 실행될 때 생성되는 실행 환경을 의미 합니다. 즉, 자바스크립트 엔진이 코드를 해석하고 실행하는 동안의 환경을 말하며 함수 호출이나 코드 블록이 실행될 때 새로운 실행 컨텍스트를 생성합니다.

실행 컨텍스트의 구성 요소는 크게 렉시컬 환경, 변수 객체, this 값이 있습니다.

1. 렉시컬 환경은 변수나 함수가 어디서 선언 되었는지를 기억하고 저장합니다.
2. 변수 객체는 변수와 함수 선언이 포함된 객체로 함수 내에서 사용되는 변수들이 저장됩니다.
3. this 값은 함수가 어디서 실행되었는지에 따라서 동적으로 결정됩니다.

정리하자면,

• 렉시컬 환경을 통해 변수와 함수 선언이 어디서 정의되었는지를 추적하고 변수의 스코프를 결정합니다.
• 실행 컨텍스트는 코드 실행 시 생성되는 실행 환경으로 렉시컬 환경을 포함하고 있어 함수가 실행될 때마다 변수에 접근할 수 있도록 도와줍니다.

따라서, 렉시컬 환경을 통해 변수와 함수의 선언 위치를 추적하고 이를 바탕으로 실행 컨텍스트 내에서 변수에 접근 할 수 있도록 도와주기 때문에 클로저가 가능하게 됩니다.

3️⃣ 클로저 활용 예시

클로저는 다음과 같은 일을 가능하게 합니다.

데이터의 은닉화

데이터의 은닉화는 외부에서 특정 데이터를 직접 수정하지 못하도록 하고, 그 데이터를 수정하는 메서드만을 제공하는 방식입니다. 이를 통해 중요한 데이터를 보호하고, 예기치 않은 변경을 방지할 수 있습니다.

function createCounter() {
  let count = 0; // 외부에서는 접근할 수 없는 변수
  return {
    increment: function() {
      count++;
      console.log(count);
    },
    decrement: function() {
      count--;
      console.log(count);
    },
    getCount: function() {
      return count;
    }
  };
}

const counter = createCounter();
counter.increment(); // 1
counter.increment(); // 2
counter.decrement(); // 1
console.log(counter.getCount()); // 1

이 예시에서 count 변수는 createCounter 함수 내부에 정의되어 있으며, 외부에서 직접 접근할 수 없습니다. 대신, 클로저를 통해 반환된 메서드(increment, decrement, getCount)만 사용하여 값을 변경하거나 조회할 수 있습니다. 이렇게 데이터를 은닉하고 외부에서의 직접적인 접근을 차단하는 방식으로 데이터의 은닉화가 이루어집니다.

함수형 프로그래밍

함수형 프로그래밍은 함수를 일급 객체로 취급하며, 함수들이 다른 함수를 반환하거나 인자로 받을 수 있는 특징이 있습니다. 클로저는 이러한 함수형 프로그래밍에서 유용하게 사용됩니다. 특히, 내부 함수가 외부 상태에 의존하면서 그 상태를 기억하는 데 클로저가 사용됩니다.

function multiply(factor) {
  return function(number) {
    return number * factor;
  };
}

const multiplyBy2 = multiply(2);
const multiplyBy3 = multiply(3);

console.log(multiplyBy2(5)); // 10
console.log(multiplyBy3(5)); // 15

위 코드에서 multiply 함수는 내부에서 또 다른 함수를 반환합니다. 이때 반환된 함수는 factor 변수에 접근할 수 있는데, 이는 클로저 덕분입니다. 클로저를 사용하면 외부 함수의 인자 값을 기억하는 고차 함수를 쉽게 구현할 수 있으며, 이러한 방식은 함수형 프로그래밍에서 자주 사용됩니다

콜백 함수 및 비동기 작업

클로저는 비동기 작업에서 상태를 유지하는 데 유용하게 사용됩니다. 비동기 작업이 완료된 후 콜백 함수가 실행될 때 외부 함수의 변수에 접근할 수 있습니다.

function fetchData(url) {
  let data = null;
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      data = `Fetched data from ${url}`;
      resolve(data);
    }, 1000);
  });
}

function displayData() {
  fetchData('https://api.example.com').then(data => {
    console.log(data); // "Fetched data from https://api.example.com"
  });
}

displayData();

위 코드에서 fetchData 함수는 비동기적으로 데이터를 가져오는 작업을 합니다. 데이터가 가져와지면, then 안의 콜백 함수에서 data를 사용할 수 있습니다. 이때 data는 fetchData 함수 내에서 정의된 변수입니다. 비록 비동기 작업이 완료되었지만, 클로저 덕분에 비동기 작업 후에도 data에 접근할 수 있는 것입니다. 이처럼 클로저는 비동기 작업에서 중요한 역할을 하며, 작업이 끝난 후에도 데이터를 안전하게 사용할 수 있게 합니다.

🙌🏻 마무리

사실 클로저는 새로운 개념은 아니고 이미 알고 있고 사용하는 개념이었습니다. 클로저에 대해 정확히 정의하고, 자바스크립트에서 왜 가능한지를 이해함으로써 자바스크립트의 동작 원리를 더욱 깊이 이해할 수 있었습니다. 특히 그동안 통신할 때 사용했던 비동기 처리 방식을 이해하는데 큰 도움이 됐습니다. 원리를 이해하고 사용하는 것의 중요성을 다시 한번 느끼면서 20000...

1️⃣ enum 이란?

enum은 열거형(enumeration)의 줄임말로, 연관된 상수들을 하나의 그룹으로 묶어 표현하는 TypeScript의 기능입니다. 이를 통해 코드의 가독성과 유지보수성을 높일 수 있습니다.

const user1 = {
    name: "철수",
    role: 0 
}

const user2 = {
    name: "영희",
    role: 1 
}

const user3 = {
    name: "민수",
    role: 2
}

위의 예시처럼 역할에 숫자 값을 부여했을 때 0,1,2만 보고 어떤 의미인지 바로 알기가 어렵습니다. 이런 경우 enum을 통해 개선할 수 있습니다.

enum Role {
    ADMIN = 0,
    USER = 1,
    GUEST = 2
}

const user1 = {
    name: "철수",
    role: Role.ADMIN 
}

const user2 = {
    name: "영희",
    role: Role.USER  
}

const user3 = {
    name: "민수",
    role: Role.GUEST 
}

enum을 활용하여 역할을 정의하고 그 의미를 명확하게 할 수 있습니다. 또한, 0 대신 Role.ADMIN 을 사용함으로써 코드의 가독성을 올릴 수 있으며 오타도 방지할 수 있습니다.

enum의 자동 할당

enum은 값을 명시적으로 할당하지 않으면 자동으로 0부터 시작해서 순차적으로 값을 할당합니다.

enum Role {
    ADMIN,  // 0
    USER,   // 1
    GUEST   // 2
}

또한, 특정 값에서 시작하도록 지정할 수도 있습니다.

enum Role {
    ADMIN = 9,  // 9
    USER = 10,  // 10
    GUEST       // 11
}

enum과 union의 차이점

• enum은 연관된 상수들을 하나의 그룹을 묶어 관리합니다.

      enum Role {
        ADMIN = 0,
        USER = 1,
        GUEST = 2
    }

• union은 특정 변수나 속성이 여러 개의 정해진 값 중 하나를 가집니다.

    type Role = "ADMIN" | "USER" | "GUEST";

• 즉, enum은 하나의 객체처럼 동작하며 특정 값에 접근할 수 잇지만 union은 값들의 집합을 나타내는 타입이며 값들의 범위를 제한하는 역할을 합니다.

2️⃣ enum 의 취약점

위 처럼 enum은 편리한 기능을 제공하지만, 몇 가지 단점이 존재합니다.

불필요한 런타임 코드 생성

enum은 컴파일된 Javascript 코드에서 객체로 변환되어 추가적인 코드가 생성됩니다.

이러한 추가 코드는 번들 크기를 증가시키고 최적화에 불리할 수 있습니다.

Three Shaking의 어려움

Three Shaking은 사용하지 않는 코드를 제거하여 번들 크기를 줄이는 최적화 기법입니다. 그러나 enum은 실제로 런타임에 객체로 변환되기 때문에 이를 잘라내기 어렵습니다.

enum의 값은 컴파일된 후 객체 형태로 존재하고, 해당 객체를 참조하는 코드가 존재할 수 있기 때문에, tree shaking이 제대로 동작하지 않습니다. 이로 인해 사용하지 않는 enum 값들이 최종 번들에 포함되어 최적화가 어려워집니다.

타입 안정성 문제

enum은 숫자 값을 기본으로 하기 때문에, 역방향 매핑 을 지원합니다. 따라서 의도치 않은 값이 할당되는 문제가 발생할 수 있습니다.

enum Status {
  Loading,
  Success,
  Error,
}

let statusName: string = Status[1]; // "Success"
let statusIndex: number = Status["Success"]; // 1

3️⃣ 그렇다면 어떻게 사용해야 할까?

as const

타입스크립트 공식 문서에서는 enum 대신 as const 사용을 지향하고 있습니다.

as const 는 TypeScript에서 객체나 배열을 리터럴 타입으로 고정할 수 있게 해줍니다.

리터럴 타입이란? 변경 불가능한 값을 나타내는 타입입니다. 예를 들어, "loading", "success", "error" 같은 값을 리터럴 타입으로 지정하면, 해당 값만 허용되고 다른 값은 타입 오류가 발생합니다. 이를 통해 값의 범위를 제한하고 예상치 못한 값을 방지 할 수 있습니다.

따라서, as const 를 사용하면 값이 변경되지 않도록 고정되고, 타입은 해당 값에 정확히 맞춰지기 때문에 의도치 않은 값 할당을 방지할 수 있습니다.

const Status = {
  Loading: "loading",
  Success: "success",
  Error: "error",
} as const;

type Status = typeof Status[keyof typeof Status];

let status: Status = "loading"; // 정상
status = "completed"; // 에러 발생

위 예시에서 Status는 as const 로 리터럴 타입으로 고정되었고, 그 결과 Status 타입은 "loading", "success", "error"로 제한됩니다. 이렇게 하면 원하는 기능을 사용하면서 enum에서 발생할 수 있는 여러 문제들을 피할 수 있게 됩니다!

막상 사용해보니 이렇게 효율적일 수가 없더라구요 진작에 공부해서 써볼껄 이라는 후회가 들었습니다. next.js 15버전을 공부하던 중에 가장 인상 깊었던 것은 캐시 기능이었고 새로워진 next.js는 같은 일 계속 시키는거 정말 싫어하는 구나라고 느꼈습니다.

그래서 오늘은 next.js의 데이터 캐시하는 방법에 대해서 정리해보려고 합니다~!

1️⃣ 데이터 페칭

먼저, 데이터 페칭에 대해서 어떻게 이뤄지는지 간략히 알아보도록 하겠습니다.

Page Router 버전에서 데이터 페칭

• 페이지 파일에서 SSR, SSG, Dynamic SSG를 통해 서버에서 데이터를 가져와서 page에 props로 데이터를 전달합니다.
• 모든 컴포넌트가 클라이언트 컴포넌트로 동작합니다. (= 컴포넌트가 서버와 클라이언트에서 모두 실행된다는 것을 의미합니다.)
• 최상단에서 데이터를 필요로 하는 페이지까지 props로 계속 전달해줘합니다. (props drilling 문제)

App Router 버전에서 데이터 페칭

• 서버 컴포넌트에서 async - await 키워드와 fetch 메서드를 활용해서 데이터를 직접 불러오는 데이터 페칭 로직을 만들 수 있습니다.

     export async function Page(props){
         const data = await fetch('...');

         return <div>...</div>
    }

• 하지만 클라이언트 컴포넌트에서는 async - await 키워드 를 사용할 수 없습니다.
• 데이터가 필요한 곳에서 직접 불러오는 것을 권장합니다.

🧐 async - await 키워드 사용이 서버 컴포넌트에서는 되지만, 클라이언트 컴포넌트에서는 안되는 이유

• 서버 컴포넌트는 서버에서 데이터를 미리 가져와서 HTML을 렌더링할 수 있기 때문입니다. 서버 측에서는 비동기 작업이 완료된 후 렌더링을 처리하므로, 비동기 작업을 문제없이 사용할 수 있습니다.
• 반면, 클라이언트 컴포넌트는 브라우저에서 실행되며, 랜더링 시에 비동기 작업을 바로 처리할 수 없기 때문에 제대로 렌더링이 이루어지지 않을 수 있습니다.

☝🏻 주의사항 데이터 패칭을 위한 환경 변수를 설정할 때 .env 파일에서 NEXT_PUBLIC 이라는 접두사를 붙이지 않으면 next 는 자동으로 해당 환경변수를 서버측에서만 접근 가능한 것으로 인식하여 해당 환경변수에 대해 클라언트 컴포넌트에서는 접근이 불가능합니다!

2️⃣ 데이터 캐시

Next.js에서 데이터 캐시란

• fetch 메서드를 활용해 불러운 데이터를 Next 서버에서 보관하는 기능을 말합니다.
• 영구적으로 데이터를 보관하거나, 특정 시간을 주기로 갱신 시키는 것도 가능합니다.
• 캐시의 목적은 불필요한 데이터 요청의 수를 줄여서 웹 서비스의 성능을 개선하는 것이라고 할 수 있습니다.

캐시 옵션

📢 Next 서버에서 발생하는 데이터 패칭을 로그로 남기는 설정

  import type { NextConfig } from "next";
  const nextConfig: NextConfig = {
        logging: {
            fetches: {
                fullUrl: true,    
            },
        },
    };
  export default nextConfig;

• next.config.ts 파일을 위와 같으 설정하면 터미널에서 데이터 패칭에 대한 로그를 확인할 수 있습니다!

const response = await fetch('~/api', {cache: "force-cache});

• {cache: "force-cache"}
  • 요청의 결과를 무조건 캐싱합니다.
  • 한번 호출 된 이후에는 다시는 호출되지 않습니다.
• {cache: "no-store"}
  • 기본값으로, 데이터 페칭의 결과를 저장하지 않습니다.
  • 캐싱을 아예 하지 않아 매번 데이터를 요청합니다.
• {next: {revalidate: 3}}
  • 특정 시간을 주기로 캐시를 업데이트합니다.
  • 마치 Page Router의 ISR방식과 비슷하다고 생각하면 됩니다.
• {next: {tags: ['a']}}
  • on-Demand Revalidate
  • 요청이 들어왔을 때 데이터를 최신화하는 방식입니다.

예시

책 리스트 불러오는 API로 예시를 살펴보도록 하겠습니다!

async function AllBooks() {
  const response = await fetch(
    `${process.env.NEXT_PUBLIC_API_SERVER_URL}/book`,
    { cache: "no-store" } // 이 부분을 원하는 캐시 옵션으로 설정합니다!
  );
  if (!response.ok) {
    return <div>오류가 발생했습니다...</div>;
  }
  const allBooks: BookData[] = await response.json();

  return (
    <div>
      {allBooks.map((book) => (
        <BookItem key={book.id} {...book} />
      ))}
    </div>
  );
}

export default function Home() {
  return (
    <div>
      <section>
        <h3>등록된 모든 도서</h3>
        <AllBooks />
      </section>
    </div>
  );
}

• {cache: "force-cache"} 로 설정했을 때

• {cache: "no-store"} 로 설정했을 때

3️⃣ 리퀘스트 메모이제이션

마지막으로 리퀘스트 메모이제이션이란 "요청을 기억한다." 라는 뜻으로, 중복된 요청이 발생하지 않도록 캐싱하는 것을 말합니다. 그렇다면 여기서 "데이터 캐시랑 뭐가 다른거지?" 라는 의문을 생길 수 있습니다.

✋🏻 데이터 캐시 VS 리퀘스트 메모이제이션

• 데이터 케시는 백엔드 서버로부터 불러온 데이터를 거의 영구적으로 보관하기 위해 사용됩니다. 따라서 서버 가동중에는 영구적으로 보관됩니다.

• 리퀘스트 메모이제이션은 하나의 페이지를 렌더링 하는 동안에 중복된 API 요청을 캐싱하기 위해 존재합니다. 따라서, 랜더링이 종료되면 모든 캐시가 소멸됩니다.

결론적으로 데이터 캐시는 지속적으로 유지되는 반면, 리퀘스트 메모이제이션은 렌더링 동안에만 유지된다고 정리할 수 있습니다.

🤷🏻‍♀️ 리퀘스트 메모이제이션의 등장 배경

리퀘스트 메모이제이션이 필요한 이유는 서버 컴포넌트의 도입 때문인데요 하나의 페이지에서 컴포넌트가 각각 자신이 필요한 데이터를 페칭하기 때문에 한 페이지에서 서로 다른 컴포넌트에서 동일한 API를 요청하는 경우가 발생할 수 있기 때문입니다.

그리고 리퀘스트 메모이제이션은 Next.js에서 자동으로 제공하는 기능으로 별도의 설정은 필요하지 않습니다!

📚 참고 한 입 크기로 잘라먹는 next.js

1️⃣ CSS-in-JS

CSS-in-JS는 자바스크립트 코드내에서 CSS를 작성하고, 이를 런타임에 동적으로 생성하여 DOM에 삽입하는 방식을 말합니다. 대표적인 라이브러리로는 styled-components와 Emotion 이 있습니다.

랜더링 과정

CSS-in-JS의 경우 브라우저 랜더링 과정을 간략히 나타내면 다음과 같습니다.

1. HTML 파싱 및 DOM 생성 브라우저는 HTML을 파싱하고 DOM을 생성합니다. 2. JS 실행 자바스크립트가 실행되면서 CSS-in-JS 라이브러리가 스타일을 동적으로 생성합니다. 3. CSS 파싱 및 CSSOM 생성 자바스크립트가 실행되면서 CSS 코드가 DOM에 삽입되고, 브라우저는 이를 파싱하여 CSSOM을 생성합니다. 4. 랜더 트리 생성 CSSOM과 DOM을 결합한 렌더 트리를 생성하고, 화면에 콘테츠가 렌더링 됩니다.

Styled-Components

import styled from 'styled-components';

const Button = styled.button`
  background-color: ${props => (props.primary ? 'blue' : 'gray')};
  color: white;
  padding: 10px;
  border-radius: 5px;
`;

function App() {
  return <Button primary={true}>Click me</Button>;
}

• 동적 스타일링 지원 자바스크립트의 로직을 활용하여 동적으로 스타일을 계산할 수 있습니다.
• 컴포넌트 기반 스타일을 컴포넌트와 함께 관리할 수 있어 코드가 더 모듈화되고 관리하기 쉬워집니다.
• 자동 고유 클래스 이름 생성 Styled-components는 각 스타일을 컴포넌트와 연결하고, 이를 고유한 클래스 이름으로 변환하여, 다른 컴포넌트와 스타일 충돌을 방지합니다.

문제점

CSS-in-JS를 SSR 환경에서 사용한다면, 스타일이 초기 렌더링에 누락되는 문제가 발생할 수 있습니다.

SSR 환경에서는 서버에서 HTML을 미리 렌더링해서 클라이언트로 전달하는데요. CSS-in-JS방식에서는 스타일이 JS코드에서 동적으로 생성되기 때문에, 서버 측에서 스타일을 미리 계산해서 HTML에 삽입하지 않으면, 클라이언트에서 JS가 실행되기 전까지 스타일이 적용되지 않습니다.

이로 인해, 클라이언트에서 HTML을 로드한 후, JS가 실행될 때까지 스타일이 적용되지 않은 HTML 페이지가 나타날 수 있습니다.

해결 방법이 궁금하다면 블로그🔽 를 참고해주세요 [Next.js] CSS in JS 사용시 HTML렌더링 시 스타일이 적용되지 않는 문제

2️⃣ 제로 런타임 CSS

제로 런타임 CSS는 스타일을 미리 빌드 타임에 생성하여, 런타임에 자바스크립트가 실행되기 전에 스타일이 완전히 준비된 상태로 제공되는 방식입니다. 대표적으로 Sass, CSS Modules, Vanilla Extract, TailwindCSS 제로 런타임 CSS에 해당합니다.

랜더링 과정

제로 런타임 CSS의 경우 브라우저 랜더링 과정을 간략히 나타내면 다음과 같습니다.

1. HTML 파싱 및 DOM 생성 브라우저는 HTML을 파싱하고 DOM을 생성합니다. 2. CSS 파일 로드 및 CSSOM 생성 빌드 타임에 컴파일된 CSS 파일을 브라우저가 로드하고, 이를 바탕으로 CSSOM을 생성합니다. 3. 렌더 트리 생성 DOM과 CSSOM을 결합하여 렌더 트리를 생성합니다. 4. 레이아웃 계산 및 페인팅 렌더 트리를 바탕으로 레이아웃을 계산하고, 각 요소를 화면에 그립니다.

Tailwind CSS

// TailwindCSS 사용 예시 

<button className="bg-blue-500 text-white p-[10px] rounded-[5px]">
  Click me
</button>

• 빌드 타임 스타일 생성 CSS를 빌드 타임에 미리 생성하여, 런타임에서 추가적인 스타일 계산이 필요하지 않습니다.(JS 실행 없이도 브라우저가 CSS를 바로 적용 가능)
• 유틸리티 클래스 기반 스타일링 미리 정의된 유틸리티 클래스를 조합하여 스타일을 적용할 수 있어 빠른 개발이 가능합니다.
• 최적화된 번들 크기 사용하지 않는 CSS를 빌드 타임에 제거하기 때문에 최종 CSS크기를 최소화할 수 있습니다.(렌더링 성능 최적화)

문제점

동적 스타일링 관리하기가 어렵고, 조건이나 스타일이 복잡해지면 코드가 점점 길어져 가독성에도 불편함을 줄 수 있습니다.

(실제 사용 코드 예시🔽)

3️⃣ 결론

CSS-in-JS와 제로 런타임 CSS의 차이점 정리

특징 | CSS-in-JS | 제로 런타임 CSS | |:---|:---|:---| | 스타일 준비 시점 | 런타임에 자바스크립트 실행 시 동적으로 스타일 생성 | 빌드타임에 스타일을 미리 계산하고 정적 CSS로 제공 | | 성능 | 초기 렌더링 시 스타일 적용이 늦어질 수 있으며, 런타임에 스타일 계산이 필요 | 빠른 초기 렌더링으로 스타일이 즉시 적용됨 | | 유연성 | 자바스크립트 변수나 로직을 사용한 동적 스타일링 가능 | 동적 스타일링에 제한이 있음 | | 스타일 관리 | 컴포넌트와 스타일을 함께 관리 가능 | CSS 파일과 스타일을 별도로 관리하고 최적화 가능 | | 장점 | 컴포넌트화된 스타일링, 동적 스타일링 가능 | 빠른 렌더링, 스타일 최적화 가능, 전통적인 CSS 방식 호환 | | 단점 | 성능 저하, FOUC 가능성, 런타임 의존 | 동적 스타일링에 유연성 부족, 스타일 코드 중복 가능성 |

두개의 차이를 간단히 아래와 같이 정리할 수 있을 것 같습니다.

CSS-in-JS는 동적이고 유연한 스타일링을 제공하지만, 초기 렌더링 성능에서 다소 불리할 수 있다. 제로 런타임 CSS는 빠른 렌더링을 가능하게 하지만, 동적 스타일링에는 한계가 있다.

둘중에 뭐가 더 좋다 라기 보다는 각 방식의 장단점을 고려해서 사용하는 프로젝트와 요구사항에 맞는 방법을 선택하는게 좋을 것 같습니다! 👍🏻

참고 [블로그] Zero RunTime CSS-in-JS에 대해 알아보자

먼저 Next/Image가 웹 성능 최적화를 위해 사용된다는 점은 알고 계실 텐데요, 그렇다면 웹 성능 최적화란 무엇인지, 그리고 이미지가 웹 성능과 왜 연관이 있는지 간단히 짚고 넘어가겠습니다!

웹 성능 최적화란?

웹 성능 최적화는 사용자가 웹사이트에 방문했을 때 최대한 빠르고 원활하게 페이지를 로드하고 인터렉션이 자연스럽게 개선하는 과정을 말합니다. 속도가 빨라야 사용자가 서비스를 이용하는데 불편함이 없을 것고 사용자가 많아야 SEO에도 더 좋겠죠?

이미지 최적화

웹 성능 최적화를 위해서는 이미지 최적화를 뺴놓을 수 없습니다. 이유는 아래와 같습니다.

1. 이미지 차지 비중

• 일반적으로 웹 페이지의 50~80% 용량이 이미지입니다.
• 이미지 최적화를 통해 페이지 크기를 줄이면 로딩 속도를 획기적으로 개선할 수 있습니다.

2. 네트워크 비용 절감

• 최적화된 이미지는 더 작은 크기로 전송되므로, 사용자 데이터 소모를 줄이고 네트워크 비용을 절감할 수 있습니다.

3. 레이아웃 안정성 확보

• 최적화되지 않은 이미지는 로드 중 레이아웃 이동(CLS)을 유발해 사용자 경험을 저하시킬 수 있습니다. 하지만, 최적화 과정에서 이미지 크기를 미리 정의하면 이런 문제를 방지할 수 있습니다.

4. 최적화된 포맷 제공

• WebP와 같은 최신 이미지 표맷은 동일한 화질을 유지하면서도 파일 크기를 줄일 수 있습니다. 일반적인 JPEG나 PNG 대비 25~34% 더 작은 크기를 제공합니다!

<img> 의 한계

1. 이미지 최적화를 수동으로 처리해야 함

• <img>는 브라우저가 제공한 이미지를 그대로 로드합니다.
• 화면 크기와 해상도에 따라 다른 이미지를 제공하려면 개발자가 직접 미디어 쿼리를 작성하거나 이미지를 별도로 준비해야 합니다.

2. Lazy Loading을 기본적으로 지원하지 않음

• loading="lazy" 속성을 추가하면 브라우저에서 Lazy Loading이 가능하지만, 모든 브라우저에서 지원하지 않거나 추가 설정이 필요합니다.

3. 포맷 변환 기능 없음

• WebP, AVIF 등 최신 포맷으로 변환하려면 별도의 이미지 처리 도구나 CDN 서비스를 사용해야 합니다.

4. CLS(누적 레이아웃 이동) 문제

• <img>는 이미지 로드 전에 크기 정보를 제공하지 않아, 로딩 도중 레이아웃 이동이 발생할 수 있습니다.

Next/Image 컴포넌트

Next/Image는 성능 최적화의 핵심적인 역할을 합니다. Next.js 공식 문서에서는 Next/Image에 대해서 다음과 같이 소개하고 있습니다.

Next.js Image 구성 요소는 HTML <img> 요소를 확장하여 자동 이미지 최적화 기능을 제공합니다:

• 사이즈 최적화: 각 디바이스에 맞는 크기의 이미지를 자동으로 제공하며, WebP와 AVIF와 같은 최신 이미지 포맷을 사용하여 성능을 최적화합니다.
• 시각적 안정성: 이미지를 로드할 때 레이아웃 이동을 자동으로 방지하여 화면이 안정적으로 표시됩니다.
• 빠른 페이지 로딩: 이미지는 뷰포트에 들어올 때만 로드되며, 기본적으로 브라우저의 Lazy Loading을 사용합니다. 또한, 블러 효과로 로드가 완료될 때까지 잠깐의 placeholder 이미지를 표시할 수 있습니다.
• 유연성: 원격 서버에 저장된 이미지도 필요에 따라 크기를 조정할 수 있어, 다양한 상황에 맞는 유연한 이미지 처리가 가능합니다.

Next/Image에서 제공하는 대표 기능은 다음과 같습니다.

Lazy Loading

Lazy Loading은 사용자가 이미지를 보게 될 때까지 이미지를 로드하지 않고, 스크롤을 통해 이미지가 뷰포트에 들어올 때에만 이미지를 로드하는 기술입니다. 이렇게 하면 페이지가 처음 로드될 때 불필요한 이미지 로딩을 피할 수 있어 초기 로딩 속도를 대폭 향상시킬 수 있습니다.

만약, 중요한 이미지 일부에 lazy loading을 적용하고 싶지 않은 경우에는 해당 기능을 끌 수도 있습니다. Image 컴포넌트의 priority라는 prop을 true로 설정하거나, loading prop에 “eager” 값을 설정하면 됩니다. (priorty 값을 설정하는 것이 더 권장되는 방식입니다.)

이미지 사이즈 최적화

이미지 사이즈 최적화는 사용하는 화면 크기와 디바이스의 해상도에 맞게 이미지를 적절히 조정하여 성능을 개선하는 기술입니다. 이는 파일 크기를 줄여 로딩 속도를 개선하고, 다양한 디바이스에서 최적화된 이미지를 제공합니다.

layout 속성(intrinsic, responsive, fill)을 통해 이미지 크기를 반응형으로 설정할 수 있습니다. 이 방식은 페이지 크기나 화면 크기에 맞춰 이미지 크기를 자동으로 조정합니다.

Next.js는 WebP와 같은 최신 이미지 포맷을 자동으로 제공하여 더 작은 파일 크기로 전송합니다. WebP는 동일한 품질의 이미지에 대해 JPEG보다 30% 이상 더 작은 파일 크기를 제공합니다.

Placeholder 제공

Next/Image는 이미지를 로드할 때 blur-up 효과를 제공합니다. 이미지가 로드되는 동안, 저해상도 이미지가 먼저 표시되고, 이후 고해상도 이미지가 로드되면 자연스럽게 교체됩니다. 또한, 이미지 로딩이 끝나기 전에도 화면에 흰 공간이나 빈 곳이 아닌, 로딩 중인 이미지를 표시함으로써 누적 레이아웃 이동(CLS)을 방지할 수 있습니다.

placeholder="blur" 속성을 사용하면 이 기능을 활성화할 수 있습니다.

내가 느낀 Next/Image 장단점

장점

자동으로 최적화된 이미지를 제공하여, 추가적인 설정이나 라이브러리 없이도 성능을 향상시킬 수 있습니다. 웹 성능을 높이기 위한 여러 가지 기능들이 기본적으로 내장되어 있어, 직접 최적화 옵션을 고민하거나 설정할 필요가 없어서 작업할 때 편리했던 것 같습니다.

단점

개인적으로 저는 항상 사용할 때마다 속성에 대한 설정이 헷갈렸습니다...ㅎㅎ

<img> 같은 경우는 직접 사이즈를 넣어주면 그만인데 Next/Image 는 설정해줘야할 속성들이 있고 그것이 어떤 것들인지에 대해도 다 알고있어야 했습니다.

특히 가장 헷갈렸던 것이 layout 속성이었습니다. layout 속성에는 fixed, intrinsic, responsive, fill과 같은 옵션이 있는데, 잘못된 값을 설정해서 이미지가 의도하지 않게 왜곡되거나 크기가 너무 커지는 문제를 겪기도 했습니다😅

그리고 layout 속성에 따라서 width와 height 속성의 의미도 달라진다는 점도 새롭게 알게 되었습니다.

• intrinsic은 원본 이미지 비율을 유지하면서 크기 조정.
• fixed는 설정한 크기로 정확히 표시.
• responsive는 width와 height로 비율을 정의하고, 화면 크기에 맞게 크기를 조정.
• fill은 width와 height가 설정되지 않고, 부모 컨테이너의 크기에 맞춰 이미지가 채워짐.

결론

쓰다 보니 장점보다 단점이 길어졌는데, 사실 단점이라기보다는 잘 몰라서 쓰기 어려웠던 개인적인 헤프닝이었던 것 같습니다ㅎㅎ

평소에 Next/Image를 사용하면서 <img>를 쓰지 않고 굳이 Next/Image를 써야 하는 이유와 성능 최적화에서의 차이가 얼마나 큰지 궁금했었는데, 이렇게 글로 정리하면서 그 궁금증을 조금 해소할 수 있었던 것 같습니다~!

다음 작업에서는 무작정 사용하는 것이 아닌, 성능 차이를 비교하면서 직접 눈으로 확인하고 진행해 봐야겠다는 생각이 듭니다.

📚 참고 Next/Image를 활용한 이미지 최적화 NEXT.JS의 이미지 최적화는 어떻게 동작하는가?

문제

스토리북 초기 세팅을 마치고 본격적인 컴포넌트 작업에 앞서, Foundation(Colors, Fonts, 여백 등)을 설명하는 문서를 작성하고 싶었습니다. 피그마에 이미 관련 자료가 정리되어 있지만, 개발과 디자인 모두가 디자인 시스템 관련 내용을 한눈에 확인할 수 있는 문서를 스토리북에 통합하면 훨씬 효율적일 거라고 판단했습니다.

그래서 MDX 파일을 활용해 문서를 작성하려고 했습니다. 그런데 파일을 작성 후 실행하자마자 아래와 같은 오류를 만났습니다.

Error: Unable to index ./src/stories/Color.stories.mdx:

스토리북에서 Color.stories.mdx 파일을 읽지 못한다는 오류였고, 랜더링에 실패했습니다. 몇 시간 동안 헤매며 다양한 설정을 점검했지만, 결국 문제는 파일 확장자와 스토리북의 역할 분리에 대한 이해 부족에서 비롯되었습니다. 😅

원인 및 해결 방법

원인 분석

최신 스토리북(8.0 이상)에서는 .mdx와 .stories.mdx 파일의 역할이 명확히 분리되었습니다:

• .mdx 파일: 독립적인 문서 페이지용으로 사용. 컴포넌트와 관계없는 문서화를 위해 작성.
• .stories.mdx 파일: 스토리와 문서를 함께 정의하기 위한 파일. 하지만 최신 스토리북에서는 기본 지원이 중단됨.
• .stories.ts 파일: 컴포넌트의 스토리를 정의하는 데 사용. CSF(Component Story Format) 기반.

제가 작성한 Color.stories.mdx 파일은 최신 스토리북에서는 적합하지 않은 구조였고, 파일 역할과 설정이 일치하지 않아 오류가 발생한 것이었습니다.

해결 방법

최종적으로 mdx 파일을 제대로 랜더링하기 위해서 아래와 같은 작업을 수행했습니다.

1. main.ts 설정 스토리북에서 mdx 파일을 올바르게 읽을 수 있도록 main.ts 파일의 stories 설정을 수정했습니다.

const config = {
  stories: [
    "../src/**/*.mdx", // 문서화용 MDX 파일 추가
    "../src/**/*.stories.@(js|jsx|ts|tsx)" // 스토리용 파일
  ],
  addons: [
    "@storybook/addon-docs", // 문서화 애드온
    "@storybook/addon-essentials",
  ],
  framework: {
    name: "@storybook/react-vite",
    options: {},
  },
  core: {
    builder: "@storybook/builder-vite",
  },
};
export default config;

2. 필수 패키지 설치 최신 스토리북에서는 mdx3를 사용하기 때문에 필요한 패키지를 설치했습니다.

npm install @storybook/react-vite @storybook/addon-docs @mdx-js/react @mdx-js/rollup --save-dev

3. 파일 확장자 수정 스토리북의 역할 분리에 따라 Color.stories.mdx 파일을 Color.mdx로 이름 변경 후 문서화 페이지로 활용했습니다.

컴포넌트 스토리는 별도의 .stories.ts 파일에서 정의합니다.

4. mdx 파일 작성 아래는 테스트를 위해 예시로 작성한 파일이니 참고 부탁드립니당🥸

import { Meta } from "@storybook/addon-docs";

<Meta title="Foundation/Colors" />

# 색상 팔레트

디자인 시스템에서 사용되는 색상들을 소개합니다. 이 색상들은 컴포넌트의 속성으로 사용됩니다.

## 기본 색상

| 색상 이름 | 색상 코드 |
| --------- | --------- |
| Primary   | #007bff   |
| Secondary | #6c757d   |
| Success   | #28a745   |
| Danger    | #dc3545   |
| Warning   | #ffc107   |
| Info      | #17a2b8   |
| Light     | #f8f9fa   |
| Dark      | #343a40   |

## 강조 색상

이 색상들은 UI의 주요 액션이나 강조에 사용됩니다.

| 색상 이름 | 색상 코드 |
| --------- | --------- |
| Accent    | #ff5733   |
| Highlight | #00c853   |

마무리

이번 오류를 통해 공식 문서를 꼼꼼히 확인하는 것의 중요성을 다시 한번 깨달았습니다! 버전 업데이트와 함께 제공되는 공식 문서를 확인하고, 새로운 규칙과 사용법에 빠르게 적응하는 것도 개발자로서 중요한 역량이라는 점을 느꼈습니다.

앞으로도 문제를 만났을 때 기본 설정부터 차근차근 점검하고, 공식 문서와 커뮤니티 리소스를 활용하는 습관을 이어가야겠습니다. 😊

참고

MDX | Storybook docs

TBD

TBD 전략이란?

TBD(Trunk-Based Development) 전략은 모든 개발자가 하나의 main 브랜치(트렁크)를 중심으로 작업을 진행하는 Git 브랜치 전략입니다. 이 전략에서 중요한 점은 작은 단위로 자주 커밋하고, 개발자가 빠르게 main 브랜치에 병합하는 것입니다.

개발자는 feature 브랜치에서 작업할 수 있지만, 이 브랜치를 오래 유지하지 않고 작은 작업 단위로 main 브랜치에 빠르게 병합합니다. 작업이 완료되면 PR을 생성하여 코드 리뷰를 받으며, 리뷰가 완료된 후 main 브랜치에 병합됩니다. 이러한 프로세스는 가능한 자주 일어나며, 모든 개발자는 최신 main 브랜치를 기반으로 작업을 계속합니다.

TBD 전략을 사용한 이유는?

당시 서비스가 빠르게 성장하고 있었기 때문입니다. 이로 인해 잦은 배포가 이루어졌고, 배포 주기가 정해져 있지 않은 상황에서 기획과 디자인이 완료되면 곧바로 개발에 착수하여, 개발이 끝나는 즉시 운영 서버에 배포하는 방식으로 진행되었습니다.

이러한 방식은 빠르게 기능을 개발하고, 유저의 반응을 확인한 뒤, 이를 기반으로 기능을 수정 및 보완하는 것을 목표로 했습니다. 따라서** 배포 과정에서 복잡한 절차를 줄이고자 했습니다.**

또한, 당시 개발 인원이 많지 않았기 때문에 긴 배포 프로세스가 오히려 비효율적이라고 판단되었습니다. TBD 전략은 작은 단위로 작업을 자주 병합하고, 빠르게 배포할 수 있는 방식을 제공했기 때문에 이러한 요구를 충족시키기에 적합하다고 보아 선택하게 되었습니다.

어떤 문제점이 있었나?

하지만 서비스 안정화와 규모 확장으로 인해 다음과 같은 문제가 발생했습니다.

배포 시기의 불일치

서비스의 규모가 커지고, 장기간 프로젝트, 단기간 작업, 유지보수 작업이 동시에 진행되면서 개발자들 간 배포 시점이 서로 달라지는 상황이 빈번해졌습니다. TBD에서는 모든 작업이 main 브랜치에 자주 병합되기 때문에, 이러한 배포 시기의 불일치는 예기치 않은 충돌이나 의존성 문제를 발생시켰고, 결과적으로 배포 프로세스의 효율성을 저하시켰습니다.

코드 정리 및 유지보수 부담 증가

작업 간 배포 시점의 차이로 인해 이미 배포된 코드와 배포 대기 중인 코드가 동시에 main 브랜치에 존재하는 상황이 생겼습니다. 이로 인해 미사용 코드 정리, 충돌 해결, 배포 이후의 추가적인 수정 작업 등 유지보수에 많은 시간이 소요되었습니다. 이러한 문제는 코드의 복잡성을 증가시키고, 작업 효율성을 저하시키는 결과를 낳았습니다.

git-flow

git-flow 전략이란?

Git-Flow 전략은 소프트웨어 개발에서 효율적인 브랜치 관리와 배포 프로세스를 지원하는 Git 브랜칭 모델입니다. 주요 브랜치로는 main(배포용), develop(개발용), feature(기능 개발), release(배포 준비), hotfix(긴급 수정) 브랜치가 있으며, 각각 명확한 목적과 작업 흐름을 가지고 있습니다.

git-flow 전략을 선택한 이유는?

Git-Flow 전략을 선택한 이유는 작업 유형과 배포 주기를 명확히 분리하여 안정성을 확보하기 위함이었습니다. TBD 전략에서는 작업 간 배포 시점의 불일치로 인해 충돌과 의존성 문제가 발생하고, 배포되지 않은 코드와 배포된 코드가 동시에 main 브랜치에 존재하는 상황이 빈번했기 때문에, 이를 해결할 필요가 있었습니다. Git-Flow는 main, develop, feature, release, hotfix 브랜치를 통해 각 작업의 목적과 배포 프로세스를 명확히 구분하고, 체계적인 관리로 배포 안정성을 높일 수 있어 기존의 문제를 해결하는 데 적합했습니다.

git-flow 를 어떻게 사용했나?

저희 팀은 Git-Flow 전략을 원칙대로 사용하지 않고, 프로젝트 특성과 배포 프로세스에 맞게 변형하여 적용했습니다. 이를 통해 개발 완료와 배포 시기를 유연하게 분리하고, 작업 효율성과 코드 관리를 높였습니다. 아래는 세부적인 브랜치 구조와 사용 방식입니다.

main 브랜치

운영 서버에 배포된 안정된 코드를 관리하는 브랜치입니다. 버그 수정이나 긴급 작업 완료 후 이곳에 병합됩니다.

release 브랜치: 배포 직전

배포 직전 상태의 feature 브랜치들을 모아 관리하는 브랜치입니다. 배포 준비가 완료된 코드는 이 브랜치로 병합되며, 최종적으로 Main 브랜치로 PR을 생성해 배포를 진행합니다.

release에 병합된 feature 브랜치는 삭제하여 브랜치 관리를 간소화합니다.

stage 브랜치: 개발 완료

QA 및 테스트를 위한 브랜치로, 배포 시기와 상관없이 개발이 완료된 feature 브랜치들을 모아 관리합니다.

Release 브랜치와의 차이점

• Stage 브랜치는 개발 완료 시점에 병합되며, 배포 날짜에 구애받지 않습니다.
• 이는 작업 완료와 배포를 분리하여, 긴 QA 과정이 필요한 작업과 즉시 배포 가능한 작업을 구분하기 위함이었습니다.

feature 브랜치 : 기능 개발

각 기능 개발을 위한 브랜치로, 작업이 완료되면 stage 브랜치로 병합하고 QA를 진행합니다. QA가 완료되고 배포 시점이 다가오면, release 브랜치로 병합합니다.

bugfix 브랜치 : 오류 수정

운영 중 발생한 버그나 긴급 CS 이슈를 해결하기 위한 브랜치입니다. 작업 완료 후 main 브랜치로 PR을 생성해 바로 병합하고, 이후 main 브랜치와 release 브랜치를 동기화하여 배포 상태를 유지합니다.

refactor 브랜치: 코드 개선

*코드 리팩토링 *작업을 위한 브랜치입니다.

Squash Merge 사용

feature 브랜치를 release 브랜치로 병합할 때는 Squash Merge를 사용했습니다.

• 커밋 기록의 간결화 Squash Merge는 작업 과정을 한 번에 합쳐 하나의 커밋으로 병합하기 때문에, 불필요한 커밋 로그를 줄이고 히스토리를 깔끔하게 유지할 수 있습니다.

• PR 리뷰 과정 간소화 커밋 수가 많을 경우 PR 리뷰가 복잡해질 수 있지만, Squash Merge를 통해 PR을 단일 작업 단위로 처리할 수 있습니다.

• 코드베이스 관리 효율성 병합 이후 각 브랜치의 기록을 단순화하여, Git 히스토리를 추적하거나 문제가 발생했을 때 디버깅을 쉽게 할 수 있습니다.

마무리

TBD 전략은 초기에는 빠르고 간소화된 배포 프로세스를 지원해 효과적이었지만, 서비스가 성장하고 팀 규모와 작업 범위가 확대되면서 여러 문제들이 발견됐습니다. 이러 문제를 해결하기 위해 Git-Flow 전략을 프로젝트에 맞게 변형하여 도입함으로써 작업과 배포를 명확히 분리하고 효율성을 높일 수 있었던 것 같습니다!

비록 전보다 지켜야하는 규칙과 관리해야하는 브랜치들이 많아지기는 했지만, 빠르고 간편한게 무조건 좋은 것 만은 아니라는 것도 깨달았습니다!ㅎㅎ 이번 경험을 통해 프로젝트 환경과 팀의 요구에 따라 브랜치 전략을 유연하게 조정하는 것이 중요하다는 것을 배울 수 있었습니다. 이런 시행착오를 통해 더 발전할 수 있을거라고 믿으며 우리 모두 상황에 맞는 브랜치 전략을 선택합시다~ ! 🙌🏻

제가 소개할 합성 컴포넌트는 feature 컴포넌트에 속해있는 컴포넌트 중 하나입니다. 이번 포스팅에서는 합성 컴포넌트란 무엇이고, 합성 컴포넌트를 적용한 과정에 대해서 소개해보려고 합니다.

ASIS 컴포넌트

오늘 다룰 컴포넌트는 책 UI를 나타내는 컴포넌트입니다. (편의상 Book컴포넌트라고 부르겠습니다!) API를 호출해서 책에 대한 정보(책 이미지, 책 이름, 출판사 이름, 책 플래그)를 받아오고 이를 UI에 맞게 배치해서 보여줍니다.

위와 같은 Book 컴포넌트를 구현하기 위한 코드는 아래와 같습니다. (이해를 돕기 위한 예시로 생략된 부분이 있으니 참고해서 봐주세요!)

import Text from "components/common/text"
import Flag from "components/common/flag"
import OriginalBook from "components/features/original/book"
import OriginalBookImage from "components/features/original/book/image"
import OriginalBook from "components/features/original/book/caption"
import MySchoolBookImage from "components/features/original/book/svg/image"


const BookList = () => {
      ...

    return (
      ...

                {gerOriginalSchoolBookListResponse.data.book_list.map((item, index) => {
              return (
                <OriginalBook
                  key={item.id}
                  onClick={() => onClickBookItem(item.id)}
                >
                  {/* 책 이미지 png 파일 */}
                  {item.thumbnail_url && <OriginalBookImage src={item.thumbnail_url} />}
                    {/* 책 이미지 svg 파일 */}
                  {item.my_school_thumbnail_detail && (
                    <MySchoolBookImage schoolName={schoolName} subsubjectName={item.subsubject_name} colorDetail={item.my_school_thumbnail_detail} />
                  )}
                  {/* 책 출판사 */}
                  {item.school_publisher_name && (
                    <Text type="caption2" color="gray_400">
                      {item.school_publisher_name}
                    </Text>
                  )}
                  {/* 책 이름 */}
                  <OriginalBookCaption>{item.name}</OriginalBookCaption>
                  {!AuthOriginalActive?.is_active && item.is_trial && <Flag type="book">이 달의 무료 문제집</Flag>}
                   {/* 책 플래그 */}
                  {!isOpen(item.opened_at) && (
                    <Flag type="book" color="blue_400">
                      {getMonth(item.opened_at)} 말 OPEN 예정
                    </Flag>
                  )}
                </OriginalBook>
              )
            })}

     ...

    )
}

이해를 돕기 위해 위 코드에 대해서 간단히 설명하자면

• gerOriginalSchoolBookListResponse 는 책에 대한 정보를 갖고 있는 API response 값 입니다.
• <OriginalBook /> 은 <OriginalImage /> , <OriginalCaption /> 등 책을 구성하는데 필요한 요소들을 자식으로 받는 부모 컴포넌트입니다.
• <OriginalImage /> 은 책의 png 이미지를 나타내는 컴포넌트 입니다.
• <OriginalCaption /> 은 책의 이름을 나타내는 컴포넌트 입니다.
• <MySchoolBookImage /> 은 책의 svg 이미지를 랜더링 해주는 컴포넌트 입니다.
• <Flag /> 는 책의 플래그(9월 말 오픈예정 등)를 나타내는 공용 컴포넌트 입니다.
• <Text /> 는 출판사 이름을 나타내는 공용 컴포넌트 입니다.

문제점

위와 같은 방식으로 컴포넌트를 구성했을 때 제가 느꼈던 문제점은 아래와 같습니다.

1. 매번 <OriginalBook>, <OriginalBookImage>, <OriginalBookCaption> 을 각각 import 해야합니다.
2. <OriginalBookCaption> 을 사용 기준이 개발자마다 다릅니다.
   • <OriginalBookCaption> props로 이름을 받는게 아니라 children으로 받고 있어서 누구는 책 이름, 책 출판사까지 포함하고, 누구는 책 이름까지만 포함시키고 책 출판사는 따로 추가하는 방식으로 사용되어 협업시 혼란을 주고 있습니다.
3. <OriginalBookImage> 은 현재 png 파일만 받고 있어서 svg 파일의 경우 각각 페이지마다 해당 컴포넌트 <MySchoolBookImage> 를 import 해서 추가해야 합니다.
4. 책 플래그(이 달의 무료 문제집, 오픈예정, 내신연구소 단독)를 표시해주려면 매번 <Flag> 컴포넌트를 import 해서 추가해야 합니다.
5. 모든 response 값에 대해서 그 값이 존재하는지 아닌지에 대해서 체크를 하는 로직이 매번 필요합니다.

개선점

1. Book 컴포넌트를 구성하기 위한 요소들을 각각 import 하지 않고 한번만 import해서 사용 할 수 있도록 합니다.
2. 각 컴포넌트의 기준을 정확하게 정의하여 개발자가 사용하는데 있어 혼란을 줄입니다.
3. 컴포넌트의 사용 여부(보여지고 안보여지고)에 대한 로직은 컴포넌트를 import하는 페이지에서 처리하는 것이 아닌 해당 컴포넌트에서 처리하도록 합니다.

TOBE 컴포넌트

위에 개선점을 반영시키기 위한 방법을 찾아보다가 합성 컴포넌트에 대해서 알게 되었고 제가 하려고 하는 방향성과 맞다고 판단되어 적용하게 되었습니다. 먼저 합성 컴포넌트에 대해서 간단히 소개하도록 하겠습니다.

합성 컴포넌트란?

합성 컴포넌트는 하나의 컴포넌트를 여러 가지 집합체로 분리한 뒤, 분리된 각 컴포넌트를 사용하는 쪽에서 조합해서 사용하는 컴포넌트 패턴을 의미합니다.

간단한 예시로 html의 select를 볼 수 있는데, select는 <select>와 <option> 태그의 조합으로 이루어집니다. <select>와 <option>은 각각 독립적으로는 큰 의미가 없지만 사용하는 곳에서 이를 조합해 사용함으로써 화면에 의미 있는 요소가 됩니다.

<select>
  <option value="1">Option 1</option>
  <option value="2">Option 2</option>
</select>

구현하기

합성 컴포넌트 패턴을 적용한 예시를 위해 각각의 컴포넌트들의 상세한 props 와 로직들은 포함되어 있지 않으니 이 점 참고해서 봐주세요!

1. 서브 컴포넌트

html의 <option> 태그에 해당하는 서브 컴포넌트를 구현합니다. Book 컴포넌트를 구성하는 각각의 컴포넌트들이 여기에 해당합니다. <BookImage> <BookCaption> <BookFlag>

2. 메인 컴포넌트

html의 <select> 태그에 해당하는 메인 컴포넌트를 구현합니다. 서브 컴포넌트들을 묶어서 화면에 적잘하게 보이도록 하는 Wrapper 성격의 컴포넌트입니다.

import styled from "@emotion/styled"
import {ClickMotion} from "@repo/ui"

export interface OriginalBookGroupProps extends OriginalBookContextValue {
  children: React.ReactNode
  onClick?: () => void
}

export type Props = OriginalBookGroupProps & HTMLAttributes<HTMLDivElement>

export const OriginalBookGroup: React.FC<Props> = ({children, onClick, ...props}) => {

  return (
      <ClickMotion onClick={onClick}>
        <Wrapper {...props}>
          {children}
        </Wrapper>
      </ClickMotion>
  )
}

const Wrapper = styled.div<{width?: string}>`
  position: relative;
  display: flex;
  flex-direction: column;
  gap: 8px;
`

위처럼 작성하면 children으로 들어오는 서브 컴포넌트들을 받을 수 있고 순서대로 배치 할 수 있습니다.

3. 메인 & 서브를 묶어서 export하기

이렇게 구현된 컴포넌트들을 묶어서 export하면 각각의 컴포넌트가 Book의 서브 컴포넌트임을 좀 더 확실하게 할 수 있어 코드의 가독성에 도움이 될 수 있습니다.

import {OriginalBookGroup} from "./group"
import {OriginalBookImage} from "./image"
import {OriginalBookCaption} from "./caption"
import {OriginalBookFlag} from "./flag"

export const OriginalBook = Object.assign(OriginalBookGroup, {
  Image: OriginalBookImage,
  Caption: OriginalBookCaption,
  Flag: OriginalBookFlag
})

4. 결과

import { OriginalBook } from "components/features/original/book"


const BookList = () => {
      ...

    return (
      ...
            {gerOriginalSchoolBookListResponse.data.book_list.map((item, index) => (
              <OriginalBook key={item.id} onClick={() => onClickBookItem(item.id)}>
                <OriginalBook.Flag isTrial={item.is_trial} isLms={item.is_lms_exclusive} openedAt={item.opened_at} />
                <OriginalBook.Image
                  pngUrl={item.thumbnail_url}
                  svgColorInfo={item.my_school_thumbnail_detail}
                  subsubjectName={item.subsubject_name}
                />
                <OriginalBook.Caption bookName={item.name} publisherName={item.school_publisher_name} />
              </OriginalBook>
            ))}

     ...

    )
}

문서화하기

위에 개선점 중에 하나인 개발자들이 컴포넌트를 사용할 때 혼동을 줄이기 위해서는 컴포넌트에 대한 문서자료가 필요했습니다. 컴포넌트를 문서화하는 도구에는 스토리북과 같은 라이브러리들이 존재하지만 바로 도입하기에는 러닝커브가 있다는 것을 고려하여 일단 피그마에 정리해서 팀원들에게 공유했습니다.

마무리

컴포넌트 개선 후 이전보다 간단해진 코드를 보면서 뿌듯함을 느꼈다. 이 점이 리팩토링하는 큰 이유 중 하나인 것 같다. 처음 합성 컴포넌트 개념에 대해서 접했을 때는 잘 이해가 가지 않았는데 내가 실제로 컴포넌트에 적용할 목적으로 계속 보다 보니 이해하기가 수월했던 것 같다. 역시 나는 실제로 내가 부딪혀봐야 아는 것 같다!ㅎㅎ

컴포넌트 개발은 항상 처음 시작할 때는 이 정도는 금방 하겠지? 라는 마음으로 시작하는데 하다 보면 어려운 점이 생겨서 길게 고민하게 되는 것 같다. 근데 나는 이런 고민하는 시간이 나쁘지만은 않은 것 같다. 이런 고민을 통해서 컴포넌트가 단순히 기능이나 UI 단위로 쪼개놓기만 한 것이 아니라 진짜 효율적인 개발을 위한 수준 높은 컴포넌트가 될 수 있는 과정이라는 생각이 들기 때문이다. 그리고 내가 개발한 컴포넌트를 다른 개발자들이 편하게 쓰고 일관된 코드와 UI를 보면 그때만큼 또 뿌듯한 게없는 것같다!ㅋㅋㅋ

이번 컴포넌트 개선을 하면서 아쉬웠던 점은 문서화 부분이다. 예전에 스토리북을 도입하려고 했었는데 그 당시 다른 기능 개발에 우선순위가 밀려서 제대로 도입하지 못했었다. 이제 컴포넌트가 점점 많아지면서 문서화의 필요성에 대해서 크게 느끼고 있다. 하루빨리 스토리북을 제대로 도입해서 제대로 된 디자인시스템을 구축하고 싶다!

📚 참고

합성 컴포넌트로 재사용성 극대화하기

처음에는 웹뷰를 통한 개발 방식이 쉽게 이해가지 않았었는데 이제는 익숙해지기도 했고 혹시 예전에 나처럼 웹뷰 개발에 대해서 궁금하거나 어려운 사람들을 위해서 정리해보고자 한다! ✨

1. 웹뷰란?

웹뷰는 모바일 어플리케이션에서 웹 콘텐츠(웹 페이지)를 표시하는 컴포넌트이다. 네이티브 앱 내부에 HTML, CSS, Javascript 로 작성된 웹 페이지를 렌더링하는 방식으로 주로 네이티브와 웹을 혼합한 하이브리드 앱에서 많이 사용된다.

우리 회사같은 경우에는 앱 내부의 모든 페이지 및 기능들을 Next.js로 개발하고 있다. 즉, 개발 방식은 웹 개발과 동일하며 Next.js로 개발한 웹페이지를(URL) 웹뷰를 통해 보여준다.

react-native-webview

react-native에서 웹뷰를 사용하기 위해서는 react-native-webview 라이브러리가 필요하다. react-native 초기 버전에는 WebView 가 내장된 컴포넌트였으나, 현재는 별도의 패키지로 분리되어 react-native-webview 라는 이름으로 제공되고 있다.

이 라이브러리를 통해서 웹 페이지와 네이티브 앱 간의 통신과 상호작용을 관리할 수 있다. 간단한 예시 코드를 통해 기본 구조를 살펴보자.

WebView 컴포넌트에서 제공하는 옵션은 매우 많지만 가장 기본으로 알고 있어야 하는 두가지 정도만 소개하려고 한다.

import React from 'react';
import { WebView } from 'react-native-webview';

const MyWebView = () => {

  const handleMessage = (event) => {
    alert("Message from WebView: " + event.nativeEvent.data);
  };

  return (
    <WebView 
      source={{ uri: "https://example.com" }} 
        onMessage={handleMessage}
    />
  );
};

export default MyWebView;

• source
  • 웹뷰에서 로드할 콘텐츠를 지정하는 옵션이다.
  • URL을 전달하면 해당 웹 페이지가 웹뷰 내에서 랜더링된다.
• onMessage
  • 웹 페이지와 네이트브 앱 간의 통신을 처리하는 옵션이다.
  • 웹뷰에서 수신한 메세지를 처리합니다. 웹 페이지에서 Javascript로 메세지를 전송하면 해당 함수가 호출된다. (자세한 예시는 아래에서 살펴보도록 할게요)

2. 웹뷰 통신이 필요할 때는?

웹에서는 제공하지 않는 앱에서만 제공하는 기능을 필요할 때 웹뷰 통신을 한다. 내가 경험했던 것을 예로 들자면 모달에서 흔히 볼 수 있는 1일 동안 보지 않기 , 알림 설정 허용/거부 등 여러가지 기능이 존재한다. 이런 기능들은 일반적인 웹 페이지에서는 구현할 수 없고 네이티브 기능을 직접 활용해야하기 때문에 네이티브 코드에서 처리한 후 그 결과를 웹 페이지로 다시 전달해야한다.

이런 네이티브 기능은 실제 디바이스나 시뮬레이터에서만 확인할 수 있기 때문에 개발 중에는 시뮬레이터를 통해 테스트를 진행하며 통신이 올바르게 이루어지는지 확인하는 것이 중요하다.

3. 예시 코드

웹뷰 통신을 할때는 위에서 언급했던 react-native-webview를 통해서 할 수 있다. 이해를 돕기 위해서 자세한 예시를 살펴보도록 하자.

asyncStorage

asyncStorage 는 내가 웹뷰 통신에서 가장 자주 사용하는 기능이다. 이름부터 감이 오겠지만 웹에서의 localStorage와 같은 역할을 한다고 생각하면 된다.

웹에서 클라이언트단에서 어떠한 정보를 임시로 저장해야할 때 사용하는 곳이 localStorage인데 앱에서도 어떠한 정보를 디바이스에 저장해야할 때 사용하는 것이 asyncStorage이다. localStorage 처럼 Key 와 value 값으로 이루어져 저장하고 수정하고 삭제할 수 있다.

asyncStorage가 필요한 경우는 다양하지만 대표적으로 다시 보지 않기 가 있다.

이해를 돕기위한 예제 코드로 생략된 부분이 있을 수 있으니 이 점 참고해주세요

1. Next.js -> RN으로 데이터 보내기

// Next.js

const EventModal = () => {

    // react native 로 메세지 전송
    const handleClickClose = () => {
       window.ReactNativeWebView.postMessage("hideOneDay")
    }  


    return (
        <div>
           ...
           <button onClick={handleClickClose}>다시 보지 않기</button>
        </div>
    )

}

export default EventModal

• window.ReactNativeWebView.postMessage("hideOneDay")를 호출하여, 웹 페이지에서 React Native 웹뷰로 "hideOneDay"라는 메세지를 전달한다.
• 이 메세지는 React Native 애플리케이션으로 전달되어 특정 동작(예: "다시 보지 않기" 설정)을 트리거하게 된다.

2. RN에서 수신된 데이터 저장하기

// React Native

import { WebView } from 'react-native-webview';
import AsyncStorage from '@react-native-async-storage/async-storage';

const App = () => {

  // 웹뷰에서 받은 메시지 처리
  const handleMessage = async (event) => {
    const message = event.nativeEvent.data;
    if (message === "hideOneDay") {
      try {
        // AsyncStorage에 데이터 저장
        await AsyncStorage.setItem("hideOneDay", "true");
        alert("모달을 다시 보지 않도록 설정이 완료되었습니다.");
      } catch (error) {
        console.error("Error saving data to AsyncStorage", error);
      }
    }
  };

  return (
   <WebView 
      source={{ uri: "https://example.com"}} 
      onMessage={handleMessage}
    />
  )
}


export default App

• handleMessage를 통해서 수신된 메세지를 처리한다.
  • event.nativeEvent.data를 통해 수신된 메시지를 확인하고, 메시지가 "hideOneDay"일 때, AsyncStorage에 "hideOneDay" 키로 "true" 값을 저장하게 된다.
• 정상적으로 저장에 성공하면 alert이 노출된다.

3. RN에서 저장된 데이터 불러오기

// React Native

import { WebView } from 'react-native-webview';
import AsyncStorage from '@react-native-async-storage/async-storage';

const App = () => {
  const webViewRef = useRef(null);

  ...

  // 저장된 데이터 불러와 웹뷰로 전송
  useEffect(() => {
      const checkAsyncStorage = async () => {
       try {
        const hideOneDay = await AsyncStorage.getItem("hideOneDay");

        if (hideOneDay === 'true' && webViewRef.current) {
          // 저장된 데이터가 있으면 웹뷰로 메시지 전송
          webViewRef.current.postMessage("hideModal");
        }
      } catch (error) {
        console.error('Error retrieving data from AsyncStorage', error);
      }
    };

    checkAsyncStorage();
  }, [])

  return (
   <WebView 
      ref={webViewRef}
      source={{ uri: "https://example.com"}} 
      onMessage={handleMessage}
    />
  )
}


export default App

• webViewRef 설정을 통해서 웹뷰에 직접 접근할 수 있다.
• useEffect를 통해 checkAsyncStorage 함수가 실행되고 AsyncStorage 에서 "hideOneDay" 값을 불러온다. 만약 true로 설정되어 있으면 webViewRef.current.postMessage("hideModal") 로 호출하여 웹뷰로 "hideModal" 을 전송하며 이를 통해 웹 페이지에서 모달을 숨길 수 있다.

4. Next.js에서 모달 숨기기

import EventModal from "./EventModal"

const Home = () => {

  // 모달의 표시 여부를 상태로 관리
  const [isModalVisible, setModalVisible] = useState(true);

  useEffect(() => {
    const handleMessage = (event: MessageEvent) => {
      // 메시지 내용 확인
      if (event.data === "hideModal") {
        // 모달 숨기기
        setModalVisible(false);
      }
    };

    // 메시지 이벤트 리스너 등록
    window.addEventListener("message", handleMessage);

    // 컴포넌트 언마운트 시 이벤트 리스너 제거
    return () => {
      window.removeEventListener("message", handleMessage);
    };
  }, []);

    return (
     <div>
        {isModalVisible && <EventModal />}
           <h1>메인 페이지</h1>
      </div>
    )
}

export default Home

• useEffect를 통해 페이지가 랜더링되면 window.addEventListener("message", handleMessage) 를 호출하고 handleMessage 함수를 통해 "hideModal" 메세지를 받으면 isModalVisible 상태값을 업데이트 시켜 모달을 숨긴다.

4. 마무리

입사하고 같이 취업을 준비하던 동기들을 만나면 _"회사에서 어떤 일을 하고 있어요?"_가 가장 많이 듣는 질문이었다. 그리고 앱 개발을 한다고 하면 _"React Native 사용하시나요?"_라고 물어보시는데, 이때마다 난감(?)할 때가 있었다. 왜냐하면 우리 앱은 React Native로 되어있긴 하지만 그때 나는 React Native를 전혀 만지지 않고 있었고 Next.js로만 개발하고 있었기 때문이다.

생각해보면 그때 나는 웹뷰 개발에 대해 제대로 이해하고 있지 못해서 남에게 설명하는 데 자신이 없었던 것 같다. 하지만 언제나 그렇듯 막상 겪어보면 별거 없고 익숙해지기 마련이다. 2년차 개발자가 된 지금은 웹뷰 앱 개발에 대해 누가 물어본다면 자세하게 설명해줄 수 있다. 그래서 혹시 웹뷰 개발을 이제 막 시작했거나 궁금증을 가진 분들에게 도움이 되었으면 좋겠다는 마음으로 이 글을 쓰게 됐다.

물론 글을 정리하면서 나도 웹뷰에 대해 다시 한 번 정리하게 되어 좋았다. 이래서 블로그를 꾸준히 써야 하나보다ㅎㅎ 기록의 중요성!

사실 회사 코드에서 내가 사용한 부분을 예제로 가져오고 싶었는데, 회사 코드에서는 sendMessage 부분(RN 통신)을 lib 폴더에 모듈화해서 사용하고 있어서 내가 소개하고 싶었던 부분 외에도 복잡한 부분이 많아 직접 예제 코드를 만들었다. 이번 포스팅에서는 RN 통신의 기본 개념에 대해서만 소개하려고 했기 때문에 너무 딥한 내용은 최대한 덜어내려고 했다. RN 통신의 심화 버전은 다음 포스팅에서 다뤄야겠다.

📚 참고

1. [FrontEnd] Webview로 React를 App으로 만들기
2. react native webview 사용법