본 글은 기존 AWS CodePipeline 기반의 CI/CD 환경을 GitHub Actions로 전환하여 구성한 과정을 정리한 글입니다.

기존 프로젝트에서는 CI는 GitHub Actions를, CD는 AWS CodePipeline과 CodeBuild를 사용하는 구조로 운영되고 있었습니다. 해당 구성은 초기에는 큰 문제 없이 동작하였으나, 프로젝트 구조가 모노레포 형태로 확장되면서 불필요한 소스 다운로드 시간이 증가하였고, CI 설정이 GitHub Actions와 CodeBuild 두 곳에서 중복 관리되는 구조적 비효율이 확인되었습니다.

이에 따라 CI와 CD를 분리하여 운영하던 기존 구조를 재검토하게 되었으며, 설정 통합과 워크플로우 최적화 측면에서 CI/CD 전반을 GitHub Actions로 통합하는 방향이 보다 적합하다고 판단하였습니다.

본 글에서는

• AWS CodePipeline에서 GitHub Actions로 전환하게 된 배경과 판단 근거
• GitHub Actions의 개념과 워크플로우 구성 방식
• 프로젝트에 적용한 CI/CD 설정 및 Discord 알림 연동

을 중심으로 정리하겠습니다.

전환 배경

기존 프로젝트는 CI는 GitHub Actions로, CD는 AWS CodePipeline으로 분리하여 운영하고 있었습니다. 그러나 프로젝트 구조가 모노레포로 전환되면서 기존 구성 방식의 한계가 확인되었습니다.

1. 모노레포 환경에서의 소스 다운로드 비효율

프로젝트는 web, app, admin 코드를 하나의 저장소에서 관리하는 모노레포 구조로 구성되어 있습니다.

CodePipeline은 트리거 발생 시 저장소 전체를 다운로드하도록 구성되어 있어, 특정 서비스만 배포하는 경우에도 불필요한 코드가 함께 다운로드되었습니다. 특히 React Native 기반의 app 디렉토리 크기가 크다 보니 다운로드 시간이 크게 증가하였습니다.

• 모노레포 도입 이전: 약 5초
• 모노레포 도입 이후: 40초 이상

빌드 이전 단계에서 발생하는 불필요한 대기 시간으로, 배포 효율성을 저하시키는 요인으로 확인되었습니다.

2. CI 설정의 중복 관리

CI는 GitHub Actions를 통해 PR 생성 및 리뷰 과정에서 자동으로 실행되도록 구성되어 있었습니다. 그러나 CodePipeline 배포 과정에서도 배포 전 CI가 필요하여 CodeBuild에서 동일한 작업을 수행하도록 설정되어 있었습니다.

결과적으로 CI 설정이 GitHub Actions와 CodeBuild 두 곳에서 관리되는 구조였으며, 설정 변경 시 양쪽 모두 수정해야 하는 번거로움이 존재하였습니다. CI는 단일 지점에서 관리하는 것이 적합하다고 판단하였습니다.

3. UI 기반 설정과 레퍼런스 부족

CodePipeline의 설정은 대부분 AWS 콘솔 UI를 통해 이루어집니다. UI는 주기적으로 변경되며, 검색을 통해 확인한 자료의 화면과 실제 UI가 일치하지 않는 경우가 많았습니다.

또한 CodePipeline 관련 레퍼런스는 상대적으로 제한적이어서 문제 해결 시 참고 자료를 찾기 어려웠습니다. 반면 GitHub Actions는 YAML 기반 설정과 풍부한 커뮤니티 자료를 통해 설정 의도를 명확히 파악하고 적용하기에 용이하였습니다.

4. 설정 변경을 위한 콘솔 접근 비용

개발 과정에서 GitHub는 항상 열어두고 작업하는 반면, AWS 콘솔은 필요한 경우에만 접근하는 환경이었습니다. 그럼에도 환경 변수나 트리거 변경과 같은 사소한 작업에도 AWS 콘솔 접속이 필요하였습니다.

CI/CD 설정을 코드와 함께 GitHub 저장소에서 관리하는 것이 개발 흐름과 더 자연스럽게 연결된다고 판단하였습니다.

위와 같은 배경으로 CI/CD를 GitHub Actions로 통합하여 구성하는 방향으로 전환을 진행하였습니다.

GitHub Actions 개요

GitHub Actions는 GitHub 저장소에서 발생하는 이벤트를 기준으로 자동화된 작업을 실행할 수 있는 CI/CD 도구입니다. 코드 변경, PR 생성, 리뷰 요청과 같은 이벤트가 발생하면 사전에 정의한 워크플로우가 실행되는 구조로 동작합니다.

워크플로우 구성 방식

GitHub Actions는 저장소 내 .github/workflows 디렉토리에 정의된 YAML 파일을 기준으로 동작합니다. 각 YAML 파일은 하나의 워크플로우를 의미하며, 다음과 같은 정보를 포함합니다.

• on: 어떤 이벤트를 기준으로 실행할 것인지 (push, pull_request, pull_request_review 등)
• runs-on: 어떤 환경에서 작업을 수행할 것인지
• jobs, steps: 어떤 작업을 어떤 순서로 실행할 것인지

GitHub 저장소에서 이벤트가 발생하면, 해당 이벤트 조건에 부합하는 워크플로우를 탐색하여 실행합니다. 이후 워크플로우에 정의된 잡(Job)이 실행되고, 각 잡 내부의 스텝(Step)이 순차적으로 수행됩니다.

이러한 구조를 통해 "언제 실행할 것인지"와 "무엇을 실행할 것인지"를 명확히 분리하여 관리할 수 있으며, CI/CD를 포함한 다양한 자동화 작업을 코드 기반으로 구성할 수 있습니다.

다음 섹션에서는 본 프로젝트에 적용한 CI/CD 워크플로우의 구체적인 트리거 설정과 작업 실행 순서, 그리고 Discord 알림 연동을 통한 개발 환경 개선 사례를 다루겠습니다.

프로젝트에 적용한 CI/CD 구성

본 프로젝트의 CI/CD 구성은 다음과 같은 요구사항을 기준으로 설계되었습니다.

• PR 생성 및 push 시 린트와 타입 체크를 수행하는 CI 자동 실행
• dev, main 브랜치 머지 시 최종 CI 수행 후 배포까지 자동 진행
• CI 로직은 단일 워크플로우로 관리하여 중복 제거

이를 위해 다음과 같이 3개의 워크플로우 파일로 구성하였습니다.

워크플로우 파일 구조

전체 워크플로우는 다음과 같은 파일로 구성되어 있습니다.

frontend-ci-base.yml
공통 CI 로직을 정의한 재사용 가능 워크플로우입니다. workflow_call 이벤트를 통해 다른 워크플로우에서 호출할 수 있도록 구성하였습니다.

frontend-pr-ci.yml
PR 단계에서 실행되는 워크플로우로, frontend-ci-base.yml을 호출하여 코드 품질 검증을 수행합니다.

frontend-deploy.yml
dev, main 브랜치에 대한 빌드 및 배포를 수행하는 워크플로우입니다. CI 수행 후 S3 업로드와 CloudFront 캐시 무효화를 순차적으로 진행합니다.

공통 CI 워크플로우 (frontend-ci-base.yml)

공통 CI 워크플로우는 소스 체크아웃부터 빌드까지의 전체 과정을 포함하며, run-build 입력값에 따라 빌드 수행 여부를 제어할 수 있도록 구성하였습니다.

name: Frontend CI Base

on:
  workflow_call:
    inputs:
      run-build:
        required: false
        type: boolean
        default: false

워크플로우는 다음 단계로 구성됩니다.

1. 소스 체크아웃 및 pnpm 환경 설정
   Corepack을 활성화하고 pnpm 10.12.1 버전을 설정하였습니다.

2. 의존성 캐싱
   pnpm store를 캐싱하여 반복 실행 시 설치 시간을 단축하였습니다.

3. 린트 및 타입 체크
   모든 실행에서 공통적으로 수행됩니다.

4. 조건부 빌드
   run-build 입력값이 true일 경우에만 빌드를 수행합니다.

- name: Build
  if: inputs.run-build == true
  env:
    CHANNEL_TALK_PLUGIN_KEY: ${{ secrets.CHANNEL_TALK_PLUGIN_KEY }}
    SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
    CLARITY_PROJECT_ID: ${{ secrets.CLARITY_PROJECT_ID }}
    API_BASE_URL: ${{ vars.API_BASE_URL }}
    MONITORING_STATUS_URL: ${{ vars.MONITORING_STATUS_URL }}
    SERVER_TYPE: ${{ vars.SERVER_TYPE }}
  run: pnpm run web:build

빌드가 수행될 경우, 결과물은 아티팩트로 업로드되어 후속 job에서 사용할 수 있도록 구성하였습니다.

실제 워크플로우 실행 시에는 위와 같이 Setup, Checkout, pnpm 환경 구성, 캐싱, 의존성 설치, Lint, Type Check, Build, 아티팩트 업로드 순서로 단계가 진행됩니다.

PR 단계 CI (frontend-pr-ci.yml)

PR이 생성되거나 업데이트될 때 자동으로 실행되며, pull_request 이벤트를 트리거로 사용합니다.

name: Frontend PR CI

on:
  pull_request:

jobs:
  pre-build:
    uses: ./.github/workflows/frontend-ci-base.yml
    with:
      run-build: false

PR 단계에서는 빌드를 수행하지 않고 린트와 타입 체크만 실행하도록 run-build: false를 전달하였습니다. 이를 통해 코드 변경에 대한 빠른 피드백을 제공하면서 불필요한 빌드 비용을 줄일 수 있습니다.

배포 워크플로우 (frontend-deploy.yml)

dev, main 브랜치에 코드가 push될 때 실행되며, 빌드부터 배포까지 전체 과정을 자동화하였습니다.

on:
  push:
    branches:
      - main
      - dev

concurrency:
  group: deploy-${{ github.ref_name }}
  cancel-in-progress: true

concurrency 설정을 통해 동일 브랜치에서 배포가 중복 실행되는 것을 방지하였습니다. 새로운 배포가 시작되면 진행 중인 배포는 취소됩니다.

1. Build Job

배포 워크플로우는 먼저 공통 CI 워크플로우를 호출하여 빌드까지 수행합니다.

jobs:
  build:
    uses: ./.github/workflows/frontend-ci-base.yml
    secrets: inherit
    with:
      run-build: true

secrets: inherit를 통해 환경별 시크릿 값을 전달하며, 빌드 결과물은 아티팩트로 저장됩니다.

2. Deploy Job

빌드가 완료되면 아티팩트를 다운로드하여 S3에 업로드하고, CloudFront 캐시를 무효화합니다.

deploy:
  runs-on: ubuntu-latest
  needs: build
  environment: ${{ github.ref_name == 'main' && 'prod' || 'dev' }}

현재 브랜치를 기준으로 실행 환경(prod 또는 dev)을 자동으로 결정하며, 각 환경에 정의된 시크릿과 변수를 사용합니다.

S3 업로드는 --delete 옵션을 사용하여 삭제된 파일도 반영되도록 구성하였습니다.

- name: Upload to S3
  run: |
    aws s3 sync web/dist s3://${{ secrets.S3_BUCKET }}/build-origin --delete

배포 후에는 CloudFront 캐시를 전체 무효화하여 변경사항이 즉시 반영되도록 하였습니다.

- name: CloudFront Invalidation
  run: |
    aws cloudfront create-invalidation \
      --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
      --paths "/*"

3. Notify Job

배포가 완료되면 다음에 설명드릴 Discord로 알림을 전송합니다. 환경별로 다른 메시지와 색상을 사용하여 운영 배포와 개발 배포를 구분할 수 있도록 구성하였습니다.

notify:
  runs-on: ubuntu-latest
  needs: deploy

  steps:
    - name: Send Post-Deploy Notification
      uses: ./.github/actions/discord-notify
      with:
        webhook: ${{ secrets.DISCORD_WEBHOOK_DEPLOY }}
        content: ${{ github.ref_name == 'main' && '🚀 **운영 서버에 새로운 버전이 배포되었습니다!**' || '🧪 **개발 서버에 새로운 버전이 배포되었습니다!**' }}

전체 배포 워크플로우는 위와 같이 build (53초) → deploy (18초) → notify (5초) 순서로 실행되며, 각 job이 순차적으로 완료되는 것을 확인할 수 있습니다.

환경별 변수 관리

환경별 설정은 GitHub Actions의 Environment 기능을 활용하여 관리하였습니다. prod와 dev 환경을 분리하여 각각에 필요한 변수와 시크릿을 정의하였으며, 워크플로우에서는 브랜치명을 기준으로 자동으로 환경을 선택합니다.

민감한 값(API Key, AWS 자격 증명 등)은 Secrets로, 비민감 설정(API URL, 서버 타입 등)은 Variables로 구분하여 관리하였습니다. 이를 통해 코드 수정 없이 환경별 설정을 유연하게 변경할 수 있습니다.

이와 같은 구조를 통해 CI 로직은 단일 워크플로우에서 관리하면서도, PR 검증과 배포 과정을 명확히 분리하여 운영할 수 있도록 구성하였습니다.

Discord 알림을 통한 개발 환경 개선

GitHub Actions를 활용한 CI/CD 구성 외에도, PR 리뷰 과정에서의 커뮤니케이션 효율을 개선하기 위해 Discord 알림 기능을 추가로 구성하였습니다.

기존에는 PR 생성, 리뷰 요청, 승인 등의 상태 변화를 확인하기 위해 GitHub 페이지를 주기적으로 확인해야 했습니다. 이러한 방식은 알림 확인이 지연되거나 누락될 가능성이 존재하였으며, 개발 흐름이 단절되는 요인으로 작용하였습니다.

이에 따라 PR 리뷰 프로세스의 주요 시점마다 Discord로 자동 알림을 전송하도록 구성하여, GitHub를 별도로 확인하지 않아도 리뷰 상태를 즉시 파악할 수 있도록 개선하였습니다. 구성한 알림은 다음과 같습니다.

1. PR 생성 시 리뷰어에게 알림
2. Request Changes 시 PR 작성자에게 알림
3. Re-review 요청 시 리뷰어에게 알림
4. 최소 2명 이상 승인 완료 시 알림

Custom Action을 통한 알림 기능 공통화

Discord 알림은 PR 생성, 리뷰 요청, 승인 완료, 배포 완료 등 여러 시점에서 사용됩니다. 각 워크플로우에서 동일한 알림 로직을 반복 작성하는 대신, Custom Action으로 공통화하여 재사용할 수 있도록 구성하였습니다.

name: 'Discord Notify'
description: 'Send Discord webhook'

# 사용처에서 받고자 하는 input
inputs:
  webhook:
    description: 'Discord Webhook URL'
    required: true
  content:
    description: 'Notification content'
    required: true
  mentions:
    description: 'Notification mentions'
    required: false
  title:
    description: 'Embed title'
    required: true
  url:
    description: 'Embed URL'
    required: true
  color:
    description: 'Embed color'
    required: false
    default: '15158332'
  fields:
    description: 'Embed fields'
    required: false
    default: '[]'

runs:
  using: 'composite'
  steps:
    - shell: bash
      run: |
        RAW_FIELDS='${{ inputs.fields }}'

        FINAL_FIELDS=$(echo "$RAW_FIELDS" | jq '
          map(. + {inline: true})
        ')

        curl -X POST \
          -H "Content-Type: application/json" \
          # 알림 내용
          -d "{
            \"username\": \"FE Bot\",
            \"content\": \"${{ inputs.content }}\n${{ inputs.mentions }}\",
            \"embeds\": [
              {
                \"title\": \"${{ inputs.title }}\",
                \"url\": \"${{ inputs.url }}\",
                \"color\": ${{ inputs.color }},
                \"fields\": $FINAL_FIELDS,
                \"footer\": { \"text\": \"자동 알림 메시지입니다\" }
              }
            ]
          }" \
          "${{ inputs.webhook }}"

이 Action은 Discord Webhook을 통해 메시지를 전송하며, 알림 내용, 멘션 대상, Embed 형식 등을 입력값으로 받아 유연하게 구성할 수 있도록 설계하였습니다. fields 입력값은 JSON 배열로 전달받아 jq를 통해 inline: true 속성을 추가한 뒤 전송합니다.

다른 워크플로우에서 이 Action을 사용할 때는 폴더 경로를 참조하는 방식으로 호출합니다.

- name: Send Notification
  uses: ./.github/actions/discord-notify
  with:
    webhook: ${{ secrets.DISCORD_WEBHOOK_PR }}
    content: "알림 내용"

중요: Custom Action을 사용할 때는 파일 경로가 아닌 폴더 경로를 지정해야 합니다. .github/actions/discord-notify/action.yml 경로에 정의하고, GitHub Actions는 지정된 폴더 내의 action.yml 파일을 자동으로 탐색하여 실행합니다.

Discord Webhook URL 생성 방법과 Discord ID 확인 방법은 다음 문서를 참고할 수 있습니다.

• Discord WebHook 사용해서 알림 보내기
• Discord Webhook Action (GitHub Marketplace)

PR 생성 알림 구성

PR 생성 시 알림을 예시로 전체 구성 방식을 설명하겠습니다. PR이 생성되면 프론트엔드 팀원들에게 리뷰 요청 알림이 전송됩니다.

name: PR Open Notifications

on:
  pull_request:
    types: [opened, reopened, ready_for_review]

jobs:
  notify-reviewers:
    runs-on: ubuntu-latest
    if: github.event.pull_request.draft == false

ready_for_review 이벤트를 포함하여 Draft PR이 Ready 상태로 전환될 때도 알림이 발송되도록 구성하였으며, Draft 상태에서는 알림이 전송되지 않도록 조건을 설정하였습니다.

워크플로우는 다음 작업을 순차적으로 수행합니다.

1) Discord 멘션 대상 구성

.github/notify_ids.json 파일에 GitHub 계정과 Discord ID를 매핑하여 관리하고 있으며, 이를 기반으로 멘션 대상을 동적으로 구성합니다.

- name: Load Reviewers from JSON
  id: get-reviewers
  uses: actions/github-script@v6
  with:
    script: |
      const fs = require('fs');
      const mapping = JSON.parse(fs.readFileSync('.github/notify_ids.json', 'utf8'));
      const members = Object.keys(mapping);

      const author = context.payload.pull_request.user.login;
      # 멘션 대상에 author 제외
      const filtered = members.filter(member => member !== author);

      const mentions = filtered
      # 디스코드 멘션 텍스트로 변경
        .map(login => `<@${mapping[login]}>`)
        .join(' ');

      # 다음 단계에서 사용할 수 있도록 output 설정
      core.setOutput("discord_mentions", mentions);

