i18next 기반 프로젝트에서 국제화 작업을 진행하고 있었습니다. 한국어 텍스트를 하나씩 번역 키로 옮기다 보니, 이런 게 눈에 들어왔습니다.

"deleteModalDescription": "{{name}}을/를 삭제하시겠습니까?"

{{name}}에 들어올 단어에 따라 을이 맞을 수도, 를이 맞을 수도 있습니다. 그러면 이걸 쓰는 곳마다 사용부에서 직접 분기해야 하나? 싶었습니다.

모든 페이지를 국제화해야 하는 상황에서 이렇게 DX가 안 좋을 리 없다고 생각했고, 이 문제를 좀 파보게 되었습니다. 한국어의 조사 문제였습니다.

왜 이게 문제가 되는가

한국어는 앞 글자의 받침(종성) 유무에 따라 조사가 달라집니다.

보통은 문제가 되지 않습니다. 글을 쓰는 시점에 앞 단어를 알고 있으니까요.

그런데 i18n에서는 상황이 다릅니다. {{name}}에 "모델"이 올지 "도구"가 올지는 런타임에 결정됩니다. 번역 키를 작성하는 시점에는 어떤 조사가 맞는지 알 수가 없습니다.

영어에는 이 문제 자체가 없습니다. "Delete {{name}}"은 name에 뭐가 오든 문법이 동일하거든요. 한국어-영어 다국어 프로젝트에서 한국어 쪽만 이 짐을 안게 되는 셈이죠.

그렇다면 프로젝트에서는 이 문제를 어떻게 다루고 있었을까요?

프로젝트에서 발견한 세 가지 패턴

ko.json을 더 살펴보니, 이 문제를 나름대로 회피하려는 세 가지 패턴이 섞여 있었습니다.

패턴 1. 슬래시 표기: "을/를"을 그대로 노출

"deleteModalDescription": "{{agentName}}을/를 삭제하시겠습니까?"

가장 흔한 패턴이었습니다. 양쪽 다 써놓으면 틀릴 일은 없으니까요. 하지만 "을/를"이 화면에 그대로 나옵니다. UI가 비전문적으로 느껴지는 게 가장 큰 문제였습니다.

패턴 2. 하드코딩된 단일 조사: 특정 단어에서만 맞음

"fieldPlaceholder": "{{name}}를 입력하세요"

"를"로 고정해뒀는데, name에 "설명"이 들어오면 "설명를"이 됩니다. 받침 있는 단어에서 무조건 틀리죠. 아마 처음 작성할 때 테스트한 단어가 받침 없는 단어였을 겁니다.

패턴 3. 키 2개로 분리: 유지보수 부담

"selectFieldPlaceholder": "{{name}}을 선택하세요",
"selectFieldPlaceholder2": "{{name}}를 선택하세요"

가장 정직한 접근이지만, 호출하는 쪽에서 받침 판단을 직접 해야 합니다. 컴포넌트마다 "이 단어는 받침이 있으니 1번 키, 저 단어는 없으니 2번 키"라는 분기 코드가 들어가고, 조사가 필요한 키가 늘수록 키도, 판단 로직도 같이 불어납니다.

세 패턴 모두 근본적인 해결은 아니었습니다. 제가 원한 건 번역 키 하나로, 런타임에 올바른 조사를 자동 선택하는 것이었습니다. 거기에 영어 번역에는 아무 영향을 주지 않아야 했고요.

세 가지 접근법을 비교하다

i18next 생태계에서 이 문제를 해결하는 방법은 크게 세 가지가 있었습니다.

접근법 1. Formatter 커스텀

i18next의 내장 format 함수를 오버라이드하는 방식입니다.

"selectPlaceholder": "{{name, 을}} 선택하세요"

보간 구문 안에 조사 힌트를 넣고, format 함수에서 받침을 판별해 올바른 조사를 반환합니다. 조사를 하나만 쓰면 되니 구문은 간결합니다. 다만 i18next의 기존 formatter와 충돌할 수 있고, 날짜 포맷 같은 다른 format 기능과 조사 처리가 한 함수에 얽히게 되는 점이 걸렸습니다.

접근법 2. Post-Processor 직접 구현

i18next가 보간을 완료한 뒤, 후처리 단계에서 조사를 교체하는 방식입니다.

"selectPlaceholder": "{{name}}(을/를) 선택하세요"

보간이 끝난 문자열을 정규식으로 순회하면서, (을/를) 앞 글자의 받침을 보고 올바른 쪽을 고릅니다. 보간 시스템과 완전히 분리되니 충돌 걱정은 없습니다. 대신 양쪽 조사를 다 써야 하고, 받침 판별 로직과 엣지 케이스(숫자, 영어, 괄호 등)를 직접 챙겨야 합니다.

접근법 3. 검증된 라이브러리 도입

찾아보니 i18next-korean-postposition-processor라는 npm 패키지가 이미 있었습니다. Post-Processor 방식인데, 직접 구현 대신 검증된 코드를 가져다 쓰는 겁니다.

"selectPlaceholder": "{{name}}[[를]] 선택하세요"

조사를 하나만 쓰면 됩니다. [[를]]이라고 쓰면 앞 글자의 받침에 따라 "을" 또는 "를"로 자동 변환됩니다. 숫자나 괄호로 감싸진 텍스트 같은 엣지 케이스도 이미 처리되어 있었습니다. 이 라이브러리가 내부적으로 받침을 어떻게 판별하는지는 뒤에서 따로 살펴봅니다.

어떤 걸 선택했는가

최종적으로 라이브러리를 도입하기로 했습니다. 받침 판별이라는 문제는 이미 잘 정의되어 있고, 검증된 구현체가 있는데 굳이 직접 만들 이유가 없었습니다.

Formatter 방식도 구문이 간결해서 끌렸지만, 결정적으로 처리 시점이 달랐습니다. Formatter는 보간 값 자체를 변환하는 단계에서 동작합니다. {{name, 을}}에서 name 값을 받아 조사를 붙인 결과를 돌려주는 방식인데, 이러면 format 함수 하나가 날짜 포맷, 숫자 포맷, 조사 처리를 전부 분기해야 합니다.

반면 Post-Processor는 보간이 끝난 완성된 문자열을 받습니다. "모델[[를]] 선택하세요"처럼 이미 보간이 끝난 상태에서, [[를]] 앞 글자만 보고 조사를 결정하면 됩니다. 기존 format 로직에 영향을 주지 않고, 조사 처리는 어차피 "앞 글자가 확정된 뒤"에야 할 수 있는 작업이니까 Post-Processor가 더 자연스러운 시점이라고 판단했습니다.

구현 과정

바꿔야 할 파일은 4개(package.json, pnpm-lock.yaml, i18n.ts, ko.json), 세 단계로 끝났습니다.

1단계. 설치

pnpm add i18next-korean-postposition-processor

2단계. 플러그인 등록

기존 i18n 설정에 두 줄만 추가하면 됩니다.

// src/lib/i18n/i18n.ts
import koreanPostpositionProcessor from 'i18next-korean-postposition-processor';

i18n
  .use(initReactI18next)
  .use(koreanPostpositionProcessor) // 추가
  .init({
    // ... 기존 설정 유지
    postProcess: ['korean-postposition'], // 추가
  });

여기서 한 가지 주의할 게 있습니다. postProcess 배열에 넣는 이름 'korean-postposition'은 라이브러리 소스의 get name()에서 정의된 값입니다. 이 이름이 틀리면 아무 동작도 하지 않으니, 라이브러리의 실제 name 속성을 꼭 확인해야 합니다.

3단계. 번역 키 마이그레이션

ko.json에서 기존 조사 관련 키들을 [[조사]] 구문으로 바꿨습니다. 규칙은 단순합니다. 기존 조사 자리를 [[조사]]로 감싸면 됩니다.

// 하드코딩 조사 → [[조사]]
"{{name}}를 입력하세요"       →  "{{name}}[[를]] 입력하세요"
"새로운 {{item}}가 생성되었습니다."  →  "새로운 {{item}}[[가]] 생성되었습니다."

// 슬래시 표기 → [[조사]]
"{{agentName}}을/를 삭제하시겠습니까?"  →  "{{agentName}}[[를]] 삭제하시겠습니까?"

[[를]]이든 [[을]]이든 상관없습니다. 앞 글자의 받침에 따라 알아서 올바른 형태로 바뀝니다.

이 작업을 하면서 하나 더 정리한 게 있습니다. 기존에는 "를 입력하세요", "을 선택하세요" 같은 placeholder가 컴포넌트마다 따로 있었는데, 공통 키 두 개로 통합했습니다.

"selectPlaceholder": "{{name}}[[을]] 선택하세요",
"inputPlaceholder": "{{name}}[[을]] 입력하세요"

사용하는 쪽에서는 이렇게 쓰면 됩니다.

commonT('selectPlaceholder', { name: t('model') })
// → "모델을 선택하세요"

en.json은 손대지 않았습니다. [[]] 패턴이 없는 문자열은 post-processor가 그냥 통과시키거든요.

라이브러리는 어떻게 동작하는가

앞에서 "엣지 케이스가 이미 처리되어 있다"고 했는데, 실제로 어떤 과정인지 궁금해서 라이브러리 내부를 들여다봤습니다.

1. i18next가 {{name}}을 보간해서 "모델[[를]] 선택하세요"라는 문자열을 만듭니다.
2. post-processor가 정규식으로 [[를]]을 찾습니다.
3. [[를]] 바로 앞 글자 '델'의 유니코드를 분석합니다.

한글 유니코드에서 받침을 판별하는 공식은 (charCode - 0xAC00) % 28입니다. 결과가 0이면 받침 없음, 0이 아니면 받침 있음. 생각보다 단순한 산술 연산 하나로 끝나는 게 인상적이었습니다.

'델'의 코드포인트는 0xB378이고, (0xB378 - 0xAC00) % 28 = 8이니까 받침이 있다고 판별됩니다. 받침이 있으니 를 대신 을이 선택되고, 최종 출력은 "모델을 선택하세요"가 됩니다.

숫자는 한국어 발음 규칙을 따릅니다. "3"은 "삼"으로 읽히니 받침이 있고, "2"는 "이"로 읽히니 받침이 없는 식이죠. "모델"처럼 따옴표나 괄호로 감싸진 텍스트는 괄호 안의 마지막 문자를 기준으로 판별합니다. 직접 구현했다면 이런 케이스를 하나씩 테스트하고 처리해야 했을 텐데, 라이브러리를 선택한 이유가 여기에 있었습니다.

마치며

처음에 ko.json에서 발견한 "을/를"이 화면에 그대로 찍히던 문제(슬래시 표기, 하드코딩 조사, 키 분리)는 결국 같은 원인이었습니다. 런타임에 결정되는 보간 값의 받침을 번역 키 작성 시점에 알 수 없다는 것이죠.

세 가지 접근법을 비교하고, 구현 비용과 검증도를 기준으로 라이브러리를 도입했습니다. 하드코딩 텍스트를 i18n으로 옮기는 작업과 함께 조사 처리까지 한 PR로 정리할 수 있었습니다. "사용부마다 조사를 직접 분기해야 하나?"라는 처음의 DX 고민은 번역 키에 [[조사]]를 쓰는 것만으로 해소되었고, 이제 "을/를"이 화면에 나오는 일도 없어졌습니다.

앞으로 새 번역 키를 작성할 때는 이렇게 쓰면 됩니다.

// ko.json
"message": "{{name}}[[를]] 삭제하시겠습니까?"

// en.json - 변경 없음
"message": "Do you want to delete {{name}}?"

지원되는 조사는 [[을]] [[를]] [[은]] [[는]] [[이]] [[가]] [[과]] [[와]] [[으로]] [[로]] [[이랑]] [[랑]]이고, 어느 쪽을 써도 알아서 올바른 형태로 변환됩니다.

다만 이 방식은 i18next의 post-processor로 동작하기 때문에 i18next 없이는 쓸 수 없습니다. 순수 유틸리티 함수가 필요하다면 Toss의 slash josa나 hangul-postposition 같은 독립 라이브러리도 있습니다.

그리고 [[]] 구문은 번역자에게 익숙하지 않을 수 있습니다. 팀 내에서 번역 키 작성 규칙으로 공유하고, 이 구문의 의미를 문서화해두는 게 좋겠다고 느꼈습니다.

참고 자료

• i18next-korean-postposition-processor (GitHub)
• Toss slash josa 유틸리티
• hangul-postposition (npm)

interface State {
  user?: { name: string };
}

function showGreeting(state: State) {
  if (state.user) {
    setTimeout(() => {
      console.log(`안녕하세요, ${state.user.name}님!`);
      // ❌ 'state.user' is possibly 'undefined'
    }, 100);
  }
}

"분명 if문에서 체크했는데, 왜 아직도 undefined인가?"

TypeScript를 사용하다 보면 이런 상황을 만나게 됩니다. 존재 여부를 확인했는데, 바로 다음 줄에서 "undefined일 수도 있다"고 말하는 TypeScript. 처음에는 버그인 줄 알았습니다.

그런데 지역 변수에 담으면 에러가 사라집니다.

function showGreeting(state: State) {
  const user = state.user;
  if (user) {
    setTimeout(() => {
      console.log(`안녕하세요, ${user.name}님!`); // ✅ 정상 동작
    }, 100);
  }
}

같은 값인데, 왜 결과가 다를까요?

이 글에서는 TypeScript가 왜 우리 코드를 "의심"하는지, 그 뒤에 숨은 설계 철학을 살펴보겠습니다.

Type Narrowing 복습

Type Narrowing이 처음이라면 이전 글: if문 하나로 TypeScript가 똑똑해지는 이유를 먼저 읽어보시기 바랍니다.

TypeScript는 코드의 흐름을 분석해서 타입을 좁혀나갑니다. 이를 Control Flow Analysis라고 부릅니다.

function greet(value: string | number) {
  if (typeof value === 'string') {
    console.log(value.toUpperCase()); // string으로 좁혀짐
  } else {
    console.log(value.toFixed(2)); // number로 좁혀짐
  }
}

if문을 통과하면 TypeScript가 타입을 좁혀줍니다. 덕분에 타입 단언 없이도 안전하게 코드를 작성할 수 있습니다.

그런데 이 기능이 어떤 상황에서는 왜 제대로 동작하지 않는 걸까요?

TypeScript의 의심, 그 합리적인 이유

결론부터 말하면, TypeScript는 "지금 체크한 값이 나중에 쓸 때도 같을까?"를 의심합니다.

"체크하고 바로 쓰는데 뭐가 바뀌는가?"라고 생각할 수 있습니다. React 개발에서 자주 겪는 상황들을 살펴보겠습니다.

상황 1: props로 받은 객체의 프로퍼티

interface ChatState {
  connection?: WebSocket;
  messages: Message[];
}

function ChatRoom({ state }: { state: ChatState }) {
  const sendMessage = (text: string) => {
    if (state.connection) {
      // 이 시점: connection이 있음

      setTimeout(() => {
        // ❌ 'state.connection' is possibly 'undefined'
        state.connection.send(text);
      }, 100);
    }
  };
}

state.connection을 체크했지만, setTimeout 콜백 안에서 다시 접근하면 에러가 발생합니다. 부모 컴포넌트에서 state를 업데이트하면 connection이 undefined가 될 수 있기 때문입니다.

상황 2: 외부 store나 전역 객체

// Zustand나 전역 상태를 직접 참조하는 경우
const authStore = {
  user: null as User | null,
  logout() { this.user = null; }
};

function UserGreeting() {
  const handleClick = () => {
    if (authStore.user) {
      // 이 시점: user가 있음

      setTimeout(() => {
        // ❌ 'authStore.user' is possibly 'null'
        console.log(`안녕하세요, ${authStore.user.name}님!`);
      }, 100);
    }
  };
}

authStore.user를 체크했지만, setTimeout이 실행되기 전에 다른 곳에서 logout()이 호출될 수 있습니다. TypeScript는 이 가능성을 인식하고 에러를 냅니다.

상황 3: ref.current는 언제든 바뀔 수 있다

function VideoPlayer() {
  const videoRef = useRef<HTMLVideoElement | null>(null);

  const handlePlay = () => {
    if (videoRef.current) {
      // 이 시점: video 엘리먼트가 있음

      someAsyncOperation().then(() => {
        // 🤔 이 사이에 조건부 렌더링으로 video가 사라졌다면?
        videoRef.current.play();
      });
    }
  };
  // 조건에 따라 video가 렌더링되거나 안 될 수 있음
  return showVideo ? <video ref={videoRef} /> : <div>영상 없음</div>;
}

ref.current는 DOM이 업데이트되면 언제든 바뀔 수 있습니다. if로 체크한 시점과 실제 사용 시점이 다르면 null일 수 있습니다.

왜 TypeScript는 이렇게 설계됐을까?

TypeScript 팀의 입장은 다음과 같습니다:

"각 프로퍼티 접근이 다른 값을 반환할 수 있다고 가정하는 것이 유일하게 안전한 방법입니다."

React의 상태는 언제든 바뀔 수 있고, ref는 DOM과 함께 변하고, 비동기 작업은 "나중에" 실행됩니다. TypeScript는 이 모든 가능성을 고려해서 런타임 에러보다는 컴파일 타임의 불편함을 선택한 것입니다.

보수적으로 느껴질 수 있지만, 이것은 버그가 아니라 의도적인 설계 결정입니다.

언제 TypeScript가 의심할까?

모든 상황에서 의심하는 것은 아닙니다. 패턴을 알아두면 도움이 됩니다.

의심하는 경우: 나중에 실행되는 코드

if (state.user) {
  // ❌ setTimeout 콜백
  setTimeout(() => {
    console.log(state.user.name); // 에러
  }, 100);

  // ❌ 배열 메서드 콜백
  items.forEach(() => {
    console.log(state.user.name); // 에러
  });

  // ❌ 이벤트 핸들러
  button.addEventListener('click', () => {
    console.log(state.user.name); // 에러
  });

  // ❌ Promise 콜백
  fetchData().then(() => {
    console.log(state.user.name); // 에러
  });
}

이 코드들의 공통점은 모두 "나중에 실행되는" 콜백 함수라는 점입니다.

의심하지 않는 경우: 바로 실행되는 코드

if (state.user) {
  // ✅ 바로 다음 줄
  console.log(state.user.name);

  // ✅ 함수 호출 후에도
  doSomething();
  console.log(state.user.name);

  // ✅ await 후에도 (같은 함수 본문이므로)
  await fetchData();
  console.log(state.user.name);
}

동기적으로 실행되는 코드에서는 TypeScript가 narrowing을 유지합니다.

지역 변수는 왜 안전한가?

const user = state.user; // 이 시점의 값을 "스냅샷"으로 저장

if (user) {
  setTimeout(() => {
    console.log(user.name); // ✅ 안전
  }, 100);
}

지역 변수(특히 const)의 특성:

• 재할당이 불가능함
• 외부에서 값을 바꿀 방법이 없음
• TypeScript가 완전히 추적 가능

state.user가 나중에 바뀌더라도, user 변수에 담긴 값은 그대로입니다. TypeScript는 이를 알고 있어서 안심하고 narrowing을 유지합니다.

실무에서 자주 만나는 상황

React에서 이벤트 핸들러

function UserProfile() {
  const { data } = useQuery(['user'], fetchUser);

  // ❌ 콜백에서 직접 접근
  const handleSave = () => {
    if (data?.user) {
      saveUser(data.user).then(() => {
        toast(`${data.user.name}님 저장 완료`); // 에러
      });
    }
  };

  // ✅ 지역 변수로 해결
  const handleSave = () => {
    const user = data?.user;
    if (user) {
      saveUser(user).then(() => {
        toast(`${user.name}님 저장 완료`); // OK
      });
    }
  };
}

배열 순회에서

function processUsers(state: State) {
  // ❌ forEach 콜백
  if (state.user) {
    items.forEach(item => {
      sendNotification(item, state.user.email); // 에러
    });
  }

  // ✅ 지역 변수로 해결
  const user = state.user;
  if (user) {
    items.forEach(item => {
      sendNotification(item, user.email); // OK
    });
  }
}

클래스 메서드에서

class NotificationService {
  private user?: User;

  // ❌ this 프로퍼티 + 콜백
  notify() {
    if (this.user) {
      setTimeout(() => {
        this.send(this.user.email); // 에러
      }, 1000);
    }
  }

  // ✅ 지역 변수로 해결
  notify() {
    const user = this.user;
    if (user) {
      setTimeout(() => {
        this.send(user.email); // OK
      }, 1000);
    }
  }
}

더 나은 타입 설계

지역 변수 외에도 TypeScript가 잘 이해하는 패턴이 있습니다.

Discriminated Union

type ApiResult =
  | { status: 'success'; data: User }
  | { status: 'error'; message: string };

