맨날 BEM으로 클래스명 길게 짓거나 CSS Modules, 혹은 Styled Components 쓰면서 스타일 충돌 막으려고 애썼잖아요. 저만 그런 거 아니죠? 그런데 이제 네이티브 CSS만으로 컴포넌트의 스타일 범위를 딱 지정해서 가둬버릴 수 있게 됐어요. 특정 컴포넌트 안에서만 스타일이 먹히게 하는 거죠.

예를 들어 .card 컴포넌트 안의 h2 태그에만 스타일을 주고 싶으면, 이제 전역 오염 걱정 없이 깔끔하게 처리할 수 있다는 뜻입니다. 이거 진짜 물건이네요. 무거운 라이브러리나 복잡한 빌드 과정 없이도 컴포넌트 기반 스타일링이 훨씬 직관적으로 변하겠어요.

물론 당장 모든 프로젝트에 도입하긴 어렵겠지만, 이 기능이 가져올 변화의 바람은 무시 못 할 것 같습니다. @scope를 실무에 활용하기 위한 제 생각 몇 가지를 공유해 볼게요.

• 디자인 시스템 컴포넌트에 우선 적용해 보세요. 버튼, 카드, 인풋 필드처럼 재사용성이 높고 독립적이어야 하는 컴포넌트부터 @scope로 리팩토링하면 효과가 가장 클 겁니다. 스타일이 외부로 새어 나가거나 내부를 침범할 걱정이 확 줄어들겠죠.
• 기존 CSS 방법론과 섞어서 써보세요. 처음부터 모든 걸 바꿀 순 없으니, 특히 스타일 충돌이 잦았던 복잡한 레이아웃이나 위젯 영역에만 부분적으로 @scope를 도입해서 점진적으로 개선해 나가는 전략이 현실적일 것 같아요.
• 'Donut Scope' 개념을 이해해 두세요. @scope는 특정 영역을 시작점으로 잡고, 특정 영역을 끝점으로 지정해서 그 사이의 요소에만 스타일을 적용하는 것도 가능해요. 이걸 '도넛 스코프'라고 부르던데, 중첩된 컴포넌트 구조에서 아주 유용하게 쓰일 것 같습니다.

오랜만에 CSS 네이티브에 이렇게 설레는 기능이 추가된 것 같네요. 더 이상 클래스명 짓느라 머리 싸매지 않아도 되는 날이 올지도 모르겠습니다.

다들 어떻게 생각하세요? 이거 실무에 바로 써먹을 수 있을까요? 댓글로 자유롭게 의견 나눠봐요!

🔗 원문 보기: https://smashingmagazine.com/2026/02/css-scope-alternative-naming-conventions/

React 19 및 Next.js App Router를 사용하고 계신다면 이 글을 꼭 확인하시고, 즉시 업데이트하시길 권장합니다.

🚨 CVE-2025-55182?

2025년 12월 초, React Server Components(RSC) 구현체에서 치명적인 원격 코드 실행(RCE) 취약점이 발견되었습니다.

• CVE ID: CVE-2025-55182
• 별칭: React2Shell
• 심각도: Critical (CVSS 10.0 / 10.0)
• 영향 범위: React 19.0.0 ~ 19.2.0 버전을 사용하는 RSC 환경

이 취약점은 해커가 인증 절차 없이 단 하나의 HTTP 요청만으로 서버에서 임의의 코드를 실행할 수 있게 만듭니다. 이미 야생에서 랜섬웨어 배포 등에 악용된 사례가 보고되기도 했습니다.

🐛 상세 내용

이 문제는 React Server Components가 클라이언트로부터 받은 요청을 처리할 때, 데이터 역직렬화(Deserialization) 과정에서 발생합니다.

구체적으로 react-server-dom-webpack, react-server-dom-turbopack 등의 패키지가 페이로드 검증을 제대로 수행하지 않아, 공격자가 조작된 데이터를 보내면 서버 내부 로직을 오염시키고 임의의 자바스크립트 코드를 실행할 수 있게 됩니다.

영향받는 버전

다음 버전의 React를 사용 중이라면 위험합니다.

• 19.0.0
• 19.1.0, 19.1.1
• 19.2.0

특히 Next.js (App Router) 와 같이 RSC를 기본적으로 사용하는 프레임워크가 주된 타겟이 됩니다.

🛡️ 대응 방법

다행히 React 팀에서 빠르게 패치를 배포했습니다. 가장 확실하고 유일한 해결책은 버전을 올리는 것입니다.

1. 즉시 업데이트 (권장)

사용 중인 패키지 매니저에 맞춰 react와 react-dom을 최신 패치 버전(19.2.1 이상)으로 업데이트하세요.

npm

npm install react@latest react-dom@latest

yarn

yarn upgrade react react-dom

pnpm

pnpm upgrade react react-dom

2. 버전 확인

업데이트 후, package.json이나 락 파일에서 버전이 19.2.1 (또는 19.0.1, 19.1.2) 이상인지 꼭 확인해 주세요.

📝 마치며

프론트엔드 영역, 특히 서버 사이드 렌더링(SSR)과 RSC가 보편화되면서 프론트엔드 개발자도 서버 보안에 대해 더 민감하게 반응해야 할 시점인 것 같습니다.

우리 프로젝트도 확인해 보니 19.2.0을 사용 중이라 식겁해서 바로 업데이트를 진행했네요. 😅 여러분의 프로젝트도 지금 바로 확인해 보세요!

Reference

• NVD - CVE-2025-55182
• React 공식 블로그 및 보안 권고 사항

그런데 간헐적으로 이상한 리포트가 들어오기 시작했습니다.

"어떤 사진을 선택하면 미리보기가 안 뜨고 그냥 가만히 있어요."

보통 버그라면 앱이 죽거나(Crash), 콘솔에 빨간색 에러 로그라도 떠야 하는데, 이 녀석은 아무런 반응도, 로그도 없이 그저 조용히 멈춰버리는 것이 특징이었습니다.

범인은 바로 범용적으로 쓰던 이미지 압축 함수 속 "끝나지 않는 Promise"였습니다.

원인 추적

제가 구현하려던 로직은 아주 일반적인 흐름이었습니다.

1. 사용자가 <input type="file" />을 통해 채팅창에 보낼 사진을 선택합니다.
2. 선택된 파일이 너무 클 수 있으니, processImage 함수가 리사이징 및 압축을 수행합니다.
3. 압축이 완료되면 결과물을 받아 화면에 미리보기(Preview) 썸네일을 띄웁니다.

대부분의 이미지는 잘 동작했지만, 특정 고화질 이미지나 일부 손상된 파일을 선택했을 때 2번 단계에서 코드가 멈춰버렸습니다. 함수가 영원히 종료되지 않으니(Hang), 당연히 3번 단계인 '미리보기 출력' 코드는 실행될 기회조차 얻지 못했던 것이죠.

원인 분석

기존 compressImage 함수를 살펴보니, Promise를 반환하면서 내부적으로 new Image()를 생성해 로드하고 있었습니다.

기존 코드

const compressImage = (file: File): Promise<File> => {
  return new Promise(resolve => {
    const img = new Image()

    img.onload = () => {
      resolve(compressedFile) 
    }

    img.src = URL.createObjectURL(file)
  })
}

문제의 핵심: 브라우저가 img.src에 할당된 Blob URL을 해석하지 못하거나 로드에 실패할 경우 onload 이벤트가 발생하지 않습니다. 이때 onerror 핸들러가 없으면 이 Promise는 영원히 pending 상태로 남게 됩니다.

결국 await compressImage(file) 부분에서 코드가 멈춰버려, 그 뒤에 있는 setPreviewImageSrc 로직이 실행되지 않았던 것입니다.