PR 작성자를 제외한 팀원들을 대상으로 Discord 멘션을 생성하며, 이 값은 다음 단계에서 알림 전송 시 사용됩니다.

2) Discord 알림 전송

- name: Send PR Open Notification
  uses: ./.github/actions/discord-notify
  with:
    webhook: ${{ secrets.DISCORD_WEBHOOK_PR }}
    content: "🚀 새 PR이 생성되었습니다! 리뷰 부탁드립니다 🙏"
    # get-reviewers 단계에서 보내준 멘션 텍스트 사용
    mentions: ${{ steps.get-reviewers.outputs.discord_mentions }}
    title: ${{ github.event.pull_request.title }}
    url: ${{ github.event.pull_request.html_url }}
    color: 16753920
    fields: |
      [
        { "name": "작성자", "value": "${{ github.event.pull_request.user.login }}" }
      ]

앞서 정의한 Custom Action을 사용하여 리뷰어들에게 멘션과 함께 알림을 전송합니다.

실제 Discord 채널에서는 위와 같이 PR 제목, 작성자 정보와 함께 멘션된 팀원들에게 알림이 전송됩니다.

다른 알림 트리거 구성

Request Changes, Re-review 요청, 승인 완료 알림은 PR 생성 알림과 유사한 구조로 구성되며, 트리거 이벤트와 알림 메시지만 변경하여 적용하였습니다.

각 알림의 트리거 이벤트는 다음과 같습니다.

• Request Changes: pull_request_review 이벤트의 submitted 타입, changes_requested 상태
• Re-review 요청: pull_request 이벤트의 review_requested 타입
• 승인 완료: pull_request_review 이벤트의 submitted 타입, 승인 수 2개 이상 조건

트리거 이벤트 설정에 대한 자세한 내용은 GitHub Docs - 워크플로를 트리거하는 이벤트에서 확인할 수 있습니다.

알림 구성의 효과 및 확장 가능성

이러한 알림 설정을 통해 다음과 같은 개선 효과를 확인할 수 있었습니다.

• 리뷰 응답 속도 개선: GitHub 페이지를 주기적으로 확인하지 않아도 Discord 알림을 통해 즉시 리뷰 요청을 인지할 수 있습니다.
• 컨텍스트 스위칭 감소: 개발 중 Discord로 알림을 받아 필요한 시점에만 GitHub로 이동하여 리뷰를 수행할 수 있습니다.
• 리뷰 상태 추적 용이: PR 생성부터 승인까지의 전체 흐름을 Discord 채널에서 확인할 수 있어 리뷰 진행 상황을 파악하기 쉬워졌습니다.

Discord 알림 설정은 CI/CD 자동화와 함께 개발 프로세스 전반의 효율성을 개선하는 데 기여하였습니다.

마무리하며

본 글에서는 AWS CodePipeline에서 GitHub Actions로 CI/CD 환경을 전환한 과정과 Discord 알림을 통한 개발 환경 개선 사례를 정리하였습니다.

전환 과정에서 가장 중점을 둔 부분은 설정의 중복 제거와 재사용성 확보였습니다. workflow_call을 활용한 공통 CI 워크플로우 설계, Custom Action을 통한 알림 기능 공통화를 통해 동일한 로직이 여러 곳에서 관리되는 구조를 제거할 수 있었습니다.

이 과정에서 GitHub Actions의 워크플로우 파일 또한 코드라는 점을 다시 확인할 수 있었습니다. 일반적인 애플리케이션 코드와 마찬가지로 가독성과 재사용성을 고려하여 설계해야 하며, 중복을 제거하고 변경에 유연하게 대응할 수 있는 구조로 구성해야 합니다. CI/CD 설정을 코드로 관리함으로써 변경 이력 추적과 협업이 용이해졌으며, GitHub 중심의 개발 흐름과 자연스럽게 통합할 수 있었습니다.

본 글이 CI/CD 구성 시 다음 사항을 고려하는 데 참고가 되기를 바랍니다.

• 워크플로우 설정도 코드로 접근하여 가독성과 재사용성을 고려할 것
• 공통 로직은 재사용 가능한 형태로 설계할 것
• 설정은 코드로 관리하여 변경 이력과 협업을 용이하게 할 것
• 개발 도구를 통합하여 컨텍스트 스위칭을 최소화할 것

본 글은 GA4 사용자 행동 데이터 설계 (1)의 후속 글입니다.

1편에서는 사용자 행동 데이터를 어떤 구조로 수집하고, 어떤 기준으로 분석 및 활용할 것인지에 대해 정리하였습니다.

이번 글에서는 해당 설계를 바탕으로, React 환경에서 GA4를 실제로 어떻게 설정하였는지를 정리합니다.

GA4 설정 방식을 직접 선택한 이유

React 환경에서 GA4를 연동할 때, react-ga4와 같은 라이브러리를 사용하는 방식도 고려할 수 있습니다.

다만 본 프로젝트에서는 GA4를 직접 설정하는 방식을 선택하였습니다.

• 사용을 고려하였던 라이브러리의 경우 마지막 업데이트 시점이 오래되어 있었고,
• GA 정책 변경이나 브라우저 환경 변화에 대한 대응이 제한적일 수 있다고 판단하였습니다.
• 또한 본 서비스에서 필요로 하는 기능이 초기화, 이벤트 수집, 사용자 식별 정도로 비교적 명확하였기 때문에 외부 라이브러리에 의존할 필요가 크지 않았습니다.

설정 난이도도 높지 않았고, 직접 구성하면 동작 흐름을 더 명확히 파악할 수 있다고 판단했습니다.

GA 기본 설정

GA를 사용하기 위해서는 우선 GA 스크립트를 로드하고, 이벤트를 전송할 수 있는 기본 환경을 구성해야 합니다.

이 섹션에서는 GA가 정상적으로 동작하기 위해 반드시 필요한 최소한의 설정을 중심으로, 초기화 과정과 이벤트 수집 방식을 정리합니다.

initGA 함수

GA4 초기화는 gtag.js 스크립트를 로드하고, window.gtag와 dataLayer를 설정하는 과정으로 시작합니다.

declare global {
  interface Window {
    dataLayer: unknown[];
    gtag?: (...args: unknown[]) => void;
  }
}

export const initGA = (
  googleAnalyticsId: string,
  gtagUrl: string = 'https://www.googletagmanager.com/gtag/js',
) => {
  if (!googleAnalyticsId) {
    console.warn('[GA] Measurement ID missing');
    return;
  }

  // gtag.js 삽입
  const script = document.createElement('script');
  script.async = true;
  script.src = `${gtagUrl}?id=${googleAnalyticsId}`;
  document.head.appendChild(script);

  // gtag 초기화
  window.dataLayer = window.dataLayer || [];
  window.gtag = function gtag() {
    window.dataLayer.push(arguments);
  };

  window.gtag('js', new Date());

  // SPA 환경에서는 page_view를 직접 제어
  window.gtag('config', googleAnalyticsId, {
    send_page_view: false,
  });
};

• React SPA 환경에서는 라우팅 변경 시점을 직접 제어하기 위해 자동 page_view 전송을 비활성화하였습니다.

GAInitializer 컴포넌트

초기화 로직은 앱 실행 시 한 번만 수행되도록 별도의 컴포넌트로 분리하였습니다.

const GAInitializer = () => {
  useEffect(() => {
    if (!isProduction) return;

    initGA(GOOGLE_ANALYTICS_ID);
  }, []);

  return null;
};

• 개발 환경에서는 불필요한 데이터 수집을 방지하기 위해 production 환경에서만 초기화가 수행되도록 구성하였습니다.

이벤트 수집

사용자 행동을 GA 이벤트로 기록하기 위해 공통으로 사용할 trackEvent 함수를 정의하였습니다.

GA4에는 Universal Analytics의 category / action / label 개념이 존재하지 않지만, 이벤트를 의미 단위로 묶어 분석하기 위해 커스텀 파라미터 형태로 유사한 구조를 유지하였습니다.

interface TrackEventParams {
  category: string;
  action: string;
  label?: string;
  value?: number;
}

export const trackEvent = ({
  category,
  action,
  label,
  value,
}: TrackEventParams) => {
  if (typeof window.gtag !== 'function') return;

  window.gtag('event', action, {
    event_category: category,
    event_label: label,
    value,
  });
};

사용 예시는 다음과 같습니다.

<button
  onClick={() => {
    handleClick();
    trackEvent({
      category: 'Navigation',
      action: '로그인 버튼 클릭',
      label: 'Header Login Button',
    });
  }}
>
  로그인
</button>

이와 같은 방식으로 이벤트를 정의하여, 개별 이벤트 자체보다 사용자 행동 흐름 단위로 분석할 수 있도록 구성하였습니다.

GA 데이터 해석을 위한 추가 설정

앞선 기본 설정만으로도 GA 이벤트 수집은 가능하지만, 해당 상태로는 데이터를 해석하는 데 한계가 존재하였습니다.

이 섹션에서는 수집된 데이터를 페이지 단위, 사용자 단위, 접속 환경 단위로 해석하기 위해 추가로 설정한 내용을 정리합니다.

페이지별 타이틀 설정

GA4 연동 이후 확인된 문제 중 하나는 모든 페이지의 title이 동일하게 수집되는 현상이었습니다.

React와 같은 SPA 환경에서는 라우팅이 변경되더라도 document.title이 자동으로 변경되지 않기 때문에, GA 리포트 상에서도 모든 페이지가 동일한 이름으로 집계되고 있었습니다.

이 상태에서는 페이지 단위의 사용자 행동을 해석하기 어렵다고 판단하였습니다.

useEffect를 이용한 페이지 타이틀 설정

가장 먼저 적용한 방식은 라우팅 변경을 감지하여 document.title을 직접 변경하는 방법이었습니다.

const TITLE_MAP: Record<string, string> = {
  '/': '봄봄 | 오늘의 뉴스레터',
  '/storage': '봄봄 | 뉴스레터 보관함',
  '/recommend': '봄봄 | 뉴스레터 추천',
  '/login': '봄봄 | 로그인',
  '/signup': '봄봄 | 회원가입',
};

const PageTitle = () => {
  const location = useLocation();

  useEffect(() => {
    let title = '봄봄';

    // 동적 라우트는 prefix 매칭으로 처리
    if (location.pathname.startsWith('/articles/')) {
      title = '봄봄 | 아티클 상세';
    } else {
      title = TITLE_MAP[location.pathname] ?? '봄봄';
    }

    document.title = title;
  }, [location.pathname]);

  return null;
};

이 방식은 구현이 단순하고, GA에서 페이지별 타이틀이 정상적으로 구분되는 것을 빠르게 확인할 수 있다는 장점이 있었습니다.

다만, 페이지 타이틀 관리 로직이 라우팅 로직과 분리된 상태로 존재하게 되면서, 페이지 메타 정보가 여러 곳에 흩어질 수 있다는 점은 아쉬운 부분이었습니다.

TanStack Router의 Document Head Management 활용

프로젝트에서는 TanStack Router를 사용하고 있으며, 해당 라우터는 라우트 정의 단계에서 문서 헤더를 관리할 수 있는 기능을 제공합니다.

현재 프로젝트에서는 페이지별 타이틀과 메타 정보를 라우트 단위로 정의하는 방식으로 전환하였습니다.

export const Route = createFileRoute('/_bombom/storage')({
  head: () => ({
    meta: [
      {
        title: '봄봄 | 뉴스레터 보관함',
      },
    ],
  }),
  component: () => (
    <RequireLogin>
      <Storage />
    </RequireLogin>
  ),
});

이 방식의 경우

• 페이지 타이틀과 메타 정보가 라우트 정의와 함께 관리되며
• document.title을 직접 제어할 필요가 없고
• GA를 포함한 모든 문서 기반 도구에서 동일한 메타 정보를 활용할 수 있습니다.

결과적으로 페이지 단위의 타이틀 관리가 라우팅 구조와 자연스럽게 결합되었고, GA 리포트에서도 페이지별 데이터 해석이 더욱 명확해졌습니다.

프로젝트의 라우터 구성과 구조에 따라 두 방식 중 적절한 방법을 선택하여 적용할 수 있습니다.

페이지별 타이틀 설정을 적용한 결과는 아래 사진과 같습니다.

사용자 식별 (user_id)

GA4는 사용자를 단일 기준으로 식별하지 않고, User ID → Device ID → 모델링된 데이터의 우선순위를 기반으로 사용자를 식별합니다.

이 중 User ID는 개발자가 직접 전달해야 하는 값이며, 설정되지 않은 경우 GA는 자동으로 생성한 Device ID를 기준으로 사용자 식별을 수행합니다.

웹 환경에서 Device ID는 브라우저 및 쿠키 기반으로 관리되기 때문에, 동일한 로그인 사용자라도 웹과 모바일 등 서로 다른 기기나 접속 환경에서는 각각 다른 사용자로 인식될 수 있습니다.

이러한 한계를 보완하기 위해, 로그인 기반 서비스에서는 User ID를 설정하여 동일 사용자의 여러 기기·브라우저 접속을 하나의 사용자로 통합하여 분석하는 것이 바람직합니다.

본 프로젝트는 Web / iOS / Android 환경 모두에 배포되어 있어, 동일 사용자를 고유한 사용자로 인식하기 위해 User ID를 설정하였습니다.

초기 서비스 진입 시

서비스 진입 시 사용자 정보를 조회한 뒤, 로그인된 사용자라면 user_id를 GA에 설정합니다.

const user = await queryClient.fetchQuery(queries.userProfile());

if (user) {
  window.gtag?.('set', { user_id: user.id });
}

이 방식은 GA 설정을 다시 초기화하지 않고, 현재 측정 컨텍스트에 User ID만 추가하는 형태입니다.

로그아웃 시

로그아웃 이후에도 이전 User ID가 유지되는 것을 방지하기 위해, 로그아웃 mutation이 성공했을 때 User ID를 초기화합니다.

onSuccess: () => {
  window.gtag?.('set', { user_id: null });
  window.location.reload();
},

이를 통해 로그아웃 이후 발생하는 이벤트가 이전 사용자와 연결되지 않도록 처리하였습니다.

userAgent 설정 (WebView 환경)

초기에는 WebView 환경에서 웹에서 필요한 정보만을 userAgent로 설정하였습니다.

구체적으로는,

• 앱 버전 정보
• Android / iOS 구분을 위한 식별 정보

와 같은 커스텀 정보만을 userAgent에 포함하도록 구성하였습니다.

그러나 이와 같이 커스텀 정보만 userAgent로 설정하였을 경우, GA에서는 해당 접속을 정상적인 기기 정보로 인식하지 못하는 문제가 발생하였습니다.

이는 GA가 기기 카테고리(Desktop / Mobile), OS, 브라우저 여부 등을 userAgent 문자열에 포함된 기본 agent 정보를 기준으로 판단하기 때문입니다.

기본 agent 정보가 누락된 상태에서는, GA가 접속 환경을 올바르게 해석할 수 없었습니다.

해결 방식

이 문제를 해결하기 위해, 커스텀 userAgent를 단독으로 사용하는 대신 기본 agent 정보인 navigator.userAgent를 함께 포함하도록 수정하였습니다.

<WebView
  ref={webViewRef}
  source={{ uri: ENV.webUrl }}
  userAgent={`${navigator.userAgent} ${WEBVIEW_CUSTOM_USER_AGENT}`}
  ...
/>

이와 같이 구성함으로써, navigator.userAgent를 통해 기기 종류 및 플랫폼 정보가 정상적으로 전달되고 추가한 커스텀 문자열을 통해 앱 버전 및 WebView 접속 여부를 함께 식별할 수 있도록 하였습니다.

마무리하며

이번 글에서는 GA4 사용자 행동 데이터 설계를 바탕으로, React 환경에서 GA를 실제로 어떻게 설정하였는지를 정리하였습니다.

초기 설정부터 페이지 단위, 사용자 단위, 접속 환경 단위로 데이터를 해석하기 위한 설정까지, 실제 서비스 운영 과정에서 고려했던 포인트들을 중심으로 정리하였습니다.

다음 글에서는, 이렇게 수집된 데이터를 GA4 탐색 리포트에서 어떻게 분석하고 활용하였는지를 정리해보려고 합니다.

참고자료

• [TIL] GA4의 사용자 식별값, 뭐가 다를까? – User ID, Device ID, Client ID, Google Signals
• GA4가 사용자를 식별하는 방법과 사용자 ID(User ID) 수집하기
• GA4, 3분만에 기기별 데이터 분석하기

프로젝트 규모가 커지면서 가장 먼저 체감한 변화는 Hot Reloading 속도 저하였습니다.

작은 수정에도 화면 반영이 늦어지면서 개발 흐름이 끊기기 시작했고, 이 과정에서 전체 Webpack 빌드 시간 역시 함께 증가하고 있다는 문제도 확인했습니다.

개발 속도와 배포 템포 모두에 영향을 주는 신호였기 때문에, 빌드 파이프라인 전반을 점검하고 최적화가 필요하다고 판단했습니다.

👉 최적화 과정을 더 잘 이해하고 싶다면 아래 글을 먼저 읽어보세요! Webpack 빌드 프로세스 처음부터 끝까지 한 번에 이해하기

이번 글에서는 Hot Reloading과 전체 빌드 시간이 느려진 원인을 분석한 방법과, 이를 어떻게 개선했는지 구체적인 과정과 결과를 공유합니다.

문제와 원인 분석

1. Hot Reloading 속도 저하

프로젝트가 커지면서 가장 먼저 체감된 변화는 Hot Reloading 속도 저하였습니다. 초기에는 저장 즉시 화면이 갱신됐지만, 코드가 늘어날수록 변경 반영에 0.5~1초까지 걸리며 개발 흐름을 끊어놓는 병목이 되었습니다.

이 문제를 이해하기 위해 Hot Reloading의 동작 방식을 살펴보면 다음과 같습니다.

• Webpack은 변경된 모듈만 다시 빌드하지만, 그 작업은 전체 의존성 그래프와 캐시 정보를 기반으로 수행됩니다.
• 변경된 파일은 다시 파싱되며, 이에 따라 babel-loader, css-loader 등 로더가 재실행됩니다.

여기서 자연스럽게 다음과 같은 의문이 생깁니다.

“변경된 모듈만 처리하는데, 왜 프로젝트가 커지면 Hot Reloading이 느려질까?” “변경된 범위는 비슷한데 처리 시간은 왜 증가할까?”

핵심은, Webpack의 부분 빌드조차 “전체 프로젝트 규모를 기반으로” 이루어진다는 점입니다. 따라서 프로젝트가 커질수록 Hot Reloading이 수행해야 하는 기본적인 처리 비용도 함께 증가하게 됩니다.