function handle(result: ApiResult) {
  if (result.status === 'success') {
    setTimeout(() => {
      console.log(result.data.name); // ✅ 콜백에서도 OK
    }, 100);
  }
}

status 프로퍼티가 전체 타입을 결정하는 "판별자" 역할을 합니다. TypeScript가 가장 잘 이해하는 패턴입니다. API 응답이나 상태 관리에서 이런 형태로 타입을 설계하면 좋습니다.

해결 방법 정리

1. 지역 변수에 담기

const user = state.user;
if (user) {
  setTimeout(() => console.log(user.name), 100); // ✅
}

2. 구조 분해 할당

const { user } = state;
if (user) {
  items.forEach(() => console.log(user.name)); // ✅
}

3. Early Return 패턴

function process(state: State) {
  const user = state.user;
  if (!user) return;

  // 이 아래 전체가 user가 있는 스코프
  setTimeout(() => console.log(user.name), 100); // ✅
}

4. Discriminated Union으로 타입 설계

type State =
  | { status: 'idle' }
  | { status: 'loaded'; user: User }
  | { status: 'error'; message: string };

마치며

정리하면 다음과 같습니다.

• TypeScript가 "의심"하는 것은 버그가 아니라 의도적 설계입니다
• "나중에 실행되는 코드"에서 값이 바뀔 가능성을 고려하는 것입니다
• 지역 변수에 담으면 TypeScript가 안전하게 추적할 수 있습니다
• Discriminated Union을 활용하면 더 나은 타입 추론을 받을 수 있습니다

처음에는 TypeScript가 지나치게 의심이 많다고 느꼈습니다. "분명히 체크했는데"라고 생각했습니다.

하지만 생각해보면 맞는 말입니다. setTimeout 콜백이 실행되는 100ms 동안 상태가 바뀌고, 컴포넌트가 언마운트되고, 사용자가 로그아웃할 수도 있습니다.

지역 변수 하나를 더 만드는 작은 습관으로 잠재적인 런타임 에러를 방지할 수 있습니다.

참고 자료

• TypeScript Handbook - Narrowing

function process(value: string | number) {
  console.log(value.toUpperCase());
  // ❌ Property 'toUpperCase' does not exist on type 'string | number'.
}

TypeScript를 처음 사용할 때 이 에러를 자주 만났습니다.

value가 string일 수도 있으니 toUpperCase()를 쓸 수 있어야 하는 것 아닌가? 하지만 TypeScript 입장에서는 value가 number일 가능성도 있습니다. number에는 toUpperCase()가 없으니 에러를 내는 거죠.

그런데 if문 하나를 추가하면 에러가 사라집니다.

function process(value: string | number) {
  if (typeof value === 'string') {
    console.log(value.toUpperCase()); // ✅ OK!
  }
}

TypeScript가 if문 안에서는 value가 string이라는 걸 인식합니다. 별도의 타입 단언(as string) 없이도요.

이게 바로 Type Narrowing입니다. 이 개념을 이해하고 나면 TypeScript 코드 작성이 훨씬 수월해집니다.

Type Narrowing이란?

Type Narrowing은 넓은 타입을 좁은 타입으로 좁혀가는 과정입니다.

string | number → string처럼, 가능한 타입의 범위를 줄여나가는 것이죠.

왜 이게 중요할까요?

TypeScript의 핵심 가치는 컴파일 타임에 에러를 잡는 것입니다. 그런데 Union 타입을 사용하면 "이 값이 정확히 어떤 타입인지 모른다"는 상황이 생깁니다.

function formatValue(value: string | number) {
  // value가 string인지 number인지 알 수 없으므로
  // 어떤 메서드도 안전하게 호출할 수 없습니다
}

Type Narrowing은 이 문제를 해결합니다. "이 시점에서 이 값은 확실히 string이다"라고 TypeScript에게 알려주는 것이죠.

TypeScript는 어떻게 타입을 추론할까요?

TypeScript는 코드의 흐름을 분석해서 타입을 자동으로 좁혀줍니다. 이 분석을 Control Flow Analysis(제어 흐름 분석)라고 부릅니다. (TypeScript 2.0부터 도입된 기능입니다.)

function greet(value: string | number) {
  // 여기서 value는 string | number

  if (typeof value === 'string') {
    // 이 블록에서 value는 string
    console.log(value.toUpperCase());
  } else {
    // 이 블록에서 value는 number
    console.log(value.toFixed(2));
  }
}

그리고 이런 분석을 가능하게 하는 조건문들을 Type Guard라고 합니다.

그럼 이제부터는 Type Guard를 실제 상황에서 어떻게 사용할 수 있을지 정리해보겠습니다.

Type Guard 총정리

1. typeof

원시 타입을 구분하는 가장 기본적인 방법입니다. 개인적으로 가장 자주 쓰는 Type Guard이기도 합니다.

function formatValue(value: string | number | boolean) {
  if (typeof value === 'string') {
    return value.trim(); // string
  }
  if (typeof value === 'number') {
    return value.toFixed(2); // number
  }
  return value ? 'Yes' : 'No'; // boolean
}

TypeScript는 typeof 연산자의 결과를 신뢰합니다. JavaScript 런타임에서 typeof가 반환하는 값은 확실하기 때문입니다. typeof value === 'string'이 true라면, 그 시점에서 value는 100% string입니다.

typeof가 반환하는 값들: "string", "number", "boolean", "undefined", "object", "function", "symbol", "bigint"

API 응답을 처리할 때 특히 유용합니다. 서버에서 숫자가 문자열로 올 때도 있고, 숫자 그대로 올 때도 있거든요.

function parseAmount(value: string | number): number {
  if (typeof value === 'string') {
    return parseFloat(value);
  }
  return value;
}

주의할 점: typeof null은 "object"를 반환합니다. JavaScript의 오래된 버그입니다. 따라서 null 체크는 typeof로 하면 안 됩니다.

2. Truthiness 체크

null이나 undefined를 걸러내는 가장 간단한 방법입니다. 코드도 짧고 직관적이라 자주 쓰게 됩니다.

function greet(name: string | null | undefined) {
  if (name) {
    console.log(`Hello, ${name}!`); // string
  }
}

JavaScript에서 null과 undefined는 falsy 값입니다. 따라서 if (value)를 통과했다면, value는 null도 undefined도 아닌 것이 확실합니다. TypeScript는 이 JavaScript 동작을 알고 있어서 타입을 자동으로 좁혀줍니다.

아래는 React에서 Optional props를 처리할 때 자주 사용하는 패턴입니다.

function UserCard({ user }: { user?: User }) {
  if (user) {
    return <div>{user.name}</div>;
  }
  return <div>Loading...</div>;
}

배열에도 동일하게 적용됩니다.

function getLength(arr?: string[]) {
  if (arr) {
    return arr.length; // string[]
  }
  return 0;
}

그런데 여기서 함정이 하나 있습니다. 0, "", NaN도 falsy 값이라서 의도치 않게 걸러질 수 있습니다.

function goToPage(page: number | null) {
  if (page) {
    // ⚠️ page가 0이면 이 블록에 진입하지 않습니다
    navigate(`/list?page=${page}`);
  }

  // 명시적인 null 체크가 더 안전합니다
  if (page !== null) {
    // page가 0이어도 진입합니다
    navigate(`/list?page=${page}`);
  }
}

실제로 페이지네이션에서 첫 페이지(0)로 이동이 안 되는 버그를 만난 적이 있습니다. if (page) 조건 때문이었습니다. 그 이후로 숫자를 다룰 때는 !== null을 명시적으로 사용합니다.

3. 동등 비교 (===, !==)

Truthiness 체크는 "falsy가 아닌 모든 것"을 통과시킵니다. 반면 동등 비교는 정확히 그 값인지 확인합니다. null만 걸러내고 싶을 때, 0이나 ""는 살리고 싶을 때 동등 비교가 필요합니다.

function handle(value: string | null) {
  if (value === null) {
    return 'No value';
  }
  return value.toUpperCase(); // string
}

리터럴 타입과 함께 사용하면 더 강력해집니다.

type Status = 'loading' | 'success' | 'error';

function getMessage(status: Status) {
  if (status === 'loading') {
    return 'Loading...'; // 'loading'
  }
  if (status === 'success') {
    return 'Done!'; // 'success'
  }
  return 'Something went wrong'; // 'error'
}

API 호출 상태를 관리할 때 유용한 패턴입니다.

4. in 연산자

객체에 특정 프로퍼티가 있는지로 타입을 구분합니다.

interface AdminUser {
  role: 'admin';
  permissions: string[];
}

interface GuestUser {
  role: 'guest';
  expiresAt: Date;
}

function getUserInfo(user: AdminUser | GuestUser) {
  if ('permissions' in user) {
    console.log(`권한: ${user.permissions.join(', ')}`); // AdminUser
  } else {
    console.log(`만료일: ${user.expiresAt}`); // GuestUser
  }
}

API 응답 처리에서 성공/실패 응답의 구조가 다를 때 유용합니다.

interface SuccessResponse { data: User; }
interface ErrorResponse { error: string; }

function handleResponse(res: SuccessResponse | ErrorResponse) {
  if ('error' in res) {
    console.error(res.error); // ErrorResponse
    return;
  }
  console.log(res.data); // SuccessResponse
}

res.error로 바로 접근하면 안 되는 이유가 있습니다. SuccessResponse에는 error 프로퍼티가 정의되어 있지 않기 때문에 접근 자체가 타입 에러가 됩니다. in 연산자는 런타임에 프로퍼티 존재 여부를 체크하면서 TypeScript에게 타입 정보도 전달합니다.

5. instanceof

클래스로 만든 객체를 구분할 때 씁니다.

class ApiError extends Error {
  statusCode: number;
  constructor(message: string, statusCode: number) {
    super(message);
    this.statusCode = statusCode;
  }
}

function handleError(error: Error) {
  if (error instanceof ApiError) {
    console.log(`Status: ${error.statusCode}`); // ApiError
  } else {
    console.log(error.message); // Error
  }
}

instanceof는 객체의 프로토타입 체인을 확인합니다. error instanceof ApiError가 true라면, error는 ApiError 클래스(또는 그 하위 클래스)의 인스턴스입니다. TypeScript는 이를 통해 해당 클래스의 프로퍼티와 메서드에 안전하게 접근할 수 있다고 판단합니다.

커스텀 에러 클래스를 만들어서 에러 종류별로 다르게 처리할 수 있습니다.

class ValidationError extends Error {
  field: string;
  constructor(field: string, message: string) {
    super(message);
    this.field = field;
  }
}

class NetworkError extends Error {
  retryable: boolean;
  constructor(message: string, retryable: boolean) {
    super(message);
    this.retryable = retryable;
  }
}

function handleError(error: Error) {
  if (error instanceof ValidationError) {
    showFieldError(error.field, error.message);
  } else if (error instanceof NetworkError && error.retryable) {
    showRetryButton();
  } else {
    showGenericError(error.message);
  }
}

6. Array.isArray

typeof []는 "object"를 반환합니다. 그래서 배열인지 확인하려면 Array.isArray를 써야 합니다.

function process(input: string | string[]) {
  if (Array.isArray(input)) {
    return input.join(', '); // string[]
  }
  return input; // string
}

API 응답이 단일 객체일 수도 있고 배열일 수도 있을 때 유용합니다.

function normalizeResponse(data: User | User[]) {
  if (Array.isArray(data)) {
    return data; // User[]
  }
  return [data]; // User -> User[]
}

이렇게 정규화하면 이후 코드에서 항상 배열로 일관되게 처리할 수 있습니다.

7. Discriminated Union

복잡한 상태를 다룰 때 가장 권장하는 패턴입니다. 공통된 리터럴 프로퍼티(discriminant)로 타입을 구분합니다.

type ApiState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: User }
  | { status: 'error'; error: string };

function render(state: ApiState) {
  switch (state.status) {
    case 'idle':
      return <div>Ready</div>;
    case 'loading':
      return <Spinner />;
    case 'success':
      return <UserCard user={state.data} />; // data 접근 가능
    case 'error':
      return <ErrorMessage message={state.error} />; // error 접근 가능
  }
}

이 패턴의 핵심 장점은 불가능한 상태 조합을 타입 레벨에서 방지한다는 것입니다.

아래와 같은 설계를 비교해보면 차이가 명확합니다.

// ❌ 문제가 있는 설계: 불가능한 상태 조합이 허용됨
interface State {
  isLoading: boolean;
  data: User | null;
  error: string | null;
}

// isLoading: true이면서 data와 error가 모두 존재하는 상태가 가능
// 이런 상태는 논리적으로 말이 안 됩니다

Discriminated Union을 사용하면 이런 논리적 오류를 컴파일 타임에 방지할 수 있습니다.

Redux나 Zustand의 액션 타입에서도 이 패턴이 널리 사용됩니다.

type Action =
  | { type: 'INCREMENT' }
  | { type: 'DECREMENT' }
  | { type: 'SET'; payload: number };

function reducer(state: number, action: Action) {
  switch (action.type) {
    case 'INCREMENT': return state + 1;
    case 'DECREMENT': return state - 1;
    case 'SET': return action.payload; // payload 접근 가능
  }
}

사용자 정의 Type Guard (is 키워드)

기본 Type Guard들로 해결이 안 되는 경우가 있습니다. 복잡한 조건이 필요하거나, 조건을 재사용하고 싶을 때입니다.

이럴 때 is 키워드로 직접 Type Guard를 정의할 수 있습니다.

기본 문법

function isAdmin(user: AdminUser | GuestUser): user is AdminUser {
  return 'permissions' in user;
}

반환 타입이 user is AdminUser인 것이 핵심입니다. "이 함수가 true를 반환하면 user는 AdminUser 타입이다"라고 TypeScript에게 알려주는 것이죠.

단순히 boolean을 반환하는 것과의 차이를 살펴보겠습니다.

// ❌ boolean 반환: 타입이 좁혀지지 않음
function isAdminBoolean(user: AdminUser | GuestUser): boolean {
  return 'permissions' in user;
}

if (isAdminBoolean(user)) {
  console.log(user.permissions); // 에러: user는 여전히 AdminUser | GuestUser
}

// ✅ is 키워드 사용: 타입이 좁혀짐
function isAdmin(user: AdminUser | GuestUser): user is AdminUser {
  return 'permissions' in user;
}

if (isAdmin(user)) {
  console.log(user.permissions); // OK: user는 AdminUser
}

실무 예시: API 응답 체크

interface SuccessResponse {
  success: true;
  data: User;
}

interface ErrorResponse {
  success: false;
  error: string;
}

type ApiResponse = SuccessResponse | ErrorResponse;

// 사용자 정의 Type Guard
function isSuccess(res: ApiResponse): res is SuccessResponse {
  return res.success === true;
}

// 사용
function handleResponse(res: ApiResponse) {
  if (isSuccess(res)) {
    console.log(res.data); // SuccessResponse
  } else {
    console.error(res.error); // ErrorResponse
  }
}

이렇게 정의하면 여러 곳에서 isSuccess 함수를 재사용할 수 있습니다.

배열 필터링에서의 활용

Type Guard는 filter와 함께 사용할 때 특히 유용합니다.

const items: (string | null)[] = ['a', null, 'b', null, 'c'];

// ❌ 일반 filter: 타입이 (string | null)[]로 유지됨
const filtered1 = items.filter(item => item !== null);
// filtered1의 타입: (string | null)[]

// ✅ Type Guard 사용: 타입이 string[]로 좁혀짐
function isNotNull<T>(value: T | null): value is T {
  return value !== null;
}
const filtered2 = items.filter(isNotNull);
// filtered2의 타입: string[]

이 차이가 중요한 이유는, filtered1을 사용할 때마다 null 체크를 다시 해야 하기 때문입니다. filtered2는 그럴 필요가 없습니다.

실무에서는 이런 식으로 활용합니다.

// 비어있지 않은 문자열만 필터링
function isNonEmptyString(value: string | null | undefined): value is string {
  return value !== null && value !== undefined && value.length > 0;
}

const tags = ['react', '', null, 'typescript', undefined];
const validTags = tags.filter(isNonEmptyString); // string[]

어떤 Type Guard를 선택할까?

상황별로 정리하면 다음과 같습니다.

마치며

정리하면 다음과 같습니다.

• Type Narrowing은 넓은 타입을 좁은 타입으로 좁혀가는 과정입니다
• TypeScript는 Control Flow Analysis로 이를 자동으로 수행합니다
• Type Guard는 이 분석을 가능하게 하는 조건문입니다
• 상황에 맞는 Type Guard를 선택하면 타입 단언(as) 없이도 안전한 코드를 작성할 수 있습니다

Type Narrowing을 제대로 활용하면서 as 키워드 사용이 크게 줄었습니다. 이전에는 "TypeScript가 왜 이걸 모르지?"라며 as를 자주 사용했는데, 이제는 "내가 TypeScript에게 충분한 정보를 제공하지 않았구나"라고 생각하게 되었습니다.

그런데 한 가지 의문이 남습니다.

if (state.user) {
  setTimeout(() => {
    console.log(state.user.name); // ❌ 에러?!
  }, 100);
}

분명 if문에서 체크했는데, 왜 콜백 안에서는 에러가 발생할까요?

이 질문에 대한 답은 다음 글에서 다루겠습니다.

다음 글: TypeScript는 왜 내 코드를 의심할까

참고 자료

• TypeScript Handbook - Narrowing

이메일 빌더 애플리케이션을 개발하는 중 이상한 문제가 발생했습니다. Fast Refresh가 실행된 후 (코드를 수정하고 저장할 때마다 발생) 이메일 블록들이 화면에서 완전히 사라지는 현상이 일어났습니다.

콘솔에는 "Fast Refresh done in 228ms"라는 메시지만 표시될 뿐, 이메일 콘텐츠 영역은 텅 비어 있었습니다. 저장할 때마다 작업 내용이 모두 사라지니 개발 효율이 크게 떨어지는 상황이었습니다.

솔직히 말하면, React를 꽤 오래 사용했음에도 불구하고 이런 문제가 발생할 거라고는 전혀 예상하지 못했습니다. 처음에는 단순히 구현 방식의 문제인 줄 알았는데, 알고 보니 React의 핵심 원칙을 위반한 결과였습니다.

문제 분석 🔍

문제의 본질을 파악하기 위해 코드를 면밀히 분석했습니다. 원래 코드는 다음과 같은 방식으로 작동했습니다.

1. 템플릿 HTML을 렌더링하는 함수가 있었습니다.
2. 숨겨진 div에 블록 컴포넌트들을 렌더링했습니다.
3. useEffect 훅 내에서 innerHTML과 appendChild를 사용해 DOM을 직접 조작했습니다.

// 이전 코드 (문제가 있던 부분)
useEffect(() => {
  const contentElement = document.getElementById('email-content');
  if (contentElement && content) {
    contentElement.innerHTML = '';
    contentElement.appendChild(content);
  }
}, [template, blocks, blockOrder, content]);

이 부분이 문제의 핵심이었습니다. React 내에서 DOM을 직접 조작하고 있었고, 이것이 Fast Refresh와 충돌을 일으키고 있었습니다. 생각해보니 React의 핵심 철학인 "선언적 UI 업데이트"와 정면으로 충돌하는 접근 방식이었습니다.

원인 파악 🤔

문제의 원인이 무엇일지에 대해 다음과 같은 가설을 세웠습니다.

1. React의 가상 DOM과 충돌: React는 가상 DOM을 통해 UI를 업데이트합니다. 직접적인 DOM 조작은 이 메커니즘을 우회해 React가 DOM의 현재 상태를 알 수 없게 만듭니다. 그 과정에서 충돌이 있었던 걸까..?
2. Fast Refresh와의 충돌: Fast Refresh는 React 컴포넌트의 상태를 보존하면서 변경된 코드만 새로 로드합니다. DOM을 직접 조작해 React가 관리하지 않는 DOM 요소가 생겨 Fast Refresh 후 이 요소들이 사라지고 생성이 되지 않은걸까
3. 컴포넌트 언마운트 시 DOM 참조 유실: Fast Refresh 과정에서 컴포넌트가 일시적으로 언마운트되면 DOM 참조가 유실, 없는 참고에 접근을 해서 생기지 않는걸까..

이런 분석을 통해 문제의 근본 원인이 명확해졌지만, 솔직히 처음부터 React의 방식을 따르지 않은 제 실수였습니다. "빠르게 구현하려다" 오히려 더 큰 문제를 만든 셈이죠.

해결 방법 💡

이 문제를 해결하기 위해 코드를 완전히 리팩토링했습니다.

1. DOM 직접 조작 제거

가장 중요한 변경은 innerHTML과 appendChild를 사용한 직접적인 DOM 조작을 완전히 제거했습니다. React의 선언적 렌더링 방식을 활용하는 것이 핵심입니다.

