Gatsby Starter Blog RSS Feed

운영 환경에서 소스맵 적용으로 Sentry 오류 추적 개선하기

Tue, 25 Feb 2025 20:01:24 GMT

혹시 Sentry 에서도 소스 맵을 지원한다는 것을 알고계시나요?

Sentry는 에러 발생 시점의 정보를 수집하고 상세한 에러 보고서를 제공하여 효율적인 디버깅을 가능하게 합니다.

그러나 기본적으로 Sentry에 표시되는 코드는 Uglify된 상태입니다. 비록 에러에 대한 다양한 정보를 제공해주지만, 개발자들은 Uglify된 코드를 해석하여 실제 발생 지점을 다시 찾아내는 데 추가적인 시간을 소모하게 됩니다.

이러한 비효율적인 디버깅 플로우를 해결하기 위해 Sentry 에서는 소스 맵을 Sentry로 업로드할 수 있도록 지원하고 있습니다.

소스 맵 업로드 구성 방법은 크게 세 가지로 아래와 같습니다.

Sentry Wizard를 통한 소스 맵 업로드
번들러 또는 빌드 도구 수동 설정을 통한 소스 맵 업로드
Sentry CLI를 통한 소스 맵 업로드

이번 글에서는 Sentry Wizard와 번들러 또는 빌드 도구를 통한 소스 맵 업로드 방식을 다룹니다.

Sentry Wizard를 통한 소스 맵 적용

가장 간단한 방법으로, Sentry Wizard를 사용하는 것입니다.

아래의 명령어를 실행하면, Sentry 연동부터 패키지 설치, 빌드 도구 설정 등이 자동으로 진행됩니다.

npx @sentry/wizard@latest -i sourcemaps

번들러 또는 빌드 도구를 통해 소스 맵 수동 업로드

Sentry 에서 지원하는 대표적인 번들러 또는 빌드 도구로 webpack, rollup, vite 등이 있습니다. (Sentry 번들러 지원)

번들러를 통한 소스 맵 업로드는 현업에서 다양한 환경에 따라 분기 처리할 수 있기 때문에 매우 유용합니다.

보통 개발 환경에서는 개발중에도 배포가 진행되고, 반영 주기가 잦기 때문에 그에 따른 추가 비용이 발생하여 설정을 꺼놓는 경우가 있습니다. 이 외에도 브랜치별 도메인 분리로 Sentry를 사용하지 않는 도메인 같은 경우 예외적으로 번들러를 통해 소스 맵 생성과 업로드를 제어할 수 있습니다.

번들러 또는 빌드 도구에서 Sentry 소스맵을 적용하기 위해선 Sentry 에서 제공하는 플러그인을 통해 설정할 수 있습니다.

1. Sentry Auth Token 발급

Sentry 에 수동으로 소스 맵을 업로드하기 위해선 인증 토큰 발급이 필요합니다.

Sentry.io 접속 > Settings > Developer Settings 섹션 > Auth Tokens 메뉴

2. Sentry 플러그인 설치

해당 포스팅은 webpack 기준으로 작성되었습니다.

프로젝트에 Sentry 에서 제공하는 플러그인을 설치합니다.

npm i @sentry/webpack-plugin --save-dev

3. Sentry 플러그인 설정

소스 맵 수동 업로드 전 실제 빌드 시점에 소스 맵이 생성되고, 생성된 소스 맵은 Sentry 플러그인의 소스 맵 설정에 따라 업로드 후 제거됩니다.

❗️ 소스 맵 생성과 제거 로직은 함께 제어되어야하는 부분에 주의해주세요.

소스 맵이 제거가 진행되지 않았다면 운영 환경에 이미 모든 코드가 노출된 상태입니다.

// webpack.config.js
const { sentryWebpackPlugin } = require('@sentry/webpack-plugin')

const isProd = settings.SERVER !== 'development'

const webpackConfig = {
  devtool: isProd ? 'source-map' : false,
  ... // 그 외 설정
}

if (isProd) {
  webpackConfig.plugins.push(
    sentryWebpackPlugin({
      // 조직명
      org: settings.SENTRY_ORG,
      // 프로젝트명
      project: settings.SENTRY_PROJECT,
      // // Sentry 에서 발급 받은 인증 토큰
      authToken: settings.SENTRY_AUTH_TOKEN,
      // 소스맵 설정
      sourcemaps: {
        // 소스맵 파일 업로드 후 삭제할 파일 패턴
        filesToDeleteAfterUpload: '**/**/*.map',
        ignore: ['node_modules'],
      },
    })
  )
}

소스 맵 업로드 시 주의해야될 점

1. 소스 맵 업로드 과정 훑어보기

소스 맵이 정상적으로 업로드되지 않았을 경우를 위해 실제 빌드 시 소스 맵이 어떻게 업로드되는 지 알아야합니다.

빌드 실행
소스 맵 생성
Sentry에 소스 맵 업로드
업로드 후 소스 맵 파일 제거
빌드 완료

위의 과정을 통해 Sentry에 소스 맵이 업로드되고, 업로드 후에는 소스 맵이 안전하게 제거됩니다.

2. 소스 맵 생성과 Sentry 업로드는 동일한 조건으로 실행되어야 한다

위에서 소스 맵 생성과 Sentry 업로드는 동일한 조건으로 제어되어야한다고 말씀드렸습니다.