해결 방법

두 가지를 개선하여 코드를 수정했습니다.

1. onerror 핸들러 추가: 이미지 로드 실패 시, 압축을 포기하고 원본 파일 그대로 resolve 하도록 처리하여 로직이 멈추지 않게 함.
2. 메모리 누수 방지: URL.createObjectURL로 만든 객체는 사용 후 반드시 URL.revokeObjectURL로 해제해 주어야 하므로, 성공/실패 모든 케이스에 cleanup 로직 추가.

수정된 코드

const compressImage = (file: File): Promise<File> => {
  return new Promise(resolve => {
    const canvas = document.createElement('canvas')
    const ctx = canvas.getContext('2d')
    const img = new Image()

    const objectUrl = URL.createObjectURL(file)


    img.onload = () => {
      canvas.toBlob(blob => {
        URL.revokeObjectURL(objectUrl)
        if (blob) {
          const compressedFile = new File([blob], file.name, {
            type: 'image/jpeg',
            lastModified: Date.now(),
          })
          resolve(compressedFile)
        } else {
          resolve(file)
        }
      }, 'image/jpeg', 0.8)
    }

    img.onerror = () => {
      URL.revokeObjectURL(objectUrl)

      resolve(file)
    }

    img.src = objectUrl
  })
}

결과

이제 손상된 이미지나 브라우저가 압축할 수 없는 포맷이 들어오더라도, catch나 onerror를 타고 원본 파일로 fallback 처리되므로 프리뷰가 즉시 정상적으로 표시됩니다.

프론트엔드에서 Promise를 직접 생성(new Promise)해서 사용할 때는, resolve뿐만 아니라 예외 케이스(reject 혹은 fallback resolve)를 반드시 고려해야 함을 다시 한번 상기하게 되었습니다.

특히 EC2 인스턴스를 직접 운영하면서, 하드웨어 성능이 곧 서비스 응답 속도와 직결된다는 것을 뼈저리게 배웠습니다. CloudWatch를 뚫어지게 보며 분석했던 4대 핵심 지표와 실전 기록을 공유합니다.

CPU Usage: t3 인스턴스의 크레딧 소진과 TTFB의 함수 관계

파일럿 초기, 저렴한 t3 인스턴스를 사용하다가 특정 시점에 페이지 응답 속도(TTFB)가 갑자기 수 초대로 늘어나는 현상을 겪었습니다.

CPU Credits & Burst t계열 인스턴스 특유의 'CPU 크레딧'이 모두 소진되자 성능이 기본 수준으로 베이스라인화되면서 SSR 렌더링 속도가 처참하게 느려졌습니다. 프로덕션급 SSR 서버에는 c5나 m5 같은 전용(Dedicated) 인스턴스 타입이 왜 권장되는지 실감했습니다.

Event Loop Lag 모니터링 CloudWatch의 CPU 사용률만 봐서는 알 수 없는 Node.js Event Loop Delay가 100ms를 돌파하고 있었습니다. CPU가 100%가 아니더라도 싱글 스레드가 복잡한 연산에 묶이면 전체 요청이 밀린다는 점을 확인하고 로직을 최적화했습니다.

Prometheus 설정 과정은 다음 게시물에 올리겠습니다

Memory Usage: 스왑(Swap) 공간과 불시의 프로세스 종료

운영 중 Node.js 서버 프로세스가 조용히 종료(Crash)되는 현상이 발생했습니다. 범인은 메모리 부족으로 인한 리눅스 커널의 자가방어였습니다.

OOM Killer와 dmesg 인스턴스 메모리가 꽉 차자 리눅스 커널이 가장 메모리를 많이 먹는 Node.js 프로세스를 죽여버렸습니다. dmesg 명령어로 OOM(Out Of Memory) 킬러의 흔적을 발견하고 깜짝 놀랐습니다.

Swap File 설정의 명암 메모리 부족 시 바로 죽지 않도록 EBS에 스왑 파일을 생성해 두었으나, 디스크를 메모리처럼 쓰니 I/O 부하가 치솟으며 서버가 '좀비 상태'가 되었습니다. 결국 인스턴스 RAM 용량을 올리고 누수가 발생하는 전역 캐시 로직을 걷어냈습니다.

Network Bandwidth: 데이터 전송 비용(Egress)의 압박

파일럿 서비스임에도 불구하고 월말 AWS 청구서에서 'Data Transfer Out' 항목이 예상치를 훌쩍 상회했습니다.

Egress 비용 최적화 EC2에서 사용자의 브라우저로 나가는 데이터 전송 비용이 상당했습니다. 완성된 HTML 크기를 줄이기 위해 Gzip/Brotli 압축을 적용하고, 거대했던 API 응답 데이터를 BFF(Backend For Frontend) 레이어에서 파이썬처럼 필요한 것만 발췌해 렌더링하도록 수정했습니다.

ALB와 커넥션 유지 Application Load Balancer(ALB)와 EC2 간의 Keep-Alive 설정을 최적화하여 잦은 연결 수립으로 인한 오버헤드를 줄였습니다.

Disk Usage & I/O: EBS 성능과 ISR 페이지 갱신

Next.js의 ISR(Incremental Static Regeneration) 기능을 쓰면서 디스크 성능이 렌더링 지연에 영향을 줄 수 있다는 것을 알게 되었습니다.

EBS IOPS의 벽 새로운 페이지를 생성하고 디스크에 쓰는 과정에서 EBS의 초당 입출력 횟수(IOPS)가 부족하면 I/O Wait이 발생했습니다. 이는 CPU가 연산을 못 하고 디스크 작업이 끝나길 기다리게 만들어 전체 응답 속도를 떨어뜨렸습니다.

로그 로테이션(Logrotate) pm2 프로세스 매니저가 뿜어내는 로그가 EBS 용량을 가득 채워 서버가 멈추는 사고를 방지하기 위해, 주기적으로 S3로 로그를 넘기고 로컬은 비우는 정책을 세웠습니다.

파일럿은 시작일 뿐입니다.

이번 파일럿 출시를 통해 단순히 브라우저 단의 성능 최적화를 넘어, AWS 인프라의 관점에서 서비스를 바라보는 법을 배웠습니다.

CloudWatch 대시보드의 꺾은선 그래프 하나하나가 우리 사용자가 느끼는 실제 반응 속도임을 깨달았습니다. EC2 인프라를 직접 만지며 얻은 이 값진 수치들을 바탕으로, 정식 버전에서는 더욱 탄탄하고 효율적인 아키텍처를 구축하려 합니다.

하지만 저는 기존에 세팅해둔 Shared Package 전략이 있어 한번 세팅을 해보려합니다. (이전 게시글 참고)

sentry 공식 홈페이지에서도 모노레포를 위한 문서가 딱히 없어 걱정반 설렘 반으로 작업을 시작했네요.

그 과정 바로 공유해 드릴게요.

왜 그냥 설치하지 않고 "패키지"로 만드나요?

Shared Package 전략글에 상세히 설명되어 있어 간단히 짚고만 가겠습니다.

보통은 npx @sentry/wizard를 각 앱에서 돌리지만, 모노레포에선 이게 기술 부채가 됩니다.

• 중복 설정: beforeSend 로직이나 에러 마스킹 수정을 모든 앱에서 반복해야 합니다.
• 버전 불일치: A 앱은 Sentry v7, B 앱은 Sentry v10을 쓰는 혼란이 생깁니다.
• 파편화된 DSN: DSN 주소 하나 바뀌면 모든 .env를 뒤져야 하죠.