2. 템플릿 처리 방식 개선

템플릿을 헤더와 푸터 부분으로 나누어 처리하고, {{content}} 부분을 분기점으로 사용했습니다:

// 개선된 코드
// 템플릿 HTML의 헤더 부분
const templateHeader = template
  ? template.content
      .split('{{content}}')[0]
      .replace('{{meta-title}}', '이메일 제목')
      .replace('{{title}}', '이메일 제목')
  : '';

// 템플릿 HTML의 푸터 부분
const templateFooter = template ? template.content.split('{{content}}')[1] : '';

이렇게 하면 템플릿의 앞뒤 부분을 구분해서 처리할 수 있고, 콘텐츠는 React 컴포넌트로 직접 렌더링할 수 있습니다.

3. useState에서 useRef로 변경

상태 관리를 단순화하기 위해 useState와 hidden div 접근법 대신 useRef를 사용했습니다

const contentRef = useRef<HTMLDivElement>(null);

이를 통해 DOM 요소를 참조하되 React의 렌더링 사이클에 영향을 주지 않도록 했습니다.

4. 직접적인 콘텐츠 렌더링

이전에는 숨겨진 div에 렌더링한 후 DOM 조작으로 이동시켰지만, 이제는 직접 콘텐츠 영역에 블록들을 렌더링합니다

<div
  id="email-content"
  ref={contentRef}
>
  {blockOrder.map((blockId, index) => (
    <BlockItem
      key={blockId}
      isFirst={index === 0}
      isLast={index === blockOrder.length - 1}
      {...blocks[blockId]}
    />
  ))}
</div>

이 방식은 React의 선언적 패러다임을 따르므로 Fast Refresh와 완벽하게 호환됩니다.

지금 생각해보면 처음부터 이렇게 구현했어야 했는데, 어떻게든 빨리 동작하는 코드를 만들고 싶다는 욕심이 불필요한 복잡성을 가져왔습니다.

문제 해결 결과 ✅

위 변경사항을 적용한 후, Fast Refresh가 작동할 때도 이메일 블록들이 정상적으로 화면에 유지되었습니다. 코드를 수정하고 저장해도 더 이상 콘텐츠가 사라지지 않았고, 개발 효율이 크게 향상되었습니다.

가장 기뻤던 건, 이제 코드를 저장할 때마다 모든 내용이 사라져서 다시 상태를 만들어야 하는 스트레스에서 벗어났다는 점입니다. 이런 경험을 통해 "빠른 구현"과 "올바른 구현" 사이에서 후자를 선택하는 것이 결국 더 효율적이라는 점을 다시 한번 깨달았습니다.

알게 된 점 📚

이 문제를 해결하며 React 개발에서 몇 가지 중요한 점을 알게 되었습니다

1. React 내에서 DOM 직접 조작은 피해야 합니다. React는 가상 DOM을 통해 UI를 관리하는데, 직접 DOM을 조작하면 이 메커니즘이 무너집니다.
2. Fast Refresh는 React의 선언적 렌더링에 의존합니다. DOM을 직접 조작하면 Fast Refresh 후 React가 UI 상태를 복원할 수 없습니다.
3. React의 선언적 렌더링 방식을 따르는 것이 중요합니다. 상태 변화에 따라 UI가 자동으로 업데이트되는 React의 방식이 더 예측 가능한 결과를 가져옵니다.
4. useEffect의 의존성 배열은 신중하게 설계해야 합니다. 특히 DOM 조작이 포함된 경우 의존성 관리가 복잡해질 수 있습니다.

솔직히 이런 기본적인 React 원칙을 어기면서 코드를 작성했다는 게 아쉬웠습니다. "빠르게 동작하는 코드"를 만들려다가 오히려 개발 과정을 더 복잡하게 만든것 같네요. React의 선언적 방식을 믿고 따랐다면 이런 문제로 시간을 낭비하지 않았을 텐데, 이번 경험을 통해 다시 한번 프레임워크의 철학을 따르는 것의 중요성을 깨달았습니다.

결론적으로, 이 경험은 빠른 해결책보다 올바른 해결책을 찾는 것의 중요성을 다시 일깨워주었습니다. 아마 대부분의 개발자들이 비슷한 실수를 한 번쯤은 해봤을 거라 생각합니다. 하지만 중요한 건 실수를 인정하고, 더 나은 방향으로 코드를 개선해 나가는 과정이 아닐까 싶습니다.

GitAnimals 프로젝트를 진행하면서 한 가지 고민이 있었습니다. 이 서비스는 깃허브 커밋을 통해 포인트를 얻고 그 포인트로 펫을 뽑아 키우는 서비스인데요, 일회용성 접근이 아닌 사용자 참여가 지속적으로 이루어지도록 하고싶었어요. 더 나은 사용자 경험과 접근성을 위해 앱 형태로 제공하는 것을 고려하게 되었습니다.

처음에는 RN을 이용한 웹 앱 개발을 고려했지만, 몇 가지 현실적인 제약이 있었습니다. 🤔

1. GitHub 로그인과 계정 연동이 필수적인데, iOS 앱의 경우 소셜 로그인을 구현하려면 Apple 로그인 기능도 필수적으로 요구됩니다.
2. 복잡한 인증 플로우로 인해 개발 일정이 지연될 가능성이 높았습니다.
3. 앱 스토어 심사 과정과 배포 시간도 부담으로 다가왔습니다.

이러한 고민 속에서 "꼭 앱이어야 할까?"라는 질문을 하게 되었고, 그 대안으로 PWA(Progressive Web App)를 발견하게 되었습니다.

PWA가 뭐길래?

PWA는 웹 기술을 사용하여 개발되지만 네이티브 앱과 유사한 사용자 경험을 제공하는 웹 애플리케이션입니다. 웹사이트를 모바일 기기의 홈 화면에 설치할 수 있고, 오프라인에서도 작동하며, 심지어 푸시 알림과 같은 네이티브 앱의 주요 기능도 활용할 수 있습니다.

이런 강력한 기능들은 대부분 '서비스 워커(Service Worker)'라는 기술 덕분에 가능합니다. 웹의 접근성과 앱의 사용자 경험을 결합한 하이브리드 접근 방식이라고 생각하면 이해하기 쉬울 것 같습니다.

서비스 워커란?
PWA의 핵심 기술인 서비스 워커는 웹 페이지와 브라우저 사이에서 동작하는 JavaScript 파일입니다. 네트워크 요청을 가로채고 캐싱 전략을 적용하여 오프라인 작동, 성능 향상, 백그라운드 동기화, 푸시 알림 등의 기능을 가능하게 합니다. 서비스 워커 덕분에 웹사이트가 앱처럼 동작할 수 있는 것이죠!

처음 PWA 개념을 접했을 때는 의구심이 들었지만, 알아볼수록 실용적인 기술이라는 생각이 들었습니다. 특히 앱 스토어의 심사 과정 없이도 앱과 같은 경험을 제공할 수 있다는 점이 매력적이었습니다.

PWA의 장점들

PWA를 검토하면서 가장 끌렸던 장점들은 다음과 같습니다.

1. 앱 스토어 우회 ⏭️ - 앱 스토어 심사 없이 바로 배포할 수 있어 빠른 개발 사이클을 유지할 수 있습니다.
2. 푸시 알림 🔔 - 웹인데도 네이티브 앱처럼 푸시 알림을 보낼 수 있어 사용자 참여를 유도하기 좋습니다.

이런 장점들이 GitAnimals 프로젝트의 현재 상황과 딱 맞는 것 같아 PWA 적용을 결정했습니다.

GitAnimals 프로젝트에 PWA 적용하는 방법

Gitaninmals는 Next.js App router 환경으로 이루어져있는 서비스입니다. Next.js로 개발된 프로젝트에 PWA를 적용하는 과정을 공유해보려고합니다.

1. 패키지 설치하기

첫 단계는 간단했습니다. next-pwa 패키지를 설치하는 것이었죠.

npm install next-pwa

이 패키지는 Next.js 프로젝트에 PWA를 손쉽게 적용할 수 있게 해줍니다. 처음에는 직접 서비스 워커를 구현해야 하나 걱정했는데, 이 패키지 덕분에 많은 부분이 자동화되어 편리했습니다.

2. Next.js 설정 파일 수정하기

다음으로 next.config.mjs 파일을 수정했습니다. 여기서 PWA의 핵심 설정을 추가하는 작업이었죠.

import createNextIntlPlugin from 'next-intl/plugin';
import NextPWA from 'next-pwa';

const withNextIntl = createNextIntlPlugin();
const withPWA = NextPWA({
  dest: 'public',
  disable: process.env.NODE_ENV === 'development' || process.env.DISABLE_PWA === 'true',
  register: true,
  skipWaiting: true,
});

const nextConfig = withNextIntl({
  // 기존 설정들...
});

export default withPWA(nextConfig);

개발 과정에서 한 가지 깨달은 점은 개발 환경에서는 PWA 기능을 비활성화하는 것이 좋다는 것이었습니다. 서비스 워커가 활성화되면 캐싱 때문에 코드 변경사항이 즉시 반영되지 않아 개발 효율이 떨어지더라고요. 그래서 disable: process.env.NODE_ENV === 'development' 옵션을 추가했습니다.

3. PWA 설치 안내 배너 만들기

PWA를 구현하면서 가장 큰 도전 과제는 설치 프로세스였습니다. 기본 기능 구현은 next-pwa 패키지 덕분에 쉬웠지만, 사용자들에게 "이 웹사이트를 앱으로 설치할 수 있어요"라고 알려주고 그 과정을 안내하는 것은 온전히 제 몫이었습니다.

브라우저에서는 PWA를 설치할 수 있을 때 작은 알림을 표시하지만, 대부분의 사용자는 이를 놓치거나 무시하게 될것 같고, 그래서 직접 설치 안내 배너를 만들기로 했습니다.

'use client';
import { useEffect, useState } from 'react';
import { css } from 'panda/css';
import { flex } from 'panda/patterns';
import { AnimatePresence, motion } from 'framer-motion';

export const PWAInstallBanner = () => {
  const [showBanner, setShowBanner] = useState(false);
  const [showModal, setShowModal] = useState(false);

  useEffect(() => {
    // PWA 설치 이벤트 감지
    window.addEventListener('beforeinstallprompt', (e) => {
      e.preventDefault();
      setShowBanner(true);
    });

    // 이미 설치된 경우 감지
    window.addEventListener('appinstalled', () => {
      setShowBanner(false);
    });
  }, []);

  const handleInstall = () => {
    setShowModal(true);
  };

  // 배너 UI 렌더링 코드
}

이 코드에서 핵심은 beforeinstallprompt 이벤트를 감지하는 부분입니다. 브라우저가 "이 사이트는 설치 가능합니다"라고 판단할 때 이 이벤트가 발생하고, 이때 사용자에게 배너를 보여주는 방식으로 구현했습니다.

4. 브라우저별 설치 가이드 구현과 설치 과정의 복잡함 해결하기

먼저 설치 안내 배너를 만든 후, 곧바로 더 큰 문제를 발견했습니다. PWA 설치 방법이 브라우저마다 완전히 다르다는 점이었죠. Chrome, Safari, Samsung Internet 등 브라우저별로 설치 UI와 과정이 달라서 모든 사용자에게 적용할 수 있는 통일된 안내를 만들 수 없었습니다.

그래서 사용자의 브라우저를 자동으로 감지하고 맞춤형 설치 가이드를 제공하는 모달을 구현했습니다.

export const PWAInstallGuideModal = ({ onClose }: { onClose: () => void }) => {
  const [currentSlide, setCurrentSlide] = useState(0);
  const [browserType, setBrowserType] = useState('unknown');

  useEffect(() => {
    // 브라우저 탐지
    const userAgent = navigator.userAgent.toLowerCase();
    if (/iphone|ipad|ipod/.test(userAgent)) {
      setBrowserType('safari');
    } else if (/android/.test(userAgent)) {
      if (/samsung/.test(userAgent)) {
        setBrowserType('samsung');
      } else if (/kakao/.test(userAgent)) {
        setBrowserType('kakao');
      } else if (/naver/.test(userAgent) || /whale/.test(userAgent)) {
        setBrowserType('whale');
      } else {
        setBrowserType('chrome');
      }
    }
  }, []);

  // 브라우저별 설치 가이드 슬라이드 구성
  const slides = [
    // 인트로 슬라이드
    {
      title: '앱으로 설치하기',
      description: '홈 화면에 설치하여 더 빠르게 접근하고 오프라인에서도 사용해보세요!',
      image: '/images/pwa-intro.png',
      isIntro: true,
    },
    // 브라우저별 가이드 슬라이드...
  ];

  // 슬라이드 UI 및 네비게이션 코드
}

PWA의 경우 브라우저마다 설치 과정이 다르고, 사용자가 여러 단계를 거쳐야 합니다. 그러다보니 사용자가 앱 설치를 하는 접근성이 좋지 않다고 생각하였고, 우선적으로 해결해야하는 문제라고 생각했어요.

이런 문제들을 해결하기 위해 여러 전략을 적용해보았습니다.

• 맞춤형 안내: 주요 브라우저 각각에 대해 맞춤형 설치 가이드를 만들었습니다.
• 시각적 자료 활용: 각 단계를 스크린샷과 함께 제공하여 사용자가 직관적으로 따라할 수 있도록 했습니다.
• 설치 혜택 강조: "앱으로 설치하면 더 빠르게 접근하고 오프라인에서도 사용할 수 있어요"와 같은 구체적인 이점을 강조했습니다.

특히 iOS Safari의 경우 PWA 설치가 직관적이지 않고 숨겨져 있어서 단계별 가이드가 필수적이었습니다. 사용자가 "공유" 버튼을 누르고, 스크롤을 내려 "홈 화면에 추가" 옵션을 찾고, 설명을 읽고, "추가" 버튼을 눌러야 하는 복잡한 과정을 거쳐야 합니다.

그럼에도 불구하고 이상적인 설치 경험에는 여전히 미치지 못한다는 생각이 듭니다. 앱 스토어에서 하나의 "설치" 버튼으로 끝나는 단순함과 비교하면, PWA 설치 과정은 여전히 진입 장벽이 높습니다. 이 부분은 PWA 기술 자체의 한계이기도 하며, 앞으로 브라우저들이 더 일관되고 직관적인 설치 경험을 제공하기를 기대해 봅니다.

아직 남은 고민들

PWA 구현을 진행하면서 여전히 몇 가지 해결되지 않은 고민이 남아있습니다.

첫째, 푸시 알림 권한입니다. PWA에서 푸시 알림을 보내려면 사용자의 권한이 필요한데, 이 과정도 브라우저마다 다릅니다. 특히 iOS에서는 알림 권한 획득이 더 까다롭고, 사용자가 거부한 경우 다시 요청하기가 어렵습니다.

둘째, iOS 제약사항입니다. iOS Safari의 PWA 지원은 Android Chrome보다 제한적입니다. 예를 들어, 백그라운드 동기화나 일부 웹 API가 제한되어 있어서 완전한 앱 경험을 제공하기 어렵습니다. 이는 Apple이 앱 스토어 생태계를 보호하기 위한 전략으로 보이지만, 개발자 입장에서는 제약이 많습니다.

셋째, 브랜딩과 발견성입니다. 앱 스토어는 사용자들이 새로운 앱을 발견하는 중요한 채널인데, PWA는 이런 발견성이 떨어집니다. 사용자들이 웹사이트에 먼저 방문해야만 PWA를 알 수 있고, 앱 검색 시장에서는 완전히 배제되어 있습니다.

이런 고민들이 있지만, 그래도 PWA는 네이티브 앱 개발 리소스가 제한적인 상황에서 괜찮은 타협점이라고 생각합니다. 특히 GitAnimals 같은 GitHub 통합 서비스에서는 네이티브 앱의 인증 복잡성을 우회할 수 있다는 점이 큰 장점입니다.

앞으로의 계획

PWA 도입은 아직 초기 단계이지만, 앞으로 몇 가지 계획을 가지고 있습니다.

우선 사용자 테스트를 통해 설치 가이드의 효과를 검증할 예정입니다. 실제 사용자들이 얼마나 쉽게 PWA를 설치하고 사용할 수 있는지 피드백을 수집하고, 지속적으로 UX를 개선하려고 합니다. 특히 다양한 브라우저 환경에서의 설치 성공률을 측정하고 중간에 포기하는 지점을 파악하여 설치 가이드를 최적화할 계획입니다.

또한 푸시 알림을 활용한 사용자 참여 전략을 구체화할 계획입니다. 예를 들어, 일일 커밋 알림이나 펫 상태 변화 알림 등을 통해 사용자들의 지속적인 참여를 유도할 수 있을 것 같습니다. 다만 iOS와 Android의 푸시 알림 지원 차이를 고려한 대응책도 함께 마련해야 할 것 같습니다.

PWA 푸시 알림 팁
iOS 16.4부터 Safari에서도 PWA 웹 푸시 알림이 지원되기 시작했습니다. 단, iOS에서는 사용자가 먼저 PWA를 설치한 후에만 푸시 알림 권한을 요청할 수 있으니 요청 타이밍에 주의해야 합니다!

무엇보다 중요한 건 사용자 경험이라고 생각합니다. 기술적인 구현 방식보다는 사용자들이 GitAnimals를 얼마나 편리하게 이용할 수 있는지가 핵심이니까요. PWA든 네이티브 앱이든, 최종적으로는 사용자들에게 가장 좋은 경험을 제공하는 방향으로 결정할 것입니다.

사실 현재는 프로젝트의 상황에 맞춰 PWA를 선택했지만, 장기적으로는 Apple 로그인을 구현할 수 있는 리소스가 확보된다면 결국 앱 스토어 심사를 거치는 네이티브 앱 방향으로 변경하게 될 가능성도 있습니다. PWA는 완벽한 해결책이라기보다는 현재 상황에서의 적절한 타협점이라고 생각합니다.

이번 PWA 도입 과정은 기술적 제약 속에서 창의적인 해결책을 찾아가는 여정이었습니다. 완벽한 솔루션은 아니지만, 현재 상황에서 최선의 선택을 하기 위한 탐색 과정이었다고 생각합니다. 앞으로의 발전 과정도 기회가 되면 공유하겠습니다.

📝 참고: 이 글은 코드 구현보다 문제 인식과 해결 접근법에 중점을 두고 작성되었습니다

회사에서 새로운 프로젝트를 시작한 지 몇 주가 지났습니다. 디자인 시안이 나올 때마다 새로운 아이콘들이 추가되었고, 그때마다 개발자인 제가 해야 하는 작업이 있었죠.

😧 "또 아이콘 추가 작업이네..."

이번에도 디자인팀에서 새로운 페이지 시안이 나왔고, 거기에 들어갈 새로운 아이콘들을 추가해야 했습니다. 한두 개라면 모를까, 이번에도 어김없이 5개가 넘는 아이콘들이 추가되어야 했죠.

반복되는 일상

매번 새로운 아이콘을 추가할 때마다 이런 과정을 거쳐야 했습니다.

1. 피그마 열기
2. 필요한 아이콘 찾기
3. SVG로 추출
4. VSCode로 전환
5. 새 파일 만들기
6. SVG 코드 붙여넣기
7. React 컴포넌트로 변환
8. props 연결하기
9. 인덱스 파일 수정

😧 "하... 이걸 또 5번 반복하라고?"

피그마와 VSCode를 왔다 갔다 하면서 같은 작업을 반복하다 보니 지루함을 넘어 짜증이 나기 시작했습니다. 실수도 자주 났죠. 'stroke' 속성을 'color' props로 바꾸는 걸 깜빡한다거나, kebab-case를 camelCase로 바꾸는 걸 놓친다거나...

문제 인식

"이렇게 단순 반복적인 일을 계속 하고 있어도 되나?"

문득 그런 생각이 들었습니다. 개발자란 게 결국 문제를 해결하는 사람 아닌가요? 그런데 이렇게 단순 반복적인 일을 손으로 계속하고 있다니. 뭔가 더 나은 방법이 있을 것 같았습니다.

기존 아이콘 시스템 살펴보기

우리 팀은 아이콘을 이렇게 사용하고 있었습니다.

<Icon type="arrow-right" color="#000000" size={24} />

간단해 보이는 이 컴포넌트 뒤에는 복잡한 구조가 있었죠.

export const IconComponentMap = {
  'arrow-right': ArrowRightIcon,
  'check-circle': CheckCircleIcon,
  // ... 수십 개의 아이콘들
}

export type IconType = keyof typeof IconComponentMap;

이 구조를 유지하면서, 새로운 아이콘을 추가하는 과정을 자동화할 수 있지 않을까? 그렇게 해결책을 찾아 나서기 시작했습니다.