소스 맵 생성이 되지 않는 경우는 위와 같이 Sentry 업로드 시 파일을 찾을 수 없다는 오류가 발생합니다.

플러그인을 통해 Sentry 업로드가 되지 않을 경우 더 최악의 상황이 발생할 수 있습니다.

소스 맵 생성
소스 맵 생성과 조건이 달라 Sentry 업로드 로직이 실행되지 않음 (😱)
소스 맵 파일이 제거되지 않은 채 빌드 완료

동일한 변수로 또는 필드로 소스 맵 생성과 Sentry 업로드 로직을 제어해야합니다.

한 프로젝트안에 여러 환경이 존재하는 경우 피처 플래그 방식을 통해 안전하게 제어할 수 있습니다.

소스 맵 적용 전 / 소스 맵 적용 후

마무리

소스 맵이 실서비스에 업로드되게 되면 코드가 사용자에게 공개되어 취약점 분석을 통한 공격이나 인증 토큰 탈취 등 큰 보안 문제가 발생할 수 있습니다. 그렇기 때문에 반드시 Sentry 로 소스맵 업로드 후 제거되었는 지 환경별로 확인해야 합니다.

이번 Sentry 소스맵 업로드 작업은 소소해 보이지만, 이런 개선이 팀의 효율성을 크게 높이면서도, 적절한 주의와 테스트를 통해 보안 위험을 최소화할 수 있다는 점이 인상적이었습니다. :)

앞으로도 이런 작은 개선들을 통해 개발 환경과 프로세스를 지속적으로 발전시켜 나가려고 합니다.

[Book Review] 타입으로 견고하게 다형성으로 유연하게

Fri, 02 Aug 2024 23:35:37 GMT

지인을 통해 알게된 책으로 타입을 제대로 알기위해선 타입 검사기의 동작 원리를 알야한다는 것을 일깨워준 책입니다.

뒤로 갈수록 앞에서나온 개념이 심화되어 설명되고, 함수형 언어에서의 타입검사기의 확장된 기능까지 소개되어 매우 흥미로웠던 책이었던 것 같습니다.

첫 단원 요약

1장 타입 검사 흝어보기에서는 타입 검사가 왜 필요한 지 그리고 타입 검사기와 정적, 동작 타입 언어 등 타입의 기본적인 개념을 설명하며 마지막으로 앞으로 나올 다형성에 대해 설명합니다.

왜 불편함을 감수하면서까지 타입 검사를 해야되나요?

잠재적으로 존재하는 버그를 찾기 위해서입니다. 수 많은 버그 중 가장 흔한 원인은 타입 오류(type error)입니다. 타입 오류는 프로그램이 예기치 않게 종료되버리기 때문에 매우 치명적입니다.

타입 검사기는 무엇이고, 어떤 원리로 동작되나요?

타입 검사기(type checker)는 작성된 프로그램이 타입 오류를 일으키는 지 자동으로 판단해주는 검사기입니다. 타입은 작은 부품들이 결합한 하나의 큰 타입이고, 작은 타입의 정보를 읽고, 얻은 정보를 통해 큰 타입을 구성할 때 각각의 작은 타입들이 올바르게 사용되었는 지를 확인하는 것을 반복합니다.

타입 검사의 원칙 : "타입 검사기는 계산 결과를 절대 알아내려 하지 않는다."

타입 검사의 장점

타입 오류를 빠트리지 않고 모두 찾을 수 있다.
오류 메시지를 통해 올바르게 고치기 쉽다
코드 편집기에서 다양한 기능을 제공하고, 대표적인 기능으론 자동 완성 기능과 이름 바꾸기 기능이 있다.
뛰어난 성능, 타입 검사에서 얻은 정보를 바탕으로 실행 중에 할 일을 줄일 수 있다.
- 실행 중에 불필요한 검사(매번 인자가 정수인지 확인) 시간을 줄여준다.

타입 추론은 기본적으로 사용하되, 타입 검사기가 잘못 추론하거나 추론할 수 없는 경우, 또는 코드를 명확히 해야 할 때만 명시적인 타입 표시를 사용하는 것이 좋습니다.

// ❌ file 이 File 타입인지 File Path인 string 타입인 지 정확히 알 수 없다.
function readFile(file) { ... }

// 🅾️ readFile 의 인자로 File 타입을 넘기면 된다는 것을 명확히 알 수 있다.
function readFile(file: File) { ... }

다형성

다형성은 타입 검사기 동작 원리의 가장 중요한 개념입니다. 다형성은 하나의 타입에 여러 객체를 대입할 수 있는 성질로 하나의 값이 여러 타입에 속할 수 있고, 하나의 함수를 여러 타입의 합수로 사용할 수 도 있다는 것입니다.

다형성은 어떤 개체에 어떻게 부여하는지에 따라 나눌 수 있습니다.

서브타입에 의한 다형성
매개변수에 의한 다형성
오버로딩에 의한 다형성

다형성 규칙 한 번에 보기

서브타입에 의한 다형성 규칙

요구 조건 : A가 B이다.

A가 B이면 A는 B의 서브타입이다.
A가 B의 서브타입이면 B는 A의 슈퍼타입이다.

interface Person { ... }

// 이 때 Student 는 Person 의 서브타입입니다.
// Student(학생)는(은) Person(사람)이기 떄문입니다.
interface Student extends Person { ... }

반대로 Person은 Student 일 수 없습니다. 그러므로 Person 은 Student의 슈퍼타입!