우리는 @repo/sentry라는 이름의 독립된 공간에서 이 모든 걸 관리할 겁니다.

Shared Package 구축하기

packages/sentry에 자리를 잡고, 모든 앱이 가져다 쓸 수 있는 "Sentry 컨트롤 타워"를 만듭니다.

통합 Entry Point 설계 (index.ts)

단순히 초기화만 하는 게 아니라, 서버/클라이언트/엣지 환경에 맞춰 최적화된 초기화 함수를 정의합니다.

센트리 옵션은 공식문서, 블로그 등 많은 곳에세 이미 정리되어 있기에 index.ts에 어떻게 합쳤는지만 보여드리겠습니다.

import * as Sentry from "@sentry/nextjs";

// 중앙에서 관리하는 DSN
const SENTRY_DSN = 'https://...'; 

export const initSentryClient = () => {
  Sentry.init({
    dsn: SENTRY_DSN,
    tracesSampleRate: 1.0,
    integrations: [Sentry.consoleLoggingIntegration({ levels: ["log", "warn", "error"] })],
    enableLogs: true,
  });
};

export const initSentryServer = () => {
  Sentry.init({
    dsn: SENTRY_DSN,
    tracesSampleRate: 1.0,
  });
};

// ...Edge 로직도 동일하게

next.config.js 옵션 공통화

빌드 시 소스맵 업로드나 터널링(광고 차단 우회) 설정도 패키지에서 미리 정의해 둡니다.

export const sentryConfigOptions = {
  org: "조직명",
  project: "프로젝트명",
  silent: !process.env.CI,
  tunnelRoute: "/monitoring",
};

앱에서 간단하게 적용하기

현재 저는 Next.js 15+ 버전을 사용중이기에 최신 규격에 맞게 instrumentation.ts를 활용했습니다.

instrumentation 훅은 아래와 같으니 참고해보세요.

서버와 클라이언트를 동시에 잡는 법

instrumentation.ts (Server)

import * as Sentry from '@repo/sentry';

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { initSentryServer } = await import('@repo/sentry');
    initSentryServer();
  }
}
export const onRequestError = Sentry.captureRequestError;

instrumentation-client.ts (Client)

import * as Sentry from '@repo/sentry';
Sentry.initSentryClient();
export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

여담

요번 작업에서 제 스스로 잘 도입했다 싶은 기능들을 아래에 정리하였으니 참고해보세요.

1. Tunneling: "광고 차단기에 의해 로그가 유실되는 걸 막기 위해 Rewrites를 통해 터널링을 구축"
2. Shared Package: "모노레포 환경에서 일관된 에러 트래킹을 위해 Sentry 설정을 공통 패키지화하여 DX를 개선"
3. Source Maps: "CI/CD 단계에서 자동 소스맵 업로드, 배포 후에도 난독화된 코드 대신 원본 코드로 에러 분석"

마무리하며

Sentry는 단순히 에러를 쌓아두는 창고가 아닙니다. 잘 세팅된 Sentry는 개발자가 잠든 사이에도 서비스의 건강도를 체크해 주는 소중한 동료가 되죠.

오늘 정리해 드린 모노레포 Sentry 설정으로 여러분의 DX를 한 단계 높여보세요!

오늘은 이 문제의 원인과 해결 방법에 대해 정리해 보겠습니다.

문제 상황

• 특정 브랜치(예: feature/bridge-fix)에서 작업을 완료한 후 pnpm changeset 실행.
• 나는 A 패키지만 수정했는데, changeset 목록에는 B, C, D 등 프로젝트 내 거의 모든 패키지가 포함됨.
• 실수로 그대로 진행할 경우, 의도치 않은 패키지들의 버전이 일괄적으로 올라가는 대참사가 발생할 수 있음.

원인 분석: baseBranch 설정

changeset은 현재 브랜치의 변경 사항을 감지하기 위해 기준이 되는 브랜치와 비교를 수행합니다. 이 기준은 .changeset/config.json 파일의 baseBranch 속성에 정의되어 있습니다.

보통 기본값은 main 또는 master로 되어 있습니다.

// .changeset/config.json
{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "baseBranch": "main",
  ...
}

왜 문제가 발생하나요?

만약 여러분의 작업 흐름(Workflow)이 다음과 같다면 문제가 발생합니다.

1. main 브랜치에서 dev 브랜치가 파생됨.
2. dev 브랜치에 여러 피처 브랜치들이 머지됨 (이 과정에서 많은 패키지들의 코드가 수정됨).
3. 아직 dev 브랜치의 내용이 main으로 머지되지 않음.
4. 나는 dev 브랜치에서 새로운 feature/my-task 브랜치를 따서 작업함.
5. pnpm changeset 실행.

이때 changeset은 feature/my-task와 main을 비교합니다. dev에 이미 머지되어 있던 모든 변경 사항들이 main에는 없기 때문에, changeset 입장에서는 그 모든 것들이 "이번 작업에서 변경된 사항"으로 간주되는 것입니다.

해결 포인트

baseBranch 수정

만약 프로젝트의 주요 개발 및 머지 기준 브랜치가 dev라면, changeset 설정에서도 이를 명시해 주어야 합니다.

// .changeset/config.json 수정
{
  "baseBranch": "dev",
  ...
}

이렇게 수정하면 changeset이 현재 브랜치를 dev와 비교하게 되어, 내가 실제로 이번 태스크에서 수정한 파일이 포함된 패키지만 정확하게 필터링해 줍니다.

마치며

changeset은 버전 관리와 Changelog 생성을 자동화해 주는 아주 편리한 도구입니다. 하지만 잘못된 기준 설정은 의도치 않은 버전 펌핑(Version Bumping)을 유발할 수 있으므로, 프로젝트의 브랜치 전략에 맞춰 config.json을 꼭 확인해 보세요!

Prettier 로그를 열어보면 대충 이런 에러가 떠있죠.

Error: Cannot find module 'prettier-plugin-tailwindcss'

분명 공통 설정 패키지(@repo/prettier-config)에는 설치를 해뒀는데, VS Code 확장 프로그램이 이걸 못 찾아서 생기는 문제입니다. 앱마다 똑같은 플러그인을 중복으로 깔자니 모노레포 쓰는 의미가 퇴색되는 것 같고... 이럴 때 깔끔하게 해결하는 방법을 공유합니다.

왜 못 찾는 걸까?

VS Code의 Prettier 확장은 현재 작업 중인 파일의 위치나 프로젝트 루트에서 플러그인을 찾으려고 합니다. 그런데 모노레포 구조에선 실제 플러그인이 저 멀리 공통 패키지의 node_modules 안에 숨어있으니 확장 프로그램 입장에선 "플러그인 어디 있어?" 하고 뻗어버리는 거죠.

특히 ESM 방식(type: module)을 쓰면 모듈 탐색이 더 까다로워지는데, 이걸 해결하려면 절대 경로를 직접 꽂아주는 게 가장 확실합니다.

해결: 절대 경로 주입하기

createRequire를 써서 플러그인이 설치된 실제 경로를 찾아낸 다음, Prettier 설정의 plugins 배열에 넘겨주면 됩니다.

packages/prettier-config/base.js 수정

import { createRequire } from 'module'

const require = createRequire(import.meta.url)

export default {
  singleQuote: true,
  semi: false,
  tabWidth: 2,
  trailingComma: 'es5',
  printWidth: 80,
  bracketSpacing: true,
  arrowParens: 'avoid',
  endOfLine: 'auto',
  // 이름만 적는 게 아니라 require.resolve로 실제 파일 위치를 넘겨줍니다.
  plugins: [require.resolve('prettier-plugin-tailwindcss')],
}