해결책 찾기

검색 끝에 SVGR이라는 도구를 발견했습니다. SVG를 React 컴포넌트로 변환해주는 도구였는데, 특히 Custom Template 기능이 눈에 띄었죠. 이를 활용하면 우리 팀의 아이콘 컴포넌트 형식에 맞게 자동으로 변환할 수 있을 것 같았습니다.

하지만 SVGR만으로는 부족했습니다. 해결해야 할 문제들이 더 있었거든요.

팀의 상황에 맞추기 위해서 해결해야할 문제 외에는 Custom Template 기능을 그대로 따라갔습니다. 해당 기능이 궁금하시다면 아래 문서를 참고해주세요. SVGR Custom Template 기능 사용법

우리가 원하는 것

• 피그마에서 받은 SVG 파일을 자동으로 처리
• 기존 아이콘 시스템과 호환되는 컴포넌트 생성
• IconComponentMap 자동 업데이트
• 팀 컨벤션 준수

해결해야 할 문제들

가장 먼저 마주친 문제는 파일 이름 처리였습니다. 피그마에서 아이콘을 다운로드하면 Name=ArrowRight.svg처럼 prefix가 붙어있었죠. 이걸 우리 팀 컨벤션인 ArrowRightIcon.svg로 변환해야 했습니다.

// 변환 예시
Name=ArrowRight.svg → ArrowRightIcon.svg
Name=check-circle.svg → CheckCircleIcon.svg
arrow-left.svg → ArrowLeftIcon.svg

단순해 보이지만 여러 엣지 케이스를 고려해야 했습니다. 파일명에 하이픈이 있는 경우, 이미 'Icon'이 포함된 경우, 첫 글자가 소문자인 경우 등 다양한 상황을 처리해야 했죠.

두 번째 문제는 기존 아이콘 파일과의 충돌이었습니다. /src/components/Icon 폴더에는 이미 수십 개의 아이콘 컴포넌트가 있었고, 이 파일들은 건드리지 않은 채로 새로운 아이콘만 추가해야 했습니다. 실수로 기존 파일을 덮어쓰면 큰 문제가 될 수 있었죠.

가장 까다로웠던 건 index.ts 파일 수정이었습니다. 이 파일은 모든 아이콘의 진입점 역할을 하는 중요한 파일이었죠.

// index.ts의 구조
import { SVGProps } from 'react';
import { ArrowLeftIcon } from './ArrowLeftIcon';
// ... 수십 개의 import 구문

export const IconComponentMap = {
  'arrow-left': ArrowLeftIcon,
  // ... 수십 개의 매핑
};

export type IconType = keyof typeof IconComponentMap;

이 파일에 새로운 아이콘을 추가할 때는 세 가지를 고려해야 했습니다

• import 구문을 적절한 위치에 추가
• IconComponentMap에 새로운 매핑 추가
• 기존 코드의 구조를 해치지 않기

단순히 파일 끝에 새로운 코드를 추가하는 게 아니라, 파일의 구조를 이해하고 적절한 위치에 코드를 삽입해야 했습니다. 이를 위해 AST(Abstract Syntax Tree) 파싱을 사용했죠.

const ast = parser.parse(content, {
  sourceType: 'module',
  plugins: ['typescript'],
});

// 마지막 import 구문 위치 찾기
const lastImport = ast.program.body.findIndex(
  (node) => node.type !== 'ImportDeclaration'
);

// 새로운 import 추가
ast.program.body.splice(lastImport, 0, /* 새로운 import 구문 */);

이렇게 파일을 파싱하고 수정하는 방식을 택한 이유는, 단순한 문자열 처리보다 훨씬 안전하고 정확하기 때문이었습니다. 실수로 기존 코드를 망가뜨릴 위험도 줄일 수 있었죠.

마지막으로는 생성된 컴포넌트의 일관성 문제가 있었습니다. 모든 아이콘 컴포넌트는 동일한 구조를 가져야 했고, 특히 props 처리 방식이 일관되어야 했습니다. SVGR의 custom template을 활용해 이 문제를 해결했습니다.

이런 여러 문제들을 하나씩 해결하면서, 점점 더 안정적이고 사용하기 쉬운 도구가 만들어져 갔습니다.

드디어, 자동화

결과물은 생각보다 단순했습니다.

• SVG 파일을 정해진 폴더에 넣기
• $ yarn icons cli 실행
• 끝!

이제 10개의 아이콘을 추가하는 시간이 이렇게 바뀌었습니다.

• 전: 20-30분 (중간중간 실수 수정 포함)
• 후: 1분 (커피 한 모금 마시면 끝)

실제 사용 후기

"어, 이거 진짜 편하다!"

팀원들의 첫 반응이었습니다. 특히 좋았던 점들을 꼽자면

• 피그마와 VSCode를 왔다 갔다 할 필요가 없어졌습니다.
• 실수할 걱정이 없어졌습니다.

작은 자동화가 주는 큰 가치

이 작업을 통해 새삼 깨달은 것이 있습니다.

"불편함을 그냥 참지 말자"

개발자로서 우리는 종종 작은 불편함들을 그냥 넘어가곤 합니다. "이 정도는 참아야지", "이런 건 그냥 해야지" 하면서요. 하지만 그 작은 불편함들이 쌓이면 결국 큰 시간 낭비가 됩니다.

특히 인상 깊었던 건 팀원들의 반응이었습니다.

"이제 아이콘 추가하는 게 전혀 스트레스가 안 돼요." "다른 것도 이렇게 자동화할 수 있는 게 있을까요?"

작은 변화가 팀 전체의 생산성과 사기를 높일 수 있다는 걸 직접 경험한 소중한 기회였습니다.

마치며

개발자의 시간은 소중합니다. 단순 반복 작업에 시간을 쓰기에는 해야 할 일이 너무 많죠.

여러분의 일상에도 이런 자동화할 수 있는 작업이 있지 않을까요? 당장은 2-3분밖에 안 걸리는 일이라도, 그게 매일 반복된다면 자동화를 고민해볼 만합니다.

"이 정도는 그냥 해야지"라고 생각하는 그 순간, 잠깐 멈춰서서 생각해보세요. "이걸 자동화하면 어떨까?"

긴 글 읽어주셔서 감사합니다.

참고 자료

• SVGR 공식 문서
• SVGR Custom Templates

구현 목표 🎯

프로젝트의 메인 페이지에 동영상을 넣기 위해 다음과 같은 요구사항이 있었습니다.

1. 페이지 로드와 함께 자동 재생 시작
2. 플레이어 컨트롤 없이 GIF처럼 재생
3. 현재 페이지 내에서만 재생 (전체 화면 전환 없음)

문제 상황 😓

iOS에서 테스트를 진행하던 중 예상치 못한 동작이 발견되었습니다. 가장 큰 문제는 동영상을 탭했을 때 iOS의 기본 동영상 플레이어로 전환되는 것이었습니다.

<!-- 처음 시도했던 코드 -->
<video autoplay loop muted>
    <source src="video.mp4" type="video/mp4">
</video>

이러한 동작은 UX를 해치는 요소였습니다. 사용자가 GIF처럼 자연스럽게 보기를 원하는데, 플레이어로 전환되면서 페이지의 흐름이 끊기게 되었기 때문입니다.

해결 방법 💡

1. playsinline 속성 추가

iOS에서 페이지 내 재생을 위해서는 playsinline 속성이 필수적이었습니다. 이 속성은 iOS에서 동영상을 현재 페이지 내에서 재생하도록 지정합니다.

<video playsinline>
    <source src="video.mp4" type="video/mp4">
</video>

2. GIF와 같은 효과를 위한 속성 조합

완벽한 GIF 대체를 위해서는 여러 속성을 조합해야 했습니다:

<video 
    playsinline 
    autoplay 
    loop 
    muted
    class="video-element"
>
    <source src="video.mp4" type="video/mp4">
</video>

각 속성의 역할:

• playsinline: iOS에서 페이지 내 재생
• autoplay: 자동 재생 활성화
• loop: 반복 재생
• muted: 음소거 (자동 재생을 위해 필수)

관련 스타일:

.video-element {
    width: 100%;
    max-width: 720px;
    /* 필요한 경우 object-fit 속성 추가 */
    object-fit: cover;
}

추가 고려사항 📝

1. 자동 재생 정책

• 대부분의 모바일 브라우저에서는 음소거된 상태에서만 자동 재생이 가능
• muted 속성이 없으면 자동 재생 정책에 의해 차단될 수 있음

2. 성능과 데이터 사용량

• 동영상 파일 크기 최적화 필요
• 필요한 경우 모바일 환경에서는 더 낮은 해상도의 동영상 제공 고려

  <video playsinline autoplay loop muted>
    <source src="high-quality.mp4" type="video/mp4" media="(min-width: 720px)">
    <source src="low-quality.mp4" type="video/mp4">
  </video>

3. 브라우저 호환성

• Safari (iOS): playsinline 속성 필수
• Chrome (Android): 대부분의 속성이 잘 동작
• Samsung Internet: Chrome과 유사한 동작

마치며 🌱

모바일 환경에서 동영상을 다룰 때는 생각보다 많은 요소들을 고려해야 합니다. 특히 iOS의 경우 playsinline 속성이 필수적이며, 자동 재생을 위해서는 반드시 음소거 상태여야 한다는 점을 알게되었고,

이러한 경험을 통해 모바일 웹 개발에서는 각 플랫폼의 특성을 이해하고, 그에 맞는 해결 방법을 찾는 것이 중요하다는 것을 알게 되었습니다.

참고 자료 🔗

• iOS Safari Video Policy
• MDN - Video Element

프론트엔드 개발자로 일하면서 종종 받는 요청이었어요. 매번 기존 템플릿을 활용해 새로운 이메일을 만들고, 스타일을 수정하고... 간단해 보이는 작업인데 매번 2시간 정도는 훌쩍 걸렸죠. 이메일 템플릿 작업은 생각보다 까다로웠어요. 우선 이메일 클라이언트마다 지원하는 CSS가 달라서 호환성을 체크해야 했고, 모바일에서도 확인이 필요했어요. 그리고 가장 큰 문제는 테스트였죠. 실제 이메일로 발송해서 확인하는 과정이 필요했거든요.

더 큰 문제는 이메일 내용을 수정할 때였어요.

"폰트 크기를 조금만 더 키워주세요!", "이 문구를 이렇게 바꾸면 좋을 것 같아요."

마케팅팀과 이런 작은 수정사항들을 주고받는 데만 꽤 많은 시간이 필요했어요. 텍스트 하나를 바꾸더라도 개발자가 수정하고, 다시 테스트 메일을 보내고, 마케팅팀의 확인을 받고... 이런 과정이 반복되다 보니 서로 답답할 수밖에 없었죠.

'이걸 좀 더 효율적으로 할 수 없을까?'

주말 동안 이 문제를 해결하기 위한 아이디어를 고민했어요. 마케터가 직접 템플릿을 수정할 수 있는 도구를 만들면 어떨까 하는 생각이 들었죠. 혼자서 시작한 작은 프로젝트였지만, 팀에 도움이 될 거라는 확신이 있었어요.

어떻게 만들었나요? 🛠

이메일 클라이언트 호환성 해결하기

가장 먼저 고민했던 건 이메일 클라이언트 호환성이었어요. Gmail, Outlook, Apple Mail 등 각각의 클라이언트가 지원하는 HTML/CSS가 달랐기 때문에, 안전하게 사용할 수 있는 태그와 스타일을 먼저 정의했어요.

최신 CSS 기능은 대부분의 이메일 클라이언트에서 지원하지 않아서, 테이블 기반 레이아웃과 인라인 스타일을 사용하기로 했죠. 예를 들어 flexbox나 grid 같은 최신 레이아웃 기능 대신, 테이블을 활용해 레이아웃을 잡았어요. 모든 스타일은 인라인으로 적용해서 클라이언트 호환성을 최대한 보장했죠.

직관적인 인터페이스 설계

이메일 템플릿 빌더는 크게 좌측 패널과 우측 패널로 나누어 설계했어요.

좌측 패널에서는 전체적인 템플릿을 관리할 수 있어요. 새로운 템플릿을 추가하거나 기본 템플릿을 적용할 수 있죠. 가장 중요한 건 실시간 미리보기예요. 수정사항을 바로바로 확인할 수 있게 했어요.

우측 패널은 실제 편집이 이루어지는 공간이에요. 블록 기반으로 구성해서, 각 블록마다 필요한 설정을 할 수 있어요. 텍스트 굵기, 정렬, 크기 등 기본적인 스타일을 수정할 수 있어요.

블록 기반 시스템

비개발자도 쉽게 사용할 수 있도록 블록 기반 시스템을 도입했어요. 현재는 세 가지 기본 블록을 제공하고 있는데요.

첫 번째로 버튼 블록이에요. 링크를 설정할 수 있고, 텍스트 스타일과 정렬을 조정할 수 있어요. 기본적인 기능에 충실하게 구현했죠.

두 번째는 텍스트 블록이에요. 일반 텍스트를 편집할 수 있고, 글자 색상도 변경할 수 있어요. 제목, 본문, 강조 텍스트 등 다양한 용도로 활용할 수 있죠.

마지막으로 테이블 블록이에요. 데이터를 구조화해서 보여줄 때 사용해요. 각 셀마다 텍스트 색상과 정렬을 설정할 수 있어요.

각 블록은 TypeScript로 타입을 정의해서 안전하게 관리하고 있어요.

interface EmailBlock {
  id: string;
  type: 'h1' | 'h2' | 'p' | 'strong' | 'div' | 'table' | 'button';
  content: string;
  customStyles?: Record<string, string>;
}

테스트 이메일 발송 기능

프로젝트를 팀에 공유했을 때, 마케팅팀에서 가장 반겼던 기능이 테스트 이메일 발송이었어요. 이전에는 실제 이메일을 발송해서 확인해야 했는데, 이제는 빌더에서 바로 테스트 메일을 보내볼 수 있거든요.

Next.js의 Route Handler와 nodemailer 라이브러리를 활용해서 구현했어요. 프론트엔드 개발자인 저도 서버 기능을 구현하는 게 부담스러웠는데, Next.js의 Route Handler를 사용하니 생각보다 쉽게 구현할 수 있었죠.

기술 스택 🛠

프로젝트는 이렇게 구성했어요.

Frontend

• Next.js App Router
• shadcn/ui
• TypeScript

Email 처리

• Route Handler를 통한 서버 기능 구현
• nodemailer를 활용한 테스트 메일 발송

앞으로의 계획 🚀

현재는 기본적인 기능만 구현된 상태예요. 앞으로는 더 다양한 기능을 추가할 계획인데요.

우선 새로운 블록들을 추가하려고 해요. 특히 이미지 블록에 대한 요청이 많아서 이 부분을 우선적으로 개발할 예정이에요. 각 블록별로도 더 다양한 스타일 옵션을 제공하려고 해요. 버튼 블록에는 배경색 변경이나 다양한 스타일 프리셋을 추가하고, 다른 블록들은 텍스트 색상을 변경할 수 있게 하는 등 자유도를 높일 계획이에요.

서비스를 만든 후에 뿌듯했던 점은, 개발자와 마케터 모두의 시간을 아껴줄 수 있는 도구를 만들었다는 거예요. 팀원들의 긍정적인 반응을 보면서, 앞으로도 이런 방식으로 팀의 업무 효율을 높이는 프로젝트들을 만들어가고 싶다는 생각이 들었어요.

이메일 템플릿 빌더 사용해보기 👋

현재 이메일 템플릿 빌더는 베타 버전으로 운영되고 있어요. 여러분들의 의견을 통해 더 좋은 서비스를 만들어가고 싶어요!

서비스 이용하기

• 서비스 바로가기
• 사용 가이드
• 템플릿 파일 개발자 가이드

피드백 남기기

더 나은 서비스를 위한 여러분의 의견을 기다리고 있어요. 새로운 기능 제안부터 버그 리포트, 사용성 개선 의견까지 어떤 의견이든 환영합니다.

피드백은 이 글의 댓글이나 이메일(selina2000@naver.com)로 보내주시면 감사하겠습니다. 사소한 의견이라도 서비스를 발전시키는 데 큰 도움이 될 거예요.

많은 관심과 응원 부탁드려요! 여러분의 소중한 의견 하나하나가 서비스를 발전시키는 원동력이 됩니다. 🙌

DEPROMEET 14기 활동 💪

운영진과 참가자, 두 가지 역할

저는 디프만 13기에 이어 14기 활동까지 했어요. 디프만 14기는 2023년 11월에 시작했지만, 저는 운영진으로서 2023년 8월부터 활동을 시작했습니다. 정말 먼 일처럼 느껴지지만, 돌아보니 1년 정도밖에 지나지 않은 일이네요. 운영진 활동을 하면서 동시에 참가자로도 활동했는데, 1팀 '10MM'의 팀장과 프론트엔드 개발을 맡았고, 최종적으로 최우수상을 받을 수 있었어요

10MM 프로젝트와 특별했던 팀 문화

10MM(십분만)이라는 앱 서비스를 개발하면서 주로 타이머 관련 기능과 게이미피케이션 요소를 구현했습니다. 팀장이라는 자리를 맡아 프로젝트를 이끄는 것이 처음이라 걱정이 많았지만, 좋은 팀원들을 만나 어려움 없이 마무리할 수 있었습니다.

지금 돌이켜보면 10MM 프로젝트에서 가장 기억에 남는 건 우리만의 특별한 팀 문화예요. 코어 타임을 정해두고 게더타운에 모여서 작업하면서 마치 실제로 한 공간에 있는 것처럼 소통했고, Thank To 제도를 통해 피쳐가 배포될 때마다 작업자들에게 진심 어린 감사를 전했어요. 팀원들을 각자의 특징을 닮은 별명으로 부르며 만들어간 친근한 분위기는 단순한 팀 문화를 넘어 우리를 하나로 만들어줬죠 🥺

이런 특별했던 문화 덕분인지 프로젝트가 끝난 지금까지도 팀원들과 자주 만나면서 깊은 인연을 이어가고 있어요. 지금까지 개발자로 살아오면서 만났던 수많은 사람들 중에서도 10MM 팀원들이 제일 소중한 것 같아요. 그냥 프로젝트 했던 동료가 아니라, 서로 응원하고 도와주는 평생 동료이자 친구가 된 느낌?

새로운 시작을 위한 마무리

디프만 14기에서의 활동은 이렇게 특별한 추억과 소중한 인연으로 끝이 났어요. 이후에는 다른 동아리 활동보다는 여기서 만난 인연들과 더 깊은 관계를 이어가는 데 집중하고 있습니다. 가끔 다 같이 모여서 프로젝트 할 때 추억 이야기하면서 웃곤 하는데, 그때의 열정과 즐거움이 아직도 생생하게 남아있네요 😊

UNITHON 스태프 경험 🎯

우연한 기회로 시작된 스태프 활동

친구가 UNITHON이라는 해커톤의 스태프를 구한다는 걸 알려주고, 어떻게 인지 아는 인맥을 통해 UNITHON 스태프에 지원할 수 있었어요. 실제 활동할 때는 아는 사람이 없었지만, 오히려 그때 만난 사람들과 친해질 수 있었어요.

뜻밖의 소중한 인연

같은 시간에 스태프했던 친구와는 응원하는 야구팀이 같아 야구도 보러 다닐 수 있을 정도로 친해졌어요. 운영진 분들이랑 친해지면서 'SIPE'라는 동아리에 대해 알게 되었고, 이후에 SIPE의 외부 행사에 놀러가며 사람들을 많이 만날 수 있었죠.

새로운 시각으로 바라본 해커톤

스태프를 하면서 운영진분들이랑 이야기 나눌 시간이 많았는데, 덕분에 어떻게 해커톤을 운영하고 진행하는지 참가자가 아닌 운영진의 시각에서 경험할 수 있는 새로운 기회였던 것 같아요. 그래서 이후에 정션 해커톤을 나가면서 더 좋은 운영 방식을 기대했는데... 아쉬웠죠 😅

SIPE와의 인연

UNITHON 스태프 활동을 통해 알게 된 SIPE 동아리는 기수마다 두 번 정도 외부 행사를 여는데, 제가 간 곳은 '사담콘'과 '내친소'라는 활동이었어요. 사담콘은 컨퍼런스의 일종인데 그렇게 무겁지 않으면서도 새로운 인사이트를 얻을 수 있었고, 내친소는 다양한 사람들이랑 만나고 이야기해볼 수 있는 간단한 커피챗의 장이라 정말 좋았어요 ☕

Junction 해커톤 서포터즈 경험 👩‍💻

참가자에서 서포터즈로