`이름`과 `구조`에 의해 결정되는 서브타입

이름에 의한 서브타입(nominal subtyping)

타입 검사기가 interface (or class) 이름과 타입 간의 extends된 관계만 고려합니다. A가 B를 extends(확장/상속)한다면 A는 B의 서브타입입니다.

다음과 같이 Student 는 extends 를 통해 Person 으로 확장합니다. class 에서는 상속을 말하고, 아래와 같이 명시적으로 확장/상속한 것을 직접확장/상속 이라 합니다.

interface Person { ... }
interface Student extends Person { ... }

Student는 간접적으로 School을 확장/상속하고 있습니다. 이를 간접확장/상속 이라 합니다. Student는 Person 과 School 의 서브타입입니다.

interface School { ... }
interface Person extends School { ... }
interface Student extends Person { ... }

구조에 의한 서브타입(structure subtyping)

구조적으로 정의된 필드와 메서드가 동일하게 정의되어있다면 A는 B의 서브타입입니다.

다음의 Student는 Person 의 필드가 동일하게 정의되어있습니다. 그러므로 Student는 Person의 서브타입입니다. 반대로 Person은 Student의 no 필드가 없으므로 슈터파입이 됩니다.

interface Person {
  name: string
}

interface Student {
  no: number
  name: string
}

`매개변수`에 의한 다형성

이번장에서는 제네릭 함수, 제니릭 메서드와 같이 타입 매개변수를 통해 다형성을 만드는 기능에 대해 소개합니다.

제네릭 함수

제네릭 함수는 아래와 같이 한 개 이상의 타입 매개변수를 갖는 함수입니다.

// 차례대로 <T> 는 타입 매개변수, 매개변수 타입, 결과타입이다.
const testFun = <T> (a:T, b:T): T => { ... }

// <int> 타입인자를 통해 타입 매개변수를 설정한다.
testFuc<int>(1, 2);

왜 제네릭 함수를 사용하나요?
같은 일을 하는 함수를 타입만 다르게 하나 더 만드는 중복을 피하고 싶기 때문입니다.

제네릭 메서드

제네릭 함수와 동일하지만, 클래스 내에서 정의된다는 차이점이 있습니다.

class Person<T> {
  getName(name: T): T {
    return name
  }
}

제네릭 타입

타입에 타입 매개변수를 추가한 타입을 제네릭 타입이라합니다. List, Map 과 같은 자료구조는 제네릭 타입으로 되어있습니다. (e.g List, Map)

아래와 같이 제네릭 타입은 타입을 재사용하기 위해 사용됩니다.

// 이미지 타입의 공통된 필드를 재사용한다.
type Img<T> = T & {
  width: number
  height: number
}

T가 타입 매개변수일 때, 특정 타입으로 좁히지 않은 T 타입 부품은 아무 능력도 요구되지 않는 곳에서만 사용해야 합니다. 그렇지 않으면 그 사용 방식을 예측할 수 없기 때문입니다.

타입 챌린지

책을 읽고, 타입 챌린지를 통해 타입 검사기의 원리를 생각하면 타입을 작성해볼 수 있었습니다.

요구 조건 : Omit 제네릭 타입을 사용하지 않고 만들기

type MyOmit<T extends {}, K extends keyof T> = {
  [P in keyof T as P extends K ? never : P]: T[P]
}

/* _____________ 테스트 케이스 _____________ */
import type { Equal, Expect } from '@type-challenges/utils'

type cases = [
  Expect<Equal<Expected1, MyOmit<Todo, 'description'>>>,
  Expect<Equal<Expected2, MyOmit<Todo, 'description' | 'completed'>>>,
  Expect<Equal<Expected3, MyOmit<Todo1, 'description' | 'completed'>>>
]

T는 타입 매개변수로 object 를 확장한 타입 매개변수입니다.
타입 좁히기를 통해 객체 리터럴 타입만 인자로 넘길 수 있습니다.
K는 T의 타입 매개변수를 확장한 T 객체 리터럴에 속한 key 타입으로 확장합니다. 그러기때문에 객체 리터럴의 key에 해당되는 인자만 넘길 수 있습니다.
MyOmit 함수는 객체 리터럴의 타입 매개변수를 받아 객체 리터럴에 속한 key 중 K를 제외한 타입이다.

마치며

타입 검사기가 다형성을 원리로 동작되는 것은 알고 있었지만, 책에서 소개되고 있는 규칙들에 대해선 자세히 알지 못했습니다. 이번 기회에 알게되어 타입 작성 시 타입 오류가 발생했을때 왜 타입 오류가 발생하는지를 어느정도 유추해볼 수 있게되었습니다.

이 포스팅에서 책의 모든 내용을 담지 못했지만, 4장부터는 소개되는 동적 언어인 하스켈에서 타임 검사기의 다양한 기능이 소개됩니다. 하스켈을 사용해보지 않았기 때문에 이러한 확장된 기능이 제공되었을때 어떤식으로 사용해볼 수 있을지 무척 궁금하네요. 그리하여 다음 챕터로는 프로그래밍 언어론 이란 하스켈로 알아보는 의미구조와 타입 시스템이란 책을 읽어보려고합니다.

다크 모드 적용 및 SSR 화면 깜박임 해결 (with Gatsby)

Tue, 28 May 2024 09:35:37 GMT

들어가기에 앞서