이렇게 하면 prettier-config 패키지가 있는 위치를 기준으로 플러그인을 찾아서 절대 경로를 반환합니다. VS Code 확장은 이 경로를 보고 바로 플러그인을 로드할 수 있게 됩니다.

적용 결과

수정하고 나서 VS Code에서 Cmd + Shift + P -> Developer: Reload Window 한 번 해주세요.

이제 하단 바에 Prettier가 정상 작동하면서, 파일 저장할 때마다 Tailwind 클래스 정렬이랑 포맷팅이 아주 시원하게 잘 돌아갈 겁니다.

요약

• 각 앱마다 플러그인 깔지 말고 공통 설정 패키지 하나에서 관리하자.
• 인식이 안 되면 require.resolve로 절대 경로를 주입하면 끝.

전체적인 의존성 관리 상태를 점검하던 중, 최적화할 수 있는 포인트 하나를 발견했습니다. 바로 Prettier와 ESLint 관련 플러그인의 관리 방식이었습니다.

불필요한 중복 발견

현재 구조에서도 린팅과 포맷팅은 잘 동작하고 있었습니다. 하지만 각 앱(apps/*)의 package.json을 열어보니 불필요한 중복이 눈에 띄었습니다.

// apps/client/package.json
{
  "devDependencies": {
    "prettier": "^3.0.0",
    "prettier-plugin-tailwindcss": "^0.5.0", // 중복 Prettier Plugin
    "eslint-plugin-react": "^7.33.0", // 중복 ESLint Plugin
    "@next/eslint-plugin-next": "^14.0.0", // 중복...
    "@repo/prettier-config": "workspace:*",
    "@repo/eslint-config": "workspace:*"
  }
}

이미 @repo/*-config라는 공통 패키지를 만들어 두었음에도 불구하고, 정작 플러그인은 각 프로젝트마다 개별적으로 설치해서 사용하고 있었습니다.

"모노레포의 장점은 의존성 중앙 관리인데, 서드파티 플러그인까지 각 프로젝트가 일일이 들고 있을 필요가 있을까? 공통 패키지에서 한 번에 제공해줄 수 있지 않을까?"

이 부분을 개선하면 각 서비스 프로젝트는 비즈니스 로직에만 더 집중할 수 있는 가벼운 상태가 될 것이라 판단했습니다.

고도화 준비

단순히 동작하게 만드는 단계를 넘어, 구조적 효율성을 높이는 것을 목표로 했습니다.

• AS-IS: 공통 설정(config)은 중앙에서, 실행 도구(plugin)는 각 앱에서 관리.
• TO-BE: 설정과 실행 도구 모두 공통 패키지가 캡슐화하여 제공. 각 앱은 '사용'만 함.

Prettier

package.json 파일

먼저 흩어져 있던 의존성을 한곳으로 모으는 작업을 진행했습니다. apps에 있는 플러그인을 제거하고, 이를 packages/prettier-config로 옮깁니다.

cd packages/prettier-config
pnpm add prettier-plugin-tailwindcss

// packages/prettier-config/package.json
{
  "name": "@repo/prettier-config",
  "dependencies": {
    // 플러그인을 이곳의 직접 의존성으로 선언합니다.
    "prettier-plugin-tailwindcss": "^0.7.2"
  }
}

Config 파일

이 부분이 Prettier 설정 개선의 핵심입니다. 단순히 의존성만 옮기면 Prettier가 실행될 때 플러그인을 찾지 못하는 문제가 발생합니다 (Prettier는 실행 컨텍스트의 node_modules를 탐색하기 때문입니다)

이를 해결하기 위해 설정 파일 내부에서 플러그인을 직접 주입하는 방식으로 변경했습니다.

// packages/prettier-config/base.js
import * as tailwindPlugin from "prettier-plugin-tailwindcss";

export default {
  // ... 기존 포맷팅 룰
  plugins: [
    tailwindPlugin, // 문자열 이름 대신, import한 플러그인 객체를 직접 할당
  ],
};

이렇게 하면 각 앱에 플러그인이 설치되어 있지 않아도, Config 패키지가 내부적으로 플러그인을 품고 있기 때문에 정상적으로 동작하게 됩니다.

ESM 환경 호환성을 위해 import * as 문법을 사용하여 안정적으로 모듈을 로드했습니다.

각 서비스 프로젝트 경량화

• package.json: prettier-plugin-tailwindcss 의존성 삭제
• prettier.config.js:

// apps/admin/prettier.config.js
import baseConfig from "@repo/prettier-config";

export default {
  ...baseConfig, // 완벽하게 캡슐화된 설정을 상속
};

ESLint

Prettier를 정리하고 나니 ESLint도 마찬가지였습니다. eslint-plugin-react, eslint-plugin-react-hooks, @next/eslint-plugin-next 등 수많은 의존성이 각 앱마다 중복 설치되어 있었습니다.

package.json

ESLint 역시 공통 패키지(@repo/eslint-config)로 모든 플러그인을 이동시켰습니다. 이때 주의할 점은, 이 공유 패키지를 설치하는 소비 앱들이 플러그인을 찾을 수 있게 하려면 dependencies에 플러그인을 명시해야 한다는 것입니다.

// packages/eslint-config/package.json
{
  "name": "@repo/eslint-config",
  "dependencies": {
    // devDependencies가 아닌 dependencies에 넣어야 합니다.
    "@eslint/js": "^9.39.1",
    "@next/eslint-plugin-next": "^15.4.6",
    "eslint-plugin-react": "^7.37.4",
    "eslint-plugin-react-hooks": "^5.2.0",
    "typescript-eslint": "^8.39.0"
  },
  "peerDependencies": {
    "eslint": "^9.39.1"
  }
}

Flat Config

ESLint v9의 Flat Config 시스템을 사용하였습니다. 공통 패키지에서 완성된 설정 객체(Config Object) 배열을 export 해주면 됩니다.

하지만 이 과정에서 기존 레거시 설정(eslintrc)과는 다른 몇 가지 작업을 해주어야 했습니다.

1. React Prop Types 경고 끄기 TypeScript를 사용하는 환경에서는 prop-types 검사가 불필요한데, eslint-plugin-react가 기본적으로 이 규칙을 켜둡니다. 중앙 설정에서 이를 명시적으로 꺼주어야 합니다.

2. Plugins/Rules 정의 Flat Config에서는 플러그인을 객체로 직접 매핑하고, 규칙을 정의합니다.

// packages/eslint-config/next.js
import pluginNext from "@next/eslint-plugin-next";
import pluginReact from "eslint-plugin-react";
// ... imports

export const nextJsConfig = [
  ...baseConfig,
  {
    plugins: {
      "@next/next": pluginNext, // 플러그인 객체 매핑
    },
    rules: {
      ...pluginNext.configs.recommended.rules,
      // TypeScript 프로젝트이므로 prop-types 검사 비활성화
      "react/prop-types": "off",
    },
  },
  // ...
];

각 서비스 프로젝트 경량화

이제 앱에서는 복잡한 플러그인이나 extends를 볼 필요가 없습니다.

• package.json: eslint 본체와 @repo/eslint-config만 남기고 나머지 플러그인 삭제
• eslint.config.mjs:

import { nextJsConfig } from "@repo/eslint-config/next-js";

export default nextJsConfig;

간단하게 수십 개의 규칙과 플러그인 설정이 적용됩니다.

개선 결과

리팩토링 후 pnpm format과 pnpm lint를 전체 실행해 보았습니다. 결과는 성공적이었습니다.

1. 관리 포인트 일원화: Prettier와 ESLint 관련 플러그인 버전을 올릴 때, 이제 한 곳(packages)만 수정하면 모든 앱에 반영됩니다.
2. 보일러플레이트 감소: 새로운 프로젝트를 생성할 때 반복적인 플러그인 세팅 과정이 사라졌습니다.
3. 구조적 완성도: 설정 패키지가 정말 설정에 필요한 모든 것을 책임지는 구조가 되었습니다.

모노레포 구축은 초기 세팅이 끝이 아니라, 이렇게 운영하면서 발견되는 중복을 하나씩 제거하고 구조를 다듬어가는 과정에서 진정한 가치가 드러나는 것 같습니다.

저희 회사는 빠르게 성장하고 있는 조직입니다. AI 서비스 특성상 관리자 대시보드, B2C 클라이언트, 파트너사 페이지까지 총 3개의 제품을 운영하고 있죠.

문제는 프론트엔드 개발자가 저 혼자라는 점이었습니다.

기획자, 디자이너, 백엔드 개발자분들이 쏟아내는 요구사항을 혼자 감당해야 하는데, 버전 관리까지 수동으로 하다 보니 병목이 생기기 시작했습니다.

• 높은 컨텍스트 스위칭 비용: 하루에도 몇 번씩 앱을 오가며 작업하다 보니, "어? 이거 패치했나?" 헷갈리는 순간이 잦아졌습니다.
• 배포 리스크: 급하게 핫픽스를 배포하다가 다른 앱에 사이드 이펙트가 발생한 적이 있습니다. 등골이 서늘했죠.
• 문서화의 부재: 바쁘다는 핑계로 CHANGELOG 작성을 미루다 보니, 히스토리 파악이 안 돼서 똑같은 문제를 또 고민하게 되더라고요.

혼자라고 해서 주먹구구식으로 할 순 없었습니다. 오히려 혼자니까 더 시스템이 필요했죠. 제 리소스를 '운영'이 아닌 '기능 개발'에 온전히 쏟기 위해 자동화 시스템을 구축하기로 결심했습니다.

나를 복제할 수 없다면, 시스템을 만들자

그래서 도입한 것이 Simplified Git Flow + Changesets + CI/CD 파이프라인입니다.

도입 후 변화는 명확했습니다.

✅ 릴리스 프로세스 완전 자동화 ✅ 의존성 패키지 업데이트 실수가 사라짐
✅ 어떤 기능이 배포되었는지 전사 공유 가능
✅ 나중에 팀원이 충원되어도 바로 적응 가능한 체계 구축

이제부터 어떻게 '혼자서도 잘 돌아가는 시스템'을 만들었는지 공유 해드릴게요

제 프로젝트 구조부터 소개할게요

먼저 제가 뚝딱거리고 있는 모노레포 구조입니다.

ai-client-mono/
├── apps/
│   ├── ai-agent-admin/      # 관리자 대시보드 (포트: 3000)
│   ├── ai-agent-client/     # 클라이언트 앱 (포트: 3333)
│   └── ai-partner-admin/    # 파트너 관리 (포트: 3001)
├── packages/
│   ├── ui/                  # 공유 UI 컴포넌트
│   ├── eslint-config/       # ESLint 설정
│   ├── prettier-config/     # Prettier 설정
│   ├── tailwind-config/     # Tailwind 설정
│   └── typescript-config/   # TypeScript 설정
└── turbo.json               # Turborepo 설정

3개의 앱이 packages/ui 같은 공유 패키지를 함께 쓰고 있어요. 그래서 버전 관리가 더 중요했죠.

1인 개발인데 Git Flow가 필요할까?

처음엔 고민했습니다. "어차피 나 혼자 다 머지할 건데, 그냥 메인 브랜치 하나면 되지 않나?"

하지만 안정적인 서비스 운영을 위해선 타협할 수 없는 기준들이 있었습니다.

1. 프로덕션 배포는 언제나 신뢰할 수 있어야 한다. (Main Branch)
2. 개발 중인 기능이 운영 환경을 오염시키면 안 된다. (Dev Branch)
3. 긴급 버그 픽스는 다른 기능 개발과 격리되어야 한다. (Hotfix)

그래서 복잡한 Git Flow 대신, 실용성에 초점을 맞춘 Simplified Git Flow를 정립했습니다.

브랜치 구조

main (프로덕션)
  ↑
dev (개발 통합)
  ↑
feature/* (기능 개발)
hotfix/* (긴급 수정)
release/* (릴리스 준비)

각 브랜치의 역할

1. main - 프로덕션 브랜치

• 항상 배포 가능한 상태
• 직접 커밋 금지 (PR을 통해서만 병합)
• 태그를 통한 버전 관리

2. dev - 개발 통합 브랜치

• 다음 릴리스를 위한 개발 브랜치
• feature 브랜치들이 병합되는 곳
• CI/CD를 통한 자동 테스트

3. feature/ - 기능 개발 브랜치

모노레포 특성상 앱별/패키지별로 명확한 네이밍이 필요합니다

# 앱별 기능
feature/agent-admin/user-management
feature/agent-client/chat-interface
feature/partner-admin/dashboard

# 공유 패키지
feature/ui/button-component
feature/config/eslint-rules

# 공통 기능
feature/monorepo/ci-optimization

4. hotfix/ - 긴급 수정

hotfix/agent-admin/login-bug
hotfix/shared/security-patch

5. release/ - 릴리스 준비

release/v1.2.0
release/2025-12-ai-agent-admin

커밋 컨벤션: 히스토리는 회사의 자산이니까요

"나중에 보면 알겠지"라는 생각은 프로답지 못합니다. 제가 퇴사하더라도 코드는 남고, 히스토리는 자산이 됩니다.

특히 모노레포 환경에서는 어떤 앱에 변경사항이 발생했는지 명확해야 합니다. 그래서 Conventional Commits + Scope를 강제하여, 커밋 로그만 봐도 프로젝트 흐름이 보이도록 만들었습니다.

형식

<type>(<scope>): <subject>

예시

feat(agent-admin): 사용자 관리 페이지 추가
fix(agent-client): 채팅 메시지 렌더링 버그 수정
chore(ui): 버튼 컴포넌트 스타일 개선
docs(readme): Git 전략 문서 추가
refactor(partner-admin): 대시보드 코드 리팩토링
perf(shared): Tailwind 설정 최적화

Scope 예시

• 앱: agent-admin, agent-client, partner-admin
• 패키지: ui, config, eslint-config, tailwind-config
• 공통: monorepo, deps, ci

Changesets: 운영 비용을 줄이는 마법

가장 큰 병목은 CHANGELOG 관리와 버전 태깅이었습니다. 기능 개발 후 일일이 문서를 작성하고 버전을 올리는 건, 단순 반복 작업이자 리소스 낭비였죠.

"개발 단계에서 변경사항을 선언하면, 배포는 시스템이 알아서 할 수 없을까?"

이 물음에 대한 답이 Changesets이었습니다. 개발자는 코드와 함께 변경 의도를 남기기만 하면 됩니다. 나머지는 도구가 알아서 하니까요.

install

pnpm add -D -w @changesets/cli

init

Changesets를 초기화합니다.

pnpm changeset init

이렇게 init 작업을 하게 되면 .changeset 디렉터리가 생성되고, config.json 파일이 만들어집니다.

config.json 설정

.changeset/config.json 파일을 프로젝트에 맞게 수정합니다

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

워크플로우: 개발에만 집중하는 환경

이제 Release 프로세스는 이렇게 변했습니다.

1. pnpm changeset으로 변경사항 기록 (10초)
2. PR 생성 및 병합 (코드 리뷰)
3. 나머지는 CI/CD가 처리

더 이상 package.json 버전을 수동으로 수정하거나, 히스토리를 찾아 헤맬 필요가 없습니다. 저는 그 시간에 다음 스프린트의 핵심 기능을 개발합니다.

자동화로 신뢰성 확보하기

혼자 일할 때 가장 위험한 건 "체크해 줄 사람이 없다"는 것입니다. 그래서 CI/CD 파이프라인을 구축해 코드의 품질을 기계가 검증하도록 했습니다.

안정적인 배포 파이프라인

1. Lint/Build 검사: 휴먼 에러가 있는 코드는 절대 병합되지 않습니다.
2. 자동 버전 업: Semantic Versioning 규칙에 따라 정확하게 버전이 올라갑니다.
3. Release Note 생성: 배포 내역이 자동으로 문서화되어 팀에 공유됩니다.

이제 저는 마음 놓고 배포 버튼을 누를 수 있습니다. 시스템이 저를 지켜주니까요.

마치며: 혼자라고 시스템을 포기하지 마세요

"혼자니까 대충 해도 되겠지"라고 타협하는 순간, 기술 부채는 걷잡을 수 없이 커집니다. 특히 빠르게 성장하는 스타트업일수록, 초기 단계의 시스템 구축이 중요하다고 생각합니다.

혼자 고군분투하는 프론트엔드 개발자분들에게 시간과 안정성이라는 두 마리 토끼를 분양드립니다 ㅎㅎ

"나는 혼자여서 시스템이고 코드문화도 즐기지 못해" 라는 생각보다 나중에 올 팀원 (오긴 올까,,)을 위해 시스템을 구축하고, 코드 문화를 정립해보는 경험도 좋을것 같습니다 🎶

"혼자서 3개 프로젝트 관리하다가 미쳐버릴 뻔한 개발자의 생존기"
코드 복붙의 늪에서 벗어나 개발 생산성 향상을 달성한 진짜 이야기

"또 같은 컴포넌트를 복사하고 있다..."

어느 날, 나는 세 번째 프로젝트에서 또다시 같은 컴포넌트를 복사 붙여넣기하고 있었습니다.

"이게 맞나...?"

그리고 며칠 후, 버튼에 버그가 발견되었습니다. 3개 프로젝트를 모두 수정해야 했죠.

더 큰 문제는 각 프로젝트마다 모든 설정과 의존성을 개별 관리하고 있었다는 것입니다.

😱 3개 프로젝트 × 20개+ 패키지 = 60개+ 중복 설치 😱 node_modules: 150MB × 3 = 450MB 😱 ESLint 설정 3개, Prettier 설정 3개, Tailwind 설정 3개... 😱 설정 하나 바꾸려면? 3곳 모두 수정...

그때 깨달았습니다.

"이건 지속 가능하지 않다."

"Monorepo라는 게 있다던데?"

Monorepo를 처음 들었을 때

나: "Monorepo? 그거 구글이나 페이스북 같은 대기업에서나 쓰는 거 아니야?"
동료: "요즘은 1인 개발자도 많이 쓰던데?"
나: "설마... 나한테도 필요할까?"

이후 Turborepo 문서를 읽으며 깨달았습니다.

❌ 기존 방식
- 3개 레포지토리 관리
- 같은 코드 3번 작성
- 버그 수정도 3번
- 의존성 업데이트도 3번
- 정신적 스트레스 ∞

✅ Monorepo
- 1개 레포지토리
- 코드 1번 작성
- 버그 수정 1번
- 의존성 업데이트 1번
- 정신적 평화 ∞

"이거다!"

Monorepo 도입 검토 및 설계

아키텍처 설계

ai-client-mono/
├── apps/                           # 애플리케이션 레이어
│   ├── ai-agent-admin/            # 독립 배포 가능
│   ├── ai-agent-client/           # 독립 배포 가능
│   └── ai-partner-admin/          # 독립 배포 가능
│
├── packages/                       # 공유 레이어
│   ├── ui/                        # UI 컴포넌트 (shadcn/ui 모듈화)
│   ├── eslint-config/             # 린팅 규칙
│   ├── prettier-config/           # 포맷팅 규칙
│   ├── tailwind-config/           # 디자인 시스템
│   └── typescript-config/         # 타입 설정
│
└── 인프라 레이어
    ├── Turborepo                  # 빌드 오케스트레이션
    └── pnpm workspace             # 의존성 관리

핵심 설계 원칙

Single Source of Truth

• 공통 컴포넌트는 packages/ui에만 존재
• 설정 파일은 각 packages/*-config에만 존재

Loose Coupling

• 각 앱은 독립적으로 배포 가능
• 공유 패키지 변경이 앱에 자동 반영

마이그레이션

공통 패키지 생성 (UI + 설정)

가장 먼저 한 일은 중복된 모든 것을 찾는 것이었습니다.

중복 분석

# UI 컴포넌트 중복
$ grep -r "export const Button" apps/
apps/ai-agent-admin/components/Button.tsx
apps/ai-agent-client/components/Button.tsx
apps/ai-partner-admin/components/Button.tsx

# Input, Select, Dialog, Modal... 총 25개 컴포넌트가 중복!

# 설정 파일 중복
$ find apps -name "eslint.config.js" -o -name "prettier.config.js"
apps/ai-agent-admin/eslint.config.js
apps/ai-agent-admin/prettier.config.js
apps/ai-agent-admin/tailwind.config.ts
apps/ai-agent-admin/tsconfig.json
# ... 각 앱마다 4개씩 = 총 12개 설정 파일!

공유 패키지 전략

5개의 공유 패키지로 모듈화:

packages/
├── ui/                 # shadcn/ui 컴포넌트 (25개)
├── eslint-config/      # ESLint 규칙
├── prettier-config/    # Prettier 규칙
├── tailwind-config/    # Tailwind 디자인 시스템
└── typescript-config/  # TypeScript 설정

@repo/ui 패키지 생성

shadcn/ui를 Monorepo 공유 패키지로!

shadcn/ui는 각 프로젝트에 컴포넌트를 복사하는 방식입니다.
하지만 Monorepo에서는 이를 공유 패키지(@repo/ui)로 모듈화하여
모든 앱이 동일한 shadcn/ui 컴포넌트를 사용하게 만들었습니다!

디렉토리 구조:

packages/ui/
├── src/
│   ├── components/          # shadcn/ui 컴포넌트들
│   │   ├── button.tsx      # shadcn/ui button
│   │   ├── input.tsx       # shadcn/ui input
│   │   ├── dialog.tsx      # shadcn/ui dialog
│   │   ├── form.tsx        # shadcn/ui form
│   │   └── ... (25개)
│   ├── lib/
│   │   └── utils.ts        # cn() 등 유틸리티
│   └── styles/
│       ├── adminGlobals.css
│       └── clientGlobals.css
├── package.json
└── components.json         # shadcn/ui 설정

package.json 설정:

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "exports": {
    "./components/*": "./src/components/*.tsx",
    "./lib/*": "./src/lib/*.ts",
    "./styles/*": "./src/styles/*.css"
  },
  "dependencies": {
    "@radix-ui/react-slot": "^1.2.4",
    "@radix-ui/react-dialog": "^1.1.15",
    "class-variance-authority": "^0.7.1",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.1"
    // ... shadcn/ui가 사용하는 의존성들
  }
}

모든 앱에서 동일한 shadcn/ui 컴포넌트 사용

shadcn/ui를 @repo/ui로 모듈화하면서 각 앱의 의존성이 대폭 감소했습니다!

// @repo/ui로 모듈화
// ai-agent-admin/package.json
{
  "dependencies": {
    "@repo/ui": "workspace:*",  // 이것만!
    "next": "^15.5.6",
    "react": "^19.0.2"
    // shadcn 관련 패키지 전부 제거!
  }
}

// ai-agent-client/package.json - 역시 깔끔!
// ai-partner-admin/package.json - 역시 깔끔!

// packages/ui/package.json - 여기에만 shadcn 의존성 존재
{
  "dependencies": {
    "@radix-ui/react-slot": "^1.2.4",
    "@radix-ui/react-dialog": "^1.1.15",
    // ... 모든 shadcn 의존성
  }
}

의존성 지옥 탈출

문제:

// ai-agent-admin/package.json
"next": "14.0.0"

// ai-agent-client/package.json
"next": "15.0.0"  // 버전이 다름!

// ai-partner-admin/package.json
"next": "14.2.0"  // 또 다름!

해결책: pnpm workspace로 통합

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

// 루트 package.json
{
  "dependencies": {
    "next": "^15.5.6", // 하나로 통일!
    "react": "^19.0.2"
  }
}

결과:

• 버전 충돌 제로
• node_modules 크기 감소
• 설치 시간 빨라짐

Step 3: Turborepo 캐싱 마법

처음에는 빌드가 너무 느렸습니다.

"이건 아닌데..."

그러다 발견한 Turborepo의 캐싱 기능!

// turbo.json
{
  "tasks": {
    "build": {
      "outputs": [".next/**", "dist/**"],
      "cache": true // 이 한 줄이 마법!
    }
  }
}

"와... 이게 진짜 마법이네!"

🔧 문제 해결

TypeScript Path Alias 충돌

문제

// apps/ai-agent-admin/tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]  // 앱 내부 경로
    }
  }
}

// packages/ui/tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]  // 패키지 내부 경로
    }
  }
}
// ❌ 충돌 발생!

해결

// packages/ui/tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/lib/*": ["./src/lib/*"],
      "@/components/*": ["./src/components/*"]
    }
  }
}

// turbo.json에도 추가
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["NODE_ENV"]
    }
  }
}

Tailwind CSS 스타일 충돌

문제 각 앱마다 다른 Tailwind 설정으로 스타일 불일치

해결

// packages/tailwind-config/index.ts
export default {
  theme: {
    extend: {
      colors: {
        primary: {
          50: "#f0f9ff",
          // ... 공통 색상 팔레트
        },
      },
      spacing: {
        // 공통 간격 시스템
      },
    },
  },
};

// 각 앱에서 확장만 가능
// apps/ai-agent-admin/tailwind.config.ts
import sharedConfig from "@repo/tailwind-config";

export default {
  ...sharedConfig,
  content: ["./src/**/*.{ts,tsx}"],
  theme: {
    extend: {
      // 앱별 추가 설정만
    },
  },
};