결국 Hot Reloading 속도를 개선하려면, 변경된 파일을 가장 먼저 처리하는 로더 자체를 더 빠른 도구로 교체해야 한다는 결론에 도달했습니다.

2. 전체 빌드 시간 증가

Hot Reloading 문제를 분석하던 중, 전체 Webpack 빌드 시간 역시 꾸준히 증가하고 있다는 사실을 확인했습니다. 로컬 빌드는 7~8초, 배포 환경(CodeBuild)에서는 40초 이상 걸리며, 프로젝트 규모가 커질수록 병목이 더 분명하게 나타났습니다.

빌드는 여러 단계로 구성되기 때문에 원인이 다양할 수 있습니다. 그래서 speed-measure-webpack-v5-plugin(SMWP)을 사용해 로더와 플러그인별 시간을 계측해 보기로 했습니다. 이 도구는 Webpack 파이프라인에서 어떤 단계가 시간을 가장 많이 쓰는지 정확하게 보여줍니다.

SMWP 로그를 분석해보니 측정 결과는 다음과 같았습니다.

로그를 보면 전체 빌드 시간(약 7.16초) 중 TerserPlugin이 단독으로 3.95초를 사용하고 있었습니다. 즉, 전체 빌드 시간의 50% 이상이 minify 단계에서 소모되고 있었던 것입니다.

이를 통해 병목 지점이 매우 명확해졌습니다.

• JS/TS를 변환하는 로더들은 1~2초 내외로 빠르게 끝나고
• 다른 플러그인들도 수십~수백 ms 정도만 사용하지만
• TerserPlugin만 압도적으로 긴 시간을 사용

결국 전체 빌드가 느린 근본 원인은 코드 압축 과정, 즉 Terser 기반의 minify 단계가 지나치게 느리다는 점이었습니다.

해결 전략: SWC 기반 스택으로 전환

왜 SWC인가?

빌드 병목이 Babel과 Terser에 있다는 것이 확인된 후, 대체 도구로 esbuild와 SWC를 비교했습니다. Webpack 기반 프로젝트에서 속도·호환성·마이그레이션 난이도를 고려했을 때 SWC가 더 적절한 선택이라고 판단했습니다.

1) React + TypeScript 호환성과 안정성 esbuild는 속도는 빠르지만 React/TS 트랜스파일링에서 Babel 수준의 세밀함은 부족합니다. SWC는 Babel 대체를 목표로 만들어져 호환성이 안정적입니다.

2) Babel 옵션과 구조가 유사해 교체 비용이 거의 없음 SWC는 Babel과 프리셋 옵션 구조가 비슷해, 기존 설정을 거의 그대로 옮길 수 있습니다.

3) Webpack 구조를 유지하기에 가장 자연스러운 선택 esbuild는 번들러 성격이 강해 Webpack 자체를 대체하는 방향이지만, SWC는 Babel/Terser만 대체하는 트랜스파일러·미니파이어입니다.

4) 실제 빌드 환경에서 성능 차이도 크게 벌어지지 않음 공식 비교에서는 esbuild가 더 빠르지만, Webpack 기반 빌드에서는 SWC도 충분히 빠르고 체감 속도 차이가 크지 않습니다.

1. babel-loader → swc-loader

Babel과 SWC의 결정적 차이는 구현 언어입니다.

• Babel은 JS로 구현돼 AST 변환을 JS로 처리합니다.
• SWC는 Rust 기반으로 AST 최적화를 병렬로 처리할 수 있어, 기본 구조만으로도 10~20배 이상 빠릅니다.

즉, 기능은 같지만 구현 방식 자체가 속도 차이를 만들어냅니다.

2. TerserPlugin → SwcMinifyWebpackPlugin

Terser와 SWC minifier 역시 핵심 차이는 언어 성능 + 알고리즘 최적화 정도입니다.

Webpack 빌드 분석에서도 확인했듯,

• TerserPlugin이 빌드 시간의 절반 이상(3.95초)을 차지했고
• SWC minifier로 교체하자 0.169초로 줄어드는 등 큰 효과가 있었습니다.

Rust 기반의 병렬 압축기이기 때문에 대규모 번들에서도 속도가 크게 개선됩니다.

성능 개선 결과

Webpack의 병목을 SWC 기반 스택으로 교체한 뒤, Hot Reloading부터 전체 빌드, 배포 빌드까지 전 구간에서 즉각적인 성능 개선이 확인되었습니다.

1. Hot Reloading 시간: 0.50.6초 → 0.20.3초

먼저 Hot Reloading 시간을 측정했습니다.

[개선 전 – 약 575ms]

[개선 후 – 약 220ms]

기존에는 파일 크기나 의존성 규모에 따라 0.5~0.9초까지 지연되는 경우도 있었고, 페이지 단위 변경 시 UI 전체가 잠시 멈추는 느낌도 있었습니다.

SWC 기반의 swc-loader로 교체한 뒤에는 대부분의 수정이 0.2~0.3초 내에 반영되어, 체감 속도가 완전히 달라졌습니다.

2. 로컬 빌드 시간: 7.16초 → 3.15초

가장 큰 병목이었던 TerserPlugin을 SWC 기반의 SwcMinifyWebpackPlugin으로 교체하면서, 압축 단계 → 전체 빌드 → 배포 빌드까지 전 구간에서 속도가 크게 개선되었습니다.

압축(minify) 단계: 3.95초 → 0.169초

아래는 변경 후 빌드 로그입니다.

TerserPlugin이 빌드 시간의 절반 이상(3.95초)을 차지했지만, SWC minifier는 Rust 기반의 병렬 처리로 0.169초만에 압축을 완료했습니다.

전체 빌드: 약 2배 개선

Rust 기반 로더와 minifier의 전환만으로도 전체 빌드 속도가 7.16초에서 3.15초로 약 2배 빨라졌습니다.

3. 배포 환경(CodeBuild) 빌드: 40초 → 16초 (60% 단축)

로컬 빌드보다 더 중요한 부분은 실제 배포 환경에서의 효과입니다. AWS CodeBuild는 매번 캐시 없이 완전한 cold build를 수행하기 때문에 압축기의 성능이 매우 크게 반영됩니다.

아래는 CodeBuild 빌드 로그 비교입니다.

[개선 전 – BUILD 단계 약 40초]

[개선 후 – BUILD 단계 약 16초]

빌드 단계 시간이 40초 → 16초로 줄어들며, 전체 배포 속도가 약 60% 개선되었습니다. 단순 수치로도 2.5배 이상 빠른 빌드 파이프라인을 얻게 되었습니다.

마무리하며

이번 Webpack 최적화 작업을 진행하면서 가장 크게 느낀 점은, “감으로 최적화하지 않는다”는 원칙이 얼마나 중요한지였습니다. 이전에 Webpack 전체 빌드 사이클을 처음부터 끝까지 정리해두었던 덕분에, 각 로더와 플러그인이 어떤 역할을 하는지 정확히 이해할 수 있었고, 그 이해를 기반으로 병목 구간을 명확하게 찾아낼 수 있었습니다.

Webpack 최적화를 시작한다면 다음 두 가지를 기억하세요.

1) HMR 개선은 로더에서 시작된다 변경된 파일을 가장 먼저 처리하는 로더의 속도가 Hot Reloading 체감 속도를 결정합니다.

2) 빌드 개선은 수치 기반 병목 분석이 핵심이다 SMWP 같은 도구로 실제 시간을 측정하면, 추측 없이 가장 효과적인 최적화 지점을 찾을 수 있습니다.

이 두 가지 원칙만으로도 시행착오 없이 의미 있는 성능 개선을 해낼 수 있습니다.

Webpack을 공부하게 된 이유

프런트엔드 최적화를 다루다 보면 결국 Webpack 설정으로 돌아오곤 합니다. 캐시 전략, 이미지 최적화, 환경 변수 주입 모두 Webpack 단계에서 풀어야 하는 문제들이죠. 하지만 전체 흐름을 제대로 이해하지 못한 채 설정만 추가하다 보니, "아이콘이 왜 보이지 않지?", "배포했는데 왜 배포 전 화면이 나오지?"와 같은 이슈가 터졌을 때 빠르고 정확하게 원인을 좁히기 어려웠습니다. '봄봄' 서비스가 커지면서 빌드 시간과 번들 크기, 런타임 성능까지 점차 병목이 드러나기 시작했습니다. 하지만 이것이 Webpack의 설정 부족 때문인지, 아니면 도구 자체를 Vite 등으로 전환해야 할 문제인지 판단이 서지 않았습니다. 그래서 이번 글에서는 Webpack의 전체 빌드 흐름을 처음부터 끝까지 재정리하고, 그 속에서 현재 서비스에 적용 가능한 개선 지점을 체계적으로 찾고자 합니다.

빌드란 무엇인가?

"개발자가 작성한 코드를 브라우저가 이해할 수 있는 언어로 변환하는 일"

웹 애플리케이션을 만들다 보면 수많은 파일이 얽히고설켜 있습니다. JavaScript, TypeScript, CSS, 이미지 파일까지 브라우저는 TypeScript나 JSX를 직접 실행할 수 없습니다. 그래서 빌드(build) 라는 과정이 필요한데요. 빌드는 단순히 "코드를 합치는 일"이 아니라, 변환(compile) → 최적화(optimize) → 결과물 출력(output) 으로 이어지는 하나의 자동화된 파이프라인입니다. 이 글에서는 그중에서도 프런트엔드 빌드 도구의 대표격인 Webpack을 중심으로, “빌드가 실제로 어떻게 동작하는지”를 단계별로 살펴보겠습니다.

Webpack 빌드의 큰 흐름

Webpack의 빌드는 크게 여섯 단계로 구성됩니다.

엔트리(Entry) → 의존성 그래프(Dependency Graph) → 로더(Loaders) → 플러그인(Plugins) → 번들링(Bundle) → 결과 출력(Output)

이제 각 단계가 구체적으로 어떤 일을 하는지 차근히 살펴보겠습니다.

1. 엔트리 (Entry)

엔트리는 Webpack이 빌드를 시작하는 진입점(entry point) 입니다. 가장 먼저 읽는 파일로, 보통 React 프로젝트에서는 src/main.tsx가 이에 해당하죠. 이 파일을 기준으로 import된 모든 파일들을 추적하여 의존성 그래프를 만듭니다.

module.exports = {
  entry: './src/main.tsx',
};

엔트리를 여러 개 지정하면, 여러 페이지나 앱을 동시에 번들링할 수도 있습니다.

❓ “엔트리를 여러 개 지정하면 어떻게 될까?” 예를 들어, 하나의 프로젝트 안에 사용자용 페이지(user) 와 관리자용 페이지(admin) 가 따로 있다고 해봅시다. 이때 엔트리를 다음처럼 두 개로 지정할 수 있습니다.

module.exports = {
  entry: {
    user: './src/user/index.tsx',
   admin: './src/admin/index.tsx',
  },
};

이렇게 설정하면 Webpack은 두 개의 독립된 번들(user.js, admin.js)을 생성합니다. 각 엔트리 파일을 기준으로 별도의 의존성 그래프가 만들어지고, 두 그래프에 공통으로 포함된 모듈은 자동으로 공통 청크(common chunk) 로 분리됩니다. 즉, 서로 다른 페이지를 독립적으로 로드할 수 있고, 중복된 코드(예: React, 공용 유틸 등)는 한 번만 다운로드되므로 로드 속도와 캐싱 효율이 개선됩니다.

2. 의존성 그래프 (Dependency Graph)

Webpack은 지정된 엔트리 파일에서 시작해, 코드 안의 import 또는 require 구문을 재귀적으로 탐색하며 모듈 간의 관계를 그래프로 표현합니다. 이 그래프를 Dependency Graph(의존성 그래프)라고 부릅니다.

내부 동작 원리

1) 엔트리 탐색 (Entry Resolution) Webpack은 설정에서 지정한 엔트리(예: src/main.tsx)를 첫 노드(root node)로 등록합니다. 이 파일을 AST(Abstract Syntax Tree)로 파싱하여 내부의 import, require 구문을 찾습니다.

2) 모듈 분석 (Module Parsing) 발견된 의존 경로를 기준으로 각 모듈을 로드합니다. Webpack은 모듈을 해석할 때 resolver를 사용하여, 실제 파일 경로를 찾고 해당 파일의 내용을 다시 파싱합니다. 이 과정에서 .ts, .css, .svg 등 JS 외의 파일은 로더(loader)에 의해 변환되어 JS 모듈처럼 다뤄집니다.

3) 재귀적 추적 (Recursive Traversal) 각 모듈에서 또 다른 import가 발견되면, 동일한 과정을 반복합니다. 이렇게 모든 모듈의 의존 관계를 따라가며 하나의 방향성 그래프(Directed Graph)가 구성됩니다. 루프(순환 참조)가 감지될 경우, Webpack은 이를 처리 가능한 형태(캐시 모듈 참조)로 관리합니다.

4) 노드 및 엣지 구성 그래프의 노드(Node)는 각각의 모듈(파일)을 의미하고, 엣지(Edge)는 한 모듈이 다른 모듈을 import하는 의존 관계를 의미합니다.

의존성 그래프가 중요한 이유 이렇게 만들어진 의존성 그래프는 Webpack의 모든 최적화의 기반이 됩니다.

• 번들링 단계에서는 그래프를 순회하여 모듈을 하나의 실행 순서로 정렬합니다.
• Tree Shaking은 그래프에서 실제로 참조되지 않는 노드를 제거하는 과정입니다.
• 코드 스플리팅은 그래프를 분석하여 공통 부분(vendor 모듈)을 독립된 청크로 분리합니다.
• HMR(Hot Module Replacement) 역시 이 그래프를 이용해, 변경된 노드와 그 영향을 받는 노드만 재컴파일합니다.

즉, 의존성 그래프는 빌드의 뼈대가 되는 단계입니다.

3. 로더 (Loaders)

브라우저는 오직 JavaScript 혹은 JSON만 이해할 수 있습니다. 그런데 우리는 TypeScript, CSS, 이미지 등 다양한 언어를 함께 사용하는데요. 로더(loader)는 이런 파일들을 Webpack이 이해할 수 있도록 JavaScript 형태로 변환(compile)하는 역할을 합니다.

module: {
  rules: [
    {
      test: /\.(ts|tsx)$/,
      use: [
        {
          loader: 'babel-loader',
          options: {
            presets: [
              '@babel/preset-env',
              '@babel/preset-react',
              '@babel/preset-typescript',
            ],
          },
        },
      ],
      exclude: /node_modules/,
    },
    {
      test: /\.css$/,
      use: ['style-loader', 'css-loader'],
    },
  ],
}

대표적인 로더들

• babel-loader: TypeScript, JSX를 일반 JavaScript로 변환
• css-loader: CSS 파일을 JavaScript 모듈로 변환
• style-loader: 변환된 CSS를 DOM에 <style> 태그로 삽입

즉, 우리가 작성한 최신 React + TypeScript + CSS 코드는 브라우저가 직접 이해할 수 있는 평범한 JavaScript 함수로 변환됩니다.

로더 체인의 핵심

로더는 오른쪽에서 왼쪽으로 순차적으로 실행됩니다. 예를 들어 ['style-loader', 'css-loader']는:

1. css-loader가 먼저 CSS를 JS로 변환
2. style-loader가 그 결과를 DOM에 삽입

babel-loader의 presets 또한 같은 순서대로 변환을 하게 됩니다. 이런 체인 구조 덕분에 SASS, PostCSS 같은 로더를 추가해 점진적으로 CSS를 완성할 수 있습니다.

4. 플러그인 (Plugins)

로더가 파일 단위 변환에 집중한다면, 플러그인(plugin) 은 빌드 전체 과정의 확장과 자동화를 담당합니다. Webpack의 진짜 강점이 바로 이 플러그인 시스템인데요. 빌드 타임에 파일을 생성하거나, 환경 변수를 주입하고, 정적 리소스를 복사하는 등 “코드 변환” 이상의 일을 가능하게 해줍니다. 다양한 플러그인이 존재하지만, 대표적인 플러그인을 간단하게 소개드리겠습니다.

HtmlWebpackPlugin — HTML에 빌드 결과 자동 삽입

HtmlWebpackPlugin은 빌드 시점에 HTML 파일을 생성하거나, 기존 템플릿에 번들된 JS·CSS 파일을 자동으로 삽입해주는 플러그인입니다.

new HtmlWebpackPlugin({
  template: './index.html',
  filename: 'index.html',
  inject: true,
  favicon: './public/assets/logo.png',
});

• template : 기준이 되는 HTML 템플릿을 지정
• 빌드 결과물(main.js, style.css 등)을 <script>, <link> 태그로 자동 삽입
• favicon 옵션을 지정하면 파비콘도 함께 포함됨

💡 예시 전후 비교

원본 템플릿

<!DOCTYPE html>
<html>
  <head>
    <title>My App</title>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

빌드 후 결과

<!DOCTYPE html>
<html>
  <head>
    <title>My App</title>
    <link rel="icon" href="assets/logo.png">
  </head>
  <body>
    <div id="root"></div>
    <script src="main.5c8a.js"></script>
  </body>
</html>

빌드 후 JS 파일 이름이 main.5c8a.js처럼 해시로 바뀌어도 <script>가 자동으로 갱신되므로 HTML을 직접 수정할 필요가 없습니다.

DefinePlugin — 환경 변수 및 상수 주입

DefinePlugin은 코드 안에서 사용할 전역 상수나 환경 변수(process.env)를 빌드 타임에 주입하는 플러그인입니다.

new webpack.DefinePlugin({
  'process.env': JSON.stringify(process.env),
});

이렇게 정의하면 실제 코드에서는 다음처럼 접근할 수 있습니다.

const baseUrl = process.env.API_BASE_URL;

실제로는 런타임 변수처럼 보이지만, Webpack은 빌드 시점에 다음처럼 문자열로 치환합니다 👇

const baseUrl = 'https://api.example.com/v1';

이 방식 덕분에,

• 불필요한 분기 코드는 트리쉐이킹(Tree Shaking) 으로 제거되고
• 빌드 환경(dev, staging, prod 등)에 맞게 코드가 자동 분기됩니다.

즉, DefinePlugin은 “환경별 조건 분기”를 가능하게 하는 핵심 도구입니다.

CopyWebpackPlugin

CopyWebpackPlugin은 정적 파일(public 폴더 등)을 빌드 결과물(dist) 에 자동으로 복사해주는 플러그인입니다.

예를 들어, assets, robots.txt, sitemap.xml 같은 파일을 자동으로 포함시킬 수 있습니다.