Gatsby 를 이용해 블로그 만들기를 시작하면서, 다크 모드 적용과 UI를 빠르게 구현하기 위해서 TailwindCSS, Material UI 등 UI 라이브러리 도입을 고민했습니다. 하지만 구현해야할 페이지와 컴포넌트가 다소 적기 때문에 배보다 배꼽이 더 크다 생각되어, SCSS와 모듈 방식을 선택했습니다.

이번 포스팅에선 Gatsby 블로그 구축 과정 중 CSS를 이용해 다크 모드를 적용한 경험과 마주친 문제를 해결해나간 과정을 공유해보려고합니다.

테마 모드에 따른 색상 토큰 적용하기

일반적으로 테마 모드를 적용하는 방법은 두 가지가 있습니다.

prefers-color-schema 미디어 쿼리를 이용한 방법

장점 : CSS 만으로 테마를 구현할 수 있다.
단점 : light, dark 테마 모드만 적용 가능하고, 사용자의 시스템 설정을 무조건 따라야한다.

body 태그 class 추가하는 방법

장점 : light, dark 이외의 다른 테마 모드도 적용 가능하고, 테마 변경이 자유롭다.
단점 : CSS 만으로 제어할 수 없고, 제어를 위한 추가 스크립트를 구현해야한다.

1. `prefers-color-schema` 미디어 쿼리를 이용한 다크 모드 적용

prefers-color-scheme 는 CSS 미디어 쿼리로, prefers-color-scheme 를 통해 사용자의 화면 모드에 따라 미리 정의한 모드의 컬러가 적용됩니다.

스크립트에서 시스템 화면 모드 확인 방법

// prefers-color-scheme 미디어 쿼리 값이 `dark` 인 지 매칭
window.matchMedia('(prefers-color-scheme: dark)').matches

@media (prefers-color-scheme: dark) {
  :root {
    --bg1: #1b1b1e;
    --bg2: #f8f9fc;
    --textColor: #f8f9fc;
    --borderColor: #f8f9fc;
  }
}

미디어 쿼리를 이용해 쉽게 다크 모드를 적용할 수 있지만, 주의해야될 점이 있습니다.

prefers-color-scheme 미디어 쿼리는 몇몇 구 버전에서는 지원되지 않습니다. (브라우저 호환성 확인)
항상 시스템의 결정에 따라 컬러모드를 결정해야 한다는 한계가 있습니다.

2. body 태그에 테마 모드 값 부여하기

body 태그에 테마 클래스를 추가하여 CSS를 적용하는 방법입니다.

🙋🏻 그럼 테마별로 CSS를 여려번 작성해줘야되지않나요?!
🍎 전역 CSS 변수를 이용해 토큰을 사전에 정의한 후 해당 토큰을 이용해 CSS를 작성함으로써 CSS를 여러벌 작성해야되는 번거로움을 최소화할 수 있습니다.

적용 순서

테마별 컬러 토큰을 CSS 전역 변수로 정의.
정의한 CSS 변수를 활용해 CSS를 작성.
테마 모드 변경을 위한 스크립트를 작성.

body 태그에 CSS 변수를 정의하여 body 태그의 하위의 요소에서 정의한 변수를 사용할 수 있습니다.

body 태그의 테마 클래스에 따라 CSS 변수가 적용되므로, 컨텐츠 CSS 작성 시 정의한 토큰을 활용합니다.

body {
  -—background-color: #ffffff;
  —-text-color: #000000;
}

body.dark {
  -—background-color: #000000;
  -—text-color: #ffffff;
}

button {
  background-color: var(-—background-color);
  color: var(-—text-color);
}

테마 모드 제어

간단히 로컬 스토리지를 활용한 모드 제어 방식을 사용자 시나리오로 작성해봤습니다.

사용자 시나리오 (User Scenario)

사용자가 처음으로 웹 사이트 방문 시 시스템 모드의 테마가 적용된다.

웹 사이트는 저장된 로컬 스토리지가 있는지 확인하고, 없다면 사용자의 시스템 모드를 적용한다.
사용자가 테마 모드를 변경한다.

사용자가 선택한 모드를 로컬 스토리지에 저장한다.
웹 사이트를 종료한다.
다시 웹 사이트에 방문한다. 이때 이 전에 사용자가 변경한 테마로 적용된다.

로컬 스토리지에 저장된 값이 있다면, 해당 값으로 테마가 적용된다. 이제 테마 모드 제어를 위해 스크립트를 추가해줍니다.

이제 작성된 사용자 시나리오를 기반으로 현재 테마 모드 조회와 테마 모드 변경 함수를 구현할 수 있습니다.

먼저 테마 모드 조회 함수입니다.

matchMedia window 내장 메서드를 이용해 시스템 모드를 조회하고, 로컬 스토리지에 특정 키가 있는지 조회합니다.

마지막으로 스토리지에 특정 키가 없다면 시스템 모드 테마를, 있다면 스토리지에 저장된 테마를 반환합니다.

// 현재 테마 모드 가져오기
const getThemeMode = () => {
  // STEP 1. 로컬 스토리지 값 조회
  const localMode = localStorage.getItem('theme-mode')

  // STEP 2. 시스템 모드 값 조회
  const isSystemDarkMode = window.matchMedia('(prefers-color-scheme: dark)').matches
  const systemMode = isSystemDarkMode ? 'dark' : 'light'

  // STEP 3. 우선적으로 사용자가 설정한 로컬 스토리지 값을 가져온다.
  return localMode ?? systemMode // 로컬 스토리지 값이 없다면 시스템 모드 적용
}