빌드 순서 의존성

문제 앱이 @repo/ui를 사용하는데 빌드 순서가 보장되지 않음

해결

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"], // ^ = 의존성 먼저 빌드
      "outputs": [".next/**", "dist/**"]
    }
  }
}

Turborepo가 의존성 그래프를 분석하여 자동으로 순서 결정:

1. packages/ui 빌드
2. apps/* 병렬 빌드 (ui 빌드 완료 후)

💬 마치며

Monorepo 마이그레이션은 쉽지 않았습니다. 처음에는 "내가 왜 이걸 시작했지?"라는 생각도 들었죠.

하지만 지금은 추천할만큼 긍정적으로 생각합니다.

특히 아래 상황이라면 더더욱 추천드려요.

✅ 여러 프로젝트를 혼자 관리하는 분

• 코드 중복으로 고통받고 계신가요?
• 같은 작업을 여러 번 반복하시나요?

✅ 빠른 프로토타이핑이 필요한 분

• 공통 컴포넌트 재사용으로 개발 속도 향상

✅ 일관성을 중요하게 생각하는 분

• 모든 프로젝트에서 동일한 코드 스타일 유지

여러분도 코드 복붙의 늪에서 허우적대고 계신가요?
같은 작업을 여러 번 반복하며 시간을 낭비하고 계신가요?

그렇다면 Monorepo를 시도해보세요.

과거의 나에게 감사하게 될 겁니다.

📚 참고 자료

• Turborepo 공식 문서
• pnpm Workspace
• Monorepo Best Practices

입사한지 3개월 정식계약을 맺은 달 팀장님이 제게 Sentry도입을 맡기셨다. 여지껏 SI와 B2B 회사를 다닌 나는 운영 에러에 대한 고민을 해보지 못했다. (이렇기에 B2C회사로 이직했다) 그렇기에 Sentry에 대해서 무지했고 Sentry를 이용한 운영 에러 관리를 알 수 있는 좋은 기회라 생각이 들었다. Sentry에 대해 공부하고 적용하면서 알게된 지식들을 남기고자 글을 쓰게 되었다!

Sentry란?

Sentry는 실시간 로그 취합 및 분석 도구이자 모니터링 플랫폼이다. 로그에 대해 다양한 정보를 제공하고 이벤트별, 타임라인으로 얼마나 많은 이벤트가 발생하는지 알 수 있고 설정에 따라 알림을 받을 수 있다. 발생한 로그들을 시각화 도구로 쉽게 분석할 수 있도록 도와주며 다양한 플랫폼을 지원한다. 여기까지가 오피셜적인 Sentry 설명이라면 내가 사용하면서 정의내린 Sentry를 설명하겠다! Sentry는 실시간 운영 에러에 대한 처리를 손쉽게 도와주는 플랫폼이다. 여기서 손쉽게라고 느껴진 포인트들은 이렇다

1. 실시간 발생되는 에러들이 대쉬보드에 비슷한 오류 통합하여 보여주니 에러들을 한 눈에 보기 편했다. => 같은 이벤트면 하나의 항목에 EVENTS 갯수가 오르며, 발생된 USER수를 USERS에 보여준다.
2. 에러를 커스텀하여 가치를 높일 수 있고 커스텀한 내용은 에러 상세에 표시된다. => 에러 커스텀은 밑에서 자세하게 다루겠다.
3. 에러에 대한 알림을 여러 플랫폼과 연결할 수 있어 운영중에 에러 관리가 수월해진다. => 무료버전에서는 플랫폼 제한이 있지만,,, 그래도 회사에서는 유료버전을 사용하기에 좋다고 느꼈다!
4. 화면 Replay 기능을 제공하여 에러 발생 시 사용자가 어떤 행위를 했는지 볼 수 있어 좋았다. => 에러 발생을 유발 시킨 행위를 알 수 있어 에러 추적이 매우 쉬웠다.

이렇듯 Sentry를 사용하면 유지보수 특히, 운영 중 에러 관리가 매우 손쉬워질 수 있다.

Vue 프로젝트에 Sentry 적용

1. Sentry 설치

   yarn add @sentry/vue

2. Sentry 설정 main.js에 Sentry 설정 기입 (자세한 설명은 주석 참고하세요!)

   Sentry.init({
   app,
   // dsn: 이벤트를 전송하기 위한 식별 키 (Sentry 홈페이지에서 발급)
   dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
   // environment: 애플리케이션 환경 (개발 테스트 환경 또는 운영 환경)
   environment: "prod",
   // debug: true일 경우 Sentry SDK가 디버그 모드로 작동
   // 브라우저 콘솔에 더 많은 디버깅 정보를 출력하게 됩니다. / 운영 환경에서는 false 추천
   debug: false,
   // integrations: 플랫폼 SDK별 통합 구성 설정
   integrations: [
    // Breadcrumbs를 활성화 및 콘솔(console) 이벤트를 기록하도록 설정됨 (Breadcrumbs 관련은 하기 참조!)
    new Sentry.Integrations.Breadcrumbs({ console: true }),
    //Browser Tracing: 브라우저에서의 트레이싱을 활성화
    new Sentry.BrowserTracing({
            // 트레이싱은 애플리케이션 내에서의 성능 이슈를 식별하는 데 사용
            // tracingOrigin 및 tracePropagationTargets는 트레이싱의 대상을 설정
          tracingOrigins: ['*'],
          tracePropagationTargets: ['*'],
            // Vue.js 라우터의 인스턴스를 받아 Sentry에 라우팅 이벤트를 보고할 수 있도록 도와주는 도구
          // 라우터 이벤트의 추적은 사용자 경험을 모니터링하고, 발생한 오류와 연결된 페이지 정보를 제공하는 데 유용
          routingInstrumentation: Sentry.vueRouterInstrumentation(options.router),
    }),
     // Replay를 활성화 (Sentry에 화면 기록이 저장됨)
    new Sentry.Replay(),
   ],
   // ignoreErrors: 특정 종류의 에러를 무시하도록 Sentry에게 지시 
   // ResizeObserver loop limit exceeded 에러는 성능에 문제는 되지 않고 해결하기는 어려워 보편적으로 제외 시킴
   ignoreErrors: ['ResizeObserver loop limit exceeded'],
   

// tracesSampleRate: 성능 모니터링을 위한 트랜잭션 샘플링 비율을 설정 // 모든 트랜잭션을 모니터링하여 애플리케이션의 전반적인 성능을 파악하는 데 도움 // 만약 이 값을 낮추면 일부 트랜잭션만을 샘플링하여 전체 데이터 양을 줄임 // 그러면 에러 또는 성능 문제가 발생한 트랜잭션을 감지하는 데 시간이 걸릴 수 있음 tracesSampleRate: 1.0, // Replay 관련 설정 replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, });

## Sentry 소스맵 등록하기!
현재 우리 프로젝트는 보안을 위해 소스맵을 등록하지 않고 있다.
이렇기에 Sentry에서 에러를 추적하려 해도 어느 파일에서 발생했는지 알 수 없다.
에러 상세에서 표시되는건 암호화된 소스 파일로 보여지고 있다,,
프로젝트 빌드 과정에 Sentry 소스맵을 제출하는 부분이 포함 되어있다.
그렇기에 Sentry에는 소스맵을 제출하되 프로젝트 빌드 후에는 소스맵을 삭제하는 방식을 도입했다.
(vite vue 기준 입니다.)

1.  vue 프로젝트 설정에 소스맵 설정을 켜준다.
```javascript
// vite.config.ts
  build: {
    ...
    sourcemap: 'hidden',
  },

2. sentryVitePlugin에 소스맵 관련 설정을 해준다.

   // vite.config.ts
   plugins: [
    ...
    sentryVitePlugin({
    ...
      sourcemaps: {
        assets: ['./dist/assets/**'],
        filesToDeleteAfterUpload: ['./dist/assets/*.js.map'],
      },
    }),
   ],

3. 배포 관련 YAML 파일에 Sentry 시크릿 키를 등록한다. (깃허브 액션 기준) 해당 키는 Sentry 홈페이지에서 발급 받을 수 있다.

   env: SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}

다른 분들은 여기까지 하면 빌드 후 자동으로 소스맵이 삭제 된다고 하는데 삭제 되지 않는 문제점이 발생하였다. 시행 착오 끝에 깃허브 액션 YAML 파일에서 빌드 후 강제로 소스맵을 삭제하는 로직을 추가하였다😔

4. 배포 관련 YAML 파일에 소스맵 삭제 로직을 추가한다.

   - name: Remove .js.map files
        run: |
          find dist -name "*.js.map" -type f -delete

여기까지 Sentry 초기 설정을 맞췄다! 이제 Sentry 상세 설명을 하겠다!

에러 가치 높이기!

Sentry Issue 대쉬보드를 보면 여러가지 에러들이 보인다. 그 중 에러 하나를 선택해 에러 상세 페이지에 들어가보면 에러에 대한 여러가지 사항들을 볼 수 있다. 여러가지 사항들이 무엇을 의미하고 어떻게 커스텀할지에 대한 내용을 적어보겠다

이벤트 로그

1. Exception & Message: 이벤트 로그 메시지 및 코드 라인 정보 ⇒ 소스맵 설정 필요
   
2. Device: 이벤트 발생 장비 정보 (name, family, model, memory 등)
   
3. Browser: 이벤트 발생 브라우저 정보 (name, version 등)
   
4. OS: 이벤트 발생 OS 정보 (name, version, build, kernelVersion 등)
   
5. Breadcrumbs: 이벤트 발생 과정

이벤트 로그 커스텀

기본 옵저버에서 제공되는 이벤트 로그 말고 코드 상에서 정보를 추가로 제공하여 커스텀 이벤트 로그를 남길 수 있다. 이렇게 하면 에러에 대한 필요한 정보를 손쉽게 얻어 효율을 높일 수 있다.

1. Context 세팅 에러 처리 부분에서 콘텍스트 라벨과 넣고싶은 정보를 추가한다.

   Sentry.setContext('Api Response Error', {
   status,
   path,
   });

   에러가 발생되면 아래와 같이 이벤트 로그 Context에 추가로 표시된다.

2. tag 세팅 에러 처리 부분에서 tag 네임과 value를 추가한다.

   Sentry.withScope((scope) => {
    scope.setTag('type', 'api');
    scope.setTag('api-status', status);
    scope.setTag('api-path', path);
   });

   에러가 발생되면 아래와 같이 이벤트 로그 tag에 추가로 표시된다.

3. 에러 네임 설정 에러 처리 부분에서 이름을 추가한다.

   Sentry.withScope((scope) => {
   //new Error(status) 이 부분이 이름이 된다.
      Sentry.captureException(new Error(status));
   });

   에러가 발생되면 Issue 리스트에 설정한 이름으로 표시된다.

4. 에러 레벨 설정 에러 처리 부분에서 레벨을 추가한다.

   Sentry.withScope((scope) => {
      scope.setLevel('error');
   });
   

/* 에러 레벨 Fatal = 'fatal',

Error = 'error',

Warning = 'warning',

Log = 'log',

Info = 'info',

Debug = 'debug',

Critical = 'critical', */