new CopyWebpackPlugin({
  patterns: [
    { from: 'public/assets', to: 'assets' },
    {
      from: path.resolve(__dirname, 'public', `robots.${process.env.NODE_ENV}.txt`),
      to: path.resolve(__dirname, 'dist', 'robots.txt'),
    },
  ],
});

• from: 복사할 원본 파일/폴더
• to: 결과물이 저장될 위치
• patterns 배열을 사용하면 여러 세트를 한 번에 관리 가능

💡 예를 들어,

• public/assets → dist/assets 로 복사하여 이미지 접근 경로를 유지하고
• 환경(prod, dev)에 따라 robots.txt나 sitemap.xml을 자동 교체할 수 있습니다.

이 덕분에 HTML이나 JS 코드에서 정적 파일 경로를 직접 관리할 필요 없이, assets/logo.png 형태로 접근이 가능해집니다.

5. 번들링 (Bundling)

이제 변환이 끝난 모든 모듈들을 하나로 묶는 단계입니다. Webpack은 의존성 그래프를 따라, 각 모듈의 실행 순서와 관계를 고려해 하나의 JS 번들을 만듭니다. 이 과정에서 코드 스플리팅(splitChunks)이 적용되어 공통 모듈(vendor, react 등)을 별도 파일로 분리하기도 합니다. 즉, “필요한 코드만 효율적으로 다운로드하게 만드는” 단계예요.

6. 결과 출력 (Output)

마지막으로, 번들링된 결과물이 실제 디스크에 저장됩니다.

output: {
  filename: 'js/[name].[contenthash:8].js',
  path: path.resolve(__dirname, 'dist'),
  publicPath: '/',
},

• filename: 생성될 파일의 이름 패턴 ([name]은 엔트리 이름, [contenthash:8]은 8자리 해시)
• path: 빌드 결과물이 저장될 물리적 경로 (절대 경로)
• publicPath: 브라우저에서 파일에 접근할 때 사용하는 기본 경로

여기서 filename에 포함된 [contenthash]는 파일 내용 기반의 고유 해시값입니다. 즉, 파일의 내용이 바뀌지 않으면 해시값도 동일하게 유지되고, 반대로 코드가 수정되면 해시값이 바뀌어 파일 이름도 달라집니다.

예를 들어 다음과 같습니다.

• 변경 전 : main.5c8a.js
• 변경 후 : main.ae91.js

❓ “왜 해시값을 붙일까?” 만약 우리가 매번 같은 이름(main.js)으로 빌드 결과를 내보낸다면, 브라우저는 새로 배포된 파일을 이전 캐시와 구분하지 못합니다. 즉, 파일 내용이 변경되어도 브라우저는 여전히 캐싱된 main.js를 사용하죠. 이 때문에 최신 코드가 반영되지 않거나, 사용자가 새로고침을 여러 번 해야 최신 버전이 로드되는 문제가 발생합니다. 이 문제를 해결하기 위해 Webpack은 파일 이름에 내용 기반 해시값(contenthash) 을 붙입니다. 이제 파일이 바뀌면 자동으로 파일 이름도 달라지고, 브라우저는 새로운 리소스로 인식해 최신 버전을 받아오게 됩니다.

추가 설정들

지금까지는 Webpack의 빌드 과정을 중심으로 살펴봤습니다. 하지만 실제 프로젝트에서는 빌드 외에도 “개발 환경에서의 편의성”과 “배포용 최적화”를 고려해야 합니다. 이를 제어하는 주요 옵션이 바로 mode, resolve, devServer, optimization입니다.

1. mode

mode는 Webpack이 어떤 환경에서 실행되는지를 결정하는 옵션입니다.

module.exports = {
  mode: 'production',
};

• development
  • 빌드 속도를 우선시
  • 코드 압축(X), 주석 유지
  • 디버깅에 유리한 source-map 자동 활성화
• production
  • 코드 난독화 및 압축(Uglify, Terser 등)
  • Tree Shaking 활성화로 사용되지 않는 코드 제거
  • 성능 최적화 중심의 빌드

즉, mode를 전환하는 것만으로 개발 효율 ↔ 실행 성능 간의 균형을 쉽게 맞출 수 있습니다.

2. resolve

resolve는 모듈을 어떻게 해석할지를 정의합니다.

module.exports = {
  // ...
  resolve: {
    extensions: ['.tsx', '.ts', '.js'],
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '#': path.resolve(__dirname, 'public'),
    },
  },
}

• extensions
  • 파일 import 시 확장자를 생략할 수 있게 합니다.
  • 예: import App from '@/App' → 자동으로 App.tsx, App.ts, App.js 순서로 탐색
• alias
  • 복잡한 상대 경로(../../../) 대신 간단한 별칭으로 import 가능
  • 예: src/components/Button → @/components/Button

이 설정을 잘 활용하면 코드 가독성과 유지보수성이 크게 향상됩니다.

3. devServer

webpack-dev-server는 로컬 개발 시 변경 사항을 자동으로 반영해주는 개발용 서버를 제공합니다.

module.exports = {
  // ...
  devServer: {
    static: [
      { directory: path.join(__dirname, 'dist') },
      { directory: path.join(__dirname, 'public') },
    ],
    port: 3000,
    open: true,
    hot: true,
    historyApiFallback: true,
    client: {
      overlay: true,
    },
  },
}

• static : 정적 파일(dist, public) 제공 경로 설정
• port : 로컬 개발 서버 포트 (localhost:3000)
• open : 서버 실행 시 자동으로 브라우저 열기
• hot : HMR(Hot Module Replacement) 활성화 → 새로고침 없이 즉시 반영
• historyApiFallback : SPA 라우팅을 지원 (/about 같은 경로 새로고침 시에도 index.html로 리디렉션)
• overlay : 에러 발생 시 브라우저 화면에 직접 표시

즉, 코드를 저장할 때마다 즉시 결과를 확인할 수 있어 개발 효율이 극대화됩니다.

4. optimization

optimization은 Webpack이 코드 크기와 로딩 속도를 최적화하는 핵심 설정입니다.

module.exports = {
  // ...
  optimization: {
    usedExports: true,
    sideEffects: false,
    minimize: isProduction,
    splitChunks: {
      chunks: 'all',
      // ...
    },
  },
}

• usedExports: true → Tree Shaking 활성화 (사용되지 않는 export 제거)
• sideEffects: false → 부작용 없는 모듈은 자유롭게 최적화
• minimize: true → 코드 압축(TerserPlugin 자동 적용)
• splitChunks → 코드 스플리팅으로 공통 모듈 분리

예를 들어 React와 다른 라이브러리를 별도 청크로 분리하면, 초기 로딩 속도가 빨라지고, 공통 모듈이 캐시되어 페이지 간 전환 시 훨씬 가볍게 동작합니다.

마무리하며

Webpack은 분명 러닝 커브가 있는 도구입니다. 하지만 그 원리를 이해하고 나면, 프런트엔드 최적화의 강력한 무기가 됩니다. Vite나 다른 도구로 전환을 고민하기 전에, 현재 Webpack 설정을 제대로 활용하고 있는지 먼저 점검해 보세요. 생각보다 많은 개선점을 발견해 보세요.

이번 글에서는 Webpack의 빌드 흐름을 처음부터 끝까지 정리하며 “왜 이렇게 동작하는가”를 중심으로 살펴봤습니다. 다음 글에서는 '봄봄' 프로젝트에 실제로 적용한 고급 최적화 기법을 구체적인 수치와 함께 공유하겠습니다.

봄봄은 뉴스레터를 모아 읽고 습관을 만드는 서비스입니다. 습관은 '읽기'만으로는 형성되지 않습니다. 저장하고, 활용하는 과정이 필요합니다. 그래서 본문 중 원하는 부분을 저장하는 하이라이트, 그 위에 생각을 남기는 메모를 만들었습니다. 이 두 기능은 사용자가 중요한 문장을 다시 찾고, 새롭게 알게 된 내용을 활용할 수 있도록 돕습니다.

이러한 목표를 구현하기 위해, 저는 브라우저의 Selection/Range API와 앵커(Anchor) 저장 전략을 조합하여 하이라이트를 설계했습니다. 아래에서 앵커 저장 전략의 선택 배경과 하이라이트 구현 과정을 단계별로 소개하겠습니다.

먼저 이해해야 할 것들

하이라이트는 결국 브라우저에서 “사용자가 드래그한 구간”을 안전하게 읽고, 나중에 복원하는 일입니다. 여기서 핵심은 Selection과 Range입니다.

1) Selection — “현재 선택 상태”를 나타내는 객체

• 정의: 사용자가 선택한 텍스트 범위 또는 커서(캐럿) 위치를 나타내는 브라우저 객체
• 역할: 하이라이트/메모 로직의 출발점(현재 선택 상태)

획득 방법

const selection = window.getSelection();
if (!selection) return; // 브라우저 지원 및 안전 체크

핵심 속성·메서드

• rangeCount — 포함된 Range 개수(일반적으로 0 또는 1)
• isCollapsed — 드래그 상태가 접혀 있는지 여부
• getRangeAt(index) — Range 객체 가져오기(보통 getRangeAt(0))
• removeAllRanges() / addRange(range) — 선택 영역 초기화/적용

2) Range — “선택 구간을 좌표로 표현하는” 객체

• 정의: 문서 내 연속 구간을 표현하며, 시작/끝을 노드 + 오프셋으로 갖는다
• 관계: Selection이 “상태”라면, Range는 그 상태의 정밀 좌표

획득 방법

const selection = window.getSelection();
const range = selection && selection.rangeCount > 0 ? selection.getRangeAt(0) : null;

핵심 속성·메서드(실무 필수)

• startContainer / startOffset — 시작 지점(노드, 노드 내 문자 오프셋)
• endContainer / endOffset — 끝 지점(노드, 노드 내 문자 오프셋)
• toString() — 범위의 텍스트 내용 추출(quote 저장 등에 활용)
• getBoundingClientRect() — 범위를 감싸는 단일 박스(툴팁 중앙 배치 등)
• getClientRects() — 줄바꿈 등으로 나뉜 다중 라인 박스 목록
• intersectsNode(node) — 특정 노드와의 교차 여부 확인(겹침 처리에 유용)
• commonAncestorContainer — 시작/끝이 속한 최하위 공통 조상 노드
  • 텍스트 노드일 수 있으므로 순회 루트로 쓸 땐 parentNode로 올려 사용 권장

요약: Selection으로 “지금 선택된 상태”를 얻고, Range로 그 선택의 “정확한 좌표”를 다룹니다. 이 좌표를 안정적으로 저장·복원하는 것이 하이라이트 구현의 핵심입니다.

앵커 설계 옵션 비교 & 채택 이유

이제 선택된 Range를 “다시 열어도 같은 자리”로 복원하려면, 그 위치를 식별할 앵커(Anchor)가 필요합니다.

앵커를 어떻게 설계하느냐에 따라 내구성과 정확도가 크게 달라지는데요. 흔히 쓰는 세 가지 방식을 먼저 비교한 뒤, 봄봄에서 왜 특정 조합을 채택했는지를 설명하겠습니다.

세 가지 접근 방법

1) 텍스트 기반

• TextQuote: 선택문 quote + 앞뒤 prefix/suffix로 위치 추정
• 장점: DOM이 조금 바뀌어도 문장이 같으면 복원이 쉬움
• 단점: 동일 문장 반복 시 모호성, 전역 검색으로 성능 비용

2) 구조 기반(요소 단위)

• CSS Selector / DOM Path: 선택자 경로로 요소 찾기
• 장점: 배우기 쉽고 빠름
• 단점: 텍스트 노드 단위 정밀도 부족, 클래스/구조 변경에 취약

3) 구조 기반(노드·텍스트 정밀)

• XPath: 트리 축/인덱스로 요소/텍스트 노드 직접 지정(text()[1] 등)
• 장점: 정밀도 최고(텍스트 노드 + 오프셋), 결정적 복원
• 단점: 중간 노드 삽입·이동 등 구조 변화에 인덱스 민감

이 세 가지 방법의 저장 형태를 간단한 예시 코드로 설명드리겠습니다.

<main class="article-body">
  <h1>오늘의 뉴스레터</h1>
  <p>아침 루틴을 만들기 위한 작은 팁들.</p>
  <p>데이터는 습관을 만든다. 반복은 이해를 낳는다.</p>
  <p>마지막으로 추천 아티클을 소개합니다.</p>
</main>

위와 같은 html이 있을 때, 두 번째 <p>의 “데이터는 습관을 만든다” 구절을 하이라이트 한다고 가정해봅시다.

1. 텍스트 기반 — TextQuote

{
  "quote": "데이터는 습관을 만든다",
  "prefix": "",
  "suffix": " 반복은 이해를 낳는다."
}

1. 구조 기반(요소 단위) — CSS Selector

{
  "selector": ".article-body > p:nth-of-type(2)",
  "quote": "데이터는 습관을 만든다",
  "offsetInElement": { "start": 0, "end": 13 } // 옵션: 요소 내부 오프셋
}

1. 구조 기반(노드·텍스트 정밀) — XPath

{
  "startXPath": "/html/body/main/p[2]/text()[1]",
  "startOffset": 0,
  "endXPath": "/html/body/main/p[2]/text()[1]",
  "endOffset": 13,
}

봄봄에서 XPath를 선택한 이유

봄봄의 뉴스레터는 사용자에게 발송된 뒤 내용/형식이 변경되지 않는 특성이 있습니다. 즉, 서비스 관점에서 문서 구조가 고정됩니다. 이 전제 덕분에 XPath의 약점(구조 변동 민감도)이 크게 문제가 되지 않고, 대신 아래 장점을 최대화할 수 있습니다.

• 텍스트 노드 레벨 정밀도: …/p[2]/text()[1]처럼 텍스트 노드를 직접 가리켜 startOffset/endOffset을 안정적으로 적용할 수 있습니다.

• 빠르고 결정적인 복원: 전역 탐색 없이 즉시 노드 접근이 가능해, 다수 하이라이트의 배치 복원 성능이 좋습니다.

• 템플릿 일관성과의 궁합: 발송 후 레이아웃이 바뀌지 않으므로 인덱스 기반 경로가 안정적으로 유지됩니다.

하이라이트 구현: 단계별로 뜯어보기

하이라이트의 사용자 흐름은 크게 네 단계입니다.

1. 선택/클릭 감지
2. 선택 저장(앵커 생성)
3. 복원(페이지 방문 시)
4. DOM에 하이라이트 그리기/지우기

각 단계를 구체적으로 살펴봅시다.

선택/클릭 감지

하이라이트 UX의 첫 단추는 “언제 툴바를 띄울지” 를 정확히 판단하는 것입니다. 핵심은 두 가지입니다.

1. 플랫폼별 이벤트 순서 차이를 이해하고,
2. 단순 클릭 vs 드래그 선택을 안정적으로 구분하기.

A. 플랫폼별 이벤트 흐름 파악하기

플랫폼마다, 그리고 단순 클릭과 꾹 눌러 드래그(텍스트 선택) 시의 이벤트 흐름이 다릅니다. 이를 명확히 분리해 처리해야 잘못된 동작을 방지할 수 있습니다.

1) PC 웹(브라우저)

• 클릭 & 드래그: pointerdown → mousedown → pointerup → mouseup → click

2) iOS

• 클릭: pointerdown → touchstart → pointerup → touchend → mousedown → mouseup → click
• 드래그: pointerdown → touchstart → pointerup → touchend

3) Android

• 클릭: iOS와 동일
• 드래그: pointerdown → touchstart → contextmenu(드래그 시작) → pointercancel → touchcancel → contextmenu(드래그 끝)

Android는 드래그 시작/끝 모두 contextmenu 가 발생합니다. 즉, 하나의 이벤트로 선택 완료 시점을 감지하게 되는 셈이죠.

B. 클릭 vs 드래그 판별하기

Selection API만으로도 대부분 판별이 가능합니다.

• selection.rangeCount > 0 그리고
• selection.isCollapsed === false → 드래그(텍스트 선택) 상태
• 그 외 → 단순 클릭/선택 해제

const selection = window.getSelection();
if (selection && !selection.isCollapsed && selection.rangeCount > 0) {
  // ✅ 드래그(선택) 상태 로직
  // openToolbarFromSelection(selection);
  return;
}
// ⛔ 선택 없음 → 단순 클릭 또는 선택 해제

Android의 특수성 위 방식은 PC와 iOS에서 잘 작동하지만, Android는 예외입니다. Android는 드래그 완료 시 contextmenu 이벤트가 발생하는 독특한 구조를 가지고 있습니다. 이로 인해 하나의 이벤트 핸들러로 클릭과 드래그를 함께 처리하기 어렵습니다. 따라서 Android에서는 이벤트 레벨에서 역할을 분리합니다:

• contextmenu → 선택 완료(드래그) 처리
• click → 기존 하이라이트 클릭 처리

C. 최종 구현 (핵심 코드)

위 분석을 바탕으로, 플랫폼별로 서로 다른 이벤트 핸들러 조합이 필요합니다:

이를 구현한 코드는 다음과 같습니다:

// Android 전용: 드래그 선택 완료 처리
const handleSelectionComplete = useCallback(() => {
  const selection = window.getSelection();
  if (selection && !selection.isCollapsed && selection.rangeCount > 0) {
    openToolbarFromSelection(selection);
    return;
  }
}, [openToolbarFromSelection]);

// Android 전용: 기존 하이라이트 클릭 처리
const handleHighlightClick = useCallback(
  (e: PointerEvent | MouseEvent) => {
    const target = e.target as HTMLElement;

    // 1) 기존 하이라이트 클릭 → 편집/툴바
    if (target.tagName === 'MARK') {
      openToolbarFromHighlight(target);
      return;
    }

    // 2) 아닐 경우 → 툴바 닫기
    onHide();
  },
  [openToolbarFromHighlight, onHide],
);

// iOS/PC 웹 전용: 클릭과 드래그를 하나의 핸들러로 통합
const handleHighlightClickOrSelection = useCallback(
  (e: PointerEvent | MouseEvent) => {
    const target = e.target as HTMLElement;

    // 1) 기존 하이라이트 클릭
    if (target.tagName === 'MARK') {
      openToolbarFromHighlight(target);
      return;
    }

    // 2) 드래그(선택) 여부
    const selection = window.getSelection();
    if (selection && !selection.isCollapsed && selection.rangeCount > 0) {
      openToolbarFromSelection(selection);
      return;
    }

    // 3) 둘 다 아님 → 닫기
    onHide();
  },
  [onHide, openToolbarFromHighlight, openToolbarFromSelection],
);