테마 모드 변경 함수입니다.

인자로 넘어온 변경될 모드를 스토리지에 저장한 후, 현재 적용된 모드를 prevMode 변수에 저장합니다.

prevMode 이전 테마 모드는 body 태그 클래스에서 제거하고, 변경될 테마 모드를 body 태그에 추가해줍니다.

// 테마 모드 변경하기
const setThemeMode = mode => {
  // STEP 1. 사용자가 설정한 모드를 로컬 스토리지에 저장
  localStorage.setItem(mode)

  // STEP 2. 설정한 모드로 body 태그에 클래스를 추가/삭제한다.
  const prevMode = mode === 'light' ? 'dark' : 'light'
  window.document.body.classList.remove(prevMode)
  window.document.body.classList.add(mode)
}

이제 첫 렌더링 시 테마 적용을 위한 hook을 추가해줍니다.

getThemeMode 함수를 통해 현재 테마 모드를 가져오고, body 태그에 클래스를 추가해줍니다.

페이지 첫 접근 시 적용된 테마 설정

useEffect(() => {
  // STEP 1. 현재 테마 모드 가져오기
  const currentMode = getThemeMode()

  // STEP 2. body 태그에 class 추가
  window.document.body.classList.add(currentMode)

  // STEP 3. 로컬 스토리지에 테마 모드 값 갱신
  localStorage.setItem('theme-mode', currentMode)
}, [])

서버 사이드 환경(SSR)에서 다크 모드 적용 시 화면 깜박임 해결

마지막으로 CSR과 SSR의 상태가 달라 발생하는 화면 깜박임 오류에 대해 다뤄보려고합니다.

💣 서버가 터졌습니다..

Gatsby 는 정적으로 페이지를 생성하는 SSG 방식을 사용합니다. v4가 공개되고부터는 SSG 방식 외에도 서버 사이드 렌더링(SSR) 방식 또한 지원합니다.

Gatsby 로컬 서버는 CSR 방식으로 동작되기 때문에 발생하지 않았던 오류가 실제 서버에 반영되었을때 발생한 것이였습니다..

먼저 오류를 해결하기 위해서 로컬 서버에서도 SSR 로 동작되어야하는데, 다행이 Gatsby 에서는 로컬 서버에서도 SSR 로 동작될 수 있게 옵션을 제공합니다.

gatsby-config.js 파일에 DEV_SSR옵션을 추가해줍니다.

module.exports = {
  // ...
  flags: {
    // NOTE: 로컬 서버에서 SSR 확인을 위해 true 로 변경
    DEV_SSR: true,
  },
  // ...
}

❌ localStorage is not undefined

localStorage 는 브라우저에서만 사용 가능한 API이기 때문에 예외 처리가 필요합니다.

localStorage 예외 처리 방법

if (typeof window !== undefined) { ... }

화면 깜박임 현상 (Screen Flickering)

사용자는 dark 테마를 선택했지만, 초기 테마 모드가 light이기 때문에 화면 깜박임이 발생합니다.

SSR과 CSR의 상태가 다르기 때문인데, 하이드레이팅되는 시점에 light -> dark 테마로 변경되기 때문입니다. 실제 서버에서 html를 생성하는 시점에는 typeof window !== undefined 로 모드 적용 코드가 예외 처리되었기 때문에 서버에서는 light 테마의 html 를 생성합니다. 그 후 하이드레이팅되며 테마가 적용되었기 때문에 화면 깜박임 현상이 발생하는 것입니다.

이를 해결하기 위해선 SSR과 CSR의 상태를 매칭해줘야하는데, 테마를 적용하는 로직을 스크립트 최상단에서 먼저 실행함으로써 해결할 수 있다.

화면의 첫 진입점인 index.html 내에 스크립트를 추가하여 초기 모드 값을 가져와 세팅한다. gatsby 에선 gatsby.ssr.js 파일에서 dom이 페인팅되기 전에 스크립트를 먼저 실행되도록 추가해주었다.

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    ...
  </head>
  <body>
    <script>
      const localThemeMode = localStorage.getItem('${THEME_KEY}')
      const systemThemeMode = window.matchMedia('(prefers-color-scheme: dark)').matches
        ? 'dark'
        : 'light'

      const currentMode = localThemeMode ?? systemThemeMode
      document.body.classList.add(currentMode)
    </script>
    <div id="root"></div>
  </body>
</html>

gatsby.ssr.js

/**
 * @type {import('gatsby').GatsbySSR['onRenderBody']}
 */
export const onRenderBody = ({ setHtmlAttributes, setPreBodyComponents }) => {
  const preloadScript = `
    const localThemeMode = localStorage.getItem('${THEME_KEY}')
    const systemThemeMode = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'

    const currentMode = localThemeMode ?? systemThemeMode
    document.body.classList.add(currentMode)
  `

  setHtmlAttributes({ lang: `en` })
  setPreBodyComponents(<script dangerouslySetInnerHTML={{ __html: preloadScript }} />)
}

마지막으로 페이지 첫 렌더링 시 초기값을 적용하기 위해 useEffect hook 을 수정합니다.

body 에 추가된 테마 클래스를 가져와 SSR과 CSR 테마 상태를 hydration 해줍니다.