2023년, 지인들과 함께 참가자로 참여해 수상의 기쁨도 맛봤던 Junction 해커톤. 당시 만났던 서포터즈들과의 대화가 인상적이었고, 그들과 나눴던 이야기가 재미있어서 이번에는 서포터즈로 참여해보고 싶었습니다. Junction은 해외에서부터 시작된 해커톤으로, 제가 아는 해커톤 중에서는 가장 큰 규모를 자랑합니다. 약 200여 명의 참가자들이 모이고, 코드 레벨까지 심사에 포함되는 전문적인 행사이기에 운영진이나 이를 서포트하는 사람들을 만나고 이야기 나눌 기대가 컸습니다.

기대와 달랐던 현장

하지만 실제 서포터즈 활동은 생각과는 많이 달랐습니다. 생각보다 IT 업계와 관련 없는 분들이 많았고, Crew라고 부르는 운영진들의 경험이 많아 보이지 않았습니다. 이는 운영 측면에서 체계적이지 못한 부분들로 이어졌고, 참가자분들도 느끼셨겠지만 다소 즉흥적으로 운영되는 모습이 보였습니다.

서포터즈로서의 역할도 단순했습니다. 참가자들을 접수하고 간식을 챙기거나 발표 세션 때 준비를 돕는 등의 기본적인 업무였죠. 사실 할 일이 많지 않았음에도 불구하고, 대기 시간에도 쉬지 못하고 모여 있어야 했던 점이 가장 힘들었습니다.

새로운 인연의 시작

그래도 서포터즈분들을 만나서 좋았습니다. 기대했던 것처럼 IT 업계 사람들이 많지는 않았고, 대학생들이 많았지만 친해지면서 평소에 잘 알지 못했던 영역의 사람들과 이야기를 나눌 수 있어서 좋았습니다. 의대 학생들도 있었는데, 정말 평소에는 만날 일이 없었을 사람들과 인연을 쌓을 수 있었습니다. 크루들이 잘 대우해주진 않았다고 생각했는데, 오히려 그렇기 때문에 서포터즈끼리 더 똘똘 뭉치고 친해질 수 있었던 것 같습니다. 해커톤 이후에도 SNS 등을 통해 간간히 소통을 이어가고 있습니다.

글또 활동 ✍️

기록의 중요성을 깨닫다

디프만을 그만두면서 더 이상 사이드 프로젝트에 대한 욕심이 없어졌어요. 회사에서 문서나 이런 것들을 정리하면서 기록에 대한 중요성을 느끼고 있었는데, 이때 글또라는 동아리에 관심을 가지게 되었고 글또 10기 활동을 시작할 수 있었어요.

기술 블로그 작성의 시작

글또 활동을 하면서 글을 잘 쓰게 되었냐고 하면 아닌 것 같지만, 그래도 이전보다는 글을 쓰려고 노력하는 것 같아요. 글또를 통해 글을 쓰는 습관을 만들어가는 중이랄까요? 지금도 이렇게 회고를 쓰고 있네요 😊

주로 제가 사이드 프로젝트를 하면서 알게 된 기술적인 내용들을 공유하는 글을 작성했어요. 'SVG 스프라이트 생성 스크립트 개발기'처럼 개발하면서 겪은 이야기들을 정리하는데 중점을 뒀죠. 블로그에 글 하나를 올리는 게 쉽지는 않지만, 이렇게라도 기록을 남기니까 나중에 다시 볼 때 도움이 많이 되더라고요.

새로운 네트워크의 발견

글또에서는 "관악또", "강남또"와 같은 오프라인 모임을 하면서 글또 분들이랑 친해질 수 있었어요. 사이드 프로젝트가 아니더라도 업계 사람들을 만나고 이야기할 수 있어서 좋았죠. 다들 각자의 분야에서 열심히 하시는 분들이라 이야기를 나누면서 새로운 시각도 많이 얻을 수 있었어요. 글또 활동 기간은 아직 좀 남았는데, 글 쓰는 습관도 기르고 좋은 인연도 더 만들 수 있을 것 같아요 🌱

마치며 🌈

이렇게 2024년을 돌아보면서 글을 적다 보니, 일기처럼 회상하는 형태가 되어버렸네요. 각 활동에서 얻은 인사이트나 교훈을 체계적으로 정리하진 못했어요.

하지만 이렇게라도 글로 남기면서, 제가 올해 참 많은 것들을 경험했다는 걸 새삼 깨닫게 되었어요. 각각의 활동이 저에게 남긴 추억과 의미들을 하나하나 떠올리면서 글을 쓸 수 있어서 좋았습니다.

빠른 시일 내에 이 경험들을 바탕으로 좀 더 체계적인 회고, 예를 들면 KPT 방식으로 정리해보려고 해요. 그때는 '이런 점이 좋았다', '이렇게 했으면 더 좋았을 것 같다'와 같은 구체적인 인사이트를 정리해볼 생각이에요. 그리고 그 내용도 이 블로그에 공유할 수 있었으면 좋겠네요 😃

안녕하세요! 회사에서 불편함을 느껴 이를 개선하기 위해 Figma 플러그인을 개발하게 되었어요.

평소 프론트엔드 개발을 하면서 이미지 성능 최적화를 위해 WebP 포맷을 주로 사용하는데요, 피그마에서 이미지를 WebP로 변환하는 과정이 번거로워 이를 해결하고자 플러그인을 만들어보기로 했어요. 기존에 비슷한 플러그인이 있었지만, 제가 필요로 하는 기능들이 부족해서 직접 만들어보기로 결정했죠.

이 글에서는 피그마 플러그인을 어떻게 개발했는지, 그 과정에서 마주친 문제들을 어떻게 해결했는지 공유하려고 해요.

개발이 완료된 플러그인은 Figma Community에서 직접 사용해보실 수 있어요. 😉

코드의 퀄리티와 플러그인의 완성도보다는 개발 과정 자체를 공유하는 것에 초점을 맞췄으니 참고해서 봐주세요.

플러그인을 만들게 된 배경 🤔

기존 워크플로우의 문제점

회사에서 주로 디자이너들이 Figma에 이미지를 올려주고, 프론트 개발을 하며 이미지를 WebP로 다운받아 사용하는데, 이 과정에서 불편함을 겪었어요. Figma는 PNG, JPG, SVG 등 다양한 포맷으로 export를 지원하지만, WebP는 지원하지 않았거든요. 때문에 아래와 같은 번거로운 과정을 거쳐야 했어요

1. Figma에서 PNG로 export (보통 x2 scale로)
2. Squoosh로 이동해서 PNG를 WebP로 변환
3. 변환된 파일을 다시 프로젝트에 적용

이 과정에서 파일을 하나씩 변환하고 확인하는 작업이 꽤 번거로웠어요. 저는 주로 Squoosh를 사용했는데요. 이 프로그램은 변환된 이미지의 용량이 얼마나 줄어들었는지 바로 확인할 수 있어요. 그런데 한번에 한 이미지만 변환할 수 있다보니, 매번 이 과정을 반복하면서 작업 흐름이 자주 끊기곤 했어요.

기존 플러그인의 한계

물론 Figma에도 'Webp Exporter'라는 플러그인이 있어요. 하지만 기본적인 WebP 변환 기능만 제공할 뿐, 제가 필요로 하는 기능들이 부족했죠. 그래서 기존 기능들을 포함하면서도 추가적인 기능을 갖춘 새로운 플러그인을 만들어보기로 했어요.

플러그인 기능 정의 🎯

구현하고자 하는 피그마 플러그인의 주요 기능은 아래와 같이 두 가지로 정리할 수 있어요.

1. 피그마에서 선택한 Frame을 PNG 이미지로 가져오기

피그마에서 선택한 Frame을 UI에 보여주어 사용자가 자신이 선택한 Frame이 무엇이고 어떤 이미지를 변환하려고 하는지 인지시키고, WebP로 변환하기 위해 PNG 데이터로 가져와요.

2. WebP 변환 (이미지 변환, 최적화)

• 사용자가 선택한 PNG 이미지를 WebP 형식으로 변환
• 품질(quality)과 크기 배율(scale) 조절 기능 제공
• 브라우저의 Canvas API를 활용한 이미지 변환 및 최적화

추가 기능 💡

앞으로 구현하고자 하는 추가 기능들이에요.

• 다운 이미지 배율, 이름 설정
• 원본 PNG -> 변환 WebP 간 용량 차이 시각화
• 다운 이미지 포맷 다중 선택 (WebP, PNG)
• 변환 이미지를 S3에 업로드

이번 글에서는 플러그인 개발 전체 구현보다는 피그마 플러그인 내에서 피그마와 React 코드 간의 통신, 그리고 전체적인 WebP 변환/다운 기능에 초점을 맞춰볼게요.

플러그인 구현하기 🔨

1. 개발 환경 설정

Figma 플러그인 개발은 기본적으로 HTML, CSS, JavaScript만을 사용하도록 되어있어요. 하지만 저는 React가 더 익숙해서 Figma에서 제공하는 webpack-react샘플 코드를 사용했어요

Figma 플러그인 개발 가이드 : Plugin Quickstart Guide

플러그인은 크게 두 부분으로 나뉘어요

ui.tsx - 플러그인의 UI를 담당

function App() {
  const inputRef = React.useRef<HTMLInputElement>(null);

  const onCreate = () => {
    const count = Number(inputRef.current?.value || 0);
    // parent.postMessage로 피그마와 통신
    parent.postMessage(
      { pluginMessage: { type: "create-rectangles", count } },
      "*"
    );
  };

  return (
    <main>
      <header>
        <h2>Rectangle Creator</h2>
      </header>
      ...

여기서 parent.postMessage는 플러그인 UI와 Figma 간의 통신을 담당해요. pluginMessage에 type과 필요한 데이터를 담아 보내면, Figma 쪽에서 이를 받아 처리하는 구조예요.

code.ts - Figma와의 실제 통신을 담당

figma.showUI(__html__, { themeColors: true, height: 300 });

figma.ui.onmessage = (msg) => {
  if (msg.type === "create-rectangles") {
    // 메시지 타입에 따른 처리
    ...
  }
};

figma.showUI로 UI를 띄우고, figma.ui.onmessage로 UI에서 보낸 메시지를 받아 처리해요. 이렇게 UI와 Figma가 서로 메시지를 주고받으며 동작하는 구조예요.

2. Frame 선택 기능 구현

첫 번째로 구현한 건 Figma에서 선택한 Frame을 가져오는 기능이에요. 사용자가 변환하고 싶은 Frame을 선택하면, 그 Frame의 정보와 이미지 데이터를 가져와야 하죠.

const sendPngData = async () => {
  const node = figma.currentPage.selection[0];
  if (node) {
    // exportAsync로 PNG 데이터 추출
    const bytes = await node.exportAsync({ format: 'PNG' });
    figma.ui.postMessage({
      type: 'init-png-data',
      bytes: bytes,      // PNG 바이너리 데이터
      frameName: node.name,  // 선택한 프레임 이름
    });
  }
};

// 선택이 변경될 때마다 데이터 전송
figma.on('selectionchange', sendPngData);

여기서 node.exportAsync()는 선택한 Frame을 PNG 형식의 바이너리 데이터로 변환해요. 이렇게 얻은 데이터는 Uint8Array 형태로, 이후 WebP 변환에 사용돼요.

특히 figma.on('selectionchange', sendPngData)를 통해 사용자가 다른 Frame을 선택할 때마다 자동으로 데이터를 갱신하도록 했어요. 이렇게 하면 사용자가 여러 Frame을 연속해서 변환할 때 더 편리하죠.

3. PNG 데이터를 화면에 보여주기

이제 Figma에서 선택한 Frame의 PNG 데이터를 받아서 플러그인 UI에 표시해줄 차례예요. UI 코드는 React로 작성했는데, 여기서 중요한 건 Figma와 UI 사이의 메시지 통신이에요. React 코드에서는 useEffect 훅을 사용해서 이 통신을 처리했어요.

useEffect(() => {
    // message handler
    const messageHandler = (event: MessageEvent) => {
      const msg = event.data.pluginMessage;
      if (msg.type === 'init-png-data') {
        setInitPngData(msg);
      }
    };

    window.addEventListener('message', messageHandler);
    return () => {
      window.removeEventListener('message', messageHandler);
    };
  }, []);

이 코드에서 messageHandler는 피그마로부터 받은 메시지를 처리해요. 특히 'init-png-data' 타입의 메시지를 받으면 PNG 데이터를 상태로 저장하고 화면에 보여주게 되죠.

PNG 데이터를 UI에서 받아 미리보기를 보여주는 코드를 작성하면 플러그인 UI가 아래와 같이 보여요.

이어서 이 PNG 데이터를 WebP로 변환하는 과정을 설명해드릴게요.

3. PNG를 WebP로 변환하기

이제 PNG 데이터를 WebP로 변환하는 핵심 기능을 구현해볼게요. 이미지 변환에는 브라우저의 Canvas API를 활용했는데요, 코드의 가독성과 재사용성을 높이기 위해 관련 로직을 유틸리티 파일로 분리했어요.

첫 번째로, PNG를 Canvas에 그리는 함수를 만들었어요.

const _drawPngToCanvas = async (pngBytes: Uint8Array, scale: number) => {
  // PNG 바이너리 데이터로 Blob 생성
  const blob = new Blob([pngBytes], { type: 'image/png' });
  const image = new Image();
  image.src = URL.createObjectURL(blob);

  // 이미지 로드 완료 대기
  await new Promise((resolve) => {
    image.onload = resolve;
  });

  // Canvas에 이미지 그리기
  const canvas = document.createElement('canvas');
  canvas.width = image.width * scale;   // 배율 적용
  canvas.height = image.height * scale;
  const ctx = canvas.getContext('2d');
  ctx.drawImage(image, 0, 0, canvas.width, canvas.height);

  return canvas;
};

이 함수는 Figma에서 받은 PNG 바이너리 데이터를 Canvas에 그리는 역할을 해요. 특히 scale 파라미터를 통해 이미지 크기를 조절할 수 있어요. 예를 들어 scale이 2라면 원본 크기의 2배로 이미지가 그려지죠.

그 다음으로는 Canvas의 내용을 WebP로 변환하는 함수를 만들었어요.

export const exportWebP = async (
  pngBytes: Uint8Array,
  fileName: string,
  quality: number,
  scale: number
) => {
  const canvas = await _drawPngToCanvas(pngBytes, scale);

  // Canvas를 WebP로 변환
  return new Promise((resolve, reject) => {
    canvas.toBlob(
      (webpBlob) => {
        if (webpBlob) {
          resolve(webpBlob);
        } else {
          reject(new Error('WebP 변환 실패'));
        }
      },
      'image/webp',
      quality / 100  // 품질 설정 (0~1)
    );
  });
};

이 함수는 Canvas에 그려진 이미지를 WebP 형식으로 변환해요. quality 파라미터를 통해 변환된 이미지의 품질을 조절할 수 있는데, 0부터 100 사이의 값을 받아요. 높은 값일수록 품질은 좋아지지만 파일 크기도 커지겠죠.

이렇게 변환된 WebP 이미지는 Blob 형태로 반환되어 다음 단계인 다운로드 기능에서 사용할 수 있어요.

4. 파일 다운로드 구현

마지막으로 변환된 WebP 파일을 다운로드할 수 있는 기능을 만들어볼게요. 브라우저에서 파일을 다운로드 받을 수 있도록 유틸리티 함수를 하나 만들었어요.

export const downloadFile = (blob: Blob, fileName: string) => {
  return new Promise<void>((resolve) => {
    const url = URL.createObjectURL(blob);
    const link = document.createElement('a');
    link.href = url;
    link.download = fileName;
    link.click();

    // Blob URL 정리
    setTimeout(() => {
      URL.revokeObjectURL(url);
      resolve();
    }, 1000);
  });
};

이 함수에서는 브라우저의 URL.createObjectURL()을 사용해서 파일 다운로드를 구현했어요. 특히 메모리 누수를 방지하기 위해 다운로드가 완료된 후에는 URL.revokeObjectURL()로 생성한 URL을 정리하는 것도 잊지 않았죠.

마지막으로, 변환과 다운로드를 연결하는 부분도 구현했어요.

try {
  const webpBlob = await exportWebP(pngBytes, fileName, quality, scale);
  await downloadFile(webpBlob, fileName);
  // 다운로드 완료 알림
  parent.postMessage({ pluginMessage: { type: 'export-complete' } }, '*');
} catch (error) {
  console.error('내보내기 중 오류:', error);
}

변환과 다운로드가 성공적으로 완료되면 Figma에 메시지를 보내서 사용자에게 완료 알림을 보여주도록 했어요. 혹시 오류가 발생하면 콘솔에 로그를 남겨서 디버깅할 수 있도록 했고요.

마치며 🎉

이렇게 해서 Figma에서 WebP 변환 작업을 훨씬 수월하게 할 수 있게 되었어요. 최종적으로 완성된 플러그인은 아래와 같이 동작해요

1. Figma에서 Frame을 선택하면 자동으로 미리보기가 표시돼요
2. 품질과 크기를 조절할 수 있어요
3. 파일 이름도 원하는 대로 설정할 수 있어요
4. 변환 버튼 하나로 WebP 파일이 바로 다운로드돼요

개발하면서 특히 신경 썼던 부분들이 있는데요.

• 실시간으로 Frame 선택을 감지해서 바로 미리보기를 보여주도록 한 것
• 메모리 누수를 방지하기 위해 Blob URL을 적절히 정리한 것
• 사용자에게 진행 상황과 완료를 알려주는 피드백 시스템

물론 아직 개선하고 싶은 부분들이 있어요.

• 여러 개의 Frame을 한 번에 처리하는 배치 기능
• S3에 직접 업로드하는 기능
• 더 세밀한 이미지 최적화 옵션들
• 변환 전/후 용량을 비교할 수 있는 기능

이런 기능들은 차근차근 추가해볼 계획이에요. 이번 개발을 통해 Figma Plugin API와 Canvas API에 대해 많이 배웠는데, 이런 경험들을 바탕으로 더 유용한 기능들을 만들어볼 수 있을 것 같아요.

앞으로도 플러그인을 개선하면서 겪은 이야기들을 계속 공유해볼게요. 궁금한 점이나 제안하고 싶은 기능이 있다면 언제든 피드백 주세요!

만들어진 플러그인 확인해 보러 가기 👉 Figma Community - Select Frame To WebP

GitHub Issue를 활용한 피드백 시스템을 운영하면서 예상치 못한 문제가 발생했습니다. 처음에는 모든 게 잘 돌아가는 것처럼 보였는데, 어느 날 로그를 확인하다가 이상한 점을 발견했죠. 사용자들의 피드백이 GitHub Issue에 등록되지 않는 현상이 있었습니다.

원인을 파악해보니 GitHub API의 권한 체계와 관련이 있었습니다. 기존 구현에서는 Issue를 생성할 때 assignees(담당자)를 지정하도록 되어 있었는데, 이 기능을 사용하려면 해당 레포지토리에 commit 등의 접근 권한이 필요했던 거죠. 결과적으로 권한이 없는 일반 사용자의 피드백은 등록 자체가 실패하고 있었습니다 😱

테스트 할때는 당연히 권한이 있는 제 계정을 사용했기 때문에 문제를 발견하지 못했던 것이죠

문제 해결 과정 💡

1. 권한 문제 해결 방안 모색

첫 번째로 시도한 것은 레포지토리 권한이 없는 사용자도 이슈에서 언급될 수 있도록 하는 방법을 찾는 것이었습니다. GitHub API 문서를 뒤져가며 여러 방법을 시도해봤지만, API를 통해 직접적으로 권한 없는 사용자를 언급하는 것은 불가능했습니다. 이는 GitHub에서 무분별한 할당을 막기 위해 추가한게 아닐까 생각했어요.

하지만 곧 대안을 발견했습니다. GitHub에서는 @사용자이름 형식의 텍스트만으로도 언급 기능이 활성화된다는 점을 생각했죠. 즉, API로 직접 멘션하는 대신 이슈나 댓글의 내용에 사용자 이름을 포함시키면 언급할 수 있는 거예요!

이 방법을 적용하기 위해 팀 내부에서 논의를 진행했고, 이슈 본문은 문제 상황을 명확하게 기술하는 데 집중하고, 사용자와의 커뮤니케이션은 댓글을 통해 하는 것이 더 자연스럽다고 판단해, 이슈 본문에 사용자를 언급하는 것보다는 댓글을 통해 언급하는 것이 더 적절하다는 결론을 내렸습니다.

2. Octokit 도입으로 API 활용 개선

문제 해결에 들어가기 전에, GitHub API를 더 효율적으로 사용할 방법을 찾아보았습니다. 기존에는 일반적인 fetch 요청을 사용했는데, 이는 타입 안정성이나 에러 처리 면에서 아쉬운 점이 있었어요.

Octokit이라는 GitHub의 공식 REST API 클라이언트 라이브러리를 발견 할 수 있었어요.

Octokit은 다음과 같은 장점들을 제공했습니다.

• TypeScript 지원으로 타입 안정성 확보
• 자동 인증 처리
• 레이트 리밋 관리
• 편리한 에러 핸들링

이를 활용하기 위해 먼저 Octokit을 사용하기 위한 core 로직을 다음과 같이 구성했습니다.

import { Octokit } from '@octokit/core';

const ISSUE_TOKEN = process.env.NEXT_PUBLIC_ISSUE_TOKEN;

const octokit = new Octokit({
  auth: ISSUE_TOKEN,
});

const OCTOKIT_BASE_INFO = {
  owner: 'git-good-w',
  repo: 'gitanimals',
  headers: {
    'X-GitHub-Api-Version': '2022-11-28',
  },
} as const;

export const requestOctokit = async (method: 'GET' | 'POST', url: string, data?: object) => {
  const response = await octokit.request(`${method} ${url}`, {
    ...OCTOKIT_BASE_INFO,
    ...data,
  });

  return response.data;
};

제가 의도한 주요 포인트를 살펴보자면

• 환경 변수를 통해 GitHub 토큰을 안전하게 관리합니다
• API 버전을 명시적으로 지정하여 예상치 못한 변경을 방지합니다
• 공통으로 사용되는 설정을 OCTOKIT_BASE_INFO로 분리했습니다
• 범용적으로 사용할 수 있는 requestOctokit 함수를 만들어 코드 중복을 줄였습니다

3. Issue 생성 및 댓글 기능 구현

이제 Octokit을 활용하여 실제 피드백 제출 기능을 구현했습니다. 가장 중요한 것은 Issue 생성과 댓글 작성을 안정적으로 처리하는 것이었죠.

export async function postFeedback(request: PostFeedbackRequest): Promise<PostFeedbackResponse> {
  const issueData = await postIssue(request);

  if (request.username) {
    const commentBody = `@${request.username}\nThanks for reporting the issue!`;
    await createComment({ issueNumber: issueData.number, body: commentBody });
  }

  return issueData;
}

이 구현에서 중요하게 고려한 점들은 다음과 같습니다.

안정성 확보

• Issue 생성과 댓글 작성을 분리하여 각각의 작업이 실패했을 때 독립적으로 처리할 수 있도록 했습니다
• 사용자 이름이 있는 경우에만 멘션 댓글을 추가하여 불필요한 API 호출을 방지했습니다

사용자 경험 개선

• 피드백 제출 직후 바로 멘션 댓글이 달리도록 하여 사용자가 자신의 피드백이 잘 등록되었음을 즉시 확인할 수 있습니다
• 친근한 메시지로 사용자와 소통합니다

확장성 고려

• 추후 피드백 처리 프로세스가 변경되더라도 쉽게 수정할 수 있도록 모듈화된 구조를 유지했습니다
• TypeScript의 타입 시스템을 활용하여 코드의 안정성을 높였습니다

전체 프로세스 🔄

개선된 피드백 시스템의 전체 동작 흐름을 시퀀스 다이어그램으로 표현하면 다음과 같습니다

이 프로세스를 통해 사용자의 피드백이 안정적으로 GitHub Issue에 등록되고, 사용자는 자신의 피드백 처리 현황을 쉽게 확인할 수 있게 되었습니다.

마무리 🎉

이번 개선 작업을 통해 문제를 해결할 뿐 아니라 피드백 시스템이 한층 더 안정적이게 된것 같아요. 로그를 통해 문제를 발견하고 해결하는 과정을 거치니 로그의 중요성을 더 잘 알게된것 같습니다

개발을 하다 보면 이렇게 예상치 못한 문제들을 마주치게 되는데, 이런 문제들을 해결하면서 시스템도 개선하고 새로운 것을 배울 수 있는 기회가 된 것 같아요 🌱

실제 구현된 코드는 PR #173에서 확인하실 수 있습니다. 코드를 살펴보시면서 더 자세한 구현 내용을 확인해보세요!

• 문제 상황
• 해결 과정
• 최종 해결책
• 참고 자료

문제 상황 😵

다른 서비스간 로그인 연동 기능에서 특별한 요구사항이 있었습니다. 사용자가 로그인 과정에서 서비스를 이탈하면, 실패 상태를 다른 서비스에 API로 알려줘야 했죠. (다른 서비스는 polling으로 상태를 체크하고 있었습니다)

단순히 생각했을 때는 unload 이벤트에 API를 호출하면 될 것 같았지만... 실제로는 그렇게 간단하지 않았습니다. 🤔

해결 과정 🔍

1. 첫 시도: unload 이벤트 활용

처음에는 아래와 같이 단순하게 구현했습니다.

const callback = () => {
  // API 호출 -> expired status로 변경
}

useEffect(() => {
  window.addEventListener('unload', callback);
  return () => {
    window.removeEventListener('unload', callback);
  };
}, [callback]);

하지만 이 방식에는 문제가 있었습니다. 브라우저가 종료되면서 API 요청이 간헐적으로 취소되는 현상이 발생했거든요. 🤯

2. 문제 분석

API 요청이 실패하는 이유를 파악해보니, 아래와 같이 확인할 수 있었습니다.

1. 브라우저는 열린 HTTP 요청의 완료를 보장하지 않습니다.
2. XHR 요청(fetch 또는 XMLHttpRequest)은 비동기적이고 non-blocking입니다.
3. 브라우저는 페이지가 종료될 때 진행 중인 백그라운드 프로세스를 계속 유지할 필요가 없다고 판단합니다.

3. 대안 탐색

하지만 어떻게든 API 요청이 끊기지 않게 해야했죠 😭 대안을 찾아 보았을 때, 브라우저 종료 시에도 HTTP 요청을 안정적으로 보내기 위한 두 가지 방법을 발견했습니다

1. Navigator.sendBeacon() 사용
2. fetch의 keepalive 플래그 사용

Navigator.sendBeacon() 검토 ❌

sendBeacon()은 분석 정보 전송을 위해 설계된 좋은 방법이지만, 커스텀 헤더를 지원하지 않는다는 치명적인 단점이 있었습니다.

axios keepAlive 옵션 검토 ❌

axios에서도 keepAlive 옵션을 제공하지만, Node.js 환경에서만 사용 가능했습니다.

참고 링크 : https://gist.github.com/ccnokes/94576dc38225936a3ca892b989c9d0c6

// Node.js 환경에서만 가능한 코드
const axios = require('axios');
const http = require('http');
const https = require('https');

module.exports = axios.create({
  httpAgent: new http.Agent({ keepAlive: true }),
  httpsAgent: new https.Agent({ keepAlive: true }),
  // ...
});

최종 해결책 ✨

결국 fetch와 keepalive 옵션을 조합한 방식을 채택했습니다.

const updateExpired = (uuid: string) => {
  const data = {
    status: 'expired',
  };

  const fetchConfig = {
    method: 'POST',
    body: JSON.stringify(data),
    headers: customHeader,  // 커스텀 헤더 설정
    keepalive: true, // 핵심! keepalive 옵션 추가
  };

  return fetch('API URL', fetchConfig);
};

이 방식의 장점:

• 브라우저 종료 시에도 API 요청이 안정적으로 전송됨
• 커스텀 헤더 사용 가능
• 구현이 간단함

실제 다른 서비스에서 응답을 잘 받아오는지 반복적인 테스트를 통해, 정상적으로 받아오는 것을 확인하였습니다 🎉

마무리 🎯

브라우저 종료 시의 API 호출은 생각보다 까다로운 문제였지만, keepalive 옵션을 활용하여 깔끔하게 해결할 수 있었습니다. 특히 페이지 생명주기와 브라우저의 동작 방식을 공부할 수 있는 계기가 되었던것 같아요.

참고 자료 📚

• Chrome 페이지 수명 주기 API
• MDN - Navigator.sendBeacon()
• Browser에서 페이지 종료 시 HTTP 요청 보내기

SVGO라는 라이브러리를 이용해서 SVG 파일을 최적화하고, 이를 sprite SVG 생성 과정에 통합해 보았어요.

SVGO를 이용한 SVG 최적화의 장점

*SVG 최적화가 왜 필요할까요? * 제가 생각한 이점은 아래와 같아요.

1. 파일 크기 감소: 불필요한 데이터를 제거해서 파일 크기를 줄일 수 있어요. => 웹사이트의 로딩 속도 향상
2. 코드 가독성 향상: 최적화 과정에서 SVG 코드가 정리되어 더 읽기 쉬워져요.
3. 렌더링 성능 개선: 복잡한 경로를 단순화하면 브라우저가 SVG를 더 빠르게 렌더링할 수 있어요.

가장 큰 장점은 파일 크기 감소라고 생각해요. sprite svg를 만들때 많은 svg를 사용하기 때문에 더욱 효과가 커질거라고 예상했어요.

SVG 최적화 및 Sprite SVG 생성 방법

SVGO란?

SVGO(SVG Optimizer)는 SVG 파일을 최적화하기 위한 Node.js 기반의 도구예요. 이 라이브러리는 아래와 같은 다양한 최적화 기법을 사용해 SVG 파일의 크기를 줄이고, 구조를 개선해줍니다.

1. 불필요한 메타데이터 제거
2. 중복된 요소 및 그룹 정리
3. 경로 데이터 최적화
4. 색상 값 정규화
5. 기본값과 같은 속성 제거

SVGO는 플러그인 시스템을 통해 사용자가 원하는 대로 최적화 과정을 커스터마이징할 수 있어, 사용하기로 결정하였어요

1. SVGO 라이브러리 설치

npm install svgo

이 링크에서 자세한 내용을 확인할 수 있어요.

2. SVG 최적화 설정

제가 사용한 설정은 아래와 같아요. 혹시 이미지가 깨질 수 있을것 같아 간단한 설정만을 적용해보았아요.

const svgoConfig: SvgoConfig = {
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          removeViewBox: false,
          removeUselessStrokeAndFill: false,
          cleanupIds: false,
        },
      },
    },
    'removeXMLProcInst',
    'removeXMLNS',
    'removeDimensions',
    'minifyStyles',
    'removeComments',
    'removeHiddenElems',
    'removeEmptyAttrs',
    'removeEmptyText',
    'removeEmptyContainers',
    'collapseGroups',
    'removeMetadata',
    {
      name: 'convertPathData',
      params: {
        floatPrecision: 2,
      },
    },
  ],
};