// === 플랫폼별 안전한 이벤트 바인딩 ===
if (isIOS()) {
  // iOS: pointerup 하나로 클릭/드래그 통합 처리
  document.addEventListener('pointerup', handleHighlightClickOrSelection);
} else if (isAndroid()) {
  // Android: 드래그는 contextmenu, 클릭은 click으로 분리
  document.addEventListener('contextmenu', handleSelectionComplete);
  document.addEventListener('click', handleHighlightClick);
} else if (!isWebView()) {
  // PC 웹: mouseup으로 통합, selectionchange로 해제 감지
  document.addEventListener('mouseup', handleHighlightClickOrSelection);
  document.addEventListener('selectionchange', handleSelectionClear);
}

핵심 포인트:

• 하이라이트 클릭 → 드래그 선택 → 그 외 해제의 3단 분기
• 플랫폼별 이벤트 타이밍 차이를 고려한 안전한 바인딩
• Android는 contextmenu의 특수성 때문에 핸들러 분리 필수

선택 저장(앵커 생성)

하이라이트를 저장하는 목표는 간단합니다. 지금의 Range를 "나중에 정확히 복원"할 수 있을 만큼 결정적인 좌표로 바꾸는 것인데요. 여기서는 Selection/Range → XPath + 오프셋으로 변환하는 과정을 설명합니다.

어떤 XPath를 저장하는 것이 가장 좋을까?

처음에는 드래그 시작 노드의 XPath+offset, 드래그 끝 노드의 XPath+offset을 그대로 저장하려 했습니다. 하지만 이렇게 하면 start↔end 사이의 모든 노드를 나중에 복원 시 다시 찾아 조립해야 했습니다. 드래그가 길수록 이 과정이 복잡해지고 오류 여지가 커집니다.

그래서 방향을 바꿨습니다.

1. commonAncestorContainer(공통 조상)를 구해 그 조상의 XPath만 저장
   • range.commonAncestorContainer 속성으로 공통 조상을 가져올 수 있습니다.
2. 공통 조상 하위의 모든 TextNode를 직렬로 연결한 하나의 "논리 텍스트"로 보고, 그 안에서 startOffset/endOffset을 계산해 저장

이렇게 하면 저장 형식은 단순해지고, 복원 시에도 한 번의 트리 순회로 정확한 Range를 재구성할 수 있습니다.

예시로 보는 오프셋 계산

<main class="article-body">
  <h1>오늘의 뉴스레터</h1>
  <p>아침 루틴을 만들기 위한 작은 팁들.</p>
  <p>데이터는 습관을 만든다. 반복은 이해를 낳는다.</p>
  <p>마지막으로 추천 아티클을 소개합니다.</p>
</main>

첫 번째 <p>의 "아침"부터 세 번째 <p>의 "합니다"까지 드래그했다고 가정해 봅시다.

• 공통 조상은 <main class="article-body">이고, 이 요소의 XPath를 저장합니다.

• 오프셋 계산은 <main> 내부의 모든 TextNode를 순서대로 연결한 뒤,

  • startOffset: 드래그 시작 지점까지의 누적 문자 수
  • endOffset: 드래그 끝 지점까지의 누적 문자 수

  로 정의합니다.

구체적인 계산 과정:

TextNode 1: "오늘의 뉴스레터" (8자)
TextNode 2: "아침 루틴을 만들기 위한 작은 팁들." (20자)
TextNode 3: "데이터는 습관을 만든다. 반복은 이해를 낳는다." (27자)
TextNode 4: "마지막으로 추천 아티클을 소개합니다." (22자)

→ startOffset = 8 (h1 끝) + 0 ("아침"의 시작) = 8
→ endOffset = 8 + 20 + 27 + 22 = 77

구현 코드

1) 노드 → XPath: getXPathForNode

const ROOT_PATH = '.';

/** 특정 노드의 XPath를 구하는 함수 */
export const getXPathForNode = (node: Node, root: Node = document): string => {
  // TextNode일 경우 부모 요소로 이동
  if (node.nodeType === Node.TEXT_NODE) node = node.parentNode!;
  if (node === root) return ROOT_PATH;

  const index =
    Array.from(node.parentNode!.childNodes)
      .filter((n) => n.nodeName === node.nodeName)
      .indexOf(node as ChildNode) + 1;

  return (
    // 재귀적으로 계산
    getXPathForNode(node.parentNode!, root) +
    '/' +
    node.nodeName.toLowerCase() +
    `[${index}]`
  );
};

2) 컨테이너 내부 오프셋 계산: getHighlightOffsets

export const getHighlightOffsets = (container: Element, range: Range) => {
  let start = -1;
  let end = -1;
  let currentOffset = 0;

  // NodeFilter.SHOW_TEXT를 통해서 TextNode만 필터링
  const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);

  while (walker.nextNode()) {
    const node = walker.currentNode as Text;

    if (node === range.startContainer)
      start = currentOffset + range.startOffset;

    if (node === range.endContainer)
      end = currentOffset + range.endOffset;

    currentOffset += node.textContent!.length;
  }
  return { start, end };
};

• 컨테이너 내부의 모든 TextNode를 좌→우 순회하면서 currentOffset을 누적
• startContainer/endContainer를 만나면 해당 노드 내 오프셋을 더해 문서 내 절대 오프셋으로 변환

3) 저장 페이로드 생성: saveSelection

export const saveSelection = (range: Range) => {
  const container =
    // 공통 조상이 TextNode일 경우 부모 Element를 공통 조상으로 함
    range.commonAncestorContainer.nodeType === Node.TEXT_NODE
      ? range.commonAncestorContainer.parentElement!
      : (range.commonAncestorContainer as Element);

  const xpath = getXPathForNode(container);
  const { start, end } = getHighlightOffsets(container, range);

  return {
    location: {
      startXPath: xpath,
      startOffset: start,
      endXPath: xpath,  // 공통 조상 XPath를 양쪽에 저장
      endOffset: end,
    },
    color: theme.colors.primaryLight, // 하이라이트 색
    text: range.toString(), // 선택된 텍스트(검증/미리보기용)
  };
};

API 설계 변경 기록
초기에는 startXPath/endXPath에 각각의 노드 XPath를 저장하려 했으나, 멀티 문단 드래그에서 복원이 복잡해져서 공통 조상의 XPath를 양쪽에 동일하게 저장하는 형태로 전환했습니다. 😅

복원(페이지 방문 시) — 저장된 앵커로 Range 재구성

저장까지 했다면, 이제는 저장된 데이터(location)를 바탕으로 DOM에서 다시 정확한 Range를 만들어 <mark>로 그려야 합니다. 복원의 핵심은 단순합니다. 저장의 역순으로 진행하면 됩니다.

• 입력: startXPath(=공통 조상), startOffset, endOffset
• 목표: 공통 조상 컨테이너 안에서 문자 오프셋 → (텍스트 노드, 노드 내 오프셋)으로 매핑해 Range 생성

1) XPath로 컨테이너 노드 복원하기

/** XPath로 노드를 다시 찾는 함수 */
export const getNodeByXPath = (xpath: string, root: Document = document) => {
  const result = document.evaluate(
    xpath,                              // 저장된 XPath
    root,                               // 보통 document
    null,                               // 네임스페이스 리졸버(필요 없으면 null)
    XPathResult.FIRST_ORDERED_NODE_TYPE,// 첫 번째 매칭 노드만 가져오기
    null,
  );
  return result.singleNodeValue;        // Element | Text | null
};

• XPath는 W3C 표준 쿼리 언어이기 때문에 브라우저에 표준 API가 있습니다.
• document.evaluate를 쓰면 한 줄로 노드를 쉽게 되찾을 수 있습니다.

2) 컨테이너 내부 오프셋 → Range로 변환하기

function getHighlightRange(container: Node, start: number, end: number) {
  const range = document.createRange();
  const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);

  let currentOffset = 0;

  const positions = {
    startNode: null as Text | null,
    endNode: null as Text | null,
    startOffset: 0,
    endOffset: 0,
  };

  while (walker.nextNode()) {
    const node = walker.currentNode as Text;
    const len = node.textContent!.length;

    // start 지점이 이 텍스트 노드 범위 안에 들어오는가?
    if (
      !positions.startNode &&
      start >= currentOffset &&
      start <= currentOffset + len
    ) {
      positions.startNode = node;
      positions.startOffset = start - currentOffset; // 노드 내부 오프셋으로 변환
    }

    // end 지점이 이 텍스트 노드 범위 안에 들어오는가?
    if (
      !positions.endNode &&
      end >= currentOffset &&
      end <= currentOffset + len
    ) {
      positions.endNode = node;
      positions.endOffset = end - currentOffset; // 노드 내부 오프셋으로 변환
    }

    currentOffset += len; // 다음 텍스트 노드로 이동하기 전에 누적 길이 갱신
  }

  if (!positions.startNode || !positions.endNode) {
    // 저장/복원 정규화 규칙이 다르면 오프셋 매칭 실패 가능
    throw new Error('Offset 변환 실패');
  }

  range.setStart(positions.startNode, positions.startOffset);
  range.setEnd(positions.endNode, positions.endOffset);

  return range;
}

• 컨테이너 내부의 모든 텍스트 노드를 왼쪽→오른쪽으로 순회하면서,
• 저장된 startOffset/endOffset이 어떤 텍스트 노드의 몇 번째 문자에 해당하는지 계산해 Range를 만듭니다.

3) 전체 복원 흐름 (요약)

// 1) 컨테이너 복원
const container = getNodeByXPath(highlight.location.startXPath);
if (!container) return;

// 2) Range 재구성
const range = getHighlightRange(
  container,
  Number(highlight.location.startOffset),
  Number(highlight.location.endOffset),
);

// 3)  태그로 하이라이트 그리기
renderHighlight(range, highlight.color, highlight.id);

참고: renderHighlight 함수는 다음 섹션에서 자세히 다룹니다. 이 함수는 Range 내의 텍스트 노드들을 찾아 각 노드의 해당 구간을 <mark> 태그로 감싸는 역할을 합니다.

DOM에 하이라이트 그리기/지우기

하이라이트 표시 방법은 크게 두 가지가 있습니다.

1. CSS Custom Highlight API: 실제 DOM을 건드리지 않고, HighlightRegistry에 Range를 등록해 ::highlight(name)로 스타일링합니다.
2. DOM 래핑 방식: 선택 구간을 <mark>(또는 <span>) 같은 실제 요소로 감싸 스타일링합니다.

봄봄은 <mark> 래핑을 채택했습니다. 이유는 다음과 같습니다.

• 의미/접근성(A11y): <mark>는 "문맥상 강조된 텍스트"라는 시맨틱 태그라서 스크린 리더 등 보조기술에서 의미가 분명합니다.
• 상호작용: <mark data-highlight-id="…">처럼 식별자/메타데이터를 바로 심어 클릭·롱프레스·툴팁 등 이벤트 타깃으로 쓰기 쉽습니다. Custom Highlight는 DOM 노드를 생성하지 않아서 dataset/이벤트 바인딩이 어렵습니다.
• 다중 색상/스타일: 색상·밑줄·점선 등 스타일을 하이라이트 단위로 자유롭게 적용 가능합니다.
• 호환성/일관성: 다양한 웹뷰/브라우저에서 동일한 동작을 보장하기 용이합니다. Custom Highlight는 구현·지원 레벨/행동이 플랫폼별로 상이할 수 있습니다.

하이라이트 그리기: 텍스트 조각만 <mark>로 감싸기

하이라이트는 텍스트 노드 하나 안에서도 start~end 구간만 칠해야 합니다. 그래서 원래 텍스트를 before | middle | after로 나누고, middle만 <mark>로 감싸 한 번에 교체합니다.

export const highlightNodeSegment = (
  node: Text,
  start: number,
  end: number,
  color: string,
  highlightId: number,
) => {
  const parent = node.parentNode!;
  const before = node.textContent!.slice(0, start);
  const middle = node.textContent!.slice(start, end);
  const after  = node.textContent!.slice(end);

  // 의미 태그: 문맥상 강조
  const mark = document.createElement('mark');

  // 하이라이트 색
  mark.style.backgroundColor = color;

  // 상호작용/삭제를 위한 식별자
  mark.dataset.highlightId = String(highlightId);

  // 텍스트 채우기
  mark.textContent = middle;

  // DocumentFragment로 한 번에 교체 → reflow 최소화
  const frag = document.createDocumentFragment();
  if (before) frag.appendChild(document.createTextNode(before));
  frag.appendChild(mark);
  if (after)  frag.appendChild(document.createTextNode(after));

  // 기존 텍스트 노드를 전체 교체
  parent.replaceChild(frag, node);
};

왜 DocumentFragment인가요?
appendChild를 여러 번 하는 대신, 오프라인 트리에서 조립 → 한 번에 교체하면 reflow/repaint 비용을 줄일 수 있습니다.

하이라이트 지우기: <mark>를 텍스트로 환원

삭제는 간단합니다. 특정 highlightId를 가진 <mark>들을 찾아 내부 텍스트 노드로 되돌리기만 하면 됩니다.

export const removeHighlightFromDOM = (highlightId: number) => {
  const marks = document.querySelectorAll(
    `mark[data-highlight-id="${highlightId}"]`,
  );

  marks.forEach((mark) => {
    const textNode = document.createTextNode(mark.textContent ?? '');
    mark.replaceWith(textNode);
  });
};

전체 흐름 정리

지금까지 하이라이트 구현의 네 단계를 모두 살펴봤습니다:

1. 선택/클릭 감지 - 플랫폼별 이벤트 처리
2. 선택 저장 - Range를 XPath + 오프셋으로 변환
3. 복원 - 저장된 데이터로 Range 재구성
4. 그리기/지우기 - <mark> 태그로 시각화

이 네 단계가 유기적으로 연결되어 "읽은 내용을 저장하고 다시 찾아볼 수 있는" 하이라이트 기능을 완성합니다.

전체 코드

전체 구현은 GitHub에서 자세하게 확인할 수 있습니다.

• 클릭/드래그 이벤트 처리 로직
• Selection 관련 로직
• 하이라이트 관련 로직

마무리하며

하이라이트는 "선택한 구간을 표시한다"만 보면 단순해 보입니다. 그러나 모든 플랫폼에서 일관되게 동작하도록 이벤트를 다루고, 저장/복원 로직을 안정적으로 설계하며, 실전의 예외 케이스(멀티 문단, 웹뷰 차이, 리렌더링 충돌)들을 처리하는 순간부터 복잡도가 급격히 올라갑니다.

이번 글에서는 그 복잡도를 낮추기 위해 컨테이너 XPath + 내부 오프셋이라는 앵커 전략을 선택하고, 선택→저장→복원→그리기/삭제까지의 전 과정을 단계별로 정리했습니다.

핵심은 세 가지였습니다.

• 정확성: 공통 조상과 오프셋 기반으로 멀티 문단도 결정적으로 복원
• 일관성: iOS/Android/PC 각각의 이벤트 흐름을 분리해 안정적 트리거 확보
• 실용성: 의미/접근성/상호작용에 유리한 <mark>로 DOM을 직접 마킹

하지만 "동작한다"만으로는 충분하지 않습니다. 사용자가 실제로 쓰고 싶어지는 경험을 만들려면 더 많은 디테일이 필요합니다.

다음 편에서는 하이라이트 UX를 한 단계 더 개선하는 디테일과 React 환경에서 마주치는 실전 이슈들을 구체적인 코드와 함께 공유하겠습니다.

MSW나 PWA를 사용할 때마다 ‘Service Worker’라는 말을 봤지만, 그 정체를 깊이 생각해 본 적은 없었습니다.

그러던 중 PWA 개발 과정에서 캐싱 문제를 겪으면서 “도대체 Service Worker가 뭐길래 서비스 전체에 영향을 주지?”라는 의문이 생겼습니다. 그저 백그라운드에서 도는 스크립트라고만 생각했는데, 실제로는 서비스 전반의 동작 방식까지 바꿀 수 있는 존재였던 것입니다.

그래서 이번 글에서는 Service Worker가 무엇인지, 어떤 원리로 동작하는지 차근차근 살펴보려 합니다.

대상 독자

• Service Worker를 들어본 적은 있지만 정확히 어떤 역할을 하는지 모르는 분
• Service Worker의 개념과 활용 방법을 더 깊이 이해하고 싶은 분

Service Worker란?

브라우저의 페이지와 네트워크 사이에서 요청을 가로채고 처리하는 독립 실행 환경(자바스크립트 파일).

Service Worker는 페이지의 JS와는 별도로 워커 컨텍스트에서 동작하며, 브라우저가 이벤트를 트리거할 때 실행됩니다. 이를 통해 네트워크 요청을 가로채서 원하는 응답을 반환하거나, 캐시를 이용해 오프라인 상태에서도 콘텐츠를 제공할 수 있습니다. PWA의 핵심 기술로서 푸시 알림과 백그라운드 동기화 같은 기능 구현에도 사용됩니다.

주요 특징

• 이벤트 기반: install, activate, fetch, push 등 이벤트로 동작.
• 비동기 중심: 대부분의 브라우저 API가 Promise 기반으로 동작.
• 백그라운드 실행: UI와 독립적으로 동작(직접 DOM에 접근 불가).
• HTTPS 필요: 보안상의 이유로 HTTPS 환경에서만 동작 (개발 시 localhost는 예외)

⚠️ Service Worker는 페이지와 네트워크 사이에서 요청을 가로채고 조작할 수 있기 때문에, 악의적인 중간자(Man-in-the-Middle)나 변조된 스크립트가 끼어들면 서비스 전체에 치명적인 영향을 줄 수 있다. 그래서 브라우저는 Service Worker를 HTTPS 환경에서만 동작하며, 개발 시 localhost는 예외다. 개발자는 서드파티 스크립트 검증과 안전한 배포 절차를 반드시 지켜야 한다.

Service Worker 등록하기

Service Worker는 단순한 JS 파일이 아니라, 브라우저가 별도로 인식하고 관리해야 하는 워커입니다. 따라서 일반 스크립트처럼 <script>로 불러오는 것이 아니라, 명시적으로 등록(register) 해야 브라우저가 이를 감지하고 관리할 수 있습니다.

Service Worker API를 통해서 브라우저에 Service Worker를 등록 가능합니다.

Service Worker 파일 생성

serviceWorker.js

self.addEventListener('install', function () {
  self.skipWaiting();
});

self.addEventListener('activate', function (event) {
  event.waitUntil(self.clients.claim());
});

• Service Worker에서 실행할 기능을 정의하는 자바스크립트 파일입니다.
• self는 ServiceWorkerGlobalScope를 가리키며, Service Worker의 전역 실행 환경입니다.
• Service Worker는 window와는 별도의 독립 환경에서 동작하므로, 생명주기(install, activate)나 네트워크 이벤트(fetch, push 등)를 처리할 때는 self에 이벤트를 등록해야 합니다.