useEffect(() => {
	// STEP 1. 현재 테마 모드 가져오기
	const currentMode = getThemeMode()

	// STEP 2. body 태그에 class 추가
	window.document.body.classList.add(currentMode)

	// STEP 3. 로컬 스토리지에 테마 모드 값 갱신
	localStorage.setItem('theme-mode', currentMode)

  useEffect(() => {
    // NOTE: 브라우저 환경에서만 실행
    if (isBrowser) {
      const currentMode = window.document.body.classList.contains(THEME_MODE.DARK)
        ? THEME_MODE.DARK
        : THEME_MODE.LIGHT
      setTheme({ ...theme, mode: currentMode })
    }
  }, [])

마치며

CSS 를 이용해 다크 모드를 적용하는 방법에 대해 정리해보았습니다.

개발을 하다보면 스펙에 비해 과도한 성능과 유지보수의 부담으로 다양한 상황에 유연하게 대응하기 위해서 자체적으로 개발해야될때가 올 것입니다.

"바퀴를 다시 발명하지 마라"라는 말과 같이 미리 만들어진 바퀴는 개발 시간을 단축시킬 수 있지만, 때로는 우리가 바퀴를 발명해야 할 필요성을 느낄 때도 있습니다.

이러한 순간에는 순수한 개발에 집중하여, HTML, CSS, JavaScript만을 사용하여 개발할 수 있어야 합니다.

참고

Mixin의 한계와 Composition API 도입

Tue, 14 May 2024 15:04:55 GMT

믹스인(Mixin) 란?

믹스인(mixin)은 소프트웨어 개발 원칙 중 DRY(Do not Repeat Yourself) 원칙을 지키기 위해 만들어졌습니다.

DRY는 중복을 배제하는 개념으로 같은 정보의 중복을 지양하라 이러한 원칙을 통해 믹스인이 설계되었습니다. 믹스인은 여러 컴포넌트 간에 공통된 기능을 분리하여 하나의 mixin 으로 컴포넌트간의 기능을 공유할 수 있도록 합니다.

Vue.js 3에서 믹스인 사용이 권장되지 않는 이유

이러한 믹스인은 겉으로 봤을땐 코드 재사용성과 확장성에 용이하다는 이점이 있지만, 근본적인 단점이 존재합니다.

네이밍스페이스 충돌
암시적 mixin간의 충돌
불분명한 출처
예측하지 못한 사이드 이펙트 발생 우려

믹스인은 암시적으로 data, method, life cycle hook 를 컴포넌트에 등록합니다. 이로 인해 네임스페이스 충돌이 발생하고, 코드의 추적이 어려워질 수 있습니다.

또한 컴포넌트와 믹스인 사이에 동일한 라이프 사이클을 가졌을때, 모두 실행되기 때문에 동시성 문제을 야기할 수 있습니다.

vue3 공식문서 또한 이러한 문제를 들어 Mixin 을 지양하고, Composition API 사용을 권장하고있습니다.

Composition API의 등장

Composition API 란?

Composition API는 Vue.js 3에서 도입된 새로운 API입니다.

기존 믹스인의 장점인 재사용성을 유지하며, 컴포넌트 로직을 더 유연한 코드 구조를 제공합니다.

믹스인과 Composition API 비교해보기

코드 재사용

믹스인은 컴포넌트 간에 코드를 공유하는 반면, Composition API는 함수를 통해 로직을 공유합니다.

코드 충돌

믹스인은 data, method의 이름과 life cycle hook 을 통해 충돌이 발생할 수 있고, Composition API는 함수의 스코프를 이용하기 때문에 이러한 문제를 방지합니다.

코드 구조화

믹스인은 컴포넌트의 옵션을(data, methods, life cycle hook) 기반으로 코드를 구조화하지만, Composition API는 로직(기능)을 기반으로 코드를 구조화합니다. 이로 인해 비슷한 관심사의 로직의 캡슐화와 응집도를 높일 수 있습니다.

불분명한 출처(명시성)

믹스인은 컴포넌트에 암시적으로 기능을 추가하는 반면, Composition API는 명시적으로 기능을 추가합니다. 이로 인해 로직이의 가독성이 향상되고, 로직을 쉽게 추적할 수 있습니다.

러닝 커브

믹스인은 기존 Vue.js 2에서 제공한 기능이며, 기존의 Vue.js 사용 경험이 있다면 쉽게 익힐 수 있습니다. Composition API는 Vue.js 버전 3에서 새로 등장한 개념 및 패턴으로 기존의 옵션 기반 AP에 익숙한 개발자들에게는 생소할 수 있습니다. 하지만 React.js 를 기본적으로 학습하는 프론트엔드 개발자로써는 오히려 더 쉽게 다가올 수 있는 개념이라고 생각합니다.

따라서, Composition API는 믹스인의 이점을 유지하면서도 더욱 명확하고 유연한 코드 구조를 제공하므로, Vue.js 3에서는 믹스인 대신 Composition API 사용을 권장하고 있습니다.

코드를 통해 Mixin과 Composition API 살펴보기

e.g. 멤버 정보 조회하는 API

Composition API

// useMemberInfo.js
import { ref, onMounted } from 'vue'

export const useMemberInfo = () => {
  const [memberInfo, setMemberInfo] = ref({
    email: '',
    nickName: '',
    phoneNumber: '',
  })

  const getMemberInfo = async () => {
    // 멤버 정보 조회 API 호출
  }

  onMounted(() => {
    getMemberInfo()
  })

  return {
    memberInfo,
    getMemberInfo,
  }
}

// Component.vue
import { useMemberInfo } from './useMemberInfo'

export default {
  setup() {
    // 명식적으로 data, method 가 정의된다.
    const { memberInfo, getMemberInfo } = useMemberInfo()

    onMounted(() => {
      console.log(memberInfo.value)
    })

    return { memberInfo, getMemberInfo }
  },
}

mixin

// mixin.js
export const memberInfoMixin = () => {
  data() {
    return {
      memberInfo: {
        email: '',
        nickName: '',
        phoneNumber: '',
      }
    }
  },
  methods: {
    getMemberInfo() {
      // 멤버 정보 조회 API 호출
    }
  },
  created() {
    getMemberInfo()
  }
}

// Component.vue
import { memberInfoMixin } from './mixin'

export default {
  mixins: [memberInfoMixin],
  data() {
	  return {
		  // mixin 내에 암시적으로 data, method 가 정의된다.
		  memberInfo: null // ❗️ 코드 충돌
	  }
  },
  created() {
	// mixin life cycle hook이 먼저 호출되기 때문에 this.memberInfo 는 null 이다.
    console.log(this.memberInfo); // null
  }
}

Mixin을 Composition API 로 교체하기

믹스인 사용하는 방식은 회사의 다릅니다. 이 전 회사에서는 믹스인이 여러곳에서 재사용할 수 있다는 장점을 이용해 유틸리티성 함수까지 믹스인에 작성되어있었습니다. 하지만 600 라인이 넘어가는 믹스인 파일들과 this의 출처를 추적하기 불편하고, 네이밍스페이스 충돌로 인한 사이드 이펙트까지 발생하여 기존 팀원들과 논의 후 점진적으로 리팩터링하기로 결정했었습니다.

마침 vue3 마이그레이션을 진행 중이기도 해서, Composition API로의 교체까지 고려하여 리팩터링 단계를 계획했습니다.

메서드의 역할 분리

첫번째 단계로 믹스인의 믹스인내의 메서드들의 역할을 구분했습니다.

유틸리티성 메서드
도메인 로직과 연관된 메서드
Options API를 포함한 메서드

위와 같은 역할의 메서드를 분리하여 아래와 같이 분리 작업을 진행했습니다.

유틸리티성 메서드 -> /utils 폴더로 이동
도메인 로직과 연관된 메서드 -> /features 폴더 추가 후 이동
Options API를 포함한 메서드 -> 추후 Vue3 마이그레이션 시 Composition API로 교체

위와 같은 방식으로 점차적으로 믹스인 함수를 걷어내고, 각 관심사에 맞게 구조를 변경해나갔습니다. 당연히 믹스인을 보존하거나, Composition API로 교체하거나, 또 다른 방식으로 리팩터링하는 방법이 있을 것입니다. 팀원들과 충분한 논의를 통해 알맞은 방법을 선택해나가야합니다.

참고

Formatter 당신의 선택은?

Fri, 29 Dec 2023 21:00:37 GMT

Deprecation of formatting rules - ESLint - Pluggable JavaScript Linter

포맷팅 규칙 관리의 부담감

ESLint 는 기존에 정적 코드 분석 + 코드 포맷팅 기능을 지원해왔습니다.

코드 포맷팅 기능이란 사용자가 미리 정의해놓은 규칙으로 자동 정렬해주는 기능을 말합니다.

ESLint는 JavaScript의 큰 성장과 동시에 인기가 증가함에 따라 유지 관리에 점차 부담이 가기 시작했습니다. ESLint 팀은 JavaScript 빠른 성장에 맞춰 구문의 변화에 따라가고자 기존의 규칙을 업데이트하거나, 새로운 규칙을 추가해달라는 요청이 쇄도했고, 점차 유지 보수에 부담이 가고, 벅찬 지경까지 오게 되었다고 합니다.

이에 따라 ESLint는 하나의 목표인 정적 코드 분석에 집중하기 위해 코드 포맷팅 기능을 제거하기로 결정을 내렸습니다. 결정을 내리게 된 것 중 하나는 이미 시중에 전용 코드 포맷터 라이브러리들이 편중화되어 있기 때문이었다고 합니다.

포맷팅 규칙 제거로 인한 대체방안

ESLint 팀에서는 포맷 규칙이 제거됨에 따라 이를 대체하기 위해 전문 코드 포맷터를 도입하는 것을 제안합니다.

아래는 ESLint 팀에서 제안한 코드 포맷터입니다.

Prettier
DPrint
ESLint Stylistic

Prettier

포맷팅 전문 라이브러리.
포맷팅에 전문화되어있기 때문에 세세한 규칙들까지 적용되어있다.

DPrint

Rust 기반 포맷팅 전문 라이브러리.
Prettier와 거의 유사하고, 속도가 빠르다.

ESLint Stylistic

ESLint에서 제거된 포맷팅 관련 규칙들을 모아놓은 라이브러리.
기존에 포맷팅 규칙을 사용한 프로젝트에서 제거된 규칙들을 해당 라이브러리를 통해 사용 가능하다.
각각의 규칙에 대해 옵션을 지정할 수 있으며 총 91가지의 규칙을 제공한다.

코드 포맷터 선호도 조사

실제로 Prettier 가 시중에 많이 사용되고 있고, 기존 ESLint 포맷터를 사용하던 사용자들은 ESLint Stylistic 도입을 고려할 것으로 유추됩니다.

Link : Prettier vs ESLint Stylistic vs DPrint

ESLint Stylistic 을 선택한 이유

ESLint Stylistic 을 선택한 이유는 기존에 코드 컨벤션이 어느정도 잡혀있었기 때문에 변경점을 최소화하며 팀 내의 규칙을 세밀하게 정할 수 있기 때문에 선택하게 되었습니다.

DPrint는 적용 사례가 많지 않고, 사실상 ESLint Stylistic과 Prettier 사이에서 고민을 했었는데, 아래는 그 당시 두 포맷터의 장/단점을 정리한 내용입니다.

Prettier

기존 프로덕트들에서 Prettier 가 쉽게 사용되기 때문에, 신규 입사자분이 오셨을때 해당 규칙에 더 익숙하다.
다른 포맷터들에 비해 더 오래된 전문 포맷터로, 세세한 규칙들가지 적용해준다.
printWidth 규칙 논쟁과 제한적으로 제공하는 규칙들

ESLint Stylistic

기존 규칙들을 반영하여 변경점을 최소화할 수 있다.
90개 이상의 규칙을 제공하며, 팀 내에서 원하는 코드 스타일을 적용할 수 있다.
세세한 포맷팅까지 해주진 않는다. (Prettier 는 규칙을 제한적으로 제공하는 대신 세세한 규칙들을 자동으로 포맷팅해준다의 차이..?)

결론적으로 ESLint Stylistic을 채택했고, 기존 컨벤션을 재정비하며 90개 이상의 규칙들을 논의하는 자리를 가졌습니다. ESLint Stylistic 은 아직 점유율이 낮은편이고, 곧 많은 사람들이 넘어와 기여를 통해 더 높은 품질의 코드 포맷터가 될 것이라고 생각합니다.

ESLint Stylistic 컨트리뷰터가 되었습니다!

마치며

이전 회사에서는 Prettier를 사용하며 코드 스타일에 대한 고민 없이 개발에 집중할 수 있었습니다. 하지만 ESLint만으로 구성된 현재 프로젝트에 참여하면서, 개발자마다 다른 코드 스타일로 인해 PR 코멘트가 빈번했고 리뷰 시간이 늘어나는 경험을 했습니다. 포맷팅 이슈가 앞으로의 유지보수까지 고려해야 하는 중요한 논의 주제가 되었고, 이를 통해 자동화된 코드 포맷터의 중요성을 다시 한번 실감하게 되었습니다.

이번 작업으로 코드 스타일에 대한 코멘트가 줄어들었고, ESLint Stylistic의 90개 이상의 규칙을 팀원들과 같이 논의하며 규칙들 하나하나에 대해 알아보고 적용하는 과정이 매우 흥미로운 경험이었습니다.

Gatsby Starter Blog RSS Feed

운영 환경에서 소스맵 적용으로 Sentry 오류 추적 개선하기

Sentry Wizard를 통한 소스 맵 적용

번들러 또는 빌드 도구를 통해 소스 맵 수동 업로드

1. Sentry Auth Token 발급

2. Sentry 플러그인 설치

3. Sentry 플러그인 설정

소스 맵 업로드 시 주의해야될 점

1. 소스 맵 업로드 과정 훑어보기

2. 소스 맵 생성과 Sentry 업로드는 동일한 조건으로 실행되어야 한다

소스 맵 적용 전 / 소스 맵 적용 후

마무리

[Book Review] 타입으로 견고하게 다형성으로 유연하게

첫 단원 요약

타입 검사의 장점

다형성

다형성 규칙 한 번에 보기

서브타입에 의한 다형성 규칙

이름과 구조에 의해 결정되는 서브타입

매개변수에 의한 다형성

제네릭 함수

제네릭 메서드

제네릭 타입

타입 챌린지

마치며

다크 모드 적용 및 SSR 화면 깜박임 해결 (with Gatsby)

들어가기에 앞서

테마 모드에 따른 색상 토큰 적용하기

1. prefers-color-schema 미디어 쿼리를 이용한 다크 모드 적용

2. body 태그에 테마 모드 값 부여하기

테마 모드 제어

서버 사이드 환경(SSR)에서 다크 모드 적용 시 화면 깜박임 해결

❌ localStorage is not undefined

화면 깜박임 현상 (Screen Flickering)

마치며

참고

Mixin의 한계와 Composition API 도입

믹스인(Mixin) 란?

Vue.js 3에서 믹스인 사용이 권장되지 않는 이유

Composition API의 등장

Composition API 란?

믹스인과 Composition API 비교해보기

코드를 통해 Mixin과 Composition API 살펴보기

Mixin을 Composition API 로 교체하기

참고

Formatter 당신의 선택은?

포맷팅 규칙 관리의 부담감

포맷팅 규칙 제거로 인한 대체방안

Prettier

DPrint

ESLint Stylistic

코드 포맷터 선호도 조사

ESLint Stylistic 을 선택한 이유

Prettier

ESLint Stylistic

마치며

`이름`과 `구조`에 의해 결정되는 서브타입

`매개변수`에 의한 다형성

1. `prefers-color-schema` 미디어 쿼리를 이용한 다크 모드 적용