이중에 알면 좋은 것들 몇개를 설명해보자면,,

• removeViewBox: false: viewBox 속성을 유지해요. (SVG의 크기 조정에 중요!)
• removeUselessStrokeAndFill: false: stroke와 fill 속성을 보존해요.
• cleanupIds: false: ID 충돌을 방지하기 위해 ID를 그대로 유지해요.
• convertPathData: 경로 데이터를 최적화하고, 소수점 정밀도를 2로 제한해요.

3. SVG 최적화 함수 생성

export const optimizeSvg = (svg: string): string => {
  const result = optimize(svg, svgoConfig);
  return result.data;
};

이 함수는 SVG 문자열을 받아서 최적화된 SVG 문자열을 반환하는 역할이예요. 다양한 곳에서 동일하게 사용하고 싶어 함수로 분리했어요.

4. 최적화된 SVG로 Sprite 생성

기존의 getSvgFiles 함수를 수정해서 SVG를 가져온 후 바로 최적화하도록 해볼게요.

const getSvgFiles = async (spriteInfo: SpriteInfoValue): Promise<SvgFile[]> => {
  const svgFiles = await Promise.all(
    spriteInfo.list.map(async (item) => {
      try {
        const res = await axios.get(`스프라이트 폴더 경로/${item}.svg`);
        // SVG를 가져온 후 바로 최적화해서 저장해요. 
        const optimizedSvg = optimizeSvg(res.data); 
        return {
          name: item,
          data: optimizedSvg,
        };
      } catch (error) {
        console.error(`❌ - Failed to fetch SVG for ${item}`);
        return null;
      }
    })
  );

  return svgFiles.filter((file) => file !== null) as SvgFile[];
};

마무리

이렇게 SVGO를 이용해 SVG를 최적화하고, 이를 sprite SVG 생성 과정에 통합해 보았어요. 최적화 과정을 추가했더니 생성된 sprite SVG의 크기가 눈에 띄게 줄어들더라고요. 특히 수백개의 국가 이미지를 다루는 프로젝트에서는 그 효과가 정말 크게 느껴졌어요.

실제로 최적화 전후의 sprite SVG 파일 크기를 비교해봤는데요,

위 스크린샷을 보시면 최적화 전후의 파일 크기 차이를 확실히 확인할 수 있어요 최적화 전 sprite SVG 파일의 크기가 538KB였는데, 최적화 후에는 252KB로 줄어들었어요. 반정도의 크기 감소를 이루어낸거죠! 🎉

이미지 하나의 용량을 줄여도 서비스의 성능을 크게 개선되는 것은 아니지만, 이런 작은 최적화 하나하나가 모여서 전체 프로젝트의 성능을 크게 향상시킬 수 있을거라고 생각해요. 👍

React 17에서 18로 버전을 업그레이드하면서 예상치 못한 라우팅 문제가 발생했습니다. 프로젝트에서 react-router-dom v5.3.4를 사용 중이었는데, 특정 페이지에서 뒤로가기 기능이 제대로 작동하지 않는 현상이 나타났습니다. 단순히 뒤로가기가 안되는것은 아니였고, 다른 페이지로의 이동에서도 동일한 현상이 발생하는 상황이었습니다.

밑과 같이 url은 정상적으로 변경되는데 새로 렌더링되지 않아, 화면에는 여전히 이전 페이지의 내용이 표시되는 것이 문제였어요.

http://localhost:3000/history/detail -> http://localhost:3000/history

원인 분석 🤔

문제의 원인을 찾기 위해 여러 자료를 찾아본 결과, React 18과 react-router-dom v5의 조합에서 React.StrictMode가 문제를 일으키고 있다는 알게되었고, React 18에서는 StrictMode의 동작이 변경되면서 이로 인해 react-router-dom v5와 호환성 문제가 발생한 것으로 확인하였습니다.

issue의 답변중 아래와 같은 답변이 있습니다.

Just to clarify the issue: with React 18 StrictMode, react-router does not perform the transition when navigation occurs. The route is stale when the path is changed: codesandbox.io/s/dreamy-andras-hbuco1?file=/src/index.tsx

참고한 이슈

• react-router github issue
• stackoverflow

fyi) react-router-dom v5.3.3 이상에서는 이 문제가 해결되었다고 알려져 있었지만, 실제로 v5.3.4를 사용 중임에도 같은 문제가 발생하였습니다 관련 PR

해결 방법 💡

이슈를 확인해보았을 때 해결 방법으로는 아래 두 방법을 확인하였습니다.

1. react-router-dom을 v6로 업그레이드
2. React.StrictMode의 위치를 BrowserRouter 내부로 이동

저는 프로젝트의 규모와 복잡도를 고려했을 때, v6로의 업그레이드는 상당한 작업량이 필요할 것으로 예상되어 2번 방법을 선택하였습니다.

🔍 react-router-dom v6로 업그레이드를 고려 중이라면, React Router의 공식 업그레이드 가이드를 참고하는 것이 좋을 것 같아요

코드 수정 🛠️

문제 해결을 위해 React.StrictMode와 BrowserRouter의 위치를 다음과 같이 변경했습니다.

변경 전:

<React.StrictMode>
  <BrowserRouter>
    {/* ... */}
  </BrowserRouter>
</React.StrictMode>

변경 후:

<BrowserRouter>
  <React.StrictMode>
    {/* ... */}
  </React.StrictMode>
</BrowserRouter>

구체적인 코드 변경 내용은 다음과 같습니다

변경 전 (/src/index.tsx):

const container: Element = document.getElementById('root') as Element;
const root = createRoot(container);

root.render(
  <>
    <React.StrictMode>
      <Suspense fallback={<div></div>}>
        <MypageApp /> {/* 내부에 BrowserRouter 존재 */}
      </Suspense>
    </React.StrictMode>
  </>
);

변경 후 (/src/index.tsx):

const container: Element = document.getElementById('root') as Element;
const root = createRoot(container);

root.render(
  <>
    <BrowserRouter>
      <React.StrictMode>
        <Suspense fallback={<div></div>}>
          <MypageApp />
        </Suspense>
      </React.StrictMode>
    </BrowserRouter>
  </>
);

결론 📄

React 18로의 마이그레이션 과정에서 예상치 못한 라우팅 문제가 발생했지만, React.StrictMode와 BrowserRouter의 위치를 조정하는 간단한 방법으로 해결할 수 있었어요.

하지만 위와 같은 방법을 사용하는 것은 임시 방편일 뿐, 장기적으로 보면은 react-router-dom v6로 마이그레이션 하는것이 가장 좋은 해결책일 것 같습니다 🥲

React Router Issue에서도 관련 내용이 존재합니다.

1. 어떤 sprite SVG를 만들지 선택해요.
2. 선택한 키에 따라 sprite map 정보를 가져와요.
3. SVG 리스트 데이터로 sprite SVG를 생성해요.
4. 생성된 sprite SVG를 파일로 저장해요.

스크립트 사용 예시는 아래와 같아요:

$ yarn scripts sprite countryCode

이 명령어를 실행하면 스크립트가 동작하여 countryCode.svg라는 sprite SVG 파일이 생성돼요. 이 파일 하나에 모든 국가 코드 아이콘이 포함되어 있죠! (저는 270여개의 국가 이미지를 한 sprite svg를 이용해 불러올 수 있도록 하려고해요. )

1. Sprite SVG 선택하기

먼저, 어떤 sprite SVG를 만들지 정의하는 부분부터 시작했어요. SPRITE_MAP이라는 객체를 만들어서 여기에 모든 정보를 담았죠.

const SPRITE_MAP = {
  countryCode: {
    key: 'countryCode',
    svgBaseUrl: '외부_이미지_경로',
    list: COUNTRY_CODE_LIST,
  },
} as const;

type SpriteMapKey = keyof typeof SPRITE_MAP;
type SpriteInfoValue = (typeof SPRITE_MAP)[SpriteMapKey];

이 SPRITE_MAP에는 제가 만들 수 있는 모든 sprite SVG의 정보가 들어있어요. 예를 들어, countryCode는 국가 코드 아이콘을 위한 sprite SVG의 키예요.

TypeScript를 사용해서 타입 안정성도 확보했는데, 이게 나중에 오타 같은 실수를 많이 준것 같아요. 처음에는 좀 번거롭다고 생각했는데, 쓰다 보니 정말 편하더라고요. 😉

2. 스크립트 실행하기

그 다음으로 스크립트를 실행하는 run 함수를 만들었어요.

const run = async () => {
  const spriteKey = process.argv[2] as SpriteMapKey;

  if (!spriteKey) {
    console.error(chalk.redBright(`❌ - Need to provide a sprite key`));
  }

  if (!Object.keys(SPRITE_MAP).includes(spriteKey)) {
    console.error(chalk.redBright(`❌ - Invalid sprite key: ${spriteKey}`));
    return;
  }

  const CURRENT = SPRITE_MAP[spriteKey];

  try {
    const svgFiles = await getSvgFiles(CURRENT);
    const svgSprite = await getSpriteSvg(svgFiles);

    spriteSaveFile(svgSprite, `${CURRENT.key}.svg`);

    console.log(chalk.greenBright(`COMPLETE 🎉`));
  } catch (error) {
    console.error(error);
  }
};

run(); // 스크립트 실행

이 함수는 명령줄에서 받은 spriteKey를 확인하고, 그에 따라 sprite SVG를 생성해요.

chalk 라이브러리를 사용해서 콘솔 메시지에 색을 입혔는데, 이런 작은 디테일이 개발 경험을 훨씬 좋게 만들어주더라고요. 에러는 빨간색, 성공은 초록색으로 보이니까 쉽게 구분이 가더라구요.

3. SVG 파일 가져오기와 Sprite SVG 생성하기

getSvgFiles와 getSpriteSvg 함수는 이전 글에서 설명한 것과 동일해요. 이 부분을 자동화하니까 작업 속도가 엄청 빨라졌어요!

4. Sprite SVG 저장하기

마지막으로, 생성된 sprite SVG를 파일로 저장하는 함수를 만들었어요.

const spriteSaveFile = (svgSprite: string, fileName: string) => {
  const dir = path.resolve(__dirname, '../public/assets/sprite');
  if (!fs.existsSync(dir)) {
    fs.mkdirSync(dir, { recursive: true });
  }
  fs.writeFileSync(path.join(dir, fileName), svgSprite);
};

이 함수는 생성된 sprite SVG를 지정된 디렉토리에 저장해요.