Service Worker 등록

const registerServiceWorker = async () => {
  if ("serviceWorker" in navigator) {
    try {
      const registration = await navigator.serviceWorker.register("/serviceWorker.js");
      if (registration.installing) {
        console.log("Service worker installing");
      } else if (registration.waiting) {
        console.log("Service worker installed");
      } else if (registration.active) {
        console.log("Service worker active");
      }
    } catch (error) {
      console.error(`Registration failed with ${error}`);
    }
  }
};

// …

registerServiceWorker();

• navigator.serviceWorker.register를 사용해 브라우저에 Service Worker를 등록합니다.
• 등록을 성공하면 installing, waiting, active 상태를 확인할 수 있습니다.

if (isProdunction) {
    registerPwaServiceWorker()
}

if (isDevelopment) {
    const { worker } = await import('./mocks/browser');
    worker.start()
}

• Service Worker는 도메인당 하나만 등록할 수 있습니다.
• 따라서 msw(Mock Service Worker)처럼 Service Worker를 활용하는 라이브러리를 함께 쓴다면, 환경별로 분기하여 충돌을 방지하는 것이 좋습니다.

💡 TIP: 등록된 Service Worker는 브라우저 개발자 도구에서 확인할 수 있습니다.

• Application 탭 → Service Workers: 등록 상태(installing, waiting, activated)와 업데이트/중지 버튼 확인 가능
• Sources 탭 → serviceWorker.js: 실제 등록된 스크립트를 디버깅 가능
• chrome://inspect/#service-workers
  • 크롬에서 등록된 전체 Service Worker 목록을 확인할 수 있음
  • 다른 도메인에 등록된 워커까지 한 번에 점검 가능

Service Worker의 생명주기

1. Installing

브라우저가 Service Worker 파일을 다운로드하고 파싱한 뒤, 설치 중 상태가 됩니다.

• 설치가 성공하면 Installed 상태로 넘어가고, 실패하면 Redundant 상태가 됩니다.
• install 이벤트에서 event.waitUntil()을 사용하면 특정 비동기 작업(예: 캐시 저장)이 끝날 때까지 설치 과정을 지연시킬 수 있습니다.

2. Installed/waiting

설치가 완료되면 설치됨 상태가 됩니다.

• 현재 앱을 제어하는 다른 Service Worker가 없다면 곧바로 Activating으로 넘어갑니다.
• 기존 Service Worker가 이미 동작 중이라면 새 워커는 waiting 상태로 머무릅니다.

👉 새 버전의 Service Worker가 자동으로 바로 교체되지 않고, 기존 워커가 종료될 때까지 대기하는 이유는 사용자 경험을 보호하기 위함입니다.

3. Activating

설치된 워커가 앱을 제어하기 직전 상태입니다.

• 이 단계에서 activate 이벤트가 발생합니다.
• event.waitUntil()을 사용해 캐시 정리나 마이그레이션 같은 작업을 완료할 때까지 활성화를 지연시킬 수 있습니다.

4. Activated

Service Worker가 앱을 제어할 준비가 끝난 상태입니다.

• 이 시점부터 네트워크 요청을 가로채 fetch 이벤트를 처리하거나, push 이벤트를 받아 푸시 알림을 보낼 수 있습니다.
• 사실상 실제 기능이 동작하는 단계입니다.

5. Redundant

Service Worker가 더 이상 쓰이지 않게 된 상태입니다.

• 설치 실패, 혹은 새로운 버전의 Service Worker가 교체되었을 때 발생합니다.
• 이 상태의 워커는 앱 동작에 영향을 주지 않습니다.

Service Worker 이벤트 소개

ServiceWorkerGlobalScope에는 다양한 이벤트가 정의되어 있습니다. 그중 자주 쓰이는 이벤트를 정리하면 다음과 같습니다.

생명주기 관련

install

• Service Worker가 설치될 때 발생합니다.
• 초기 리소스 캐싱 같은 설치 준비 작업을 수행합니다.
• 이 이벤트는 취소할 수 없으며, 다른 이벤트로 대체되지 않습니다.

self.addEventListener('install', function (event) {
  // 기존 활성화된 워커가 있어도 곧바로 새 워커를 활성화
  self.skipWaiting();

  // 캐시에 필요한 리소스를 미리 저장 가능
  event.waitUntil(
    caches
    .open("v1")
    .then((cache) =>
          cache.addAll([
      "/",
      "/index.html",
      "/style.css",
      "/app.js",
      "/image-list.js",
      "/star-wars-logo.jpg",
      "/gallery/",
      "/gallery/bountyHunters.jpg",
      "/gallery/myLittleVader.jpg",
      "/gallery/snowTroopers.jpg",
    ]),
         ),
  );
});

activate

• 새 Service Worker가 활성화 직전에 발생합니다.
• 이전 버전의 캐시를 정리하거나, 마이그레이션 작업을 수행합니다.

self.addEventListener("activate", (event) => {
  const cacheAllowlist = ["v2"];

  event.waitUntil(
    caches.keys().then((cacheNames) =>
                       Promise.all(
      cacheNames.map((cacheName) => {
        if (!cacheAllowlist.includes(cacheName)) {
          return caches.delete(cacheName);
        }
        return undefined;
      }),
    ),
                      ),
  );
});

네트워크 / 메시지 관련

fetch

• fetch() 메서드가 호출될 경우 발생

self.addEventListener("fetch", (event) => {
  const { method, url } = event.request;

  // 특정 요청 가로채기
  if (method === "GET" && url.endsWith("/hello")) {
    event.respondWith(
      new Response(
        JSON.stringify({ message: "Hello from Service Worker!" }),
        { headers: { "Content-Type": "application/json" } }
      )
    );
  }
});

message

• 페이지에서 postMessage()를 사용해 Service Worker로 데이터를 보낼 때 발생합니다.
• 페이지 ↔ Service Worker 간 양방향 통신에 활용됩니다. 예를 들어, 페이지에서 요청한 데이터를 워커가 가공해서 다시 응답할 수 있습니다.

// serviceWorker.js
self.addEventListener("message", (event) => {
  console.log("Message from page:", event.data);

  // 받은 메시지에 따라 응답을 보낼 수도 있음
  event.source.postMessage({
    reply: `Echo: ${event.data}`,
  });
});

// main.js (페이지 스크립트)
navigator.serviceWorker.controller.postMessage("Hello SW!");

// Service Worker가 응답 보낸 걸 수신
navigator.serviceWorker.addEventListener("message", (event) => {
  console.log("Reply from SW:", event.data.reply);
});

messageerror

• 메시지 전송 도중 직렬화(serialize)할 수 없는 데이터나 전송 불가능한 객체를 보냈을 때 발생합니다.
• 메시지 통신 실패를 감지하고 로깅하거나 대체 동작을 수행합니다.

// serviceWorker.js
self.addEventListener("messageerror", (event) => {
  console.error("Message failed:", event);
});

// main.js
try {
  // 직렬화 불가능한 데이터(예: 함수)를 보내면 오류 발생
  navigator.serviceWorker.controller.postMessage(() => {});
} catch (err) {
  console.error("Message send failed:", err);
}

푸시 / 알림 관련

push

• 서버에서 푸시 메시지를 보냈을 때 발생합니다.
• 알림(Notification API)을 띄우는 데 주로 사용됩니다.

self.addEventListener("push", (event) => {
  const data = event.data?.json() || { title: "Default title" };

  event.waitUntil(
    self.registration.showNotification(data.title, {
      body: data.body || "Hello from Service Worker!",
      icon: "/icon.png",
    })
  );
});

pushsubscriptionchange

• 브라우저가 푸시 구독을 만료하거나 변경했을 때 발생합니다.
• 새로운 구독 정보를 서버에 업데이트해야 합니다.

self.addEventListener("pushsubscriptionchange", (event) => {
  event.waitUntil(
    self.registration.pushManager.subscribe({ userVisibleOnly: true })
    .then((subscription) => {
      // 새로운 구독 정보를 서버로 전송
      return fetch("/update-subscription", {
        method: "POST",
        body: JSON.stringify(subscription),
      });
    })
  );
});

notificationclick

• 사용자가 알림을 클릭했을 때 발생합니다.
• 특정 URL을 열거나 포커스를 맞출 수 있습니다.

self.addEventListener("notificationclick", (event) => {
  event.notification.close();

  event.waitUntil(
    clients.openWindow("/welcome") // 특정 경로 열기
  );
});

notificationclose

• 사용자가 알림을 닫았을 때 발생합니다.
• 통계 수집, 서버 로깅 등에 활용할 수 있습니다.

self.addEventListener("notificationclose", (event) => {
  console.log("Notification closed:", event.notification.tag);
});

기타

sync

• 네트워크가 다시 연결되었을 때 브라우저가 백그라운드에서 동기화 작업을 수행할 수 있을 때 발생합니다.
• 오프라인 상태에서 실패한 요청(예: 서버에 저장하지 못한 데이터)을 네트워크가 복구되면 다시 전송하는 데 유용합니다.

// serviceWorker.js
self.addEventListener("sync", (event) => {
  if (event.tag === "sendFormData") {
    event.waitUntil(
      fetch("/submit", {
        method: "POST",
        body: JSON.stringify({ message: "retry after offline" }),
        headers: { "Content-Type": "application/json" },
      })
    );
  }
});

// main.js (페이지)
navigator.serviceWorker.ready.then((registration) => {
  return registration.sync.register("sendFormData");
});

마무리하며

이번 글에서는 Service Worker의 기본 개념부터 생명주기, 그리고 주요 이벤트까지 살펴보았습니다. Service Worker는 PWA의 핵심 기술이지만, 개념만 보면 추상적으로 느껴지기 쉽습니다. 중요한 것은 언제 어떤 이벤트가 발생하고, 그 이벤트 안에서 무엇을 할 수 있는지를 이해하는 것입니다.

기억해 두면 좋은 포인트

• Service Worker는 브라우저와 네트워크 사이의 독립 실행 환경이다.
• HTTPS 환경에서만 동작하며(localhost 예외), 이는 보안상 필수 제약이다.
• 한 도메인에는 하나의 Service Worker만 등록 가능하다.
• 생명주기(install → waiting → activate → activated → redundant)를 이해하자.
• Service Worker는 잘못 설계하면 서비스 전체에 영향을 주므로, 신중하게 설계해야 한다.

참고자료

• Service Worker API - Web APIs | MDN
• PWA의 핵심, 서비스 워커란?
• 서비스 워커에 대해 알아보고 Mock Response 만들기 | 카카오엔터테인먼트 테크블로그

서비스를 기획/운영하다 보면, ‘이 기능이 정말 사용자가 잘 쓸까?’, ‘사용자는 어디서 이탈할까?’ 같은 질문을 자주 던지게 됩니다. 하지만 이런 판단을 ‘감(感)’으로만 하기엔 위험합니다.

Google Analytics(GA)는 이런 불확실성을 줄여주는 도구입니다. 사용자의 행동 흐름을 감이 아닌 데이터로 정량적으로 분석할 수 있게 합니다.

제가 개발한 서비스 '봄봄(Bombom)'은 “읽는 습관을 만드는 뉴스레터 플랫폼”입니다. 이 서비스의 핵심 목표는 단순한 방문이 아니라, “얼마나 자주, 얼마나 꾸준히 다시 돌아오는가”를 데이터로 확인하는 것입니다.

그래서 서비스 초기에 GA를 도입했습니다. GA4를 통해 ‘가입 → 구독 → 첫 읽기’까지의 사용자 여정을 추적하고, 습관 형성이 실제로 이루어지는지를 데이터로 검증하고자 했습니다.

이번 글에서는 GA를 서비스에 적용하기 이전 단계인 ‘설계’ 과정을 다룹니다. 즉, 단순히 “GA를 적용하는 법”이 아니라 ‘무엇을, 왜, 어떻게 수집할 것인가’를 정의하고, 서비스의 목표에 맞게 데이터를 구조화하는 방법을 이야기합니다.

또한, 이해를 돕기 위해 실제 저희 봄봄 프로젝트에서 설계했던 예시를 함께 소개합니다. 이 글이 GA를 처음 도입하거나, 데이터를 ‘의미 있게’ 활용하고 싶은 분들께 하나의 데이터 설계 가이드라인이 되길 바랍니다.

사용자 행동 데이터 고도화 설계: 수집 · 분석 · 활용

서비스를 데이터로 성장시키기 위해서는 ‘사용자 행동을 어떻게 정의하고, 측정하고, 해석할 것인가’를 먼저 설계해야 합니다. 이 과정은 단순한 이벤트 기록이 아니라, 서비스의 목표를 데이터로 번역하는 일입니다.

Google Analytics(GA4)를 기반으로 한 사용자 행동 데이터 전략은 수집(Collect) → 분석(Analyze) → 활용(Activate) 의 세 단계로 나눌 수 있습니다.

1) 수집 (Collect)

서비스의 데이터를 설계할 때 가장 먼저 해야 할 일은 “무엇을 기록할 것인가”를 명확히 정의하는 것입니다. 이 단계는 단순히 클릭 이벤트를 저장하는 수준이 아니라, 서비스의 목표를 수치로 관찰할 수 있게 만드는 과정입니다.

📌 수집 단계의 핵심 포인트

1. 어떤 사용자 행동 데이터를 기록할지 정의하는 단계입니다. → 서비스의 핵심 플로우에서 사용자의 ‘의도 있는 행동’을 추출합니다.

2. 페이지 방문, 클릭, 체류 시간, 전환 이벤트 등 필요한 데이터를 선별하고, 코드 단에서 추적 로직(gtag 등)을 직접 심습니다.

3. 수집 단계에서의 설계가 부족하면 이후 분석과 활용에서 한계가 생기므로, 서비스 목표에 맞춘 정교한 데이터 정의가 필수적입니다.

⚠️ 수집 단계의 유의사항

1. 모든 데이터를 다 기록하지 않습니다. → 지나친 이벤트 수집은 코드 복잡도와 분석 노이즈를 높입니다. 필요한 데이터만 선별해야 합니다.

2. 수집은 ‘한 번에 완벽히’ 끝나지 않는 것입니다. → 분석 단계를 거치며 새로운 인사이트가 생기면 다시 어떤 데이터를 수집해야 할지가 달라집니다. 즉, 수집–분석–활용은 순환 구조입니다.

💡 봄봄에서의 수집 설계 예시

봄봄의 핵심 목표는 “읽는 습관을 만드는 것”이었기 때문에, 습관 형성에 직결되는 행동만 선별했습니다.

1️⃣ 아티클 카드 클릭 이벤트

• 목적: 사용자가 ‘어떤 경로에서 아티클을 읽기 시작했는가’를 파악하기 위함입니다. 봄봄은 ‘오늘의 뉴스레터’, ‘뉴스레터 보관함’ 등 다양한 진입점에서 아티클 읽기 페이지로 이동할 수 있습니다.
• 수집 이유: 아티클 읽기 페이지의 접근 경로를 데이터로 비교해, “어떤 페이지가 실제 읽기 행동으로 가장 잘 이어지는가”를 분석할 수 있도록 하기 위함입니다.

2️⃣ 하이라이트 / 메모 이벤트

• 목적: 봄봄은 “읽은 내용을 기록하고 활용하는 경험”을 동기부여 요소로 설계했습니다. 이 기능이 실제로 사용자 습관에 기여하는지를 검증하기 위해 하이라이트/메모 관련 행동 데이터를 수집했습니다.
• 수집 이유: 사용자가 얼마나 자주 하이라이트를 추가·삭제하고, 메모를 작성·업데이트하는지에 따라 기능의 실효성을 평가할 수 있습니다.

2) 분석 (Analyze)

수집 단계에서 이벤트를 정의했다면, 이제는 그 데이터를 어떻게 읽을 것인가가 중요합니다. 분석 단계는 수집된 데이터를 기반으로 사용자의 행동 흐름(Flow)을 파악하고, 서비스의 병목이나 개선 포인트를 찾아내는 과정입니다.

📌 분석 단계의 핵심 포인트

1. 수집된 데이터를 기반으로 사용자 행동 흐름을 파악하는 단계입니다. → 단순히 클릭 수를 세는 것이 아니라, 사용자가 어떤 경로로 이동하며, 어디서 멈추는지를 확인합니다.

2. 신규 사용자와 재방문자의 행동 차이, 주요 이탈 구간, 전환 경로를 살펴봅니다. → 이 과정을 통해 어떤 지점이 사용자 경험을 방해하는지 구체적으로 드러납니다.

3. 이 단계는 코드보다 GA4 인터페이스(GA 홈페이지)의 이해도가 훨씬 중요합니다. → 이벤트만 잘 보내는 것으로는 충분하지 않습니다. 실제 GA4에서 이벤트를 연결·시각화·분석하는 흐름을 설계해야 진짜 인사이트가 만들어집니다.

⚠️ 분석 단계의 유의사항

1. 이 단계는 설계 과정에서 가장 중요합니다. → 데이터를 ‘수집하는 것’보다 무엇을 해석하고, 어떤 결정을 내릴 것인가가 훨씬 중요합니다.

2. 코드가 아닌 ‘GA 설정 이해’가 핵심입니다. → 수집된 데이터는 단순히 이벤트 로그에 머물지 않습니다. GA4에서는 우리가 직접 수집한 이벤트 외에도 기본적으로 제공되는 자동 수집 데이터(DAU, MAU, 세션, 페이지 전환, 체류 시간 등)가 매우 풍부합니다. 문제는 이 방대한 데이터 중에서 무엇을 어떻게 연결하고 분석할지 GA 내부에서 설정하는 과정이 훨씬 복잡하고 중요하다는 점입니다.

💡 봄봄에서 분석하려는 행동 흐름

봄봄은 “읽기 → 기록 → 재방문”이라는 습관 형성 구조를 가지고 있습니다. 이를 검증하기 위해, 두 가지 주요 행동 흐름을 분석 대상으로 정했습니다.

1️⃣ 아티클 소비 흐름

• 목적: 사용자가 어떤 진입점에서 가장 많이 아티클 읽기로 이어지는지를 확인하기 위함입니다. 여러 페이지(오늘의 뉴스레터, 뉴스레터 보관함 등)에서 아티클을 클릭할 수 있지만, 실제로 ‘읽기 페이지’로 전환되는 비율은 다릅니다.

2️⃣ 하이라이트 / 메모 기능 활용 흐름

• 목적: 봄봄의 핵심 기능 중 하나인 ‘하이라이트/메모’가 실제로 사용자의 습관 형성에 얼마나 기여하는지를 파악하기 위함입니다.

