<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Nayounsang on Medium]]></title>
        <description><![CDATA[Stories by Nayounsang on Medium]]></description>
        <link>https://medium.com/@nayounsang722?source=rss-c7562bbf0193------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*har5D5CXVyMdBcEL0YyxTw.jpeg</url>
            <title>Stories by Nayounsang on Medium</title>
            <link>https://medium.com/@nayounsang722?source=rss-c7562bbf0193------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 07:44:05 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@nayounsang722/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Vitest와 Turborepo 프로젝트에서의 테스트 병렬 실행]]></title>
            <link>https://medium.com/@nayounsang722/typescript-%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8%EC%97%90%EC%84%9C%EC%9D%98-%EB%B3%91%EB%A0%AC-%EC%86%8C%ED%94%84%ED%8A%B8%EC%9B%A8%EC%96%B4-%ED%85%8C%EC%8A%A4%ED%8A%B8-cc7152c4b68e?source=rss-c7562bbf0193------2</link>
            <guid isPermaLink="false">https://medium.com/p/cc7152c4b68e</guid>
            <category><![CDATA[vitest]]></category>
            <category><![CDATA[software-testing]]></category>
            <category><![CDATA[ci-cd-pipeline]]></category>
            <category><![CDATA[turborepo]]></category>
            <dc:creator><![CDATA[Nayounsang]]></dc:creator>
            <pubDate>Thu, 22 Oct 2026 15:53:21 GMT</pubDate>
            <atom:updated>2026-10-22T16:47:19.451Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>병렬(Parallel)과 동시(Concurrency)는 다른 용어지만, <strong>편의상 병렬로 기술하겠다.</strong> 기술스택 역시 vitest, turborepo를 상정하고 작성한다. 테스트를 돌리면 발생하는 일</blockquote><pre>import { test, expect } from &quot;vitest&quot;;<br><br>test(&quot;addition&quot;, () =&gt; {<br>  const result = 1 + 2;<br>  expect(result).toBe(3);<br>});</pre><p>이런 테스트를 vitest run 한다면 무슨일이 발생할까?</p><p>동작하는 흐름을 보자면</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JJpYwYkSSDnZrAVU4QvtUQ.png" /><figcaption>*Worker는 설정에 따라 Thread가 될 수 있다.</figcaption></figure><ol><li>Vitest 초기화(설정, global setup, 테스트 파일 탐색 등)</li><li>Node.js Child Process(Worker) 생성</li><li>Worker가 테스트 파일 로딩(Setup File, 테스트 모듈, 의존성등)</li><li>Test Runner가 테스트 수집(describe 평가, test 등록, hook 등록)</li><li>Test Runner로 테스트 실행(V8 엔진이 hook, test callback 실행)해 결과 판정</li><li>결과 수집 후 보고</li></ol><p>이러한 초기화와 실행 과정에는 비용이 발생한다. 또한 각각의 테스트를 순차 실행한다면 많은 시간이 소요될 것이다. Vitest는 전체 테스트 수행 시간을 단축하기 위한 테크닉을 제공한다.</p><h3>Vitest의 테스트 병렬 구동</h3><h4>다중 Worker</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/680/1*BYN3bXNWMFqYI1uCJAXGiQ.png" /></figure><p>각 Worker는 테스트를 실행할 격리된 환경을 제공하는 child proccess고 한 테스트 파일은 하나의 Worker에 속한다.</p><p>따라서, Worker를 여러개 띄워 테스트파일간 병렬 처리를 한다.</p><pre>export default defineConfig({<br>  test: {<br>    maxWorkers: 2,<br>    fileParallelism: true,<br>  },<br>});</pre><p>maxWorkers와 fileParallelism(default는 true고 false는 maxWorkers : 1로 override)로 설정할 수 있다.</p><h4>Worker내 비동기 테스트 동시 실행</h4><p>test.concurrent()나 describe.concurrent()로 활성화한다.</p><pre>import { test, expect } from &quot;vitest&quot;;<br><br>const sleep = (ms: number) =&gt;<br>  new Promise((resolve) =&gt; setTimeout(resolve, ms));<br><br>test.concurrent(&quot;A&quot;, async () =&gt; {<br>  await sleep(1000);<br>  expect(1).toBe(1);<br>});<br><br>test.concurrent(&quot;B&quot;, async () =&gt; {<br>  await sleep(1000);<br>  expect(2).toBe(2);<br>});<br><br>test.concurrent(&quot;C&quot;, async () =&gt; {<br>  await sleep(1000);<br>  expect(3).toBe(3);<br>});</pre><p>이 테스트파일은 순차 실행한다면 3초 가량이 필요하지만 concurrent로 1초 가량에 완료된다. 이는 concurrent로 선언한 테스트묶음을 Promise.all로 구동하는 것이다. 따라서 CPU Bound한 동기연산은 동시 실행되지 않는다.</p><pre>// 이건 아마 실패할 것이다.<br>let counter = 0;<br><br>async function increment() {<br>  const previous = counter;<br><br>  await sleep(100);<br><br>  counter++;<br>  expect(counter).toBe(previous + 1);<br>}<br><br>test.concurrent(&quot;A&quot;, increment);<br>test.concurrent(&quot;B&quot;, increment);</pre><p>concurrent는 공유 mock 상태, 전역 변수, 훅, 파일 시스템, 외부 DB에 대한 RaceCondition을 고려해야한다. 따라서 독립성이 보장된 테스트에만 활성화해야 한다.</p><pre>export default defineConfig({<br>  test: {<br>    maxConcurrency: 3,<br>  },<br>});</pre><p>maxConcurrency로 동시에 실행할 테스트와 hook을 설정할 수 있다. 기본값은 5다.</p><h3>모노레포에서의 병렬 테스트</h3><p>turbo repo와 같은 모노레포 관리 시스템은 패키지 의존관계에 따라DAG(Directed Acyclic Graph, 방향성 비순환 그래프)형태의 task graph를 만든다. 이후 태스크 간 선행 관계와 동시 실행 한도를 고려하여 실행 가능한 태스크들을 병렬로 실행한다. 그렇게, 각각의 task를 실행하기 위한 OS Child Process를 만든다.</p><p>기본적으로 Turborepo task의 기본 동시 실행 한도는 10이며 concurrency 옵션으로 제한 가능하다.</p><p>test를 turbo task로 등록했다. 그럼 어떻게 테스트가 구동될까? 각 패키지의 test 태스크는 별도의 Vitest 인스턴스를 실행하고, 각 Vitest는 자체 Worker Pool을 관리한다.</p><p>만약에, turbo의 test task가 최대 x개 동시 실행되고 각 패키지별 test는 maxWorker가 y라고 하자. 그럼, 실행되는 Worker는 최대 x*y개가 될 수 있다.</p><p>Turborepo의 또 다른 장점은 태스크 결과를 캐싱할 수 있다는 점이다. 태스크의 입력과 설정 등을 기반으로 캐시가 적중하면 해당 태스크를 다시 실행하지 않아도 되므로 실행 시간과 자원을 절약할 수 있다.</p><h3>발생할 수 있는 문제</h3><p>여기서, turbo task와 worker는 한 머신에서 구동된다는 것이며, 머신은 리소스의 제한이 존재한다는 것이다.</p><p>테스트를 최대한 병렬로 돌린다면 그만큼 시간 이득을 볼 것 같으나, 실제론 아니다. 병렬 실행 환경에서의 테스트는 간혈적으로 test timeout error가 발생한다.</p><p>원인은 이런 것들이 있다.</p><ul><li>CPU 경합, 메모리 압박, 과도한 I/O 등에 따른 실행 지연</li><li>테스트 간 공유 자원 충돌, DB connection pool 고갈, 외부 서비스의 요청 제한</li><li>실제로 느린 테스트 로직이나 비정상적으로 오래 걸리는 비동기 작업</li></ul><p>게다가 이런 상황에 놓인 경우 테스트 자체도 기대보다 오래 걸린다. 이것은 CI도 문제지만 로컬 개발시에도 버벅이고 AI Agent 역시 이런 작업을 돌리는 것을 기피한다는 것이다.</p><p>이것을 해결 하기 위해선 “어떤 테스트가 왜 실패하는가? 그 테스트는 어떻게 돌아가는 테스트인가?”를 파악한다. 자원 경합이 원인이라면 머신 성능에 맞게 태스크 및 Worker 동시 실행 수를 제한하고, 공유 자원 충돌이라면 테스트 격리나 실행 순서를 조정할 수 있다. 정상적으로 오래 걸리는 테스트에 대해서는 timeout 설정을 조정할 수도 있다.</p><p>실제 문제 해결은 <a href="https://medium.com/@nayounsang722/%EB%AA%A8%EB%85%B8%EB%A0%88%ED%8F%AC%EC%97%90%EC%84%9C-%ED%85%8C%EC%8A%A4%ED%8A%B8-%EA%B4%80%EB%A6%AC%ED%95%98%EA%B8%B0-dc202f69a634">대규모 모노레포에서 test를 turbo task로 등록한 사례를</a> 통해 확인 가능하다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=cc7152c4b68e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[모노레포에서 테스트 관리하기]]></title>
            <link>https://medium.com/@nayounsang722/%EB%AA%A8%EB%85%B8%EB%A0%88%ED%8F%AC%EC%97%90%EC%84%9C-%ED%85%8C%EC%8A%A4%ED%8A%B8-%EA%B4%80%EB%A6%AC%ED%95%98%EA%B8%B0-dc202f69a634?source=rss-c7562bbf0193------2</link>
            <guid isPermaLink="false">https://medium.com/p/dc202f69a634</guid>
            <category><![CDATA[airi]]></category>
            <category><![CDATA[software-testing]]></category>
            <category><![CDATA[turborepo]]></category>
            <dc:creator><![CDATA[Nayounsang]]></dc:creator>
            <pubDate>Tue, 20 Oct 2026 09:50:13 GMT</pubDate>
            <atom:updated>2026-10-21T08:32:39.704Z</atom:updated>
            <content:encoded><![CDATA[<p>최근, 나만의 AI 버튜버를 띄울 수 있는 <a href="https://github.com/moeru-ai/airi">AIRI</a>에 기여중입니다. 빠르게 성장하고 있는 turbo repo기반 거대한 모노레포입니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9OfbcdCbTx5JDtoP8M04hg.png" /><figcaption>대충 이런 모노레포입니다. 복잡하지요?</figcaption></figure><p>그만큼 버그도 많이 터지는 상태입니다. 새로운 기능이 자주 나오고, 빠르게 적용되기 때문입니다. 프로젝트의 속도감을 유지하며 버그를 줄일 수 있는 방법 중 하나는 테스트입니다.</p><p>하지만, 이 레포에서 관리되는 테스트에는 결함이 있었습니다.</p><ol><li>CI에서 일부 테스트(전체 테스트 중 약 40%, 2000건 가량)이 누락됐습니다. 따라서 일부 패키지는 검증 대상이 되지 못했으며, 검증 방식에 결함이 있어도 드러나지 않습니다.</li><li>캐싱 되지 않으며, 결국 CI와 로컬 개발에서 부하가 생깁니다. 특히, ai agent로 개발되는 코드베이스에선 테스트로 코드를 검증하는 플로우가 일상적인데, 부하가 큰 테스트는 “오래 걸리니 이상하다. 스킵하겠다”라는 이상한 판단을 내립니다. 직접 돌려도 컴퓨터가 아파합니다. 결국 기본 동작도 검증하지 못한 PR들이 생깁니다.</li></ol><p>제가 잘 사용하는 프로젝트인 만큼 결함이 최소화되고, 기능도 안정적으로 추가되면 좋겠으나 어려운 상황이었습니다.</p><h3>왜 이런 문제가 있었나?</h3><p>지금까지, AIRI의 테스트는 root vitest config와 root package.json에서 직접 패키지를 지정하는 방식이었습니다.</p><pre>import { defineConfig } from &#39;vitest/config&#39;<br><br>import { providerInferenceProjects } from &#39;./packages/provider-inference/vitest.config&#39;<br><br>export default defineConfig({<br>  test: {<br>    projects: [<br>      &#39;server/apps/auth&#39;,<br>      &#39;server/apps/api&#39;,<br>      &#39;server/packages/http-error-shared&#39;,<br>      &#39;apps/ui-server-auth&#39;,<br>      &#39;apps/stage-tamagotchi/vitest.node.config.ts&#39;,<br>      &#39;packages/agents&#39;,<br>      &#39;packages/cap-vite&#39;,<br>      &#39;packages/ccc&#39;,<br>      &#39;packages/core-agent&#39;,<br>      &#39;packages/i18n&#39;,<br>      &#39;packages/pipelines-audio&#39;,<br>      &#39;packages/input-gamepad&#39;,<br>      &#39;packages/input-gamepad-vueuse&#39;,<br>      &#39;packages/input-playstation-dualsense-5&#39;,<br>      &#39;packages/model-driver-lipsync&#39;,<br>      &#39;packages/better-ws&#39;,<br>      &#39;packages/plugin-sdk&#39;,<br>      &#39;packages/plugin-sdk-tamagotchi&#39;,<br>      ...providerInferenceProjects.map(project =&gt; ({ ...project, root: &#39;packages/provider-inference&#39; })),<br>      &#39;packages/scenarios-stage-tamagotchi-browser&#39;,<br>      &#39;packages/scenarios-stage-tamagotchi-electron&#39;,<br>      &#39;packages/server-runtime&#39;,<br>      &#39;packages/server-sdk&#39;,<br>      &#39;packages/stage-shared&#39;,<br>      &#39;packages/stage-ui-live2d/vitest.node.config.ts&#39;,<br>      &#39;packages/stage-ui-three&#39;,<br>      &#39;packages/stream-kit&#39;,<br>      &#39;packages/vitest-plugin-fakemic&#39;,<br>      &#39;packages/vite-plugin-sherpaw&#39;,<br>      // Scripts that GitHub Actions run. They belong to no package.<br>      {<br>        test: {<br>          name: &#39;github-scripts&#39;,<br>          include: [&#39;.github/scripts/**/*.test.ts&#39;],<br>        },<br>      },<br>    ],<br>  },<br>})</pre><pre>    &quot;test:run&quot;: &quot;vitest run &amp;&amp; pnpm run test-stage-tamagotchi:run &amp;&amp; pnpm run test-stage-web:run &amp;&amp; pnpm run test-stage-pages:run &amp;&amp; pnpm run test-ui:run &amp;&amp; pnpm run test-stage-ui-live2d:run&quot;,</pre><p>이상합니다. 패키지내에서 test:run으로 돌리는 것도 있고, root vitest config를 통해 테스트를 돌리기도 합니다. 누락되거나 잘못된게 나올 수 밖에 없는 구조군요. 그리고, 일부 패키지 테스트는 의존 패키지가 build된 상태여야하므로 잘못된 환경에서 테스트를 돌릴수도 있겠군요. 이어서 CI도 보겠습니다.</p><pre>  unit-test:<br>    name: Unit Test<br>    runs-on: ubuntu-latest<br>    steps:<br>      - uses: actions/checkout@v6<br><br>      # Turborepo<br>      - name: Cache turbo build setup<br>        uses: actions/cache@v5<br>        with:<br>          path: .turbo<br>          key: ${{ runner.os }}-turbo-${{ github.sha }}<br>          restore-keys: |<br>            ${{ runner.os }}-turbo-<br><br>      - uses: pnpm/setup@v2<br>        with:<br>          runtime: node@26.7.0<br>          cache: true<br>          install: false<br><br>      # # Setup .NET and Godot<br>      # - name: Setup .NET<br>      #   if: matrix.app_name == &#39;stage-tamagotchi-godot&#39;<br>      #   uses: actions/setup-dotnet@v4<br>      #   with:<br>      #     dotnet-version: &#39;10.0.x&#39;<br><br>      # - name: Setup Godot<br>      #   if: matrix.app_name == &#39;stage-tamagotchi-godot&#39;<br>      #   uses: chickensoft-games/setup-godot@v2<br>      #   with:<br>      #     version: 4.7.1<br>      #     use-dotnet: true<br>      #     include-templates: true<br><br>      - run: pnpm install --frozen-lockfile<br><br>      - name: Setup Playwright<br>        run: npx playwright install chromium<br><br>      - run: pnpm run build:packages<br>      - run: pnpm run test:run<br>        env:<br>          NODE_OPTIONS: --no-experimental-webstorage</pre><p>이 이상함은 CI까지 전파됩니다. 다행히, build는 turbo task고 캐싱을 하는군요.</p><p>따라서, 패키지에서 테스트 돌리는 방식을 일원화하고 이를 turbo task로 마이그레이션 합시다.</p><h3>해결하기</h3><p>가장 간단하게, root vitest config에서 projects에 정의된 패키지들을 모두 지워버립시다. github script는 <em>They belong to no package. </em>이므로 남겨둡시다<em>.</em></p><pre>import { defineConfig } from &#39;vitest/config&#39;<br><br>export default defineConfig({<br>  test: {<br>    projects: [<br>      // Scripts that GitHub Actions run. They belong to no package.<br>      {<br>        test: {<br>          name: &#39;github-scripts&#39;,<br>          include: [&#39;.github/scripts/**/*.test.ts&#39;],<br>        },<br>      },<br>    ],<br>  },<br>})</pre><p>그리고, 해당 패키지들의 package.json에 test:run 스크립트를 추가합니다.</p><pre>    &quot;test:run&quot;: &quot;vitest run --config vitest.config.ts&quot;,</pre><p>이걸 이제 turbo task로 관리하면 됩니다. 우선 일부 테스트는 의존 패키지의 빌드 산출물을 필요로 하므로, ^build를 통해 테스트 전에 의존 패키지의 빌드를 완료하도록 설정합니다.</p><pre>    &quot;test:run&quot;: {<br>      &quot;dependsOn&quot;: [&quot;^build&quot;],<br>      &quot;env&quot;: [&quot;NODE_OPTIONS&quot;],<br>     },</pre><p>그리고 ci에선 test:run과 vitest(github script 전용)을 돌리면 되겠군요. 오 진짜 간단하다. 해치운걸까요?</p><h4>병렬 실행으로 인한 자원 경합</h4><p>turbo task + vitest로 테스트를 돌리면 (옵션을 지정하지 않는 이상) 동시에 돌아갑니다.</p><ul><li>turbo의 concurrency: 패키지간 태스크</li><li>vitest의 fileParallelism : 한 vitest 실행 내 테스트 파일</li><li>vitest의 concurrent: 한 파일 내부의 테스트</li></ul><p>예를들어, Live2D와 VRM rendering이 Chromium GPU 자원을 두고 경쟁하는 상황이 있었습니다.</p><p>그리고 특정 버그 이슈 재현을 위해 VRM을 여러번 랜더링하는 무거운 테스트도 있었습니다.</p><p>이를 해결 하기 위해, 해당 프로젝트에선 테스트 파일에 대한 <a href="https://vitest.dev/config/fileparallelism">동시 실행을</a> 비활성화 하고, 일부 테스트 케이스에 대해선 타임아웃 한도를 늘렸습니다.</p><pre>        test: {<br>          name: &#39;browser&#39;,<br>          // CI model-ready checks time out when these WebGL-heavy test files run in parallel.<br>          // Live2D Polaroid and VRM rendering compete for Chromium GPU resources.<br>          fileParallelism: false,<br>          include: [&#39;src/**/*.browser.test.ts&#39;],<br>          setupFiles: [&#39;./src/test/setup-live2d.browser.ts&#39;],<br>          browser: {<br>            enabled: true,<br>            headless: true,<br>            provider: playwright(),<br>            instances: [<br>              { browser: &#39;chromium&#39; },<br>            ],<br>          },</pre><h4>기존 테스트들의 결함</h4><p>역시, 돌려지지 않는 테스트들에 결함이 존재했습니다. 대부분 사소한 이슈였고 최신 main과 동기화를 했더니 사라진 것도 있습니다. 이젠 CI에서 돌아가므로 이런 문제가 줄겠지요.</p><p>하지만, 결국 수정하기 어려운 이상한 테스트도 있었습니다. 바로 wake word(음성 인식을 활성화 하기 위한 트리거)관련 테스트인데요, 통과할 때도 있으나 높은 빈도로 time out났습니다. 시간 한도를 늘려봐도 해결되지 않았고 원인도 불명확했습니다.</p><pre>    // CI wake word cases time out while preparation stays `preparing`. The root cause is not confirmed.<br>    // Context: audio-web wake word cases time out in the CI Unit Test job.<br>    // Remove this skip after the preparation failure has a verified fix on CI.<br>    if (env.CI &amp;&amp; plan.definition.pipelines?.includes(&#39;kws&#39;))<br>      task.context.skip(true, &#39;Wake word preparation times out on CI. The root cause is not confirmed.&#39;)</pre><p>우선순위는 테스트 케이스 수정보단 이 프로젝트에 turbo task로 test를 관리하는 것이높기 때문에 일단 스킵하고 후속 이슈를 레이징해 해결하기로 했습니다.</p><pre>&quot;test:run&quot;: {<br>      &quot;dependsOn&quot;: [&quot;^build&quot;],<br>      &quot;env&quot;: [&quot;CI&quot;, &quot;NODE_OPTIONS&quot;],<br>     },</pre><p>env.CI에서 분기하므로 turbo에도 반영합니다.</p><h4>테스트 config 파일 정리</h4><p>vitest.*.config.ts(예를들어 vitest.node.ts)가 한 패키지내 여러개 있는 경우가 있었습니다. 기존엔 root vitest config가 이 파일에 직접 프로젝트를 등록했습니다. 이를 패키지내 vitest.config.ts에 통합하고, 환경별 vitest.*.config.ts는 정리했습니다.</p><h4>환경 변수를 활용한 테스트</h4><p>몇몇 테스트는 환경변수 값을 읽어 이에 따라 테스트를 진행합니다.</p><pre>    &quot;test:run&quot;: {<br>      &quot;dependsOn&quot;: [&quot;^build&quot;],<br>      &quot;env&quot;: [&quot;CI&quot;, &quot;NODE_OPTIONS&quot;, &quot;TESTING_AUDIO_*&quot;],<br>      &quot;inputs&quot;: [<br>        &quot;$TURBO_DEFAULT$&quot;,<br>        &quot;$TURBO_ROOT$/.env*&quot;,<br>        &quot;$TURBO_ROOT$/packages/*/.env*&quot; <br>      ]<br>    },</pre><p>테스트가 올바른 값을 사용하도록 하고, env가 바뀌면 캐시를 invalidate해야하므로 필요한 값을 추가합니다.</p><h4>셋업</h4><p>누락된 테스트를 포함했더니 Xvfb(가상 화면을 만드는 서버)와 같은 셋업이 필요했던 것이 드러났습니다. 이를 추가합니다.</p><pre>      - name: Setup Xvfb<br>        run: |<br>          if ! command -v xvfb-run &gt;/dev/null; then<br>            sudo apt-get update<br>            sudo apt-get install --no-install-recommends -y xvfb<br>          fi<br><br>      - run: xvfb-run --auto-servernum --server-args=&quot;-screen 0 1920x1080x24 -nolisten tcp&quot; pnpm run test:run<br>        env:<br>          NODE_OPTIONS: --no-experimental-webstorage </pre><h3>결과</h3><p>직접 fork한 repo에서 github action을 돌려 벤치마크를 측정해봤습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FN7V-Ad_3MEaqvj8tF0lvQ.png" /></figure><p>약 2,000건의 테스트 케이스가 추가로 실행되었음에도 테스트 단계의 실행 시간은 기존과 비슷한 수준이네요. 또한 모든 테스트 태스크가 캐시된 경우에는 사실상 즉시 끝나는군요.</p><p>또한, 영향받는 패키지의 테스트만 돌리고 나머진 캐싱되므로 로컬 개발 경험도 무척이나 좋아집니다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=dc202f69a634" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[여러 시스템이 동시에 파일을 읽고 쓴다면 무엇을 고민해야 할까?]]></title>
            <link>https://medium.com/@nayounsang722/%ED%8C%8C%EC%9D%BC%EC%9D%98-%EC%9D%BD%EA%B3%A0-%EC%93%B0%EA%B8%B0%EB%A5%BC-mutex%EB%A1%9C-%EA%B4%80%EB%A6%AC%ED%95%98%EA%B8%B0-b61b345f99cf?source=rss-c7562bbf0193------2</link>
            <guid isPermaLink="false">https://medium.com/p/b61b345f99cf</guid>
            <category><![CDATA[nodejs]]></category>
            <category><![CDATA[filesystem]]></category>
            <category><![CDATA[concurrency]]></category>
            <dc:creator><![CDATA[Nayounsang]]></dc:creator>
            <pubDate>Sun, 09 Aug 2026 14:28:51 GMT</pubDate>
            <atom:updated>2026-08-09T14:50:02.689Z</atom:updated>
            <content:encoded><![CDATA[<h3>풀어볼 문제</h3><h4>맥락</h4><p><a href="https://msw-dev-tool-docs.vercel.app/docs/get-started">msw-dev-tool</a>란 msw에 의존하는 개발툴 패키지를 운영중이다.</p><p>msw-dev-tool은 브라우저 UI에서 mock 상태를 제어하던 도구였다. Node 환경과 CLI에서도 제어할 수 있도록 확장하면서, 서로 독립된 여러 프로세스가 하나의 상태를 읽고 써야 하는 요구사항이 생겼다.</p><h4>모델링</h4><p>이를 위해 CLI와 Node 프로세스끼리 통신해야한다. 하지만, 직접적으로 CLI가 Node 런타임의 인메모리를 건들 수 없다.</p><p>오픈소스 개발툴은 설정이 최대한 간단해야 하고, 영향 범위 없이 사용 가능해야 한다. 사용자가 모를 수록 좋다.</p><p>따라서, CLI와 Node 프로세스가 통신하기 위한 상태 저장 파일을 만든다. 패키지가 내부에서 알아서 파일을 생성하고 관리한다면, 사용자는 별도 설정을 할 필요가 없다.</p><figure><img alt="node and cli" src="https://cdn-images-1.medium.com/max/1024/1*NS16I_0aKsVxsM1ttwkRlA.png" /></figure><p>하지만 현실은 그림처럼 간단하지 않다. 서버 프로세스는 여러개가 될 수 있다. 따라서, 소비자인 프로세스 별로 파일을 분리해아 한다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*oT43rvEZ3-2NptrKv8NvTw.png" /></figure><p>각 프로세스가 읽는 msw-dev-tool의 상태는 프로세스별로 독립적으로 만들었다. 서로 영향 끼치지 않는다. <br>하지만, CLI는 동시에 여러 명령이 같은 파일에 대해 호출될 수 있다. 따라서, 해결해볼 문제는 다음과 같이 구조화할 수 있다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Gb1L1DLa1GTuA8L4ZF7jxA.png" /></figure><p>write가 누락돼선 안되며, 프로세스는 파일에서 적절한 상태를 읽어 적용해야 한다.</p><h3>안전하게 write하기</h3><p>결국 이는 race condition 문제이다. (언제나 어디서나 튀어나오는 그것)</p><p>이를 해결 하기 위해 mutex에서 모티브를 얻었다.</p><ul><li>하나의 공유 자원에 대한 접근</li><li>하나의 reader, 여러개의 writer</li><li>파일 I/O가 들어가고 언제 끝날지 불확실한 작업</li></ul><p>mutex 개념을 간단화 하자면</p><ol><li>파일에 락을 건다</li><li>읽고 수정을 완료한다.</li><li>락을 해제한다.</li></ol><p>이고, spin lock은 고려하지 않아도 된다. 결국 필요한 것은 lock의 구현이다.</p><h4>lock 구현</h4><p>lock은 <a href="https://www.npmjs.com/package/proper-lockfile?activeTab=readme">proper-lockfile</a>을 활용한다. 이 라이브러리는 mkdir이 원자적으로 동작한다는 점을 이용하는 파일 락 기능을 제공한다.</p><p>이 라이브러리는 대상 파일에 대해 {대상 파일}.lock/ 디렉터리를 만든다.</p><p>두 프로세스가 동시에 lock을 획득하려 해도 한쪽만 디렉터리 생성에 성공하므로 mutual exclusion이 성립한다.</p><pre>const release = lockfile.lockSync(sessionPath);</pre><p>lockSync는 락 해제 함수를 반환한다.</p><p>이 라이브러리는 단순히 락을 만들고 해제하는 것 뿐만 아니라 lock이 살아 있음을 나타내는 heartbeat까지 관리해 abandoned lock 문제를 해결해준다. 단일lock만 사용하므로 deadlock 문제는 고려할 필요 없다.</p><p>단, 잠겨있을 때 다시 시도하는 로직은 직접 구현해야 한다. 프로젝트에선 백오프 반복 방식을 사용했다.</p><pre>// 최대 10번까지 lock 획득 재시도<br>const LOCK_MAX_ATTEMPTS = 10;<br><br>// lock 획득에 실패했을 때 다음 시도까지 얼마나 기다릴지 결정<br>// 50ms -&gt; 500ms까지 매 실패마다 이전보다 1.5배 긴 시간 대기<br>const LOCK_BACKOFF_MS = {<br>  min: 50,<br>  max: 500,<br>  factor: 1.5,<br>} as const;<br><br>// 그냥 전달받은 시간만큼 기다림<br>const sleepSync = (ms: number) =&gt; {<br>  Atomics.wait(<br>    new Int32Array(new SharedArrayBuffer(4)),<br>    0,<br>    0,<br>    ms,<br>  );<br>};<br><br>const acquireLockSync = (sessionPath: string): (() =&gt; void) =&gt; {<br>  // 모든 lock 획득 시도가 실패했을 경우, 마지막 오류를 저장<br>  let lastError: unknown;<br><br>  // 최대 횟수까지 lock 획득을 시도<br>  for (let attempt = 0; attempt &lt; LOCK_MAX_ATTEMPTS; attempt += 1) {<br>    try {<br>      return lockfile.lockSync(sessionPath, {<br>        stale: LOCK_STALE_MS,<br>        realpath: false,<br>      });<br>    } catch (error) {<br>      // 이번 획득 시도의 실패 원인을 저장<br>      lastError = error;<br><br>      // 이미 마지막 시도였다면 반복 종료<br>      if (attempt === LOCK_MAX_ATTEMPTS - 1) break;<br><br>      // 대기 시간 계산<br>      const delay = Math.min(<br>        LOCK_BACKOFF_MS.min * LOCK_BACKOFF_MS.factor ** attempt,<br>        LOCK_BACKOFF_MS.max<br>      );<br>      sleepSync(delay);<br>    }<br>  }<br><br>  throw new Error(...);<br>};</pre><p>이렇게 로직은</p><pre>1. lockSync<br>2. 파일 읽기<br>3. 파싱, 뮤테이션등 로직 처리<br>4. 파일 쓰기<br>5. release</pre><p>로 구성할 수 있고 동작은 이렇게 구성된다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*afm1pPYbhae6XHBlgv6VfQ.png" /></figure><h3>안전하게 파일 read하기</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*o7Y0VFg8Oh4WG8TCCbXlrQ.png" /></figure><p>문제는, reader가 쓰는 도중의 파일을 관찰할 수 있단 것이다.</p><p>파일 읽기에 기반이 되는 로직인 fs.watch()는 운영체제(OS)의 네이티브 파일 시스템 알림에 의존하기 때문에 이벤트 자체도 완전히 신뢰할 수 있는 변경 로그처럼 취급하면 안 되는 API고, callback 시점에 reader가 읽을 파일이 완전한 상태라는 보장은 writer 쪽에서 별도로 만들어야 한다.</p><p>따라서, 파일 쓰기가 완료됨을 보장하고 reader는 완료된 상태의 파일을 읽을 수 있게 해야한다.</p><h4>Atomic Rename</h4><p>파일의 rename은 중간 상태가 존재하지 않는 연산이다. 이 이름이 어느 파일을 가리키는가를 바꾸는 것이기 때문이다.</p><p>이 아이디어를 사용해, 원본 파일이 아닌 임시파일에 쓰기를 하고 원본 파일만 읽도록 한다.</p><p>임시 파일에 쓰기가 끝나면 rename을 통해 원본 파일에 적용한다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0hF8tvUOvIW0MsbqNHu-aA.png" /></figure><p>코드로는 다음과 같이 구현 가능하다.</p><pre> const tmpPath = `${sessionPath}.${process.pid}.${Date.now()}.tmp`;<br><br>  fs.writeFileSync(<br>    tmpPath,<br>    `${JSON.stringify(snapshot, null, 2)}\n`,<br>    &quot;utf8&quot;<br>  );<br><br>  fs.renameSync(tmpPath, sessionPath);</pre><h3>안전하게 Node에 apply하기</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IXU2_ZUhury-My5XZGs6Lw.png" /></figure><p>Lock은 여러 CLI 프로세스가 파일을 동시에 수정하는 문제를 해결한다. 하지만 파일에 기록된 변경을 Node 프로세스가 언제, 몇 번, 어떤 순서로 메모리 에 반영할지에 대한 별도의 synchronization 정책이 필요하다. 반영 사항은 최종(최신) 상태만 반영하면 된다.</p><p>따라서, 상태 파일에 logical version 역할을 위한 revision 필드를 추가했다. revision 0부터 시작해 상태 파일 변경마다 단조(+1)증가 한다.</p><h4>동작</h4><h4>lock과의 관계</h4><pre>1. lockSync<br>2. 파일 읽기<br>3. 파싱, 뮤테이션등 로직 처리<br>4. **revision 1 증가**<br>5. 파일 쓰기<br>6. release</pre><p>기존 동작에서, revision을 증가시키는 로직을 포함한다. 이를 통해 1씩 안전하게 단조증가함을 lock과 함께 보장할 수 있다.</p><h4>revision의 구현과 적용</h4><p>파일에 쓰는 내용의 스키마는 이렇게 구성된다.</p><pre>export const sessionSnapshotSchema = z.object({<br>  revision: z.number(),<br>  state: // 생략, 실제 읽고 쓰는 데이터<br>});</pre><p>파일 소비처에선 다음 로직을 통해 revision을 소비한다.</p><pre>const snapshot = repository.read(); // snapshot이 파일 내용<br><br>if (<br>  !snapshot ||<br>  snapshot.revision &lt;= this.lastAppliedRevision<br>) return;</pre><p>lastAppliedRevision은 Node runtime에 마지막으로 실제 적용한 snapshot revision을 저장한 변수다.</p><p>따라서, 위 조건문으로 어떤 스냅샷을 적용할지 말지 선택 가능하다.</p><pre>1. snapshot.revision &lt; lastAppliedRevision: 오래된 상태이므로 무시<br>2. snapshot.revision = lastAppliedRevision: 이미 적용했으므로 무시<br>3. snapshot.revision&gt; lastAppliedRevision: **새로운 상태이므로 적용**해 로직 수행</pre><p>동작은 이렇게 정리 가능하다.</p><pre>1. 파일 읽기 <br>2. 리비전 판별 <br>  - snapshot.revision &lt; lastAppliedRevision: 오래된 상태이므로 무시 <br>  - snapshot.revision === lastAppliedRevision: 이미 적용했으므로 무시 <br>  - snapshot.revision&gt; lastAppliedRevision: **새로운 상태이므로 적용**해 로직 수행 <br>3. 로직 처리해 Node 프로세스에 반영 <br>4. lastAppliedRevision = snapshot.revision</pre><p>lastAppliedRevision을 단조증가 시키지 않는 이유는 중간 revision을 Node가 관찰하지 못할 수도 있기 때문이다.</p><pre>Node:<br>lastAppliedRevision = 3<br><br>CLI:<br>revision 4 작성<br>revision 5 작성<br><br>Node가 다음에 파일을 읽었을 때:<br>snapshot.revision = 5</pre><h3>결론</h3><p>여러가지 독립된 시스템이 읽기/쓰기 연산을 하는 요구사항이다. 이런 문제를 다룰 때는 먼저 어떤 시스템이 상태를 소유하고, 어디에 상태를 저장하며, 각 시스템이 언제 읽고 쓰는지를 모델링해야 한다.</p><p>그다음 데이터가 작성되고, 전달되고, 읽히고, 반영되는 흐름을 따라가며 각 단계에서 발생할 수 있는 문제를 고려해야 한다.</p><p>사용성 있는 소프트웨어를 위한 엔지니어링에서 전형적인 문제고, 적절한 정책을 선택해야 한다. 답은 이미 나와 있을 것이다.</p><p>실제로는 watch의 신뢰성을 보강하기 위한 polling 장애 처리 그리고 초기화시 Node Process도 파일을 쓰기 동작을 위한 처리를 해두었다. 하지만, 이 글은 주요 흐름을 설명한다.</p><p>마지막으로, 개발시 외부 api와 연계된 동작을 더 풍성하고, 간단하게 확인하고 싶을 때 <a href="https://msw-dev-tool-docs.vercel.app/docs/get-started">msw-dev-tool</a>을 이용해주는 것을 부탁드립니다. ai가 잘 파악 못하는 happy-case외 동작을 검증할 수 있습니다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b61b345f99cf" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[이상한 figma plugin 나라의 sandbox runtime]]></title>
            <link>https://medium.com/@nayounsang722/%EC%9D%B4%EC%83%81%ED%95%9C-figma-plugin-%EB%82%98%EB%9D%BC%EC%9D%98-sandbox-runtime-31a76c69d31f?source=rss-c7562bbf0193------2</link>
            <guid isPermaLink="false">https://medium.com/p/31a76c69d31f</guid>
            <category><![CDATA[figma-plugin]]></category>
            <category><![CDATA[javascript]]></category>
            <dc:creator><![CDATA[Nayounsang]]></dc:creator>
            <pubDate>Sat, 27 Jun 2026 09:12:21 GMT</pubDate>
            <atom:updated>2026-06-27T09:12:21.136Z</atom:updated>
            <content:encoded><![CDATA[<h3>개요</h3><p>figma plugin은 sandbox 영역과 ui 영역의 코드가 분리돼있다.</p><ul><li>그럼 sandbox 영역이란 무엇인가?</li><li>sandbox는 무엇이 <strong>이상한가?</strong></li><li>이상함을 어떻게 개선할 것인가?</li></ul><p>이 질문의 답을 찾아가며, figma plugin 개발시 알아야할 유의사항과 제약사항을 공유하고자 한다.</p><h3>figma plugin의 두 컴포넌트</h3><blockquote>tl;dr<br>figma plugin은 메인스레드에서 figma와 직접 상호작용하는 sandbox 영역과 browser api를 사용하고 ui를 그리는 iframe 영역의 두 컴포넌트로 나눠진다.</blockquote><h4>왜 분리했나?</h4><blockquote>레퍼런스: <a href="https://www.figma.com/blog/how-we-built-the-figma-plugin-system/">피그마 공식 블로그</a></blockquote><p>모놀리틱한 구조라면 다음 세가지 문제가 생긴다.</p><ul><li>보안: figma, browser api를 동시에 만지는 모놀티릭한 구조라면 공격 표면이 커진다. 그래서 권한을 분리할 필요가 생겼다.</li><li>성능: figma 문서를 iframe으로 직렬화해서 넘기는 방식은 병목이 생기기 쉽다.</li><li>비동기 사용성: 모든 read/write 동작을 message passing으로 만들면 비동기 처리가 너무 빈번&amp;복잡해지고 코드가 쉽게 더러워진다.</li></ul><h4>figma plugin의 실행</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/786/1*2kns1IQTsZC7oAb-2xhzRg.png" /><figcaption>이해를 위한 요약</figcaption></figure><ol><li>사용자가 figma 플러그인 실행시 figma는 manifest.json 엔트리를 통해 sandbox 영역 코드, ui 영역 코드 그리고 기타 설정(권한 등)을 읽는다.</li><li>manifest.json 의 main 경로에 해당하는 코드를 sandbox 영역에서 실행한다.</li><li>figma.showUI 메서드로 iframe 형태의 ui를 figma에 노출한다.</li><li>ui는 event.data.pluginMessage 를 통해 sandbox의 메시지를 받고, parent.postMessage 를 통해 sandbox에 메시지를 보낸다.</li><li>sandbox는 figma.ui.onMessage 를 통해 ui의 메시지를 받고, figma.ui.postMessage 를 통해 ui에 메시지를 보낸다.</li></ol><h3>런타임이란</h3><h4>우리가 알던 런타임</h4><p>대표적인 런타임으로는 브라우저와 Node.js가 있다.</p><p>브라우저는 화면을 그리고, 사용자 입력을 받고, DOM이나 `window` 같은 브라우저 API를 제공한다.</p><p>Node.js는 파일 시스템, 프로세스, 네트워크처럼 브라우저 밖의 환경을 다루는 API를 제공한다.</p><p>즉 같은 JavaScript라도 어떤 런타임에서 실행되느냐에 따라 사용할 수 있는 기능과 제약이 달라진다.</p><h4>sandbox 런타임 @figma</h4><p>여기서 Node.js/브라우저와 다른 sandbox라는 별도의 런타임이 등장한다.</p><p>sandbox는 최소한의 JavaScript 실행 환경이다. 브라우저(데스크톱 앱도 브라우저 기반)에서 Figma를 사용하더라도 브라우저 API를 노출하지 않고 figma 전역 객체를 노출한다.</p><p>sandbox는 JavaScript를 실행하지만, 브라우저와 다른 전역 객체와 권한을 가진 별도의 JS VM이고 WASM으로 컴파일된다.</p><h3>sandbox 런타임의 이상함</h3><blockquote>tl;dr<br>sandbox는 브라우저 api, 전역 객체 사용 뿐만 아니라 지원하지 않는 문법이 존재한다.<br>레퍼런스: <a href="https://www.sam.today/blog/bumbling-the-figma-api">Bundling around the Figma Plugin Runtime Limits</a></blockquote><pre>Syntax error on line 123: Unexpected token ...</pre><p>개발하다 보면 Unexpected token 에러가 발생하곤 한다. (<em>Use developer VM</em> 옵션을 활성화 해야 확인 가능하다.) 이는 sandbox JS 코드를 파싱할 수 없을 때 = <strong>지원하지 않는 문법을 사용했을 때</strong> 발생하는 오류다.</p><p>또한, 문법에 따라 위 사례말고 다른 오류 메시지도 확인할 수 있다</p><p>경험한다면 상당히 당황스러울 것이다. 분명 빌드 설정도 제대로 됐고, 결과물도 문제가 없는데 발생한다. 원인 조차 파악하기 어려울 것이다.</p><h4>지원하지 않는 문법들</h4><blockquote>레퍼런스에서 언급된 사례와 플러그인 개발 당시 경험적으로 식별한 것으로, 아직 식별하지 못한 것과 이미 패치된 것이 존재할 수 있다.</blockquote><p><strong>Destructuring</strong></p><pre>const foo = {x, ...y};<br>const {bar, baz} = z;</pre><p>ES6부터 지원하는 문법이다.</p><p><strong>Optional Chaining</strong></p><pre>const foo = bar?.baz;</pre><p>ES2020부터 지원하는 문법이다.</p><p><strong>Nullish</strong> <strong>coalescing</strong></p><pre>const count = current ?? 0;</pre><p>ES2020부터 지원하는 문법이다.</p><p><strong>import/export</strong></p><pre>import foo from &quot;./bar&quot;;<br><br>export { baz };</pre><p>다행인 점은, <strong>단일 파일로 번들링해야 하므로</strong> 이 구문이 산출물로 나올 일은 없단 것이다.</p><p><strong>주석 내부 import 구문</strong></p><pre>// browser and replay packages should `@sentry/browser` import<br>// from `@sentry/replay` in the future</pre><p>피그마 플러그인은 단일 파일 산출물만 허용한다. 따라서, import/export 구문을 제한하는 것과 같은 맥락이지만 이것을 식별하는 내부 동작이 <strong>주석까지 영향을 미친다.</strong></p><p><strong>console method</strong></p><pre>console.time(label);<br>console.timeEnd(label);</pre><p>log와 같은 기본적인 메서드 외 지원하지 않는 console 메서드가 있다. 디버깅시 유의해야 한다.</p><h4>참고: QucikJS?</h4><p>sanbox의 JavaScript가 <a href="https://www.figma.com/blog/an-update-on-plugin-security/#a-technology-change">QuickJS로 실행된다는 공식 포스트가</a> 있다. 하지만 이것은 <strong>신경쓰지 않아도 될 정보다.</strong> 꽤 오래전(2019년)에 작성된 글이고, <a href="https://bellard.org/quickjs/Changelog">QuickJS와 문법 지원 명세가 매우 다르다는 것을</a> 경험적으로 알아냈다.</p><p>따라서, 현재는 자체 VM으로 실행함을 알 수 있다. FIgma는 <strong>어떻게 sandbox의 코드를 실행하는지는 공개된 정보가 없다.</strong></p><h3>해결책</h3><h4>주석 제거</h4><p>대부분 프로덕션 빌드에서 자동으로 수행된다. 빌드 산출물에서 주석을 모두 제거하도록 한다.</p><h4>트랜스파일러</h4><p>빌드시 트랜스파일링 과정을 추가한다. 여기서 <strong>빌드 산출물을 ES5로 변환한다. </strong>최신 문법을 모두 제거해<strong> </strong>위험을 줄인다. desturcturing과 같은 일부 문법은 plugin으로 직접 변환한다.</p><p>코드 크기와 런타임 비용이 늘어나지만 내부툴로서 다뤄지는 피그마 플러그인에선 감안할 수 있는 문제다.</p><h4>폴리필</h4><p>console과 같이 예외적으로 호환 안되는 문법은 직접 폴리필을 추가한다.</p><pre>const timers = {};<br>if (typeof console.time !== &quot;function&quot;) {<br>  console.time = (label) =&gt; {<br>    timers[label] = Date.now();<br>  };<br>}</pre><h4>안고 가야 할 것</h4><p>피그마에서 공개된 정보가 없고, <strong>정적 분석으로 탐지 불가능해 직접 플러그인을 구동시켜봐야 </strong>한다. 게다가, 위 사례에서 과거에 적용됐고 일상적으로 사용하는 문법도 지원하지 않는다는 것을 알 수 있으며, <strong>지원하지 않는 문법이 더 존재할 수 있다.</strong></p><p>따라서 개발 사이클에서 최대한 작은 단위로 작업해 플러그인을 실행시켜 <strong>직접 확인할 수 밖에 없다.</strong></p><h3>결론</h3><p>피그마 플러그인 개발시 figma와 직접 상호작용하는 sandbox runtime이 존재한다. 이곳에서 알 수 없는 런타임 에러가 발생하곤 하는데, sandbox runtime에서 호환되지 않는 문법이 있기 때문이고 일상적으로 사용하는 문법과 이미 과거부터 지원한 문법조차 지원이 안되는 경우가 있다.</p><p>해결하기 위해 폴리필, 트랜스파일링을 도입한다. 하지만, 완전 해결은 아니고 직접 런타임에서 주의해서 개발해야 한다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=31a76c69d31f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[우리는 올바른 길로 가고 있나요?]]></title>
            <link>https://medium.com/@nayounsang722/%EC%9A%B0%EB%A6%AC%EB%8A%94-%EC%98%AC%EB%B0%94%EB%A5%B8-%EA%B8%B8%EB%A1%9C-%EA%B0%80%EA%B3%A0-%EC%9E%88%EB%82%98%EC%9A%94-bc379e26c9c0?source=rss-c7562bbf0193------2</link>
            <guid isPermaLink="false">https://medium.com/p/bc379e26c9c0</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[주니어개발자]]></category>
            <category><![CDATA[junior-developer]]></category>
            <category><![CDATA[신입]]></category>
            <dc:creator><![CDATA[Nayounsang]]></dc:creator>
            <pubDate>Sat, 07 Mar 2026 14:42:00 GMT</pubDate>
            <atom:updated>2026-03-07T14:42:00.010Z</atom:updated>
            <content:encoded><![CDATA[<h3>공포의 서막과 피어오르는 의문</h3><p>많은 것이 빠르게 쏟아져 나오고 있다. 기술의 발전 속도는 가속되고 있고, 불과 1년 전 등장한 <a href="https://code.claude.com/docs/ko/overview">claude code</a>조차 이미 낡아 보일 정도다.</p><p>그동안 새로운 기술은 설렘을 주었다. 나는 그것을 이해하고, 판단하고, 상상하며 따라잡을 수 있다고 느꼈다. 그러나 지금은 다르다. 설렘 대신 <a href="http://medium.com/r?url=https%3A%2F%2Fko.wikipedia.org%2Fwiki%2F%25ED%258F%25AC%25EB%25AA%25A8">FOMO</a>가 먼저 떠오른다. 무엇이 중요한지, 무엇을 준비해야 하는지 분간하기 어렵다.</p><p>세상은 분명히 바뀌고 있다. 낙관과 비관이 동시에 쏟아진다. 모두가 전망을 이야기하지만, 누구도 확신하지는 못한다. 몇 년 뒤의 기준이 무엇이 될지 가늠하기 어렵다.</p><p>사회초년생, 특히 주니어 엔지니어로서 이 변화는 더욱 직접적이다. 지금까지의 기준으로 쌓아온 역량이 재편될 가능성이 높다. 사람이든 시스템이든, 역할은 다시 정의될 것이다.</p><p>그래서 공포가 생긴다. 우리는 과연 올바른 방향으로 가고 있는가?</p><h3>기술 발전의 함정</h3><p>기술 발전은 반복적이고 규칙 기반인 단순 작업을 추상화한다. 과거에는 이러한 작업을 수행하기 위해 별도의 인력이 필요했지만, 자동화와 도구의 고도화가 이루어지면 상위 수준의 노동자가 이를 직접 제어할 수 있게 된다. 그 결과, 단순 작업을 담당하던 인력은 구조적으로 축소된다.</p><p>기술 발전이 새로운 일자리를 창출해 기존 일자리를 대체한다는 주장도 있다. 그러나 새롭게 등장하는 직무는 일반적으로 더 높은 숙련도와 전문성을 요구하며, 동시에 더 적은 인력으로 운영된다. 조직 내에서도 실무자는 성과를 기반으로 관리·기획 역할로 승격되지만, 이러한 상위 직무의 규모는 실무 인력보다 작다. 따라서 기술 발전은 단순한 대체가 아니라, 전체 노동 수요의 구조적 재편과 축소를 동반하는 경향이 있다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/485/1*LcpL71C2y7hbvYtZOpt5rw.jpeg" /><figcaption>나사의 계산수</figcaption></figure><p>많은 계산수들이 나사에서 탄도와 궤도를 직접 계산했으나, 계산기를 설계하는 소수의 프로그래머로 대체됐다.</p><p>많은 교환원들이 전화마다 수작업으로 선을 연결했으나, 통신망을 관리하는 소수의 시스템 엔지니어로 대체됐다.</p><h3>생산의 폭증, 유한한 파이</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*YY6A98aJAtwazCpo.png" /><figcaption>샘 울트먼: 현재의 대학 졸업생들이 “역사상 가장 운이 좋은 세대”가 될 것</figcaption></figure><p>과거 계산원은 계산기로 대체되었지만, 더 복잡한 계산이 가능해졌다. 교환원은 자동화된 통신 시스템으로 사라졌지만, 더 많은 통화를 동시에 처리할 수 있게 되었다. 기술은 단순히 노동을 제거하는 것이 아니라, 생산 능력을 확장해왔다.</p><p>지금은 그 확장의 속도가 전례 없이 빠르다. 간단한 웹페이지나 도구는 비엔지니어도 만들 수 있다. 아이디어를 구현하는 비용은 급격히 낮아졌다. 소수의 인원, 심지어 개인 단위로도 하나의 프로덕트를 완성해 시장에 내놓을 수 있는 시대가 되었다.</p><p>문제는 이 능력이 특정 소수에게만 주어진 것이 아니라는 점이다. 모두가 어느 정도 괜찮은 결과물을 만들어낼 수 있게 되었다. 진입 장벽은 낮아졌지만, 차별화의 장벽은 오히려 높아졌다.</p><p>인간의 인지 능력과 시간, 그리고 물리적 자원은 유한하다. 우리는 하루에 수십 개의 서비스를 쓰지 않는다. 동영상을 보기 위해 하나의 플랫폼을 열고, 송금을 위해 특정 앱을 사용하며, 중고 거래를 위해 몇 개의 대표 서비스를 떠올린다. 생산은 폭증했지만, 소비의 파이는 크게 늘어나지 않았다.</p><p>결국 살아남는 프로덕트는 소수다. 기술은 개인의 생산성을 증폭시켰지만, 동시에 경쟁을 밀집시킨다.</p><p>그 결과, 소수의 인원만으로도 막대한 가치를 창출 가능한 구조가 만들어졌다. 반대로 말하면, 이전에는 일정 규모의 조직이 필요했던 가치 창출이 이제는 소수에게 집중된다. 효율성은 극대화되었지만, 그 과정에서 배제되는 사람 역시 늘어난다.</p><p><strong>생산의 민주화는 성공의 민주화를 의미하지 않는다.</strong></p><h3>주니어 학살</h3><p>이제 미래가 아닌 현재를 보자. 미래에 대한 전망이 비관적이라도, 그것이 사회 전체의 인식이 되고 행동으로 나타나기까지는 긴 시간이 필요하다. 지금은 아직 그 간극 속에 있는 시기다. 우리의 생활은 생각보다 바뀌지 않았다. 그러나, 주니어들에게 변화가 먼저 드러나고 있다.</p><h4>기회는 늘었는데, 줄었어요.</h4><p>빅테크의 대규모 레이오프 뉴스가 자주 들린다. 그래서 AI가 소프트웨어 엔지니어를 대규모로 대체하고 있는 것처럼 보이기도 한다. 그러나 실제 통계는 조금 다른 그림을 보여준다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Z8_Q_3eu2Oa2CYGd.png" /><figcaption>출처: <a href="https://newsletter.pragmaticengineer.com/i/172584839/big-tech-hires-engineers-again">https://newsletter.pragmaticengineer.com/i/172584839/big-tech-hires-engineers-again</a></figcaption></figure><p>빅테크의 소프트웨어 엔지니어 채용 추이를 보면, 코로나 이후 크게 감소했다가 2024년 이후 다시 증가하는 흐름을 보인다. 즉 최근의 레이오프 뉴스와 달리 전체 고용 자체가 급격히 붕괴하고 있는 것은 아니다.</p><blockquote>연구진은 2016년부터 현재까지 미국 인구현황조사(CPS)​ 데이터를 활용해서, AI 노출 상위 25% 직군과 노출 0% 직군의 실업률을 비교했어요. 이중차분법(DID)​으로 분석한 결과, ChatGPT 출시 이후 두 그룹 간 실업률 격차의 변화는 +0.20%포인트로, 통계적으로 유의미하지 않았어요.</blockquote><blockquote>출처: <a href="https://maily.so/oz.talking/posts/wjzdpmemz3p">https://maily.so/oz.talking/posts/wjzdpmemz3p</a></blockquote><p>적어도 현재까지는 AI가 소프트웨어 엔지니어를 대규모로 실직시키고 있다는 증거는 뚜렷하지 않다. 겉으로 보면 기회는 여전히 존재하고, 심지어 늘어난 것처럼 보이기도 한다.</p><p>하지만 기회는 공평할까?</p><blockquote>청년 취업자 수는 2022년 11월부터 3년 3개월째 줄고 있다. 이 기간 줄어든 청년 취업자 수는 51만4000명에 달한다.</blockquote><blockquote>지난달 15세 이상 실업자 수는 1년 전보다 12만8000명 늘어난 121만1000명으로 나타났다. 올해 1월 전체 실업률은 4.1%로 4년 만에 가장 높았다. 지난달 15~29세 청년층 실업률(6.8%)은 5년 만에 최고치였다.<br>출처: <a href="https://www.donga.com/news/Economy/article/all/20260212/133350040/2">https://www.donga.com/news/Economy/article/all/20260212/133350040/2</a></blockquote><p>전체 노동시장을 보면 고용은 유지되거나 늘어나는 것처럼 보이지만, 청년층에서는 전혀 다른 신호가 나타난다. 특히 노동 시장의 가장 아래쪽, 즉 커리어의 시작점에서 기회가 줄어들고 있다.</p><p>기술 발전은 반복적이고 단순한 작업을 계속 추상화해왔다. 그리고 그 과정에서 ‘단순 작업’의 기준 역시 점점 올라간다. 과거에는 신입이 담당하던 일들이 이제는 자동화되거나 더 숙련된 인력이 처리하는 영역으로 이동한다. 그 결과 아직 충분히 숙련되지 않은 주니어의 필요성은 점점 줄어든다. 그리고 이 변화는 생각보다 빠르게 진행되고 있다.</p><p>아직은 고요해보이지만, 진입하는 문은 닫히고 있다.</p><p>물론 이 현상을 전부 AI 때문이라고 단정하기는 어렵다. 하지만 ‘주니어 학살’이라는 현상은 이미 여러 형태로 나타나고 있다.</p><h4>주니어를 위한 비료는 없다.</h4><p>시니어는 피의 역사로 탄생했다. 알고 보면 단 한 줄 잘못 작성한 코드가 원인이지만, 그 사실을 알아내기까지 망망대해를 항해하듯 시스템을 헤매야 한다. 잘못된 설계 하나 때문에 몇 시간 동안 로그를 뒤지고 디버깅에 매달리며 짜증을 삼킨다. 단순한 기능 하나를 구현하기 위해 두꺼운 공식 문서를 눈이 빠지도록 뒤적이기도 한다. 그렇게 몸으로 엔지니어링을 체득한다.</p><p>주니어의 학습은 이런 시니어와의 도제식 교육 구조로 이루어져 왔다. 코드를 읽고, 코드 리뷰를 받고, 질문을 던지며 문제를 이해하는 과정이 반복된다. 그 과정 속에서 개발자는 단순히 문법이나 기술만이 아니라 조직의 시스템과 설계 철학, 문제 해결 방식까지 체득하게 된다.</p><p>하지만 지금은 상황이 조금 달라지고 있다.</p><p>AI는 질문에 대해 즉각적인 답을 제공한다. 그것도 매우 친절한 형태로. 접근성 면에서 AI는 인간 멘토보다 훨씬 편하다. 그래서 매혹적이다.</p><p>문제는 이 과정이 학습의 구조 자체를 바꾸고 있다는 점이다. AI가 제시하는 결과와 과정은 항상 이해되는 것은 아니다. 왜 그런 구조가 필요한지, 어떤 설계가 더 나은지에 대한 고민 없이 결과만 사용하는 경우도 많다. 마치 시험 문제를 풀기 전에 답지를 먼저 보는 것과 비슷하다. 문제는 해결될 수 있지만, 지식이 체득되는 과정은 약해진다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*jmoYGmAgsNPCShDN" /><figcaption>출처: <a href="https://www.anthropic.com/research/AI-assistance-coding-skills">https://www.anthropic.com/research/AI-assistance-coding-skills</a></figcaption></figure><p>실제로 Anthropic의 연구에서는 AI에게 코드 작성과 디버깅을 맡긴 그룹이 AI를 사용하지 않은 그룹보다 퀴즈 점수가 약 17% 낮게 나타났다. AI는 문제 해결을 빠르게 만들어 주지만, 그 과정이 반드시 체득으로 이어지는 것은 아니라는 점을 보여준다.</p><p>여기에 또 하나의 압력이 존재한다. AI로 인해 높은 생산성이 곧 새로운 기준이 된다. 생산성을 고려하지 않고도, 조직은 주니어에게 “AI 네이티브함”을 기대한다. 결국 AI를 사용하지 않는 선택지는 점점 어려워진다.</p><p>이렇게 되면 역설적인 상황이 만들어진다. AI는 개발을 돕는 도구이지만, 동시에 깊은 학습을 방해한다. 주니어 개발자는 더 강력한 도구를 갖게 되었지만, 기초적인 설계능력과 원리를 체득하기엔 어려워졌다.</p><p>이 문제는 단순히 주니어 개인의 의지 때문만은 아니다. AI는 빠르게 발전하고 있지만, 그것을 어떻게 활용하며 배우는 것이 올바른지에 대한 방법론은 아직 부재하다. 즉각적이고 친절한 답을 제공하는 도구가 존재하고 사용을 요구하는 환경에서, 그 유혹을 피하는 일은 개인의 의지만으로 해결하기 어려운 문제다.</p><h3>우리는 올바른 길로 가고 있나요?</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/626/0*iLf9--2bEUFPnDFN.jpg" /></figure><p>주니어는 이 시대를 살아가며 앞으로 많은 것을 경험하고, 결국 그 변화에 영향을 끼치게 될 주체다. 지금도 녹록지 않고, 미래는 더욱 예측하기 어렵다. 그러나 이 거대한 흐름의 방향을 직접 결정하기에는 경험도, 권위도 아직 부족한 것이 현실이다.</p><p>사실 당연한 상황이다. 인간은 늘 발전을 추구해 온 존재이고, 우리 모두에게 이번 시대는 처음이기 때문이다. 변화는 너무 빠르고 복잡하다. 일단 우리는 어떤 방향이든 나아가고 있다.</p><p>우리는 어디로 가고 있을까. 그리고 결국 어디에 도달하게 될까.</p><h4>그래도, 우린 북극에서도 적응한 종이니까.</h4><p>인간의 아름다움은 기이할 정도의 적응력에 있다. 기근과 전쟁 속에서도, 춥고 더운 환경에서도 사람들은 결국 살아가는 방법을 찾아냈다. 그런 역사에 비하면 지금 우리가 마주한 시대가 가장 혹독한 환경은 아닐테니까.</p><p>지금의 주니어 엔지니어는 분명 많이 추운 환경에 서 있다. 학창 시절에 배웠던 것과는 다른 역량이 요구되고 있고, 어떤 역량이 정답인지도 분명하지 않다. 그래도 결국 우리는 이 꽉 깨물고 적응해야 할 것이다. 그러다보면 정답이 어느정도 나오겠지.</p><p>주도적으로 문제를 발견하고, 왜 그것이 문제인지 설득하고, 동작 원리를 이해하며 원인을 규명한다. 탄탄한 설계를 바탕으로 실험하고, 측정하고, 다시 수정한다. 그렇게 반복하다 보면 결국 단순하고 좋은 해결책에 도달하게 된다. 그 과정을 반복한다. 그것이 엔지니어의 본질이고 본질은 도통 변하는 것이 이니니까.</p><p>결국 우리는 결국 멋진 엔지니어가 되지 않을까. 그리고 그렇게, 우리 삶의 문제를 해결하는 사람이 되지 않을까.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=bc379e26c9c0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[표현을 AI에게 위임하고 싶다.]]></title>
            <link>https://medium.com/@nayounsang722/%ED%91%9C%ED%98%84%EC%9D%84-ai%EC%97%90%EA%B2%8C-%EC%9C%84%EC%9E%84%ED%95%98%EA%B3%A0-%EC%8B%B6%EB%8B%A4-ad5843e19590?source=rss-c7562bbf0193------2</link>
            <guid isPermaLink="false">https://medium.com/p/ad5843e19590</guid>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Nayounsang]]></dc:creator>
            <pubDate>Sun, 08 Feb 2026 13:55:09 GMT</pubDate>
            <atom:updated>2026-02-08T13:55:09.181Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tDKRq1GXRR7-XH27r30EMA.png" /></figure><h3>개요</h3><p>AI는 분명 포텐셜이 높다. 하지만, 아직은 할루시네이션 문제가 있기에 모든 것을 위임할 순 없다. (아직은 인력이 필요한 이유다.) 작업의 어떤 계층을 위임할 것인가? 어떻게 생산성을 높일 수 있을까?</p><p>아직 잘 모르겠다. 하지만, 노력은 하려고 한다. 그래서 글이 난잡할 것이다. 아직은 부족하다. 마치 휘갈겨 쓴 액션 페인팅 같다.</p><h3>표현이란?</h3><p>난 AI에게 표현을 위임하고자 했다. “표현&quot;이란 무엇일까? 어떤 설계도, 사고가 있을 때 이를 타인이 이해 가능한 프로토콜로 변환하는 과정이다.</p><p>예를들면, 사칙 연산이 가능한 함수를 TypeScript로 다음과 같이 “표현” 가능하다.</p><pre>type Operator = &quot;+&quot; | &quot;*&quot; | &quot;-&quot; | &quot;/&quot; ; <br><br>const doArithmeticLogic = (leftValue:number, rightValue:number, mode:Operator) =&gt; {<br>  if (mode === &quot;+&quot;) {<br>    return leftValue + rightValue;<br>  }<br>  // 각각 연산자에 대한 계산<br>}</pre><p>이것을 위해, 우린 타자를 쳐야한다. 문서 역시 똑같다. 펜이든, 타자든 글을 직접 써야한다. 노동이 발생한다.</p><p>핵심은 “무슨 문제(의제)를 어떤 식으로 설계했는가?”라고 생각한다. 이것이 확실하다면, 의사결정이 이루어져서 개선과 해결가능한 본질로 다가설 수 있다.</p><h3>엔지니어링 플로우</h3><p>문제를 정의한다. <br>이것이 왜 문제인가? 얼마나 문제인가?</p><p>문제를 해결할 방법을 설계한다. <br>A가 적절한가, B가 적절한가, 실험은 어떻게 할 것인가, 어떤 방법이 더 효율적이며 효율적이란 기준은 어떻게 비교할 것인가</p><p>표현한다.<br>코드로 작성하던지, 문서를 공유하던지, 이해관계자에게 적합한 프로토콜로 공유한다.</p><p>평가한다.<br>문제가 해결 됐는가? 트레이드 오프란 무엇인가? 피드백은 어떤 것이 있는가?</p><h3>AI는 무엇일까</h3><p>매개변수가 매우 많은 비선형 함수 머신</p><p>함수의 인수와 구성은 학습된 데이터에 대한 통계적 경향이다. 인간은 이것을 감이라 부른다.</p><p>학습이 이루어지고, 실제 input에 대해 제일 통계적으로 적합한 output을 출력한다.</p><p>즉, 통계적으로 가장 적합한 감이 좋은 기계</p><h3>병목에 AI 활용하기</h3><p>내 머릿속의 생각을 문서로 공유한다. 그리고 그것을 코드로 옮긴다.</p><p>옮기기 위해, 적절한 문장을 선택해야한다. 적절한 단어를 선택해야한다. 적절한 조사, 문장 기호를 선택해야 한다. 게다가, 한국어의 띄어쓰기와 맞춤법은 괴랄한 수준이다.(난 0개 국어를 구사하는 바보다.) 어쩄든 이런 요소를 고려하며 타자를 치는 것은 어렵다. 이것이 표현 작업이다. 생각보다 많은 병목이 발생한다. 때때로 작업 자체가 중복되기도 한다.</p><p>적절한 단어를 조합해 문장을 만들어 내는 것(코딩도 프로그래밍 언어를 이용한 문장 구상이라 생각한다.)을 AI에 위임하고 싶다.</p><h3>어떻게?</h3><p>작업의 레이어를 잘 짠다. 각 레이어에서 적절한 설계를 한다.</p><p>전체적인 레이아웃은 어떻게 되는가? 어떤 프레임워크를 사용할 것인가? 명확성이 중요한 단어(또는 문장 또는 섹션)은 무엇인가? 도메인과 조직에 의존하는 단어는 무엇인가? 참조하는 맥락은 무엇인가?</p><p>이것을 프롬프트로 옮긴다. 그리고 AI는 통계적으로 적절한 것을 선택하고 생성한다. 이제 AI의 작업을 리뷰한다. 마지막으로, 동료와 피드백 루프를 돌린다. (나의 의견이 명확하게 전달됐는지 확인하는 과정이다.)</p><p>프롬프트를 짜는 것도 병목이므로, 나의 의견을 AI에게 최대한 전달하고자 한다. claude code의 interview와 plan mode를 활용한다. 이를 통해 나의 의견이 누락된 부분을 사전에 점검할 수 있다.</p><h3>남은 문제</h3><p>어쨌든, 규모가 큰 작업은 리뷰 자체가 병목이 되기도 하고 빼먹기도 한다.<br>규모가 작은 작업을 연속한다면, 작업간 sync와 형식이 안맞기도 한다. 전체적으로 그루밍하는 태스크가 추가된다.</p><p>나의 활용 능력을 더 키워가며 생산성을 높여야 겠다.</p><p>근데, 할루시네이션은 어쩔 수 없다. 이게 제일 문제인데, AI의 한계인가 싶다.</p><h3>결국, 목적</h3><p>작업의 신뢰성을 망가뜨리지 않으면서도, 생산성을 높이는 목적을 바라보며 AI에게 위임하고 싶다.</p><p>의사 결정 거리는 나의 사고가 온전히 표현되도록 하고 싶다. “이건 AI가 했어요.”는 동료들에게 도움이 전혀 되지 않는다. (가끔은 웃기겠다!)</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ad5843e19590" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[micro frontend와 module federation]]></title>
            <link>https://medium.com/@nayounsang722/micro-frontend%EC%99%80-module-federation-38c0893f1d42?source=rss-c7562bbf0193------2</link>
            <guid isPermaLink="false">https://medium.com/p/38c0893f1d42</guid>
            <category><![CDATA[micro-frontends]]></category>
            <category><![CDATA[module-federation]]></category>
            <category><![CDATA[webpack]]></category>
            <dc:creator><![CDATA[Nayounsang]]></dc:creator>
            <pubDate>Sat, 31 Jan 2026 13:51:21 GMT</pubDate>
            <atom:updated>2026-01-31T13:51:21.249Z</atom:updated>
            <content:encoded><![CDATA[<iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FVnJLFwnuLV4%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DVnJLFwnuLV4&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FVnJLFwnuLV4%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/52f830fe720cd31c54ee903fc0868da0/href">https://medium.com/media/52f830fe720cd31c54ee903fc0868da0/href</a></iframe><h3>개요</h3><p>micro frontend가 무슨 문제를 해결하고, 언제 도입하며 이점이 무엇인지는 위 영상을 통해 알 수 있다.</p><p>그럼, 어떻게 구축하는 것일까? 무척 간단한 예제를 통해 알아보자.</p><h4>무엇을 만드나?</h4><p>간단한 react web application을 mf로 구축해보자.</p><h3>Module federation</h3><p><a href="https://webpack.kr/concepts/module-federation/">Module Federation | 웹팩</a></p><blockquote>로컬 모듈과 원격 모듈을 구별합니다. 로컬 모듈은 현재 빌드의 일부인 일반 모듈입니다. 원격 모듈은 현재 빌드의 일부가 아니며 원격 컨테이너에서 런타임에 로드되는 모듈입니다.</blockquote><p>일반적인 module은 import구문을 통해 호출한다. (*require은 다루지 않는다)</p><pre>import Avatar from &quot;./components&quot;;<br><br>return (<br>  &lt;Avatar color=&quot;red&quot;/&gt;<br>)</pre><p>import는 함께 로드된다. 최상단에서 평가된다. 모듈을 동적으로 불러올 수도 있다.</p><pre>const handleClick = () =&gt; {<br>const { foo } = await import(&#39;./foo&#39;);<br>}</pre><p>빌드한 번들이 나눠져 있고(나눠진 단위가 청크다.) 런타엠에서 청크에 대해 요청을 보내는 것이다.</p><p>두가지 방법 모두 빌드 타임에 모듈들이 생성된다. 빌드 타임과 독립적으로, 런타임에 특정 asset(app)을 불러올 수 없을까?</p><p>그 정답이 module federation이다. webpack을 통해 원격 모듈을 불러오는 어플리케이션 환경을 만들 수 있다.</p><h4>Webpack으로 react 환경 만들기</h4><pre>const path = require(&#39;path&#39;);<br>const HtmlWebpackPlugin = require(&#39;html-webpack-plugin&#39;);<br>const ModuleFederationPlugin = require(&#39;webpack/lib/container/ModuleFederationPlugin&#39;);<br><br>module.exports = {<br>  mode: &#39;development&#39;,<br>  devServer: {<br>    static: {<br>      directory: path.join(__dirname, &quot;dist&quot;),<br>    },<br>    compress: true,<br>    port: 3000,<br>    open: true,<br>  },<br>  output: {<br>    path: path.resolve(__dirname, &quot;dist&quot;),<br>    filename: &quot;bundle.js&quot;,<br>    clean: true,<br>  },<br>  resolve: {<br>    extensions: [&#39;.tsx&#39;, &#39;.ts&#39;, &#39;.jsx&#39;, &#39;.js&#39;],<br>  },<br>  module: {<br>    rules: [<br>      {<br>        test: /\.tsx?$/,<br>        exclude: /node_modules/,<br>        use: {<br>          loader: &#39;ts-loader&#39;,<br>        },<br>      },<br>      {<br>        test: /\.css$/,<br>        use: [&#39;style-loader&#39;, &#39;css-loader&#39;],<br>      },<br>    ],<br>  },<br>  plugins: [<br>    new HtmlWebpackPlugin({<br>      template: &#39;./public/index.html&#39;,<br>    }),<br>  ],<br>};</pre><p>포트 3000에서 개발 서버가 동작하게 한다.</p><p>ts-loader로 tsx파일을 트랜스파일 한다. (*정확히는, tsconfig의 “jsx”: “react-jsx”를 이용하는 것이다. ts-loader는 tsconfig를 연동하는 책임이 있다.)</p><pre>{<br>  &quot;compilerOptions&quot;: {<br>    &quot;target&quot;: &quot;ES2020&quot;,<br>    &quot;useDefineForClassFields&quot;: true,<br>    &quot;lib&quot;: [&quot;ES2020&quot;, &quot;DOM&quot;, &quot;DOM.Iterable&quot;],<br>    &quot;module&quot;: &quot;ESNext&quot;,<br>    &quot;skipLibCheck&quot;: true,<br>    &quot;moduleResolution&quot;: &quot;node&quot;,<br>    &quot;resolveJsonModule&quot;: true,<br>    &quot;isolatedModules&quot;: true,<br>    &quot;noEmit&quot;: false,<br>    &quot;jsx&quot;: &quot;react-jsx&quot;,<br>    &quot;strict&quot;: true,<br>    &quot;noUnusedLocals&quot;: true,<br>    &quot;noUnusedParameters&quot;: true,<br>    &quot;noFallthroughCasesInSwitch&quot;: true,<br>    &quot;esModuleInterop&quot;: true,<br>    &quot;allowSyntheticDefaultImports&quot;: true,<br>    &quot;forceConsistentCasingInFileNames&quot;: true<br>  },<br>  &quot;include&quot;: [&quot;src&quot;]<br>}</pre><p>css-loader은 중요도가 덜하다. url, import 구문을 해석하기 위함이다. style-loader로 head의 style 태그에 스타일을 주입할 수 있게한다.</p><p>js와 css가 주입되는 대상은 public의 index.html이다.</p><p>이 설정은 호스트 역할(*module federation에는 기술적으로 계층이 나눠져 있지 않다. 하지만, 소비자를 호스트라 개념화하며, 공급자를 remote app, micro app이라 한다.)에 해당한다.</p><h4>마이크로 앱</h4><p>호스트 앱에서 사용할 마이크로 앱은 런타임 &amp; 원격에서 불러와지며 따라서 자체 배포 프로세스를 가질 수 있다. 이는 “컨테이너&quot; 라고 불린다.</p><p>마이크로앱은 모듈이다. 페이지, 서비스가 아닌 컴포넌트가 될 수도 있다.</p><pre>  plugins: [<br>    new ModuleFederationPlugin({<br>      name: &#39;remote_whiskey&#39;,<br>      filename: &#39;remoteEntry.js&#39;,<br>      exposes: {<br>        &#39;./Lagavulin&#39;: &#39;./src/components/Lagavulin&#39;,<br>        &#39;./Signet&#39;: &#39;./src/components/Signet&#39;,<br>      },<br>    }),<br>  ],</pre><p>module federation 설정에서 어떤 것을 내보낼 것인지 설정한다. 필자는 컴포넌트를 내보낸다.</p><p>name은 다른 앱에서 이 앱을 식별할 때 쓰는 이름이며 filename은 expose된 모듈에 대한 진입점이다.</p><pre>    new ModuleFederationPlugin({<br>      name: &#39;host&#39;,<br>      remotes: {<br>        remote_whiskey: &#39;remote_whiskey@http://localhost:3001/remoteEntry.js&#39;,<br>      },<br>    }),</pre><p>호스트에서 마이크로앱을 받을 수 있다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6K_0rifArVHlJuOv-yptGw.png" /></figure><p>즉, 호스트는 리모트앱(컨테이너)을 연결할 수 있고, 연결 통로엔 expose로 선언된 모듈들이 이동한다. 컨테이너 이름이 name이며, 연결 통로의 포트는 remoteEntry.js 모양이다. (소스코드가 모양이란 것이 비직관적이나, hdmi 모양, c-type 모양 이런식으로 이해하자.)</p><p>호스트는 다음과 같이 마이크로 앱의 모듈을 사용할 수 있다.</p><pre>const Lagavulin = lazy(() =&gt; import(&#39;remote_whiskey/Lagavulin&#39;));<br>const Signet = lazy(() =&gt; import(&#39;remote_whiskey/Signet&#39;));<br><br>function App(): JSX.Element {<br>  return (<br>    &lt;div&gt;<br>      &lt;h1&gt;맛있는 술을 먹고 싶어요.&lt;/h1&gt;<br>      &lt;Suspense fallback={&lt;div&gt;Loading...&lt;/div&gt;}&gt;<br>        &lt;Lagavulin /&gt;<br>        &lt;Signet /&gt;<br>      &lt;/Suspense&gt;<br>    &lt;/div&gt;<br>  );<br>}</pre><p>import 경로의 remote_whiskey prefix는 module federation의 remotes 옵션에 의해 평가된다.</p><p>모듈이기에, (이 경우엔 react component기에) props를 이용한 통신도 가능하다!</p><h4>싱글톤</h4><p>각 마이크로 앱은 독립적인 컨테이너기에, 패키지 의존성 역시 독립적으로 동작한다.</p><p>하지만, 일부 의존성은 서비스 내에서 하나만 존재해야하는데, 이를 shared dependency라고 한다.</p><pre>    new ModuleFederationPlugin({<br>      name: &#39;remote_whiskey&#39;,<br>      filename: &#39;remoteEntry.js&#39;,<br>      exposes: {<br>        &#39;./Lagavulin&#39;: &#39;./src/components/Lagavulin&#39;,<br>        &#39;./Signet&#39;: &#39;./src/components/Signet&#39;,<br>      },<br>      shared: {<br>        react: {<br>          singleton: true,<br>          requiredVersion: &#39;^18.2.0&#39;,<br>          eager: true,<br>        },<br>        &#39;react-dom&#39;: {<br>          singleton: true,<br>          requiredVersion: &#39;^18.2.0&#39;,<br>          eager: true,<br>        },<br>      },<br>    }),</pre><p>대표적으로, react(+ react-dom)이 shared dependency로 처리해야할 의존성이다.</p><p>이때 Uncaught Error: Shared module is not available for eager consumption 와 같은 에러가 발생했다. 기본적으로 공유 의존성은 비동기 청크로 로드된다. 어떤 의존성은 초기에 동기적으로 로드돼야 하므로eager option을 true로 설정해야 한다. (호스트와 마이크로앱 모두 리액트앱이니까!)</p><h3>배포</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*sIr8C5IxaJZ8CSmAnWp4xQ.png" /></figure><p>호스트는 js,css,기타 asset들을 서빙하는 일반적인 배포방식이다. 각 마이크로 앱도 remoteEntry 진입점과 expose된 모듈을 서빙해야 한다.</p><p>따라서 호스트가 연결할 마이크로앱의 remoteEntry의 주소는 환경 변수로 다뤄져야 한다.</p><pre>    new ModuleFederationPlugin({<br>      name: &#39;host&#39;,<br>      remotes: {<br>        remote_whiskey: `remote_whiskey@${REMOTE_WHISKEY_URL}`,<br>      },<br>      shared: {<br>        react: {<br>          singleton: true,<br>          requiredVersion: &#39;^18.2.0&#39;,<br>          eager: true,<br>        },<br>        &#39;react-dom&#39;: {<br>          singleton: true,<br>          requiredVersion: &#39;^18.2.0&#39;,<br>          eager: true,<br>        },<br>      },<br>    }),</pre><p>배포 결과는 <a href="https://mf-practice.vercel.app/">https://mf-practice.vercel.app/</a> 에서 확인 가능하다.</p><p>리모트 앱은 <a href="https://remote-whsikey.netlify.app/">https://remote-whsikey.netlify.app/</a> 에서 확인 가능한데, index.html을 서빙 안하기에 아무 것도 안뜰 것이다.</p><p>소스 코드는 <a href="https://github.com/nayounsang/mf-practice">https://github.com/nayounsang/mf-practice</a> 에서 확인 가능하다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=38c0893f1d42" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[어떻게 문서를 잘 쓸까?]]></title>
            <link>https://medium.com/@nayounsang722/%EC%96%B4%EB%96%BB%EA%B2%8C-%EB%AC%B8%EC%84%9C%EB%A5%BC-%EC%9E%98-%EC%93%B8%EA%B9%8C-5b1fc5c4218a?source=rss-c7562bbf0193------2</link>
            <guid isPermaLink="false">https://medium.com/p/5b1fc5c4218a</guid>
            <category><![CDATA[docs]]></category>
            <category><![CDATA[reading]]></category>
            <category><![CDATA[notion]]></category>
            <dc:creator><![CDATA[Nayounsang]]></dc:creator>
            <pubDate>Sat, 24 Jan 2026 14:20:57 GMT</pubDate>
            <atom:updated>2026-01-24T14:20:57.084Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/512/0*CE8dZ3fVpdOGz3xD.png" /><figcaption>문서</figcaption></figure><h3>개요</h3><p>엔지니어는 코드만 짜는 사람이 아니다. 코드는 일부다. (특히 AI 시대에선 더!) 문서를 작성할 일이 많다. 문서로 코드가 전하지 못하는 정보, 과거 맥락그리고 도메인 맥락을 정리할 수 있다.</p><p>하지만, 좋은 문서란 무엇일까? 현재 회사에서 프로젝트에 대한 문제 탐구를 하고 있고, 따라서 문서로 이를 표현한다. 난 과연 동료분들에게 메시지를 잘 전달하고 있는가? 그리고 동료가 피드백하기 직관적이고 편한 구조인가?(*첫 합류자는 도메인과 과거 맥락에 대해 전무하기에, 결국 소중한 피드백이 수반돼야한다.)</p><h3>문서의 목적 정하기</h3><ol><li>이 문서는 동료에게 어떤 영향을 끼치고자 하는 것인지 밝힌다. (즉, 이 문서는 무엇을 이루고자 하는 것인지 정한다.)</li><li>이 문서에서 다루지 않을 것을 명시한다. 이를 통해 기존 영역은 맥락을 유지하고, 다른 영역은 다른 이슈로 집중시킬 수 있다.</li></ol><h3>문서의 위치 정하기</h3><p>팀 차원에서 문서를 정리중이라면, 목적에 따른 적절한 위치가 있을 것이다. 이를 통해 문서는 동료가 접근 가능한 영역에 놓인다. (*만약 없다면, 논의하거나 임시 위치를 만든다. 결국 이는 또다른 위치 개념으로 파생된다.)</p><p>이 위치 속 문서들의 경향성을 파악한다. 지키면 좋을 형식과 자유로우면 좋을 형식을 파악한다. 좋은 컨텐츠는 익숙함(읽기 편함)이란 factor도 고려해야한다.</p><h3>문서의 과거 맥락 탐구하기</h3><p>문서를 작성하는 이유는, 정리되지 않은 이야기들이 있거나, 기록해야할 이슈가 있기 때문이다. 따라서, Reference를 찾을 필요가 있다. 보통 관련 기록을 최대한 많이 확보한 뒤에, 관련성 &amp; 중복에 따라 소개해 (문서의 분량에 따라 다르지만) 가장 중요한 n가지만 남기도록 한다.</p><h4>내부 맥락</h4><p>내부 맥락이란 조직의 내부에서 다뤄진 맥락이다.</p><p>슬랙, 노션에 키워드들을 이용해 검색한다. Notion MCP, Slack MCP를 적극 활용한다. 노션 데이터 베이스를 만들고, 요약 column을 만들어 한눈에 보게 한 뒤 소거한다.</p><h4>외부 맥락</h4><p>외부 맥락이란 다른 조직의 비슷한 사례이다.</p><p>내부 맥락을 더 중요하게 보려고 하지만, 내부 맥락이 거의 없는 경우에 매우 좋은 재료가 된다. 직접 검색하고, 유용함을 판단한다.</p><h4>맥락 명시</h4><p>따로 Reference 섹션을 만들기도 한다. 주로 문서 전체에 은은하게 녹아든 맥락이다.</p><p>하지만, 가장 좋은 방법은 문서를 작성하며 해당 맥락을 직접 사용한 부분에 임베드 하는 것이다.</p><p>이를 통해, 내 문서의 신빙성을 직관적으로 파악해 피드백할 수 있는 구조다. 독자가 내 문서의 특정 섹션이 의심되거나 더 디깅하고 싶다면, 누르면 끝.</p><h3>결론이 무조건 필요?</h3><p>문서의 목적에 따라 다르다. 어떤 문서는 섣불리 결론을 제시한다면 논의시 선입견이 생기는 것을 주의해야한다. Dry하게 정성적인 맥락을 정량적으로 측정하는 것에서 멈추는 것도 아름답다. 그 뒤, 새로운 문서에서 측정문서를 Reference로 걸어 인사이트 논의 결과를 작성하면 된다. (또는 수정하거나)</p><h3>독자를 알라</h3><p>동료들은 과거 맥락에 대해 더 잘 파악할 수 있다. 또한, 배경 지식이 우연히 더 뛰어날 수 있다.</p><p>문서는 동료가 읽기에, 좋은 문서의 기준은 동료의 평가를 통해 정해진다.</p><h4>피드백 루프</h4><p>문서는 동료가 읽기에, 동료와 함께 완성해 나간다.</p><p>읽기 편한지, 누락된 것이 있는지, 근거가 타당한지, 주관적 vs 객관적이 잘 나눠져 있는지, 작성자가 배경 지식을 잘 이해했는지</p><p>동료와 함께 feedback을 수용하고, 논쟁을 하기도 하며 미래의 동료와 내가 모두 도움되는 문서를 완성해 나간다.</p><h4>가리기를 활용</h4><p>필요한 것 같긴해서(자신감 100%는 아니지만..) 지울 수 없는 내용이 있다. 핵심 정보외엔 “toggle”과 같은 ui를 활용해 작성한다.</p><p>독자는 핵심을 빠르게 파악할 수 있게하고, 이후 선택을 할 수 있게 한다. 하지만, 결코 핵심 내용을 가리면 안된다.</p><h3>문서의 여러 프레임 워크들</h3><h4>STAR: Situation → Task → Action → Result</h4><p>경험이나 사례를 설명할 때, 배경부터 결과까지 행동 중심으로 서술한다.</p><p>주로, “나&quot;라는 개인적 요소가 필요할 때 장점이 많다: 자기 PR에 적합한 구조다. 우스갯소리지만, PR(Pull Request)에도 적절하다.</p><p>단순히 Dry한 상황 설명이 아닌, 특정 사람의 행동을 알 수 있다.</p><h4>Pyramid Principle</h4><p>독자가 가장 먼저 알아야 할 핵심 결론을 맨 위에 배치하고, 그 아래에 그 결론을 뒷받침하는 이유와 상세 내용을 내려가는 구조다.</p><p>보고, 요약, 긴 문서의 도입부에 적절하다.</p><p>위 → 아래의 일반적 독해 흐름에서, 위만 봐도 내용을 알 수 있어, 동료의 시간을 절약할 수 있다.</p><h4>Issue → Cause → Solution → Impact</h4><p>어떤 현상을 설명할 때, 감상이 아니라 논리적인 문제 해결 흐름으로 정리하는 프레임워크다.</p><p>장애, 회고, 이슈등의 기술 문서에 적절하다.</p><p>상황, 도구, 결과를 알 수 있다. STAR과 비교해 dry하다.</p><h4>Problem → Hypothesis → Experiment → Result</h4><p>추측이 아니라, 검증 과정을 기록하는 과학적 사고 기반 문서 구조다.</p><p>최적화 엔지니어링, 기술 검증과 같은 long term task의 서사를 알 수 있다.</p><p>자신의 주관적인 느낌을 결국 객관적 검증 과정으로 연금술 할 수 있다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5b1fc5c4218a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[react-i18next & i18next 둘의 관계]]></title>
            <link>https://medium.com/@nayounsang722/react-i18next-i18next-%EB%91%98%EC%9D%98-%EA%B4%80%EA%B3%84-8dff2ec23943?source=rss-c7562bbf0193------2</link>
            <guid isPermaLink="false">https://medium.com/p/8dff2ec23943</guid>
            <category><![CDATA[i18next]]></category>
            <category><![CDATA[react-i18next]]></category>
            <category><![CDATA[i18n]]></category>
            <dc:creator><![CDATA[Nayounsang]]></dc:creator>
            <pubDate>Wed, 14 Jan 2026 12:09:13 GMT</pubDate>
            <atom:updated>2026-01-14T12:09:13.713Z</atom:updated>
            <content:encoded><![CDATA[<p>i18n 구현시 대표되는 framework인 i18next 생태계에 대해 분석해보자.</p><h3>Why “react”?</h3><p>i18next는, react와 독립돼 어느 생태계(ex vanillaJS)에서 동작하는 로직을 담고 있다. 따라서, react-i18next가 필요하다.</p><p>i18next 사용시, 다음과 같이 사용한다.</p><pre>export const MyComponent = () =&gt; {<br>  const {t} = useTranslation();<br><br>  return &lt;p&gt;{t(&quot;hi&quot;)}&lt;/p&gt;<br>}</pre><p>왜 이 “훅&quot;이 필요한 것일까?</p><ul><li>리액트 컴포넌트 트리와 호환되는 i18n 인스턴스</li></ul><pre>  const { i18n: i18nFromProps } = props;<br>  const { i18n: i18nFromContext, defaultNS: defaultNSFromContext } =<br>    useContext(I18nContext) || {};<br>  const i18n = i18nFromProps || i18nFromContext || getI18n();</pre><p>기본적인 설정으론 geti18n() 를 통해 싱글톤인스턴스를 사용하나, context와 props(사실 hook이므로 params가 적당하겠다.)를 통해 i18n 인스턴스를 주입하는 것을 허용하기 위함이다.</p><ul><li>최적화</li></ul><pre>  const i18nOptions = useMemo(<br>    () =&gt; ({ ...getDefaults(), ...i18n?.options?.react, ...props }),<br>    [i18n, props],<br>  );</pre><p>리액트 컴포넌트 생명주기상 발생하는 병목을 해소하기 위해 일부 로직에서 useCallback , useMemo 를 사용한다.</p><ul><li>suspense 연동</li></ul><pre>  if (i18n &amp;&amp; useSuspense &amp;&amp; !ready) {<br>    throw new Promise((resolve) =&gt; {<br>      const onLoaded = () =&gt; resolve();<br>      if (props.lng) {<br>        loadLanguages(i18n, props.lng, namespaces, onLoaded);<br>      } else {<br>        loadNamespaces(i18n, namespaces, onLoaded);<br>      }<br>    });<br>  }</pre><p>옵션에 따라 Promise를 throw하는 로직을 만들어 Suspense와 호환한다.</p><p>반대로, useSuspense를 disable했을 땐</p><pre>  useEffect(() =&gt; {<br>    if (i18n &amp;&amp; !ready &amp;&amp; !useSuspense) {<br>      const onLoaded = () =&gt; setLoadCount((c) =&gt; c + 1);<br>      if (props.lng) {<br>        loadLanguages(i18n, props.lng, namespaces, onLoaded);<br>      } else {<br>        loadNamespaces(i18n, namespaces, onLoaded);<br>      }<br>    }<br>  }, [i18n, props.lng, namespaces, ready, useSuspense, loadCount]);</pre><p>useEffect내에서 이를 처리해 loadLanguages(loadNamespaces)로직을 리액트 생명주기와 동기화한다.</p><ul><li><strong>i18next의 내부 상태를 react와 동기화</strong></li></ul><p>무엇보다, i18next는 react 밖의 로직이므로, 이를 react render cycle과 연동시켜야한다. <a href="https://ko.react.dev/reference/react/useSyncExternalStore">useSyncExternalStore</a>은 외부 store를 react 세계로 끌어온다.</p><pre>const { t, ready } = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);</pre><p>i18next의 역할에 대해선 추후 살펴보자.</p><ul><li>그 외</li></ul><p>이외 많은 역할이 있으나, 내 이해력과 시간으로 인해 남겨두겠다. 소스코드는 <a href="https://github.com/i18next/react-i18next/blob/master/src/useTranslation.js">여기서</a> 확인할 수 있다.</p><h3>Core Responsibilities</h3><p>그럼, 코어 로직을 담는 i18next가 뭐하는 것일까?</p><ul><li>use API를 통한 플러그인 연동</li></ul><pre>  use(module) {<br>    if (!module) throw new Error(&#39;You are passing an undefined module! Please check the object you are passing to i18next.use()&#39;)<br>    if (!module.type) throw new Error(&#39;You are passing a wrong module! Please check the object you are passing to i18next.use()&#39;)<br><br>    if (module.type === &#39;backend&#39;) {<br>      this.modules.backend = module;<br>    }<br><br>    if (module.type === &#39;logger&#39; || (module.log &amp;&amp; module.warn &amp;&amp; module.error)) {<br>      this.modules.logger = module;<br>    }<br><br>    if (module.type === &#39;languageDetector&#39;) {<br>      this.modules.languageDetector = module;<br>    }<br><br>    if (module.type === &#39;i18nFormat&#39;) {<br>      this.modules.i18nFormat = module;<br>    }<br><br>    if (module.type === &#39;postProcessor&#39;) {<br>      postProcessor.addPostProcessor(module);<br>    }<br><br>    if (module.type === &#39;formatter&#39;) {<br>      this.modules.formatter = module;<br>    }<br><br>    if (module.type === &#39;3rdParty&#39;) {<br>      this.modules.external.push(module);<br>    }<br><br>    return this;<br>  }</pre><ul><li>인스턴스 초기화</li></ul><p>설정 옵션으로 i18next 인스턴스를 초기화한다.</p><ul><li>리소스 관리</li></ul><pre>this.store = new ResourceStore(this.options.resources, this.options);</pre><p>loadNamespaces, loadLanguages와 같은 API를 제공하고,</p><p>init 메서드의 option으로 설정한 resource를 <strong>ResourceStore</strong>에 등록한다.</p><ul><li>번역 인터페이스 제공</li></ul><p>react와 독립적인 t, getFixedT function을 제공한다.</p><ul><li>이벤트</li></ul><p>changeLanguages와 같은 이벤트 API를 제공한다.</p><ul><li>그외</li></ul><p><a href="https://www.i18next.com/overview/api">API | i18next documentation</a></p><h3>결론</h3><ul><li>i18n 로직 자체는 i18next의 API로 제공된다.</li><li>i18next는 내부 자체 스토어로 동작한다.</li><li>i18next의 로직과 스토어를 react 컴포넌트 트리 &amp; 생명주기와 연동하며, 최적화를 할 필요가 존재해 react-i18next를 사용한다.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8dff2ec23943" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[react-i18next 갖고 놀기]]></title>
            <link>https://medium.com/@nayounsang722/react-i18next-%EA%B0%96%EA%B3%A0-%EB%86%80%EA%B8%B0-ca389185591f?source=rss-c7562bbf0193------2</link>
            <guid isPermaLink="false">https://medium.com/p/ca389185591f</guid>
            <category><![CDATA[i18next]]></category>
            <category><![CDATA[react-i18next]]></category>
            <category><![CDATA[i18n]]></category>
            <dc:creator><![CDATA[Nayounsang]]></dc:creator>
            <pubDate>Tue, 06 Jan 2026 06:51:30 GMT</pubDate>
            <atom:updated>2026-01-06T07:51:34.589Z</atom:updated>
            <content:encoded><![CDATA[<p><a href="https://flex.team/">flex</a>와 미팅에서, 합류시 다국어 적용 플랫폼 작업을 할 예정이라 했다. 저번 스타트업에선, 속도감있게 서비스에 i18n을 적용하느라 기술적인 digging이 전혀 없어 아쉬웠다. (물론, 속도를 최우선 가치를 둔 개발이 어떤 모습으로 흘러가는지 알았고, 이에 따른 기여를 할 수 있는 좋은 경험이었다.)</p><p>이참에 i18n에 대한 여러 고려사항과 기획/디자인/개발 직군을 아우르는 효율적인 플랫폼을 개선하고자 한다.</p><h3>구현해볼 것</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/958/1*OCelzsoXB1-BOpPNqIuA3A.png" /><figcaption>DECO27 — 뱀파이어의 가사를 한/영/일로 확인 가능</figcaption></figure><ul><li>react-i18next로 i18n 환경을 구축한다.</li><li>어떤 노래가사를 한/영/일로 보여주도록 한다.</li><li>다국어 리소스 파일을 런타임에서 불러오도록 한다.</li><li>디국어 리소스 파일을 서빙하는 서버를 만든다.</li></ul><h3>기술 스택 디자인</h3><ul><li>react-i18next</li><li>react-ts template@vite</li><li>express</li><li>pnpm monorepo(어쨌든, 모노레포면 편하게 토이프로젝트 만들 수 있다.)</li></ul><h3>i18next 환경 설정</h3><pre>import i18next from &quot;i18next&quot;;<br>import { initReactI18next } from &quot;react-i18next&quot;;<br>import Backend from &quot;i18next-http-backend&quot;;<br>//import koTranslation from &quot;./locales/ko/translation.json&quot;;<br><br>i18next<br>  .use(initReactI18next) // passes i18n down to react-i18next<br>  .use(Backend)<br>  .init({<br>    backend: {<br>      crossDomain: true,<br>      withCredentials: false,<br>      loadPath: &quot;http://localhost:3001/api/locales/{{lng}}/{{ns}}.json&quot;,<br>    },<br>    // the translations<br>    // (tip move them in a JSON file and import them,<br>    // or even better, manage them via a UI: https://react.i18next.com/guides/multiple-translation-files#manage-your-translations-with-a-management-gui)<br>    // resources: {<br>    //   ko: {<br>    //     translation: koTranslation,<br>    //   },<br>    // },<br>    lng: &quot;ko&quot;, // if you&#39;re using a language detector, do not define the lng option<br>    fallbackLng: &quot;ko&quot;,<br><br>    interpolation: {<br>      escapeValue: false, // react already safes from xss =&gt; https://www.i18next.com/translation-function/interpolation#unescape<br>    },<br>  });</pre><p>i18next, i18next-react 로 기본 설정을 한다. use를 이용해 플러그인을 등록하는 디자인이다.</p><p>default locale은 한국, 미지원 언어 역시 한국으로 fallback되도록 했다.</p><p>특이한 점은 i18next-http-backend 의 Backend plugin인데, 이것으로 런타임에 리소스를 불러오는 것을 편하게 셋팅 가능하다.</p><p>따라서, resources option을 주석 처리했다. <a href="https://github.com/i18next/i18next-http-backend">backend option</a>을 통해 런타임에 어떻게 불러올것인지 지정 가능하다. loadPath로 불러올 end point를 지정했다.</p><p>이제, 이 모듈을 index.tsx에서 import해 side-effect를 발생시키면 설정 완료!</p><h3>서버 디자인</h3><p>이제, loadPath에 지정한 endpoint에 GET 요청 날리면 리소스 json파일을 반환하면 된다.</p><pre>import express from &quot;express&quot;;<br>import cors from &quot;cors&quot;;<br>import { readFileSync } from &quot;fs&quot;;<br>import { join, dirname } from &quot;path&quot;;<br>import { fileURLToPath } from &quot;url&quot;;<br><br>const __filename = fileURLToPath(import.meta.url);<br>const __dirname = dirname(__filename);<br><br>const app = express();<br>const PORT = process.env.PORT || 3001;<br><br>app.use(cors());<br>app.use(express.json());<br><br>// 번역 파일 제공 엔드포인트<br>app.get(&quot;/api/locales/:lng/:ns.json&quot;, async (req, res) =&gt; {<br>  const { lng, ns } = req.params;<br><br>  try {<br>    // 로딩 상태 확인을 위한 2초 지연<br>    await new Promise((resolve) =&gt; setTimeout(resolve, 2000));<br><br>    const filePath = join(__dirname, &quot;locales&quot;, lng, `${ns}.json`);<br>    const translationFile = readFileSync(filePath, &quot;utf-8&quot;);<br>    const translation = JSON.parse(translationFile);<br><br>    res.json(translation);<br>  } catch (error) {<br>    console.error(`Error loading translation file: ${error}`);<br>    res.status(404).json({ error: &quot;Translation file not found&quot; });<br>  }<br>});<br><br>app.listen(PORT, () =&gt; {<br>  console.log(`🚀 Server is running on http://localhost:${PORT}`);<br>});</pre><p>이정도는 뭐, vibe-coding으로 했다…ㅎㅎ</p><p>서버에 한영일 json파일을 각각 준비했고, 적절한걸 리턴하는 api다.</p><pre>{<br>  &quot;language&quot;: &quot;언어:&quot;,<br>  &quot;title&quot;: &quot;뱀파이어&quot;,<br>  &quot;lyrics&quot;: {<br>    &quot;line1&quot;: &quot;나는 뱀파이어&quot;,<br>    &quot;line2&quot;: &quot;좋아? 빨아도 돼?&quot;,<br>    &quot;line3&quot;: &quot;\&quot;더 이상 무리야 더 이상 무리야\&quot;라고 하는 건 나쁜 아이네&quot;,<br>    &quot;line4&quot;: &quot;시도해보고 싶어 가득 채워서 토하고 싶어 아직 절대 할 수 있어&quot;,<br>    &quot;line5&quot;: &quot;최저 최고 계속 오가고 있어&quot;,<br>    &quot;line6&quot;: &quot;달콤해지는 불안의 열매&quot;,<br>    &quot;line7&quot;: &quot;No more 발전 질투하며 숨을 쉬어도&quot;,<br>    &quot;line8&quot;: &quot;필요 없을 뿐 시끄러울 뿐&quot;,<br>    &quot;line9&quot;: &quot;누군가와 함께라면 그건 \&quot;만약에\&quot;일 뿐&quot;,<br>    &quot;line10&quot;: &quot;강하게 구는 것도 감정에는 거스를 수 없어&quot;,<br>    &quot;line11&quot;: &quot;떨어져 있어도 느껴지는 감정&quot;,<br>    &quot;line12&quot;: &quot;연결되어 확인하면 죽을 수도 있어&quot;,<br>    &quot;line13&quot;: &quot;좋은 것 슬픈 것 아픈 것&quot;,<br>    &quot;line14&quot;: &quot;너의 모든 것을 먹어치울 때까지 절규&quot;,<br>    &quot;line15&quot;: &quot;나는 뱀파이어&quot;,<br>    &quot;line16&quot;: &quot;좋아? 빨아도 돼?&quot;,<br>    &quot;line17&quot;: &quot;\&quot;더 이상 무리야 더 이상 무리야\&quot;라고 하는 건 나쁜 아이네&quot;,<br>    &quot;line18&quot;: &quot;시도해보고 싶어 가득 채워서 토하고 싶어 아직 절대 할 수 있어&quot;,<br>    &quot;line19&quot;: &quot;나는 뱀파이어&quot;,<br>    &quot;line20&quot;: &quot;원해서 다시 말라버리고 싶어 저런 느낌&quot;,<br>    &quot;line21&quot;: &quot;울고 잊어버리면 \&quot;처음 뵙겠습니다\&quot;&quot;,<br>    &quot;line22&quot;: &quot;나는 뱀파이어&quot;,<br>    &quot;line23&quot;: &quot;애정을 주세요 아직 절대 할 수 있어&quot;,<br>    &quot;line24&quot;: &quot;나는 뱀파이어 먼저 이쪽으로 와&quot;,<br>    &quot;line25&quot;: &quot;비밀의 마음 솔직하게 토해내면 \&quot;맞아\&quot;뿐&quot;,<br>    &quot;line26&quot;: &quot;갈라지지 않지만 남은 게 아니야 살짝 아침까지 길막&quot;,<br>    &quot;line27&quot;: &quot;반복되는 싫어 제멋대로는 공짜&quot;,<br>    &quot;line28&quot;: &quot;욕심내서 또 기회를 놓치는 거야&quot;,<br>    &quot;line29&quot;: &quot;병들지 않아도 이루고 싶지만&quot;,<br>    &quot;line30&quot;: &quot;겹쳐서 눌러 부서져버릴 수도 있어&quot;,<br>    &quot;line31&quot;: &quot;좋은 것 슬픈 것 아픈 것&quot;,<br>    &quot;line32&quot;: &quot;너의 모든 것을 먹어치울 때까지&quot;,<br>    &quot;line33&quot;: &quot;좋지 않아 즐겁지 않아 기분 좋지 않아&quot;,<br>    &quot;line34&quot;: &quot;익사할 때까지가 버릇이 되네 절규&quot;,<br>    &quot;line35&quot;: &quot;나는 뱀파이어&quot;,<br>    &quot;line36&quot;: &quot;좋아? 빨아도 돼?&quot;,<br>    &quot;line37&quot;: &quot;\&quot;더 이상 무리야 더 이상 무리야\&quot;라고 하는 건 나쁜 아이네&quot;,<br>    &quot;line38&quot;: &quot;시도해보고 싶어 가득 채워서 토하고 싶어 아직 절대 할 수 있어&quot;,<br>    &quot;line39&quot;: &quot;너도 뱀파이어&quot;,<br>    &quot;line40&quot;: &quot;좋아 빨아도 돼&quot;,<br>    &quot;line41&quot;: &quot;\&quot;더 이상 무리야 더 이상 무리야\&quot;라고 말하게 해주고 싶어&quot;,<br>    &quot;line42&quot;: &quot;너 외에는 절대 안 돼 자 시켜줘&quot;,<br>    &quot;line43&quot;: &quot;너도 뱀파이어&quot;,<br>    &quot;line44&quot;: &quot;원해서 다시 말라버리고 싶어 지금 몇 번째?&quot;,<br>    &quot;line45&quot;: &quot;별이 보이는 듯한 거품 속에서&quot;,<br>    &quot;line46&quot;: &quot;너도 뱀파이어&quot;,<br>    &quot;line47&quot;: &quot;연장을 주세요 아직 절대 할 수 있어&quot;,<br>    &quot;line48&quot;: &quot;너도 뱀파이어 먼저 이쪽으로 와&quot;,<br>    &quot;line49&quot;: &quot;Na-na-na-na, na-na-na-na-na-na&quot;,<br>    &quot;line50&quot;: &quot;Na-na-na-na, na-na-na-na-na-na&quot;,<br>    &quot;line51&quot;: &quot;Na-na-na-na, na-na-na-na-na-na&quot;,<br>    &quot;line52&quot;: &quot;절대 할 수 있어&quot;<br>  }<br>}</pre><p>이런식으로 value에 텍스트 컨텐츠를 지정하면 된다.</p><p>여기서, 리소스 파일을 만들때 알아야하는 것은</p><ul><li>로케일: 지역(한국, 영어, 중국어 등), json파일의 경로로 보통 표현한다.</li><li>namepsace: 한 로케일의 서브 그룹, json파일의 이름으로 보통 표현한다. 도메인, 페이지등 특정 기준으로 나눌때 사용한다. i18next가 사용하는 default namespace는 translation이다.</li></ul><p>즉, locales/en/translation.json은 locale이 en(영어)고 namepsace 이름은 trnaslation이다.</p><h3>언어 바꾸기</h3><pre>        &lt;select<br>            id=&quot;language-select&quot;<br>            value={i18n.language}<br>            onChange={handleLanguageChange}<br>            disabled={isLoading}<br>            style={{<br>              padding: &#39;0.5rem&#39;,<br>              fontSize: &#39;1rem&#39;,<br>              border: &#39;1px solid #ccc&#39;,<br>              borderRadius: &#39;4px&#39;,<br>              cursor: isLoading ? &#39;wait&#39; : &#39;pointer&#39;,<br>              opacity: isLoading ? 0.6 : 1<br>            }}<br>          &gt;<br>            &lt;option value=&quot;ko&quot;&gt;한국어&lt;/option&gt;<br>            &lt;option value=&quot;en&quot;&gt;English&lt;/option&gt;<br>            &lt;option value=&quot;ja&quot;&gt;日本語&lt;/option&gt;<br>          &lt;/select&gt;</pre><pre>  const { i18n, t } = useTranslation()<br><br>  const handleLanguageChange = async (e: React.ChangeEvent&lt;HTMLSelectElement&gt;) =&gt; {<br>    const newLanguage = e.target.value<br>    await i18n.changeLanguage(newLanguage)<br>  }</pre><p>i18n.changeLanguage api로 언어를 바꿀 수 있다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/380/1*Ctr_NhYLaPdloyeLH1vohg.png" /></figure><h3>리소스 접근하기</h3><pre>            &lt;h2&gt;{t(&#39;title&#39;)}&lt;/h2&gt;<br>            &lt;img src=&quot;/cover.png&quot; alt=&quot;cover&quot; /&gt;<br>            &lt;ul style={{ listStyle: &#39;none&#39;, padding: 0 }}&gt;<br>              &lt;li&gt;{t(&#39;lyrics.line1&#39;)}&lt;/li&gt;<br>              &lt;li&gt;{t(&#39;lyrics.line2&#39;)}&lt;/li&gt;<br>              &lt;li&gt;{t(&#39;lyrics.line3&#39;)}&lt;/li&gt;<br>              &lt;li&gt;{t(&#39;lyrics.line4&#39;)}&lt;/li&gt;</pre><p>t function을 이용해 resource file에 접근한다. useTranslation의 인수로 namepsace를 넘길 수 있다. 아무것도 남기지 않은 경우 default namepsace를 사용한다.</p><p>.으로 중첩된 json 구조를 지원한다.</p><h3>런타임 로딩상태 관리</h3><p>런타임으로 리소스를 불러오므로, 로딩상태를 관리할 필요가 있다.</p><p>i18n.changeLanguage 는 Promise&lt;Tfunction&gt; 을 반환한다. 언어가 적용된 이후에 Promise가 resolve된다.</p><pre>  const { i18n, t } = useTranslation()<br>  const [isLoading, setIsLoading] = useState(false)<br><br>  const handleLanguageChange = async (e: React.ChangeEvent&lt;HTMLSelectElement&gt;) =&gt; {<br>    const newLanguage = e.target.value<br>    setIsLoading(true)<br>    try {<br>      await i18n.changeLanguage(newLanguage)<br>    } catch (error) {<br>      console.error(&#39;Language change error:&#39;, error)<br>    } finally {<br>      setIsLoading(false)<br>    }<br>  }</pre><p>따라서, 이를 이용해 로딩 상태를 관리할 수 있다.</p><h3>남은 과제</h3><p>실제 상황을 가정해, 2초의 지연을 줬다. 기본언어(한국어)를 로드할때도 지연으로 인해 랜더링이 오랫동안 되지 않는다! 따라서, 이를 해결할 수 없을까?</p><p>실제 서비스의 리소스 파일은 무척이나 클 것이다. 이것은 직접 실무를 뛰며 배워가야지…</p><p>스트리밍, 페이지별로 namespace를 나눠 현재 보고 있는 페이지의 리소스를 우선적으로 불러오는 방식, 번들 + 런타임 하이브리드(i18next에서 지원될까?)가 생각난다.</p><h3>코드</h3><p><a href="https://github.com/nayounsang/i18next-practice">https://github.com/nayounsang/i18next-practice</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ca389185591f" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>