마치며

이렇게 스크립트를 만들어서 sprite SVG를 자동으로 생성해보니, 정말 편하더라고요. 수동으로 SVG 파일을 합치는 번거로운 작업을 안 해도 되니까 시간도 많이 절약되고, 실수할 가능성도 줄어들었어요.

특히 이 스크립트의 장점은 확장성 이라고 생각해요. 새로운 아이콘 세트가 필요하다면 SPRITE_MAP에 새로운 키와 정보만 추가하면 돼요. 예를 들어, 결제 방법 아이콘을 추가하고 싶다면 이렇게 할 수 있죠:

const SPRITE_MAP = {
  countryCode: {
    // ... 기존 코드
  },
  paymentMethods: {
    key: 'paymentMethods',
    svgBaseUrl: '외부_이미지_경로',
    list: PAYMENT_METHODS_LIST,
  },
} as const;

그러면 yarn scripts sprite paymentMethods 명령어로 결제 방법 아이콘 sprite를 생성할 수 있어요.

이런 자동화 스크립트를 만드는 데 시간을 투자하니까, 장기적으로 봤을 때 정말 많은 시간과 노력을 아낄 수 있겠더라구요.

앞으로도 이렇게 자동화, 성능을 최적화해서 서비스를 개선할 방법을 계속 찾아보려구요!

다음에는 sprite svg를 좀 더 작은 용량으로 만들 수 있는, svg 최적화를 다뤄볼게요 👍

어쩌다 컴공을 갔더라..

고등학교 때 저는 대부분의 또래처럼 미래에 대한 뚜렷한 계획 없이 살아가고 있었어요. 이과였지만 순수 과학은 영 아니다 싶었고, 그냥 막연하게 “공대에 가야지...“하고 생각하고 있었어요.

대체로 게임을 좋아했는데, 그중 '스타듀밸리'라는 게임을 즐겨하였어요. 이 게임은 도트 그래픽 기반의 농장 시뮬레이션 게임인데, 1인 개발자가 만들어서인지 커스터마이징이 매우 자유로웠어요. 게임 공식 카페에 가보면 다양한 커스텀 모드나 리텍(그래픽, 텍스처 변경) 자료들이 많았고, 새로운 농장 기구를 추가하는 것부터 캐릭터, 주민들의 대사, 외형 등 거의 모든 것을 바꿀 수 있었어요.

카페에서 다른 사람들이 만든 모드를 다운받아 사용하다 보니 '나도 이런 걸 만들 수 있지 않을까?'하는 생각이 들었어요. 게임을 좋아하는 제게 이런 작업이 굉장히 매력적으로 느껴졌고, 이것이 제가 프로그래밍에 관심을 갖게 된 첫 계기였던 것 같아요.

그래서 대학 원서를 쓸 때, 깊은 고민 없이 모든 지원을 컴퓨터공학과로 하게 되었어요. 지금 생각해 보면 꽤 즉흥적인 결정이었지만, 이 선택이 제 인생의 방향을 결정지은 중요한 순간이었던 것 같아요

내가하고싶은게 뭘까?

대학에 입학하고 보니 주변 친구들의 실력이 너무 뛰어나서 '다들 이렇게 잘하는데 나는 뭐지?' 하는 생각을 했었던 것 같아요. 하지만 이대로는 뒤처질 수 없다, 뭐라도 해야겠다는 생각이 들었어요.

그래서 1학년 동안에는 "파워 자바"라는 책을 붙잡고 이해될 때까지 코드를 치고 실행시키는, 지금 생각하면 꽤 무식한(?) 방법으로 공부했어요. 그래도 이 과정을 통해 Java 언어를 공부하고 이후에는 C++과 같은 다른 언어들도 어렵지 않게 이해할 수 있게 되었고, 더 이상 프로그래밍이 무섭게 느껴지지 않았어요.

그러다 시간이 흘러 2학년 1학기가 끝나고, 다음 학기 수강 과목을 고민하던 중 "웹 프로그래밍" 과목이 눈에 띄었어요. 과제가 많고 힘들다는 소문이 있었지만, 다른 과목들보다는 흥미로워 보였습니다. 그래서 방학 동안 선배에게 미리 정보를 받아 선행학습을 시작했는데, 어려운 거랑 별개로 예상외로 재미있었어요.

이 과목을 통해 처음으로 웹 개발을 접하게 되었고, 결과적으로 A+를 받을 수 있었어요. 이 경험이 제가 프론트엔드 개발에 빠지게 된 결정적인 계기였던 것 같아요. 화면에 내가 원하는 대로 무언가를 만들어내고, 다른 사람이 이를 인정해 준 첫 기억이거든요.

왜 백엔드를 안 했냐고요? 글쎄요, 그냥 이쁘고 내 맘대로 만들 수 있는 것이 좋았어요. 프론트엔드 개발을 하면서 즉각적으로 결과물을 볼 수 있다는 점이 저와 잘 맞았어요. 화면에 뭔가가 나타나고, 사용자와 상호작용하는 것을 보는 게 정말 재미있었어요. 물론 백엔드도 중요하다는 걸 알고 있었지만, 프론트엔드에서 느끼는 즐거움이 더 컸던 것 같아요. 그래서 자연스럽게 프론트엔드 개발자의 길을 걷게 된 거죠.

외부 활동을 시작해 보았어요

4학년쯤 되니까 수업 듣는 게 지루해져서 인턴을 시작했어요. 사실 처음엔 그냥 학교 다니기 싫어서였는데, 결과적으로 이 경험들이 제게 정말 많은 걸 가르쳐 줬어요. 학교에서 하는 인턴십이나, 여러 외부 인턴십에 지원하였고, 운이 좋게도 여러 곳에서 일할 기회를 얻을 수 있었어요.

첫 인턴은 에너지기술원이었어요. 이름에서 알 수 있듯이, 주변에 개발자는 저 말고는 없었어요. 신소재 공학, 화학공학 하는 연구원들과 인턴들뿐이었거든요. 그러다 보니 제가 그곳의 유일한 개발자였죠.

처음엔 정말 막막했어요. 하지만 이 상황이 오히려 제게 좋은 학습 기회가 되었어요. 혼자 개발하다 보니 박사님들이나 다른 인턴들과 직접 소통하면서 일을 진행해야 했거든요. 주로 연구 결과를 저장하고 쉽게 볼 수 있는 사이트를 개선하는 일이었는데, 이 과정에서 개발의 실제적인 의미를 깨달았어요. 다른 분야 사람들의 니즈를 이해하고 그걸 기술로 구현하는 게 얼마나 중요한지 알게 됐죠. 개발자가 단순히 코드만 작성하는 사람이 아니라, 다양한 배경의 사람들과 소통하면서 니즈에 따라 문제를 해결하는 사람이라는 걸 직접 경험할 수 있었어요.

인턴 마지막쯤에 최종 발표를 했는데, 발표 전에 많이 긴장했어요. 하지만 예상외로 모두 긍정적인 평가를 해주셨어요. 그때 느낀 안도감과 성취감은 지금도 생생해요. 나중에 박사님께서 연락해 주셔서 추가 작업을 할 의향이 있는지 물어보셨어요. 제 능력을 인정받은 것 같아 기뻤지만 아쉽게도 거절하였는데, 이미 다른 인턴을 시작했기도 하였고 혼자 일하는 게 조금은 아쉽게 느껴졌거든요.

이전에는 혼자 사이드로만 진행하던 것을 처음으로 실제 프로젝트에서 개발을 해보면서, 개발이 단순히 코드를 작성하는 게 아니라는 걸 깨달을 수 있는 경험이었어요. 다양한 배경을 가진 사람들과 소통하며 문제를 해결하는 과정, 그게 바로 개발이더라고요. 이런 깨달음 덕분에 '앞으로 어떤 개발자가 되어야 할까?'를 진지하게 고민하게 됐어요.

이후에 작은 스타트업에서 인턴을 해보았는데, 제 개발 실력을 한 단계 끌어올리는 계기가 됐어요.

개발자가 몇 명 없는 환경이었지만, 특히 프론트엔드 시니어 개발자분과의 교류가 가장 값진 경험이었어요. 단순히 코드를 같이 보는 것을 넘어서, 개발자로서의 성장 방향에 대한 조언을 들을 수 있었거든요. 이 과정에서 제 코딩 스타일이 많이 다듬어졌고, 무엇보다 개발자로서의 마인드 셋을 형성할 수 있었어요.

또 하나 큰 도움이 된 건 같이 인턴을 하던 친구와의 수다였어요. 우리끼리 이런저런 기술 얘기를 하다가 모르는 게 있으면 바로 시니어분들께 물어볼 수 있는 환경이었거든요. 이런 과정을 거치면서 '어려운 문제를 함께 고민하고 해결할 수 있는 동료’가 있는 팀, 환경이 정말 행운이라는 걸 알게 되었어요.

이 인턴십은 단순히 기술을 배우는 것을 넘어서, 개발자로서의 전체적인 성장 방향을 잡는 데 큰 도움이 됐어요. 코드를 작성하는 기술뿐만 아니라, 팀워크의 중요성, 그리고 개발 철학까지 배울 수 있었던 것 같아요.

난 진짜 말하는 감자였다

대학을 졸업하고 운 좋게 디프만이라는 IT 연합동아리에 들어가게 됐어요. 디프만은 개발자와 디자이너들이 모여서 한 학기 동안 서비스를 만드는 동아리예요. 처음엔 '여기까지 왔으니 이제 개발 좀 하는 편이겠지?' 하고 은근히 자신했어요. 근데 이게 웬걸, 주변에 실력자들이 너무 많은 거예요. 그때 깨달았죠. '아... 난 아직 한참 멀었구나.'

정말 대단한 사람들 사이에 있다 보니 처음엔 기가 좀 죽더라고요. '내가 여기에 있어도 되나?' 싶기도 했어요. 하지만 이대로 포기하면 영영 따라잡지 못할 것 같아서, 끊임없이 질문하고 배우려 노력했어요.

디자이너와 처음 협업할 때는 정말 긴장됐어요. 제가 실수해서 팀에 피해 주면 어쩌나 걱정돼서 어떻게 하면 잘 소통할 수 있을지 열심히 고민했죠. 서로 다른 관점을 이해하고 존중하면서 어떻게 하면 주어진 시간 안에 좋은 결과물을 만들 수 있을지 함께 고민했어요.

개발자들과 기술 이야기를 나누는 건 정말 재밌었어요. 특히 한 프론트엔드 개발자분이 있으셨는데, 그분을 보면서 '나도 저렇게 되고 싶다'고 진심으로 생각했어요. 실력도 실력이지만, 문제를 말하는 상황에서도 상대방이 기분 나쁘지 않고 수긍할 수 있는 소프트 스킬이 대단했어요. 그분이 항상 강조하셨던 말이 있어요. "이유를 가지고 개발하라"고요. 이 말 한마디가 제 개발 방식을 완전히 바꿔놨어요. 이제는 뭔가를 할 때마다 '왜 이렇게 하지?'라고 스스로 물어보게 됐죠.

디프만에서 만난 사람들과는 지금까지도 연락하며 지내요. 서로 고민도 나누고, 힘들 때 의지도 하고... 정말 소중한 인연들이 생겼어요.

돌이켜 보면 디프만은 제 개발자 인생의 전환점인 것 같아요. 기술적으로 성장한 것은 물론이고, 협업의 중요성도 배웠고, 평생 갈 인연도 만들었으니까요. 그리고 가장 중요한 건, '아직 배울 게 많다'는 걸 깨달은 거예요. 이제는 더 이상 '말하는 감자'가 아니라 '꾸준히 성장하는 개발자'가 되려고 노력하고 있어요. 아직 갈 길이 멀지만, 그래도 이제 방향의 실마리는 찾은 것 같아요.

디프만 동아리 활동은 제게 너무나 값진 경험이어서 한 기수가 끝나고 그만둘 생각은 전혀 없었어요. 다른 중요한 일들이 있었지만, 이 활동에서 얻을 수 있는 경험을 놓치고 싶지 않았거든요. 그러다 우연한 기회에 운영진 제의를 받아 운영진과 프로젝트 활동을 동시에 하게 되었어요.

처음에는 인사부에서 동아리원 선발 과정을 기획하고, 이후에는 동아리 활동 중 세션을 기획하고 진행하는 업무를 맡았어요. 게다가 프로젝트에서는 어쩌다 보니 팀장까지 맡게 되었죠. 회사도 다니면서 운영진과 프로젝트팀장을 동시에 하는 게 쉽지는 않았어요. 다행히 스트레스를 많이 받는 성격은 아니고 개발을 즐기는 편이라, 시간 관리만 잘하면서 동아리와 회사를 병행할 수 있었어요.

힘들지 않았다고 하면 거짓말이겠지만, 그만큼 보람도 컸어요. 동아리에서 만난 사람들이 너무 좋았고, 함께 서비스를 만들어가는 과정이 정말 즐거웠거든요. 다 같이 문제를 해결해 나가고, 서로 다른 관점을 공유하고 토론하는 과정이 정말 좋은 팀 문화라고 생각했어요. 노력의 결실로 최종 발표 때 "최우수상"도 받았죠. 그때 눈물을 흘렸던 기억이 나네요. 부끄러웠지만, 팀원들이 달래주던 모습도 잊을 수 없어요.

이 활동을 통해 얻은 가장 큰 소득은 바로 우리 팀 사람들과의 인연이에요. 힘들 때 고민을 나누고, 기쁜 일도 함께 축하할 수 있는 사람들을 만났거든요. 이 소중한 인연을 앞으로도 오래오래 이어가고 싶어요. 이미 많은 인연을 만났고 다른 것들이 더 중요하다고 생각되어 디프만 활동은 더 이어가지는 않았지만, 이 경험은 제게 정말 특별했어요. 기술적 성장뿐만 아니라 리더십, 시간 관리 능력, 그리고 무엇보다 소중한 인간관계를 선물해 줬거든요.

현재? 그리고 내일은?

요즘 새로 시작한 사이드 프로젝트에 집중하고있어요. 동아리에서 하는것처럼 주변 상황같은걸 고려하기 보다는 정말 제 흥미로 시작한 프로젝트인데, 그러다보니 기능을 제안하고 하나하나 만들어가는 과정이 너무 재밌더라구요.

운좋게도 사용해주시는 분들이 많아 조금씩 성장해가고 있는데, 종종 피드백을 남겨주시는 분들이 계셔서 피드백을 볼 때 마다 더 많은 사람들이, 그리고 사용해주시는 분들이 재미있게 사용할 수 있는 서비스를 만들어야겠다고 생각하게 되는것 같아요.

만들고 있는 서비스는 Gitanimals 예요!

그리고 잠시 쉬었던 커뮤니티 활동도 다시 시작해 보려고 해요. 솔직히 오랜만이라 처음엔 어색하고 부끄러울 것 같아요. '내가 잘할 수 있을까?' 하는 걱정도 되고요. 하지만 비슷한 고민을 가진 사람들이랑 이야기를 나누다 보면 분명 새로운 아이디어도 얻고, 힘도 얻을 수 있을 거예요. 그런 기대감에 설레는 마음도 있어요.

사실 거창한 목표 같은 건 없어요. 그냥 뭐... 매일매일 조금씩 더 나아지고 싶어요. 어제보다 오늘 더 잘하고, 오늘보다 내일 더 잘하는? 그런 느낌으로요. 새로운 걸 배우고 경험하면서 재미있게 살고 싶어요. 그러다 보면 언젠가 "이 사람 대단하다!" 소리 듣는 날이 오지 않을까요? 😄

💡 Sprite SVG란 무엇일까요?

Sprite SVG는 여러 개의 SVG 이미지를 하나의 파일로 합친 거예요. 이름에서 알 수 있듯이, 여러 개의 작은 이미지(스프라이트)를 하나로 모아놓은 거죠. 이 기술은 보통 웹 성능 최적화와 효율적인 리소스 관리를 위해 사용해요

장점 👍

제가 프로젝트에 이걸 적용하게 된 가장 큰 이유는 네트워크 비용이었어요.

Sprite를 사용하지 않으면 이미지를 개별적으로 불러와야 하지만, Sprite SVG를 이용하면 여러 이미지를 한 번에 불러올 수 있거든요. 덕분에 HTTP 요청이 줄어들고, 대역폭도 절약할 수 있어요.

여러 개의 작은 파일 대신 하나의 큰 파일을 다운로드하는 게 일반적으로 더 효율적이에요.

단점 👎

물론 단점도 있어요.

1. 초기 로딩 시간: 파일 크기가 커질 수 있어 초기 로딩이 느려질 수 있어요.
2. 캐싱 효율: 작은 변경사항에도 전체 파일을 다시 다운로드해야 해요.
3. 복잡성 증가: 스프라이트를 만들고 관리하는 과정이 개별 SVG 파일을 사용하는 것보다 복잡할 수 있어요.
4. 사용하지 않는 아이콘 로드: 페이지에서 사용하지 않는 아이콘도 함께 로드될 수 있어요.

이런 장단점을 고려해봤을 때, 제 상황에는 Sprite SVG가 꽤 적합한 방법이라고 판단했어요.

FCP를 고려하지 않아도 되는 부분이었고, 한 페이지에 모든 SVG를 보여줄 예정이었거든요. 그래서 초기 로딩 시간이나 사용하지 않는 아이콘 로드 같은 단점은 크게 문제가 되지 않았어요.

Sprite SVG 만들기

Sprite SVG를 만드는 과정은 생각보다 간단해요. 기본적으로 개별 SVG 파일들을 읽어와서 하나의 큰 SVG 파일로 합치는 거예요.

전체 과정은 아래와 같아요.

1. SVG 파일 읽기
2. 각 SVG를 <symbol> 태그로 변환
3. 모든 <symbol>을 하나의 <svg> 태그 안에 모으기

1. SVG 파일 읽기 📂

먼저, 외부에 있는 SVG 파일들을 읽어와야 해요. (내부에 있는 SVG를 읽어올 수도 있지만 제 경우엔 외부에서 읽어와야 했어요.)

const getSvgFiles = async (spriteInfo: SpriteInfoValue): Promise<SvgFile[]> => {
  const svgFiles = await Promise.allSettled(
    spriteInfo.list.map(async (item) => {
      try {
        const res = await axios.get(`${spriteInfo.svgBaseUrl}/${item}.svg`);
        return {
          name: item,
          data: res.data,
        };
      } catch (error) {
        console.error(`❌ - Failed to fetch SVG for ${item}`);
      }
    })
  );
  return svgFiles
    .filter((result): result is PromiseFulfilledResult<SvgFile> => result.status === 'fulfilled')
    .map((result) => result.value);
};

이 코드는 주어진 URL에서 SVG 파일들을 가져와요. 파일을 가져오는 동안 병렬 처리를 위해 Promise.allSettled를 사용했어요.

Promise.allSettled를 이용하면 일부 파일에 문제가 있어도 전체 프로세스가 멈추지 않아요. 특히 많은 SVG 파일을 처리할 때 유용하죠. 하나의 파일 로딩이 실패해도 나머지 파일들은 계속 처리할 수 있거든요. 😌

2. Sprite SVG 생성하기 🎨

이제 읽어온 SVG 파일들을 하나의 Sprite SVG로 만들어 볼게요.

const getSpriteSvg = async (svgFiles: SvgFile[]) => {
  const symbols: string[] = [];
  if (svgFiles.length === 0) {
    throw new Error('❌ - No SVG files fetched');
  }
  svgFiles.forEach((file) => {
    const svgElement = parse(file.data).querySelector('svg') as HTMLElement;
    const symbolElement = parse('<symbol/>').querySelector('symbol') as HTMLElement;
    svgElement.childNodes.forEach((child) => symbolElement.appendChild(child));
    symbolElement.setAttribute('id', file.name);
    if (svgElement.attributes.viewBox) {
      symbolElement.setAttribute('viewBox', svgElement.attributes.viewBox);
    }
    symbolElement.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
    symbolElement.setAttribute('fill', 'none');
    symbols.push(symbolElement.toString());
  });
  const svgSprite = `<svg width="0" height="0" class="hidden">${symbols.join('')}</svg>`;
  return svgSprite;
};

이 코드는 각 SVG 파일을 <symbol> 태그로 변환하고, 모든 symbol을 하나의 <svg> 태그 안에 모아요. 이렇게 하면 각 SVG를 id로 구분할 수 있게 돼요.

여기서 중요한 점은 viewBox 속성을 유지한다는 거예요. 이 속성은 SVG의 뷰포트를 정의하는데, 이를 유지함으로써 각 아이콘의 원래 비율과 크기를 보존할 수 있어요. 또한 fill 속성을 'none'으로 설정해 기본 색상을 제거하고, 나중에 CSS로 쉽게 색상을 변경할 수 있게 했어요.