3) 활용 (Apply)

데이터 설계의 마지막 단계는 활용(Apply)입니다. 이 단계는 단순히 분석 결과를 보고서로 남기는 것이 아니라, 그 데이터를 기반으로 실제 서비스의 방향을 결정하고 실행 전략을 설계하는 과정입니다.

📌 활용 단계의 핵심 포인트

1. 분석 결과를 서비스에 반영하는 단계입니다. → 마케팅, 제품 개선, 온보딩, 리텐션 프로그램 등 다양한 영역에서 데이터를 활용할 수 있습니다.

2. 실행 자체보다 “활용 계획을 세우는 것”이 더 중요합니다. → 모든 인사이트를 즉시 반영할 수는 없지만, 무엇을 언제, 어떤 우선순위로 개선할지를 미리 설계해야 데이터 전략이 완성됩니다.

마무리하며

많은 서비스가 Google Analytics를 “적용했다”에서 멈춥니다. 그러나 목적 없이 데이터를 쌓기 시작하면, 그 수치는 금세 아무 의미 없는 숫자가 되고, GA는 더 이상 열어보지 않는 ‘형식적인 툴’로 남게 됩니다.

그래서 중요한 것은 적용보다 설계입니다. 무엇을 수집하고, 왜 분석하며, 어떻게 활용할지를 서비스의 목표와 연결된 구조로 설계해야 합니다. 이렇게 체계적으로 설계된 데이터는 다시 서비스 개선으로 이어지고, GA는 자연스럽게 ‘계속 활용하고 싶은 중요한 툴’로 자리 잡게 됩니다.

이번 글에서는 GA4를 단순한 통계 도구가 아닌, 서비스의 성장을 데이터로 뒷받침하는 설계 도구로 다루는 방법을 이야기했습니다. ‘수집(Collect) → 분석(Analyze) → 활용(Apply)’ 단계를 체계적으로 나누어 설계하면, 데이터는 더 이상 숫자가 아니라 “보고 싶고, 계속 확인하고 싶은 지표”로 바뀝니다.

이번 글에서는 GA4를 기반으로 ‘무엇을 수집하고 어떻게 해석할지’를 중심으로 데이터 설계 과정을 다뤘습니다. 다음 글에서는 이 설계 내용을 실제 코드에 적용하는 과정을 다룰 예정입니다.

React 환경에서 react-ga4 같은 외부 라이브러리 없이, 직접 GA를 초기화하고, 이벤트 트래킹 로직을 구현하는 방법을 단계별로 소개하겠습니다.

1편과 2편에서는 QueryStore와 useSyncExternalStore를 기반으로 캐시 생성 → 구독 → 갱신의 최소 골격을 구축하고, useQuery/useMutation의 기본 흐름을 정리했다. 그러나 현 구조에는 캐시를 언제 갱신하고 언제 폐기할지에 대한 정책이 없으며, 동일 데이터를 여러 곳에서 동시에 요청하는 상황이나 일시적 네트워크 오류 같은 운영 이슈에도 취약하다. 3편부터는 이 빈틈을 메우며 시스템의 완성도를 끌어올려보자.

이번 편의 주요 추가 기능

• staleTime
  • SWR에 나오는 stale을 뜻하며,
  • 캐시가 fresh → stale로 바뀌는 데 걸리는 시간이다.
  • 즉, staleTime이 지나면 새로운 데이터를 불러오게 된다.
• gcTime
  • gcTime은 Garbage Collect Time의 약자로,
  • 구독이 끊긴 캐시 데이터를 얼마나 오래 보존할지를 정하는 수명 개념이다.
• retry
  • 일시적 네트워크/서버 오류 시 해당 쿼리를 자동 재시도하는 횟수를 뜻한다.
• requestCoalescing
  • 동일 queryKey에 대한 동시 요청을 하나의 요청으로 합친다.
  • 첫 요청의 Promise를 공유해 중복 트래픽을 제거하고, 완료 결과를 모든 구독자에 반영하는 기능이다.

기능 구현 전 리팩토링: Client/Store 분리로 응집도·확장성 높이기

이번 리팩토링에서는 QueryStore와 이를 사용하는 로직을 client / store로 분리했다. 목적은 간단하다.

1. 관심사 분리(SoC)
2. 전역 상태 캡슐화
3. 응집도 향상
4. 향후 stale/gc/retry/coalescing 정책을 자연스럽게 끼워 넣기 위함

현재 QueryStore 구조의 문제점

• 전역 store/listeners 노출
• 상태 보관/구독과 네트워크 트리거 혼재 → 관심사 불명확
• getSnapshot/subscribe/updateData가 흩어진 함수로 존재 → 응집도 낮음, 객체(클라이언트/스토어)로 묶어 캡슐화 필요

Store: 데이터·구독에만 집중

export const createQueryStore = (): QueryStore => {
  const store: Store<unknown> = new Map<string, Query<unknown>>();
  const listeners: Record<string, Set<Listener>> = {};

  const getOrInit = <TData>(key: string): Query<TData> => {
    const cur = store.get(key) as Query<TData> | undefined;
    if (cur) return cur;

    const next = initState();
    store.set(key, next);
    return next as Query<TData>;
  };

  return {
    getSnapshot: <TData>(key: string) => getOrInit<TData>(key),
    setSnapshot: <TData>(
      key: string,
      next: Query<TData> | ((prev: Query<TData>) => Query<TData>),
    ) => {
      const prev = getOrInit<TData>(key);
      store.set(
        key,
        typeof next === 'function'
          ? (next as (p: Query<TData>) => Query<TData>)(prev)
          : next,
      );

      listeners[key]?.forEach((cb) => cb());
    },
    subscribe: (key, callback) => {
      if (!listeners[key]) listeners[key] = new Set();
      listeners[key].add(callback);
      return () => listeners[key]?.delete(callback);
    },
  };
};

export const queryStore = createQueryStore();

• 전역 객체 제거 → 모듈 내부 캡슐화
• getSnapshot/subscribe/setSnapshot을 한 객체로 묶어 응집도↑

Client: 정책·행위의 진입점

export const queryClient = {
  patchQuery: <TData>(key: string, partial: Partial<Query<TData>>) => {
    queryStore.setSnapshot(key, (prev) => ({ ...prev, ...partial }));
  },
  fetchQuery: async <TData>(key: string, queryFn: () => Promise<TData>) => {
    queryClient.patchQuery<TData>(key, { isLoading: true, isError: false });
    try {
      const result = await queryFn();
      queryClient.patchQuery(key, {
        data: result,
        isLoading: false,
        isError: false,
      });
    } catch {
      queryClient.patchQuery(key, {
        isLoading: false,
        isError: true,
      });
    }
  },
  loadQueryData: <TData>(key: string, queryFn: () => Promise<TData>) => {
    const snapshot = queryStore.getSnapshot(key);
    if (snapshot.data) return;

    queryClient.fetchQuery(key, queryFn);
  },
};

• 네트워크와 정책의 책임은 client가 일관되게 담당

기능 구현

staleTime

[변경 로직]

1. useQuery 훅 옵션으로 staleTime 전달
2. updatedAt 타임스탬프 저장
3. “스테일인지” 판정 로직

1) 훅에서 staleTime 받기 + 로드 시 전달

// useQuery.ts
interface UseQueryOptions<TData> {
  // ...
  staleTime?: number; // fresh 상태 유지 시간(ms)
}

export const useQuery = <TData>({ 
  //...
  staleTime = 0  // 기본 0분
}: UseQueryOptions<TData>) => {
  // ...
  queryClient.loadQueryData(queryKey, queryFnRef.current, staleTime); // staleTime 인자로 추가
  // ...
};

2) 데이터가 언제 갱신됐는지 기록: updatedAt

export type Query<TData> = {
  // ...
  updatedAt?: number;
};

3) “지금 stale 인가?”를 판단

// queryClient.ts
loadQueryData<TData>(key, queryFn, staleTime) {        // staleTime 인자 추가
  const snapshot = queryStore.getSnapshot(key);
  const isStale =
    !snapshot.updatedAt || Date.now() - snapshot.updatedAt > staleTime; // 추가

  if (snapshot.data == null || isStale) {              // 패칭 조건 추가
    queryClient.fetchQuery<TData>(key, queryFn);
  }
}

gcTime

[변경 로직]

1. useQuery 훅 옵션으로 gcTime 전달
2. 마지막 구독 해제 시 GC 타이머를 걸고, 재구독 시 타이머를 해제

1) 훅에서 gcTime 받기 + 구독 시 전달

// useQuery.ts
interface UseQueryOptions<TData> {
  // ...
  gcTime?: number;  // 캐시 보존 시간(ms)
}

export const useQuery = <TData>({
  // ...
  gcTime = 5 * 60 * 1000,  // 기본 5분
}: UseQueryOptions<TData>) => {
  // ...
  const unsubscribe = queryStore.subscribe(queryKey, onStoreChange, gcTime); // subscribe 인자로 추가
  // ...
};

2) 재구독 시 GC 타이머 해제 (캐시 보존)

// queryStore.ts
const gcTimeouts = new Map<string, ReturnType<typeof setTimeout>>();

// gcTime 인자 추가
subscribe: (key, callback, gcTime) => {
  // ...
  // 재구독 시, 기존 GC 타이머가 걸려 있었다면 해제
  const timeout = gcTimeouts.get(key);
    if (timeout) {
      clearTimeout(timeout);
      gcTimeouts.delete(key);
    }
  // ...
  return () => {
    listeners[key]?.delete(callback);

    // 구독 해제 시, 구독 수가 0일 경우 GC 타이머 가동
    if (listeners[key]?.size === 0) {
      delete listeners[key];
      const timeout = setTimeout(() => {
        store.delete(key);
        gcTimeouts.delete(key);
      }, gcTime);
      gcTimeouts.set(key, timeout);
    }
  };
}

retry: 간단한 재시도 로직을 붙이기

[변경 로직]

1. useQuery 훅 옵션으로 retry 전달
2. loadQueryData에서 실패 시 짧게 대기 후 재시도
3. fetchQuery에서 실패를 rethrow하여 상위(루프)가 감지

1) 훅에서 retry 받기 + 로드 시 전달

// useQuery.ts
interface UseQueryOptions<TData> {
  // ...
  retry?: number; // 실패 시 재시도 횟수
}

export const useQuery = <TData>({
  // ...
  retry = 3, // 기본 3회
}: UseQueryOptions<TData>) => {
  // ...
  // staleTime / retry를 함께 전달
  queryClient.loadQueryData(queryKey, queryFnRef.current, staleTime, retry);
  // ...
};

2) 실패하면 잠깐 쉰 뒤 다시: loadQueryData 재시도 루프

// queryClient.ts
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms)); // 간단 대기 유틸

export const queryClient = {
  // ...
  // 재시도 횟수 인자 추가
  loadQueryData: async <TData>(key, queryFn, staleTime, retryCount) => {
    // ...
    if (snapshot.data == null || isStale) {
      let attempt = 0;

      // 실패 시 sleep(1000) 후 다시 시도
      while (attempt < retryCount) {
        try {
          await queryClient.fetchQuery(key, queryFn);
          return; // 성공하면 종료
        } catch {
          await sleep(1000);
          attempt++;
        }
      }

      // (선택) 마지막 한 번 더 시도하고 싶다면 아래 한 줄:
      // await queryClient.fetchQuery(key, queryFn);
    }
  },
};

3) 실패를 위로 올려주기: fetchQuery에서 rethrow

// queryClient.ts
fetchQuery: async <TData>(key: string, queryFn: () => Promise<TData>) => {
  queryClient.patchQuery<TData>(key, { isLoading: true, isError: false });
  try {
    const result = await queryFn();
    queryClient.patchQuery(key, {
      data: result,
      isLoading: false,
      isError: false,
      updatedAt: Date.now(),
    });
  } catch (e) {
    queryClient.patchQuery<TData>(key, { isLoading: false, isError: true });
    // 실패를 상위(loadQueryData)로 전달해 재시도 루프가 감지하도록
    throw (e instanceof Error ? e : new Error(String(e)));
  }
},

requestCoalescing

[변경 로직]

1. inFlightFetchFns로 진행 중 요청을 키별로 기록
2. fetchQuery 내에 try/await → then–catch–finally 체인으로 변경
3. 같은 키로 들어오는 후속 호출은 기존 Promise를 그대로 반환하여 중복 요청 방지

1) in-flight 맵 추가 + 첫 호출/후속 호출 분기

// queryClient.ts
const createQueryClient = () => {
  const inFlightFetchFns = new Map<string, Promise<void>>(); // in-flight 기록

  return {
    async fetchQuery<TData>(key: string, queryFn: () => Promise<TData>) {
      // 이미 요청 중이면 해당 Promise를 반환
      if (inFlightFetchFns.has(key)) {
        return inFlightFetchFns.get(key); // request coalescing 핵심
      }

      // ...

      // 동기 예외도 Promise 거부로 표준화
      const fetchPromise = Promise.resolve()
        .then(() => queryFn())
        .then((result) => {
          queryClient.patchQuery(key, {
            data: result,
            isLoading: false,
            isError: false,
            updatedAt: Date.now(),
          });
        })
        .catch((error) => {
          queryClient.patchQuery(key, { isLoading: false, isError: true });
          throw (error instanceof Error ? error : new Error(String(error)));
        })
        .finally(() => {
          inFlightFetchFns.delete(key); // 완료 시 정리
        });

      inFlightFetchFns.set(key, fetchPromise);

      return fetchPromise; // ← 첫 호출도 Promise 반환
    },
  };
};

export const queryClient = createQueryClient();

전체 코드 보러가기

👉 전체 코드 보기 (GitHub)

마치며

처음에는 단순히 데이터를 캐싱하는 기능만 있어도 충분하다고 생각했지만, 실제로 구현을 이어가다 보니 운영 환경에서 필요한 정책들이 훨씬 많다는 걸 깨달았다. 이번 글에서는 그 빈틈을 메우는 네 가지 기능을 구현하며 시스템이 점점 '진짜' 쿼리 라이브러리답게 다듬어지는 과정을 공유했다.

다음 글에서는 이 기반 위에서 조금 더 실전적인 패턴과 최적화 포인트들을 탐구해 볼 예정이다.

지난 1편에서는 TanStack Query를 직접 구현하게 된 배경을 정리했다. 이번 글에서는 주요 기능을 직접 구현하면서, 내부 구조가 어떻게 구성되어 있는지도 함께 살펴보려고 한다.

이번 글에서 구현할 주요 기능

• useQuery
  • Data fetching: isLoading, isError, data 제공
  • Query Key 기반 데이터 캐싱
  • useSyncExternalStore를 이용한 자동 리패칭
• useMutation: 데이터를 생성, 수정, 삭제하는 등의 작업에 사용되는 훅
  • 리패칭 대상 지정 가능
  • onSuccess / onErro 콜백

핵심 개념 먼저 짚고 가기

먼저 구현할 기능들에 대한 개념과 사용법에 대해서 간단히 알아보고 넘어가자.

useQuery

사용 방법

const { data, isLoading, isError } = useQuery({ queryKey, queryFn })

Parameter (Options)

• queryKey
  • 쿼리를 고유하게 식별하기 위한 값이다.
  • 배열 형태로 지정한다.
  • 이 키가 변경되면 쿼리가 자동으로 업데이트된다.
• queryFn
  • 데이터를 가져오는 비동기 함수이다.
  • 꼭 데이터를 반환하거나 오류를 던져야한다.

Returns

• data: 성공적으로 가져온 데이터
• isLoading: 데이터 가져오기가 진행 중인지 여부
• isError: 쿼리 함수에서의 오류 발생 여부

useMutation

사용 방법

const { mutate } = useMutation({ mutationFn, onSuccess, onError })

Parameter (Options)

• mutationFn
  • queryFn와 같은 비동기 함수로, 실행할 비동기 변이 함수이다.
• onSuccess
  • 변이가 성공할 때 호출되는 함수이다.
• onError
  • 변이 중 오류가 발생할 때 호출되는 함수이다.

Returns

• mutate: 변이 실행 함수

useSyncExternalStore

사용 방법

const snapshot = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?)

Parameter

• subscribe
  • 하나의 callback 인자 함수를 받아 외부 상태 저장소(store)에 구독하는 함수이다.
  • store가 변경될 때, 제공된 callback이 호출되어 React는 getSnapshot을 다시 실행해 컴포넌트를 리렌더링한다.
  • 반드시 구독 해제 함수를 반환해야 한다. (useEffect의 clean-up 함수처럼 동작함)
• getSnapshot
  • 컴포넌트에 필요한 store 데이터의 스냅샷을 반환하는 함수이다.
  • 저장소가 변경되어 반환된 값이 다르면 (Object.is와 비교하여) React는 컴포넌트를 리렌더링한다.
• getServerSnapshot(optional)
  • store에 있는 데이터의 초기 스냅샷을 반환하는 함수이다.
  • 서버 렌더링 도중과 클라이언트에서 서버 렌더링 된 콘텐츠의 하이드레이션 중에만 사용된다.

Return

• 렌더링 로직에 사용할 수 있는 store의 현재 스냅샷.

💡 useSyncExternalStore가 왜 필요할까?

useSyncExternalStore는 React 18에서 도입된 훅으로, 외부 상태 저장소(store)를 리액트 컴포넌트와 동기화하는 데 사용된다.

export function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(navigator.onLine);

  const update = useCallback(() => {
    setIsOnline(navigator.onLine);
  }, [])

  useEffect(() => {
    window.addEventListener('online', update);
    window.addEventListener('offline', update);

    return () => {
      window.removeEventListener('online', update);
      window.removeEventListener('offline', update);
    }
  }, [update])

  return isOnline;
}

공식 홈페이지 예시 코드를 useSyncExternalStore 없이 구현한 코드이다. 위 코드를 보면 React 외부 상태 저장소를 useState, useEffect를 활용하여 충분히 동기화하고 있는 것 같아 보인다.

하지만 이 접근 방식에는 중요한 문제점이 있다. useState와 useEffect 사이의 타이밍 차이 때문에, 초기 렌더링 직전 또는 직후 외부 상태가 변경되면 해당 변경을 놓칠 수 있다. 이처럼 React의 렌더링 상태와 외부 상태 간에 불일치가 발생하는 현상을 Tearing이라고 한다.

useSyncExternalStore는 이러한 문제를 해결하며, 외부 저장소와의 동기화를 정확하고 예측 가능하게 만들어준다.

외부 저장소(QueryStore) 구현

데이터(Query) 및 저장소 구조