이렇게 에러 레벨을 설정하면 대쉬보드에서 에러 관리가 수월해 진다!
<hr/>

## 플랫폼 연동하기!
**다양한 플랫폼 연동 가능하나 유료 구독 회원만 지원하는 플랫폼이 대다수**

1. Setting → Integrations 으로 들어가서 원하는 플랫폼 설치
![](https://velog.velcdn.com/images/hb_een/post/ff700f80-70ca-4de5-bcc6-dede8da32167/image.png)

2. Alert 진입 후 Create Alert 클릭 후 Alert rule 설정
- 어떤 프로젝트의 어떤 환경을 대상으로 할 것인가?
- WHEN (ex. 새로운 이슈가 생성 됐을때, 해결한 이슈가 다시 발생됐을때 등)
- IF (ex. 이슈가 10분 이상 경과하면 등)
- THEN (ex. 연결된 플랫폼으로 알람을 보낸다 등)
⇒ 종합하면 새로운 이슈가 생성 됐을 때 이슈가 10분 이상 경과하면 연결된 플랫폼으로 알람을 보낸다.
(이런 식으로 Alert 설정 가능)
![](https://velog.velcdn.com/images/hb_een/post/6c9863a8-0eb6-4b45-a4fa-4d92ef89b344/image.png)

3. interval과 alert name 설정 하면 끝!