생성한 Sprite SVG 사용하기

Sprite SVG를 만들었다면, 이제 사용할 차례예요! 아래와 같이 간단하게 사용할 수 있어요.

<svg width={size} height={size} fill="currentColor">
  <use href={`/assets/sprite/countryCode.svg#${id}`} />
</svg>

이 코드는 <use> 태그를 사용해 sprite SVG 파일 내의 특정 symbol을 참조해요. href 속성에서 # 뒤에 오는 값이 바로 우리가 앞서 설정한 id예요.

좀 더 편리하게 사용하기 위해 컴포넌트로 만들어봤어요.

type CountryCodeSpriteSvgProps = {
  id: string;
  size?: number;
};

function CountryCodeSpriteSvg({ id, size = 28 }: CountryCodeSpriteSvgProps) {
  return (
    <svg width={size} height={size} fill="currentColor">
      <use href={`/assets/sprite/countryCode.svg#${id}`} />
    </svg>
  );
}

이렇게 컴포넌트로 만들면 여러 가지 장점이 있어요. (지극히 개인적인 생각입니다 🤔)

• 코드 재사용성이 높아져요.
• 프로젝트 내에서 일관된 방식으로 sprite SVG를 사용할 수 있어요.
• id만 넣어주면 되니까 사용하기 쉽고, 오타 같은 실수를 줄일 수 있어요.
• 나중에 sprite SVG 사용 현황을 파악하기 쉬워져요.
• 스타일링이나 크기 조절을 한 곳에서 관리할 수 있어 유지보수가 편해져요.

마치며

Sprite SVG는 처음에는 좀 복잡해 보였지만, 익숙해지니까 정말 유용한 기술이라고 생각해요. 특히 아이콘을 많이 사용하는 프로젝트에서 성능 향상에 큰 도움이 될 것 같아요.

이 기술을 사용하면서 느낀 점은, 개발자로서 항상 성능과 사용성 사이의 균형을 고민해야 한다는 거예요. Sprite SVG는 그 균형을 잘 맞춘 기술 중 하나라고 생각해요.

다음에는 script를 이용해 자동으로 sprite SVG를 생성하는 방법에 대해 알아볼게요. 저는 script를 이용해서 복잡해 보일 수 있는 sprite SVG 생성 과정을 간단하고 효율적으로 만들 수 있었어요. 🚀

다음 글: [[sprite 2, 스크립트로 Sprite SVG 자동 생성하기]]

"이 버그 좀 고쳐주세요!", "이런 기능이 있으면 좋겠어요!"

GitAnimals 서비스를 운영하다 보니 이런 피드백들이 종종 들어오곤 했어요. 특히 GitHub를 기반으로 한 서비스이었기 때문에, 사용자들이 직접 GitHub Issue를 통해 의견을 제시하는 경우도 있었죠.

그러다 문득 이런 생각이 들었어요. "잠깐, 이 모든 피드백을 한 곳에서 관리할 수 없을까?" 🤔

사용자들의 소중한 의견을 놓치지 않고, 효율적으로 관리하고 싶었거든요. 그래서 사용자 피드백을 자동으로 GitHub Issue로 등록하는 기능을 만들기로 했습니다.

채널톡 같은 방법도 있었지만, 우리 서비스만의 특별한 무언가를 만들고 싶었어요.

GitHub API와 친해지기

이 기능을 구현하려면 먼저 GitHub API를 사용해야 했습니다. Issue를 생성하려면 Personal Access Token이 필요했는데, 이걸 만드는 과정이 꽤 조금 복잡했습니다.

Personal Access Token 생성하기

1. GitHub 사이트에 로그인합니다.
2. 오른쪽 상단에 있는 자신의 프로필 아이콘을 클릭하고 Settings를 선택합니다.
3. 왼쪽 메뉴에서 Developer settings를 클릭합니다.
4. Personal access tokens를 선택하고 Generate new token을 클릭합니다.
5. Token description에 'Auto create issue token'과 같이 용도를 적어줍니다.
6. Select scopes에서 repo만 선택합니다. (Issue 관리는 repo 권한에 포함되어 있습니다)
7. Generate 버튼을 클릭하면 토큰이 생성됩니다.

주의할 점은, 토큰은 생성 직후에만 볼 수 있기 때문에, 꼭 안전한 곳에 저장해두어야 합니다.

이렇게 만든 토큰으로 GitHub API를 사용할 수 있게 되었습니다. 이제 본격적으로 코드를 작성해볼 차례입니다.

코드로 구현하기

자, 이제 본격적으로 코드를 작성할 차례예요. 저는 API 호출을 위한 함수를 만들었어요.

const ISSUE_TOKEN = process.env.NEXT_PUBLIC_ISSUE_TOKEN;
const POST_ISSUE_URL = '/repos/{owner}/{repo}/issues';

interface PostIssueRequest {
  title: string;
  body: string;
  assignees?: string[];
  labels?: string[];
}

async function postIssue(request: PostIssueRequest) {
  const response = await fetch(POST_ISSUE_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${ISSUE_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(request),
  });

  if (!response.ok) {
    throw new Error('Failed to post issue');
  }

  return response.json();
}

이 함수는 Issue의 제목, 내용, 담당자, 라벨을 받아서 GitHub에 새 Issue를 생성합니다.

1단계에서 만든 personal access token을 API를 호출할 때 header에 추가하여 넘겨줍니다. 그리고, 등록할 issue 관련 데이터는 body에 담아 POST API call을 합니다.

GitHub API에서는 /repos/{owner}/{repo}/issues라는 경로로 POST 요청을 보내 issue를 생성할 수 있습니다.

저의 경우에는 repository url이 https://github.com/git-goods/gitanimals였기 때문에 https://api.github.com/repos/git-goods/gitanimals/issues 경로로 요청을 보냈습니다.

또한 보안을 위해 토큰은 환경변수로 관리했으며, 이 함수를 더 쉽게 사용하기 위해 React Query의 useMutation을 활용했습니다.

export const usePostIssue = (options?: UseMutationOptions<unknown, unknown, PostIssueRequest>) =>
  useMutation({ mutationFn: postIssue, ...options });

이렇게 하면 컴포넌트에서 아주 간단하게 Issue를 생성할 수 있어요.

const { mutate } = usePostIssue();

const onSubmit = () => {
  const username = userData?.username;

  mutate(
    { ...content, assignees: [username] },
    {
      onSuccess() {
        setIsOpen(false);
        initContent();
        alert('Thank you for your feedback!');
      },
    },
  );
};

사용자가 피드백 제출 버튼을 누르면 onSubmit 함수가 실행되고, GitHub에 새 Issue가 생성되는 거예요!

마무리하며

이 기능을 구현하면서 정말 많은 것을 배웠어요. GitHub API 활용부터 React Query로 비동기 처리하는 방법까지, 새로운 기술을 적용해볼 수 있어 즐거웠죠.

특히 가장 만족스러운 점은 우리 서비스의 특성을 살린 피드백 시스템을 만들었다는 거예요. GitHub 기반 서비스니까 피드백도 GitHub Issue로 받는 거죠. 이런 작은 디테일이 사용자들에게 우리 서비스의 정체성을 더 잘 보여줄 수 있을 것 같아요.

실제로 지금도 사용자 피드백이 꾸준히 들어오고 있어요. 궁금하다면 GitAnimals Github Issue에서 직접 확인해볼 수 있어요. 우리 사용자들의 생생한 목소리를 들을 수 있답니다.

혹시 이 기능을 어떻게 구현했는지 자세히 알고 싶다면, PR Link에서 전체 구현 과정을 확인할 수 있어요.

이렇게 서비스에 녹아든 작은 기능 하나가 사용자 경험을 크게 바꿀 수 있다는 걸 새삼 느꼈어요. 서비스의 특성을 살린 독특한 기능 하나가 얼마나 큰 변화를 가져올 수 있는지, 이번 경험을 통해 확실히 알 수 있었죠.

그리고 추가로, 피드백을 누가 제출했는지 트래킹하기 위해 Google Sheets를 이용한 로그 수집 시스템도 만들어봤어요. 이 이야기는 다음 기회에 자세히 들려드릴게요. 기대해 주세요! 🍀

먼저, 다음과 같은 코드를 보시죠

useEffect(() => {;
    console.log('useEffect 실행');
}, []);

이 코드를 실행하면 useEffect가 한 번만 실행될 것으로 예상하게 됩니다. 하지만 실제로 콘솔을 확인해보면, useEffect 실행이 두 번 출력되는 것을 볼 수 있습니다. 왜 이런 일이 발생하는 걸까요? 🤷‍♂️

원인: React.StrictMode 🔍

이 현상은 React 18에서 도입된 Strict Mode 때문에 발생합니다. React 공식 문서에서는 Strict Mode에 대해 다음과 같이 설명하고 있습니다.

"<StrictMode>를 사용하면 개발 초기에 구성 요소의 일반적인 버그를 찾을 수 있습니다."

"Strict Mode 검사는 개발 중에만 실행되지만, 코드에 이미 존재하지만 프로덕션에서 안정적으로 재현하기 어려울 수 있는 버그를 찾는 데 도움이 됩니다. Strict Mode를 사용하면 사용자가 버그를 신고하기 전에 버그를 수정할 수 있습니다."

참고 : https://react.dev/reference/react/StrictMode

그래서 useEffect가 두번 실행되는 것을 어떻게 막을 수 있을까요? 💡

1. React.StrictMode 제거

Strict Mode를 제거하면 문제를 해결할 수 있지만, 잠재적 버그를 놓칠 수 있어 권장되지 않습니다.

2. 클린업 함수를 이용한 상태 초기화

간단한 콘솔 출력이나 상태 설정의 경우 두 번 실행되어도 큰 문제가 없습니다. 하지만 API 호출이나 반드시 한 번만 실행되어야 하는 동작이 두 번 실행되면 문제가 될 수 있습니다.

이를 해결하기 위해, useEffect의 클린업 함수에서 이전에 설정된 값을 초기화해야 합니다. 특히 API 요청의 경우, 중복 요청으로 인한 문제를 방지하기 위해 이전 요청을 적절히 처리해야 합니다.

3. AbortController 사용하기

useEffect가 두번 실행되는 것을 막기 위한 방법 중 하나는 AbortController를 사용하는 것입니다.

function Test() {
  useEffect(() => {
    const controller = new AbortController();

    console.log('doSomethingAsync: ');
    doSomethingAsync(
      { value: 'test' },
      { signal: controller.signal }
    ).then((result) => {
      console.log('result: ', result);
    });

    return () => {
      controller.abort();
    };
  }, []);
  return <div></div>;
}

function doSomethingAsync(payload: unknown, { signal }: { signal?: AbortSignal } = {}): Promise<unknown> {
  if (signal?.aborted) {
    return Promise.reject(new AbortException());
  }

  return new Promise((resolve, reject) => {
    const abortHandler = () => {
      reject(new AbortException());
    };

    setTimeout(() => {
      signal?.removeEventListener('abort', abortHandler);
      resolve(payload);
    }, 0);

    signal?.addEventListener('abort', abortHandler);
  });
}

class AbortException extends DOMException {
  constructor() {
    super('Aborted', 'AbortError');
  }
}

이 방법을 사용하면 useEffect는 두 번 실행되지만, 중요한 비동기 작업은 한 번만 완료합니다.

결과 콘솔

![[Pasted image 20240828124528.png]]

AbortController를 이용한 해결 방법의 동작 원리

1. useEffect 내에서 AbortController를 생성합니다.
2. doSomethingAsync 함수를 호출할 때 controller의 signal을 전달합니다.
3. useEffect의 클린업 함수에서 controller.abort()를 호출합니다.

이 방법이 효과적인 이유는 다음과 같습니다.

• React.StrictMode에서 useEffect가 두 번 실행되더라도, 첫 번째 실행의 클린업 함수가 두 번째 실행 전에 호출됩니다.
• 첫 번째 실행에서 시작된 비동기 작업은 setTimeout으로 인해 지연됩니다.
• 두 번째 실행 전에 첫 번째 작업이 abort됩니다.
• 두 번째 실행에서 시작된 작업만 완료되므로, 결과적으로 한 번만 실행된 것처럼 보입니다.

이렇게 하면 useEffect 자체는 두 번 실행되지만, doSomethingAsync가 취소되지 않고 실행되는 것은 단 한 번입니다.

다만, useEffect를 두번 실행하지 않기위해 사용하기에는 과도한 개발인것 같아요. 🤔

4. useRef 이용하기 ✨

function useEffectOnce(callback: () => void) {
  const ref = useRef(false);

  useEffect(() => {
    if (ref.current) return;
    ref.current = true;

    if (typeof callback === 'function') {
      callback();
    }
  }, []);
}

useEffectOnce를 이용한 해결 방법의 동작 원리

1. useRef를 사용해 효과 실행 여부를 추적합니다.
2. useEffect 내에서 ref 값을 확인하여 이미 실행됐다면 바로 반환합니다.
3. 아직 실행되지 않았다면 ref 값을 true로 설정하고 콜백을 실행합니다.
4. 빈 의존성 배열([])을 사용해 컴포넌트 마운트 시에만 실행되도록 합니다.

이 방법이 효과적인 이유는 다음과 같습니다.

• Strict Mode에서 useEffect가 두 번 호출되더라도, ref 값 덕분에 콜백은 한 번만 실행됩니다.
• useRef를 사용해 컴포넌트 생명주기 동안 값을 유지하므로, 리렌더링에도 안전합니다.
• 타입 체크를 통해 콜백이 확실히 함수일 때만 실행하므로 타입 안정성이 보장됩니다.

이렇게 하면 useEffect는 여전히 Strict Mode에서 두 번 실행되지만, 우리가 원하는 로직은 딱 한 번만 실행되는 거죠!

사용예시

function MyComponent() {
  useEffectOnce(() => {
    console.log('이 메시지는 단 한 번만 출력됩니다!');
    // 여기에 초기 데이터 로딩이나 이벤트 리스너 등록 같은 작업을 넣으면 됩니다.
  });

  return <div>My Component</div>;
}

useEffectOnce는 AbortController를 사용한 방법에 비해 더 간단하고 직관적이에요.

다만, 모든 상황에 이 훅을 사용하는 것은 주의해야 해야합니다. 때로는 useEffect의 재실행이 필요한 경우도 있을테니까요.

긴 글을 읽어주셔서 감사합니다. 추가적인 질문이나 의견이 있다면 언제든 공유해 주세요! 💬🚀

참고 : https://medium.com/@tangiblej/cancel-a-promise-inside-react-useeffect-12a101606b72

우리의 타이머, 절대 멈추지 않는다!

저희 팀에서 새로운 요구사항을 받았어요.

"앱 환경을 고려해 화면을 이탈하거나, 백그라운드에서도 타이머의 시간이 없어지면 안 됩니다."

처음엔 '아, 간단하겠네~' 했는데, 생각보다 고민할 게 많더라고요.

백엔드 vs 프론트엔드, 누가 책임질까?

먼저 백엔드 팀과 이야기를 나눴어요. "시간을 서버에 저장할까요, 아니면 클라이언트에서 처리할까요?" 고민 끝에 프론트엔드에서 처리하기로 했죠. API 콜을 줄이고 싶었거든요. 대신 타이머가 끝날 때만 서버에 시간을 보내기로 했어요.

프론트엔드의 고민: 어떻게 저장할까?

자, 이제 프론트엔드에서 어떻게 시간을 저장할지 고민이 시작됐어요. 팀원들과 브레인스토밍을 했는데, 세 가지 아이디어가 나왔어요:

1. 1초마다 저장하자! (정확하긴 한데, 좀 과하지 않을까?)
2. 10초마다 저장하자! (1초보단 나은 것 같은데...)
3. 페이지 나갈 때만 저장하자! (오, 이거 좋은데?)

처음엔 1초마다 저장하려고 했어요. 근데 생각해보니 UI가 버벅거릴 것 같더라고요. 10초도 괜찮아 보였지만, 뭔가 아쉬웠어요.

그러다 페이지를 나갈 때 저장하는 방법을 알게되었어요. "이거다!" 싶었죠. 근데 또 걱정이 되더라고요. "앱이 강제로 종료되면 어쩌지?" 하는 생각이 들었거든요.

Page Visibility API, 우리의 구원자!

고민 끝에 Page Visibility API를 알게 됐어요. 이 API를 사용하면 사용자가 페이지를 보고 있는지, 아닌지 알 수 있더라고요. 이걸 이용해서 페이지를 벗어날 때 시간을 저장하기로 했어요.

하지만 혹시 모를 상황에 대비해서, 10초마다 저장하는 방법도 함께 사용하기로 했어요. 안전빵으로요! 😉

코드로 구현하기

두 가지 방법을 모두 사용하기 위해 Custom Hook을 만들었어요. 코드를 자세히 살펴볼까요?

useRecordMidTime(time, missionId); // 10초마다 저장
useUnloadAction(time, missionId); // 페이지 나갈 때 저장

useRecordMidTime - 주기적으로 저장하는 Hook

이 Hook은 10초마다 현재 시간을 localStorage에 저장해요.

export function useRecordMidTime(time: number) {
  const onSaveTime = () => {
    localStorage.setItem(STORAGE_KEY.STOPWATCH.TIME_2, String(time));
  };

  useInterval(() => {
    onSaveTime();
  }, 10000);
}

여기서 useInterval은 React에서 setInterval을 안전하게 사용할 수 있게 해주는 Custom Hook이에요. 10초(10000ms)마다 onSaveTime 함수를 실행해서 현재 시간을 저장하죠.

useUnloadAction - 페이지 이탈 시 저장하는 Hook

이 Hook은 페이지 visibility가 변경될 때 현재 시간을 저장해요.

export function useUnloadAction(time: number) {
  const onSaveTime = useCallback(() => {
    localStorage.setItem(STORAGE_KEY.STOPWATCH.TIME, String(time));
  }, [time]);

  useVisibilityState(onSaveTime);
}

function useVisibilityState(onAction: VoidFunction) {
  const onVisibilityChange = useCallback(() => {
    if (document.visibilityState === 'hidden') {
      onAction();
    }
  }, [onAction]);

  useEffect(() => {
    document.addEventListener('visibilitychange', onVisibilityChange);

    return () => {
      document.removeEventListener('visibilitychange', onVisibilityChange);
    };
  }, [onVisibilityChange]);
}

useUnloadAction은 useVisibilityState라는 또 다른 Custom Hook을 사용해요. 이 Hook은 Page Visibility API를 이용해서 페이지가 숨겨질 때(hidden 상태가 될 때) onAction 함수를 실행해요.

useCallback을 사용한 이유는 불필요한 리렌더링을 방지하기 위해서예요. time이 변경될 때만 새로운 함수를 만들도록 했죠.

팀원의 리뷰, 새로운 깨달음

코드를 작성하고 PR을 올렸는데, 팀원에게 정말 유익한 리뷰를 받았어요.

이 리뷰를 통해 useVisibilityState Hook의 의존성 배열에 대해 다시 생각해보게 됐어요. onVisibilityChange를 useEffect의 의존성 배열에 추가하고, time prop이 바뀔 때마다 onVisibilityChange 함수가 새로 생성되도록 수정했죠.

function useVisibilityState(onAction: VoidFunction) {
  const onVisibilityChange = useCallback(() => {
    if (document.visibilityState === 'hidden') {
      onAction();
    }
  }, [onAction]);

  useEffect(() => {
    document.addEventListener('visibilitychange', onVisibilityChange);
    return () => {
      document.removeEventListener('visibilitychange', onVisibilityChange);
    };
  }, [onVisibilityChange]); // onVisibilityChange를 의존성 배열에 추가
}

이렇게 수정하면 time이 변경될 때마다 정확하게 최신 시간이 저장되면서도, 불필요한 리렌더링은 방지할 수 있어요.

마무리하며

이번 경험을 통해 정말 많은 것을 배웠어요. Custom Hook 작성 방법, React의 성능 최적화 기법, 그리고 무엇보다 팀 협업의 중요성을 몸소 느꼈죠.

코드를 작성할 때는 단순히 '작동하는' 코드를 만드는 것을 넘어서, 다른 개발자들의 관점에서도 이해하기 쉽고 유지보수가 용이한 코드를 작성해야 한다는 걸 깨달았어요. 팀원의 리뷰 덕분에 제 코드가 한 단계 더 발전할 수 있었죠.

이런 작은 경험들이 모여 우리를 더 나은 개발자로 만들어가는 것 같아요. 앞으로도 이런 도전적인 과제들을 마주하며 성장해 나가고 싶습니다. 여러분도 개발하면서 겪은 재미있는 경험이 있다면 언제든 공유해주세요! 함께 배우고 성장하는 게 개발의 묘미 아니겠어요? 😊🚀