• Query: useQuery에서 반환되는 data, isLoading, isError 값을 하나의 객체로 묶은 타입이다.
• store: useQuery에 인자로 넣어주는 queryKey를 기준으로 데이터를 저장, 수정, 삭제하는 저장소이다.
  • 이러한 작업을 효율적으로 처리하기 위해, 내부적으로 Map 자료구조를 사용했다.

type Query<TData> = { data: TData; isLoading: boolean; isError: boolean };

const store = new Map<string, Query<unknown>>();

내부적으로는 단순한 Map 객체 하나로 전체 캐시 저장소가 구성된다. 처음 봤을 때는 이 구조가 의외로 단순해서 놀라웠다.

subscribe 함수

• subscribe는 useSyncExternalStore의 첫 번째 인자로 전달되는 함수로, 외부 저장소에 특정 queryKey를 기준으로 컴포넌트를 구독하게 해준다.
• 내부적으로는 Record<string, Set<Listener>> 구조를 사용하여, queryKey마다 여러 컴포넌트가 구독될 수 있도록 한다.
• 콜백 등록 시 중복 방지를 위해 Set을 활용하였다.
• 구독 해제하는 clean-up 함수를 반환한다.

type Listener = () => void;

const listeners: Record<string, Set<Listener>> = {};

export function subscribe(key: string, callback: Listener) {
  if (!listeners[key]) {
    listeners[key] = new Set();
  }

  listeners[key].add(callback);

  // cleanup function 반환
  return () => {
    listeners[key]?.delete(callback);
  };
}

getSnapshot 함수

• getSnapshot은 현재 queryKey에 해당하는 데이터를 저장소에서 가져오는 함수다.
• 이 값은 useSyncExternalStore가 컴포넌트를 리렌더링할지 결정하는 기준이 된다.
• 값이 존재하지 않으면, 초기값(isLoading: true)을 직접 삽입한 후 반환한다.

export function getSnapshot<TData>(key: string) {
  if (!store.get(key))
    store.set(key, { data: null, isLoading: true, isError: false });

  return store.get(key) as Query<TData>;
}

외부 저장소에 저장된 데이터 update 함수

• 데이터를 패칭하는 과정에서 변경되는 data, isLoading, isError 값을 갱신해주는 함수이다.
• store에 새로운 값을 저장하고, 구독된 콜백 함수를 모두 실행한다.

export function updateQuery<TData>(key: string, newValue: Query<TData>) {
  store.set(key, newValue);

  // 해당 key에 연결된 listener만 실행
  listeners[key]?.forEach((callback) => callback());
}

💡 listeners에 등록된 callback은 무슨 함수일까?

function subscribeToStore(fiber, inst, subscribe) {
  return subscribe(function () {
    checkIfSnapshotChanged(inst) && forceStoreRerender(fiber);
  });
}

위 코드는 React 내부 코드에서 subscribe 함수를 반환하는 코드를 가져온 것이다.

간단히 함수 이름만 봤을 때, callback 함수의 역할은 다음과 같다.

1. snapshot이 변경되었는지 확인
2. 변경이 감지되면 해당 컴포넌트(fiber)를 리렌더링

즉, subscribe 함수에서 인자로 넣어주는 callback 함수는 store의 변경을 감지해 리렌더링을 일으키는 함수이다.

결국 updateQuery의 내부 로직은 store의 데이터를 바꾸는 순간, → subscribe에서 등록된 콜백 실행 → snapshot이 변경됐는지 확인 후, 필요한 컴포넌트만 리렌더링하는 것이다.

QueryStore 전체 코드

// QueryStore.ts

type Query<TData> = { data: TData; isLoading: boolean; isError: boolean };
type Listener = () => void;

const store = new Map<string, Query<unknown>>();
const listeners: Record<string, Set<Listener>> = {};

export function subscribe(key: string, callback: Listener) {
  if (!listeners[key]) {
    listeners[key] = new Set();
  }

  listeners[key].add(callback);

  return () => {
    listeners[key]?.delete(callback);
  };
}

export function getSnapshot<TData>(key: string) {
  if (!store.get(key))
    store.set(key, { data: null, isLoading: true, isError: false });

  return store.get(key) as Query<TData>;
}

export function updateQuery<TData>(key: string, newValue: Query<TData>) {
  store.set(key, newValue);

  listeners[key]?.forEach((callback) => callback());
}

👉 여기까지 구현한 subscribe, getSnapshot, updateQuery는 모두 useSyncExternalStore에서 동기화를 위한 핵심 도구이다.

useQuery 훅 구현

useQuery Parameters

• 실제 TanStack Query에서는 queryKey를 배열로 관리한다.
• 이는 동일한 쿼리라도 다양한 파라미터 조합을 다룰 수 있도록 하기 위함이다.
• 하지만 이 글에서는 기초적인 구조를 먼저 구현하는 데 집중하기 위해 문자열(string) 형태로 단순화했다.

interface UseQueryOptions<TData> {
  queryKey: string;
  queryFn: () => Promise<TData>;
}

useSyncExternalStore로 외부 저장소 동기화

const snapshot = useSyncExternalStore(
  (onStoreChange) => subscribe(queryKey, onStoreChange),
  () => getSnapshot<TData>(queryKey)
);

snapshot이 없을 때 queryFn 실행

useEffect(() => {
  const fetchQueryData = async () => {
    try {
      const result = await queryFn();
      updateQuery(queryKey, {
        data: result,
        isLoading: false,
        isError: false,
      });
    } catch {
      updateQuery(queryKey, {
        data: null,
        isLoading: false,
        isError: true,
      });
    }
  };

  if (!snapshot?.data) {
    fetchQueryData();
  }
}, [queryKey, snapshot, queryFn]);

useQuery 전체 코드

// useQuery.ts

interface UseQueryOptions<TData> {
  queryKey: string;
  queryFn: () => Promise<TData>;
}

export const useQuery = <TData>({
  queryKey,
  queryFn,
}: UseQueryOptions<TData>) => {
  const snapshot = useSyncExternalStore(
    (onStoreChange) => subscribe(queryKey, onStoreChange),
    () => getSnapshot<TData>(queryKey)
  );

  useEffect(() => {
    const fetchQueryData = async () => {
      try {
        const result = await queryFn();
        updateQuery(queryKey, {
          data: result,
          isLoading: false,
          isError: false,
        });
      } catch {
        updateQuery(queryKey, {
          data: null,
          isLoading: false,
          isError: true,
        });
      }
    };

    if (!snapshot?.data) {
      fetchQueryData();
    }
  }, [queryKey, snapshot, queryFn]);

  return snapshot;
};

useQuery 흐름도

1. useSyncExternalStore로 구독을 시작한다.
2. getSnapshot을 통해 외부 저장소에서 queryKey에 해당하는 데이터를 가져온다.
3. 가져온 snapshot을 반환한다. → 데이터가 있을 수도, 없을 수도 있다.
4. snapshot?.data가 없을 경우, useEffect에서 fetchQueryData 함수를 실행한다.
5. queryFn 실행 결과에 따라 updateQuery로 상태를 저장하고,
6. 해당 queryKey를 구독 중인 컴포넌트들이 리렌더링된다.

useMutation 훅 구현

useMutation Parameters

• TVariable: mutation 함수에 전달할 인자의 타입
• TData: mutation 결과로 반환될 데이터의 타입

interface UseMutationOptions<TVariable, TData> {
  mutationFn: (variables: TVariable) => Promise<TData>;
  onSuccess?: (result: TData) => void;
  onError?: () => void;
}

mutate 함수

const mutate = useCallback(
  async (variables: TVariable) => {
    try {
      const result = await mutationFn(variables);
      // 요청 성공 시 onSuccess 콜백 실행 (있을 경우)
      onSuccess?.(result);

      return result;
    } catch (error) {
      // 요청 실패 시 onError 콜백 실행 (있을 경우)
      onError?.();

      throw error;
    }
  },
  [mutationFn, onSuccess, onError]
);

useMutation 전체 코드

// useMutation.ts

interface UseMutationOptions<TVariable, TData> {
  mutationFn: (variables: TVariable) => Promise<TData>;
  onSuccess?: (result: TData) => void;
  onError?: () => void;
}

export function useMutation<TVariable, TData>({
  mutationFn,
  onSuccess,
  onError,
}: UseMutationOptions<TVariable, TData>) {
  const mutate = useCallback(
    async (variables: TVariable) => {
      try {
        const result = await mutationFn(variables);
        onSuccess?.(result);

        return result;
      } catch (error) {
        onError?.();

        throw error;
      }
    },
    [mutationFn, onSuccess, onError]
  );

  return { mutate };
}

+ 리팩토링

useQuery에 있는 useEffect를 없애기

• 기존 코드의 useEffect는 의존성 배열에 있는 queryKey, snapshot, queryFn 값들이 변경되면 실행된다.
• useSyncExternalStore의 첫 번째 인자로 넣은 subscribe 함수는 리렌더링이 될 때마다 호출된다.
• subscribe함수에 useCallback을 감싸면 특정 값이 변경될 때만 다시 구독하도록 가능하다.

export const useQuery = <TData>({
  queryKey,
  queryFn,
}: UseQueryOptions<TData>) => {
  const snapshot = useSyncExternalStore(
    useCallback(
      (onStoreChange) => {
        const unsubscribe = subscribe(queryKey, onStoreChange);

        const fetchQueryData = async () => {
          try {
            const result = await queryFn();
            updateQuery(queryKey, {
              data: result,
              isLoading: false,
              isError: false,
            });
          } catch {
            updateQuery(queryKey, {
              data: null,
              isLoading: false,
              isError: true,
            });
          }
        };

        const snapshot = getSnapshot<TData>(queryKey);

        if (!snapshot?.data) {
          fetchQueryData();
        }

        return unsubscribe;
      },
      [queryKey, queryFn]
    ),
    () => getSnapshot<TData>(queryKey)
  );

  return snapshot;
};

fetchQueryData 함수 분리

• fetchQueryData 함수가 구독할 때마다 새로 생성되는 것을 방지하기 위해 외부로 분리한다.
• 데이터 패칭과 상태 구독의 책임을 분리하여 useQuery 내부의 가독성을 높인다.
• 데이터 요청 로직을 외부 함수로 분리하여 테스트와 재사용이 용이해진다.

export const useQuery = <TData>({
  queryKey,
  queryFn,
}: UseQueryOptions<TData>) => {
  const snapshot = useSyncExternalStore(
    useCallback(
      (onStoreChange) => {
        const unsubscribe = subscribe(queryKey, onStoreChange);
        loadQueryData(queryKey, queryFn);
        return unsubscribe;
      },
      [queryKey, queryFn]
    ),
    () => getSnapshot<TData>(queryKey)
  );

  return snapshot;
};

export async function loadQueryData<TData>(
  key: string,
  queryFn: () => Promise<TData>
) {
  const snapshot = getSnapshot(key);
  if (snapshot.data) return;

  await fetchAndUpdateQueryData(key, queryFn);
}

async function fetchAndUpdateQueryData<TData>(
  key: string,
  queryFn: () => Promise<TData>
) {
  try {
    const result = await queryFn();
    updateQuery(key, {
      data: result,
      isLoading: false,
      isError: false,
    });
  } catch {
    updateQuery(key, {
      data: null,
      isLoading: false,
      isError: true,
    });
  }
}

💡 useEffect 안에 있던 로직을 subscribe의 인자로 전달되는 함수 내부로 옮겨도 괜찮을까?

// react/packages/use-sync-external-store/src/useSyncExternalStoreShimClient.js

useEffect(() => {
  // Check for changes right before subscribing. Subsequent changes will > be
  // detected in the subscription handler.
  if (checkIfSnapshotChanged(inst)) {
    // Force a re-render.
    forceUpdate({inst});
     }
  const handleStoreChange = () => {
    // TODO: Because there is no cross-renderer API for batching updates, it's
    // up to the consumer of this library to wrap their subscription event
    // with unstable_batchedUpdates. Should we try to detect when this isn't
    // the case and print a warning in development?
    // The store changed. Check if the snapshot changed since the last time we
    // read from the store.
    if (checkIfSnapshotChanged(inst)) {
      // Force a re-render.
      forceUpdate({inst});
    }
  };
  // Subscribe to the store and return a clean-up function.
  return subscribe(handleStoreChange);
}, [subscribe]);

• useSyncExternalStore 내부 구현 코드를 보면, 실제로 subscribe 함수는 useEffect 안에서 실행된다.
• 즉, subscribe 함수 내부에서 side effect를 수행하는 것은 React의 사용 규칙에 어긋나지 않는다.
• useEffect와 동일한 타이밍에 실행되므로, 데이터를 요청하는 로직을 subscribe 내부에 넣어도 부작용 없이 동작한다.

마치며

이번 글에서는 TanStack Query의 핵심 기능인 useQuery와 useMutation을 직접 구현해보며, React의 외부 상태와 동기화하는 방식(useSyncExternalStore)까지 함께 살펴보았다.

다음 글에서는 staleTime, gcTime, refetch 등의 고급 캐싱 전략과 Request Coalescing 등 실제 라이브러리 수준에서 필요한 기능들을 구현해볼 예정이다.

이 글에서는 TanStack Query를 직접 구현하게 된 배경과 그 과정에서 얻게 된 인사이트를 공유한다.

우아한테크코스에서 라이브러리 없이 미션을 수행하면서, 라이브러리를 사용하지 않았을 때의 불편함을 절실히 느꼈다. 이 경험을 통해, 라이브러리는 이러한 불편함을 어떻게 해결해주는지에 관심이 생겼고, 라이브러리를 하나씩 뜯어보는 과정에서 흥미를 느끼기 시작했다.

데이터 패칭 훅을 만들어보면서 이것을 전역적으로 관리하고 싶다는 생각이 들었고, TanStack Query를 직접 구현해봐야겠다는 생각이 들었다. 처음부터 쉽지 않은 라이브러리를 선택한 건 아닌가 하는 생각도 들었지만, 구현을 하면서 새롭게 알게 된 점들이 많았고, 이러한 지식을 정리하고 공유해보고자 한다.

데이터 캐싱에 대한 호기심

TanStack Query (formerly known as React Query) is often described as the missing data-fetching library for web applications, but in more technical terms, it makes fetching, caching, synchronizing and updating server state in your web applications a breeze.

TanStack Query의 공식 홈페이지 소개 글에서 caching이란 단어가 눈에 들어왔다.

"캐싱은 어떻게 구현하는 걸까?"라는 호기심이 생겼다. 캐싱이란 '데이터를 어딘가에 저장해 두었다가 필요할 때 다시 사용하는 것'이라고 알고 있었지만, 구체적으로 어떤 방식으로, 어디에 저장하는지가 궁금해졌다. 이를 계기로 TanStack Query의 내부 코드를 들여다보기 시작했다.

그 결과, 캐싱이 자바스크립트 객체에 데이터를 저장하는 단순한 방식이라는 사실을 알게 되었고, 그 단순함에 놀랐다. 하지만 단순 저장만으로 끝나는 것이 아니라, staleTime, gcTime 등의 개념을 통해 캐시를 어떻게 효율적으로 관리할 것인가가 TanStack Query의 핵심이라는 것을 깨달았다.

전역 데이터 저장소의 필요성

서버 데이터를 여러 컴포넌트에서 사용할 경우, 상태를 끌어올리는 일이 반복되었다. 이로 인해 props drilling이 발생하고, 이 현상이 심화되면 Context API를 사용할 수밖에 없었다. 서버에서 가져오는 데이터가 많아질 경우 Provider는 늘어나게 되고, 결국 Provider Hell이 발생할 가능성이 높아보였다. 그래서 Provider 없이도 원하는 위치에서 데이터를 사용할 수 있는 전역 데이터 저장소 구조를 설계하고자 했다.

또한, 서버의 데이터를 mutation(수정/추가/삭제)할 때 변경된 데이터를 다시 불러와야 했다. 하지만 이를 위해 refetch 함수를 최상단 컴포넌트에서 props나 Context를 통해 전달해야 했고, 이 과정이 번거롭고 비효율적이라고 느꼈다. 이러한 불편함을 해소하기 위해, 전역 데이터 저장소 구조를 활용하여 mutation 시 자동으로 refetch 될 대상을 명시하는 방식을 구현하고자 했다.

useSyncExternalStore

전역 상태 관리 라이브러리들은 대부분 useSyncExternalStore를 사용하고 있다.

하지만 처음 useSyncExternalStore를 접했을 때는 그 필요성과 내부 동작 방식이 쉽게 와닿지 않았다. 그래서 이 훅을 직접 사용하여 React 외부 상태와의 안정적인 동기화 방식을 직접 구현해보면서, 그 필요성과 작동 원리를 몸으로 이해하고자 했다.

내가 구현을 결심한 이유

당연한 이야기지만, TanStack Query 내부 코드를 보면서 처음에는 코드 대부분이 낯설게 느껴졌다. 대략적인 동작 원리를 파악하는 데에도 상당한 시간이 걸렸다.

코드를 분석하면서 느낀 점은, 제공하는 기능이 많고 강력하긴 하지만 구현 방식이 복잡하게 느껴졌다는 것이다. 그래서 직접 구현해보면서, TanStack Query가 어떤 의도로 이러한 구조를 선택했는지 그 배경을 이해하고자 했다.

구현 기능 목록

주요 기능

• useQuery
  • Data fetching: isLoading, isError, data 제공
  • Query Key 기반 데이터 캐싱
  • useSyncExternalStore를 이용한 자동 리패칭
• useMutation: 데이터를 생성, 수정, 삭제하는 등의 작업에 사용되는 훅
  • 리패칭 대상 지정 가능
  • onSuccess / onError 콜백

세부 기능

• staleTime: Stale-While-Revalidate (SWR) 전략 구현
• gcTime: Garbage Collection (GC) - 구독이 모두 해제되면 캐시 자동 삭제
• Request Coalescing: 동일한 데이터에 대한 중복 요청 방지
• AbortController 기반 요청 취소 (unmount 시 자동 abort)
• 자동 백그라운드 fetch: 마운트 시 stale 판단 후 자동 fetch
• 리패칭 조건 트리거
  • refetchOnWindowFocus: 브라우저 포커스 시 자동 fetch
  • refetchOnReconnect: 네트워크 재연결 시 자동 fetch
  • refetchInterval: polling 방식 주기적 refetch
• refetch(): 수동 리패칭 메서드 제공
• retry 및 retryDelay: fetch 실패 시 자동 재시도
• suspense
• removeQueries, resetQueries로 전체 초기화
• fetch 중단을 위한 수동 cancel API
• useInfiniteQuery (무한 스크롤 / 페이지네이션 지원)

추가로 구현할 기능

• convertFn을 통한 데이터 후처리
• queryKey 관리하기 쉽게 하는 유틸함수