Bobostown

[Inteview-lab] AudioContext를 사용하여 오실리에이터 UI 만들기

월월월월 — Thu, 5 Feb 2026 22:49:31 +0900

사용자의 음성이 인식되고 있다는 것을 표현하기 위해 Oscillator 컴포넌트를 만들었습니다.

피그마 디자인

음성이 인식되고 있다는 것을 사용자에게 피드백하기 위해 위와 같은 컴포넌트를 디자인 했습니다.

이 디자인의 핵심은 사용자의 음성을 주파수의 파형으로 보여주는 오실리에이터입니다.

오실리에이터를 제가 어떻게 구현했는지 설명드리겠습니다.

1. Media Capture and Streams API를 사용하여 음성데이터 가져오기

사용자의 음성을 시각화하는 것이므로 가장 먼저 해야하는 것은 음성 데이터를 가져오는 것입니다.

이를 위해 Media Capture and Streams API의 MediaDevices의 getUserMedia 메서드를 사용하여 마이크 권한을 요청하고 반환값으로 MediaStream을 받습니다.

const mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true })

2. AudioContext를 사용하여 MediaStreamAudioSourceNode 객체 생성하기

AudioContext란?

Web Audio API는 노드 기반 아키텍처를 사용합니다. 오디오 소스(Source) → 처리(Processing) → 출력(Destination)으로 이어지는 노드들을 연결하여 오디오 파이프라인을 구성하는데, AudioContext가 이 노드들을 생성하고 연결하는 역할을 합니다.

[MediaStream] → [SourceNode] → [AnalyserNode] → [Destination]
↑ AudioContext가 생성

MediaStream을 재생이나 조작하기 위해서는 MediaStreamAudioSourceNode 객체를 생성해야합니다.

const source = audioContext.createMediaStreamSource(mediaStream)

3. 주파수 분석을 위해 AnalyserNode 생성하기

AnalyserNode 인터페이스는 실시간 주파수와 시간 영역 분석 정보를 제공 가능한 노드를 표현합니다. 이것은 변경되지 않은 오디오 스트림을 입력에서 출력으로 전달하지만, 여러분은 생성된 데이터를 얻고, 그것을 처리하고, 오디오 시각화를 생성할 수 있습니다.

const analyser = audioContext.createAnalyser();
analyser.fftSize = 64;

source.connect(analyser);

FFT(Fast Fourier Transform)는 시간 영역의 오디오 신호를 주파수 영역으로 변환하는 알고리즘입니다. fftSize는 한번의 FFT 분석에 사용할 샘플 수를 결정하며, 값이 클수록 주파수 해상도는 높아지지만 시간 반응성은 낮아집니다.

4. 주파수 데이터를 저장할 배열 생성하기

AnalyserNode에서 추출한 주파수 데이터를 저장할 Uint8Array를 생성합니다.

const dataArray = new Uint8Array(analyser.frequencyBinCount);

frequencyBinCount는 fftSize / 2 값으로, 분석 결과로 얻을 수 있는 주파수 구간의 개수입니다. fftSize가 64이므로 32개의 주파수 데이터를 얻게 됩니다. 각 요소는 0~255 범위의 값을 가지며, 해당 주파수 대역의 볼륨을 나타냅니다.

5. requestAnimationFrame으로 시각화 애니메이션 구현하기

실시간 시각화를 위해 requestAnimationFrame을 사용하여 매 프레임마다 주파수 데이터를 갱신하고 화면에 그립니다.

const draw = () => {
    analyser.getByteFrequencyData(dataArray);
    drawBars(ctx, width, height, dataArray);
    animationIdRef.current = requestAnimationFrame(draw);
  };
  draw();

저는 프로젝트에서 React를 사용해서 animationId를 ref에 저장했습니다.

6. drawBars 함수로 막대 그래프 그리기

 const BAR_WIDTH = 4;
  const BAR_GAP = 2;
  const BAR_MIN_HEIGHT = 8;
  const BAR_RADIUS = 2;
  const BAR_COLOR = 'rgba(255, 255, 255, 0.6)';

  const drawBars = (
    ctx: CanvasRenderingContext2D,
    width: number,
    height: number,
    dataArray: Uint8Array,
  ) => {
    ctx.clearRect(0, 0, width, height);

    const barCount = Math.min(
      Math.floor(width / (BAR_WIDTH + BAR_GAP)),
      dataArray.length,
    );
    const totalWidth = barCount * (BAR_WIDTH + BAR_GAP) - BAR_GAP;
    const startX = (width - totalWidth) / 2;
    const centerY = height / 2;

    ctx.fillStyle = BAR_COLOR;

    const mul = Math.floor(dataArray.length / barCount);

    for (let i = 0; i < barCount; i++) {
      let sum = 0;
      for (
        let dataIndex = i * mul;
        dataIndex < (i + 1) * mul && dataIndex < dataArray.length;
        dataIndex++
      ) {
        sum += dataArray[dataIndex];
      }
      const avg = sum / mul;

      const barHeight = (avg / 255) * (height * 0.8);
      const clampedHeight = Math.max(barHeight, BAR_MIN_HEIGHT);
      const x = startX + i * (BAR_WIDTH + BAR_GAP);
      const y = centerY - clampedHeight / 2;

      ctx.beginPath();
      ctx.roundRect(x, y, BAR_WIDTH, clampedHeight, BAR_RADIUS);
      ctx.fill();
    }
  };

결과

https://www.youtube.com/watch?v=4MB5F7jrZc0

위와 같이 사용자가 말하면 주파수 파형을 보여주는 컴포넌트를 만들었습니다.

처음 다루어보는 Web API라 우여곡절이 많았지만 잘 작동하네요.☺️

[Claude code] Cluade code 알림 설정하기

월월월월 — Mon, 5 Jan 2026 16:33:44 +0900

Claude Code에게 오래 걸리는 작업을 명령한 후, 작업이 완료되기만을 기다리며 화면만 바라본 경험이 있지 않으신가요?

저 역시 /init 같은 명령어를 입력하고 작업이 끝날 때까지 무작정 기다린 적이 있습니다.

하지만 이 시간이 아깝지 않나요? Claude가 작업을 빠르게 마친다면 문제없겠지만, 오랜 시간이 걸린다면 그 시간 동안 다른 일을 하는 것이 훨씬 생산적일 것입니다.

이를 위해 Claude code에서는 알림을 설정할 수 있습니다.

알림 설정 방법은 2가지 방법으로 할 수 있습니다.

terminal의 알림 기능 사용하기 (iterm2만 가능)
Claude code 훅 사용하기

Terminal의 알림 기능 사용하기

terminal의 notification 기능을 사용하는 것은 iterm2만 가능합니다.

1. Iterm2의 설정에 들어갑니다.

2. Profile 탭에서 Terminal 탭을 들어갑니다.

3. 스크롤을 아래로 내려서 Silence bell을 체크합니다.

4. Notification Center Alerts를 체크하고 Filter Alerts 버튼을 누릅니다.

5. Send escape sequence-generated alerts를 체크합니다.

설정을 완료하면 Claude code가 작업을 완료하면 다음과 같이 알림을 볼 수 있습니다.

Claude code 훅 사용하여 알림 받기

Claude code 훅 이란?

Claude Code 훅은 Claude Code의 라이프사이클의 다양한 지점에서 실행되는 사용자 정의 셸 명령어입니다.

Claude code 훅의 사용사례는 다음과 같습니다.

알림
자동 포맷팅
로깅
피드백
사용자 정의 권한

Claude code는 다음의 훅 이벤트를 제공합니다.

PreToolUse: 도구 호출 전에 실행됩니다(차단 가능).
PostToolUse: 도구 호출 완료 후 실행됩니다.
UserPromptSubmit: 사용자가 프롬프트를 제출할 때, Claude가 처리하기 전에 실행됩니다.
Notification: Claude Code가 알림을 보낼 때 실행됩니다.
Stop: Claude Code가 응답을 마칠 때 실행됩니다.
SubagentStop: 서브에이전트 작업이 완료될 때 실행됩니다.
PreCompact: Claude Code가 컴팩트 작업을 실행하려고 할 때 실행됩니다.
SessionStart: Claude Code가 새 세션을 시작하거나 기존 세션을 재개할 때 실행됩니다.
SessionEnd: Claude Code 세션이 종료될 때 실행됩니다.

Claude code 훅은 다음 파일에서 작성할 수 있습니다.

~/.claude/settings.json - 사용자 설정
.claude/settings.json - 프로젝트 설정
.claude/settings.Local.json - 로컬 프로젝트 설정 (커밋되지 않음)
Enterprise 관리 정책 설정

Claude code 훅을 사용하여 알림 받기 (맥 버전)

저는 전역적으로 설정을 하고 싶기 때문에 ~/.claude/settings.json에 작성을 하겠습니다.

setting.json에 다음의 내용을 붙여 넣습니다.

{
  ...
  "hooks": {
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Funk.aiff"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Submarine.aiff"
          }
        ]
      }
    ]
  }
}

맥의 /System/Library/Sounds 디렉토리에는 다양한 소리 파일이 있는데 취향 것 설정하시면 될 것 같습니다.

Claude code 훅을 통한 알림 설정은 이 블로그를 참고했습니다.

https://velog.io/@leochoo/Claude-Code-%EC%95%8C%EB%A6%BC%EC%9D%8C-%EC%84%A4%EC%A0%95%ED%95%98%EA%B8%B0-%ED%84%B0%EB%AF%B8%EB%84%90-%EB%A9%8D%EB%95%8C%EB%A6%AC%EA%B8%B0%EB%8A%94-%EC%9D%B4%EC%A0%9C-%EA%B7%B8%EB%A7%8C

Claude Code 알림음 설정하기: "터미널 멍때리기"는 이제 그만!

요약: Claude Code가 작업이 끝나거나 입력이 필요할 때, 소리로 알려주는 Hook 설정 꿀팁입니다.Claude Code에게 작업을 시켜두면 짧게는 몇 초, 길게는 몇 분, 혹은 정말 긴 작업은 몇십분이 걸리기도

velog.io

해당 블로그에 맥뿐만이 아니라 윈도우와 리눅스 설정 방법도 있으니 참고하시면 좋을 것 같습니다.

[Next.js] Next.js 어플리케이션에 i18n 구현하기

월월월월 — Mon, 15 Dec 2025 22:12:30 +0900

이번 일주일 동안 저번 포스팅에서 만든 UI 라이브러리를 가지고 압축 사이트를 만들었습니다.

https://www.runzipper.app/

Runzipper

ZIP, TAR, TAR.GZ 형식을 지원하는 브라우저 기반 파일 압축 및 아카이브 도구입니다. 서버 업로드 없이, 설치 불필요하며, 완벽한 개인정보 보호를 제공합니다. 모든 압축 처리는 사용자의 기기에서

www.runzipper.app

제가 이 프로젝트를 시작한 계기는 간단한 툴을 웹서비스 형태로 제공하여 방문자수를 모니터링하고 싶어서였습니다.

이 서비스를 사용하는 사람이 충분하다면 광고를 추가하여 수익을 창출하는 것도 고려하고 있습니다.

❓ 다양한 툴 중에 왜 압축 사이트를 만들었나요?

일반 컴퓨터 사용자는 보통 압축, 압축해제를 하려면 반디집 같은 압축 프로그램을 설치하여 사용합니다.

압축 프로그램을 브라우저에서 구현하면 설치도 필요 없고, 서버로 정보가 넘어가지도 않으니 프라이버시도 지킬 수 있습니다.
특히, 설치가 필요 없다는 점에서 상용 소프트웨어에 비해 경쟁력을 가질 수 있지 않을까 하여 브라우저에서 실행되는 압축 프로그램을 만들었습니다.

방문자수를 높일 수 있는 방법이 뭐가 있을까 고민했을 때 첫 번째로 떠오르는 것은 전 세계 사람들을 대상으로 서비스하는 것이었습니다.

그래서 runzipper에 국제화를 적용하기로 했습니다.

dictionary 만들기

사실 저는 i18n을 구현하는 게 처음입니다.

그래서 next.js 공식문서의 internationalization 섹션을 참고하였고, 많은 부분을 따라서 만들었습니다.

제가 가장 먼저 한 것은 하드 코딩된 텍스트를 json 형태의 dictionary로 정리하는 것입니다.

만약 영어, 한국어, 일본어, 중국어를 지원한다면

en.json
ko.json
ja.json
zh.json

등의 dictionary를 만들면 됩니다.

하지만 무장적 json 파일을 작성하면 실수할 가능성이 높겠죠?

그래서 저는 안정성을 위해 json schema 파일을 먼저 작성했습니다.

json schema 작성하기

json schema는 타입스크립트에 비유할 수 있습니다.

타입스크립트는 타입이나 인터페이스를 정의하여 코더에게 형식을 제한할 수 있잖아요?

json schema는 json 버전의 인터페이스라고 이해하시면 됩니다.

json schema를 작성하는 방법은 이 문서에 나와있습니다.

저는 dictionary.schema.json 파일을 만들어서 스키마를 정의했습니다.

// dictionary.schema.json
{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"title": "Dictionary Schema",
	"description": "Schema for application dictionary files",
	"type": "object",
	"properties": {
		"meta": {
			//...
		},
		"compress": {
			//...
		},
		"header": {
			//...
		},
		"footer": {
			//...
	},
	"required": [
		//...
	]
}

위와 같이 레이아웃, 메타 데이터, 페이지 단위로 데이터를 정의하였습니다.

필수로 넣어야 하는 필드인 경우 required 배열에 key를 추가합니다.

json dictionary 작성하기

json schema를 정의했으니 이를 사용하여 dictionary를 작성하겠습니다.

딕셔너리를 작성할 때 먼저 $schema 키에 값으로 앞서 작성한 json schema의 url을 넣어줍니다.

// ko.json
{
	"$schema": "./dictionary.schema.json",
	//...
}

이렇게 하면 에디터에서 자동완성이 지원되고, 필수 값이 누락됐을 경우 경고 표시를 해줍니다.

dictionary 유틸 만들기

dictionary를 정의했으니 이를 사용하기 위한 유틸 함수들을 만들겠습니다.

이 코드 또한 next.js 공식문서에서 가져왔습니다.

// utils/dictionary.ts

// 앞서 정의한 dictionary를 로딩하는 함수
export const dictionaries = {
	ko: () =>
		import('@/docs/dictionanaries/kr.json').then((module) => module.default),
	en: () =>
		import('@/docs/dictionanaries/en.json').then((module) => module.default),
	ja: () =>
		import('@/docs/dictionanaries/ja.json').then((module) => module.default),
	zh: () =>
		import('@/docs/dictionanaries/zh.json').then((module) => module.default),
	de: () =>
		import('@/docs/dictionanaries/de.json').then((module) => module.default),
	pl: () =>
		import('@/docs/dictionanaries/pl.json').then((module) => module.default),
	es: () =>
		import('@/docs/dictionanaries/es.json').then((module) => module.default),
	fr: () =>
		import('@/docs/dictionanaries/fr.json').then((module) => module.default),
	it: () =>
		import('@/docs/dictionanaries/it.json').then((module) => module.default),
} as const;

export type Locale = keyof typeof dictionaries;

// string 타입을 좁히는 함수
export const hasLocale = (locale: string): locale is Locale => {
	return Object.keys(dictionaries).includes(locale);
};

// locale에 따른 dictionary를 get하는 함수
export const getDictionary = async (locale: Locale) => dictionaries[locale]();

Route 수정하기

다중 언어를 지원하려면 언어별로 route가 필요합니다.

예를 들어 /compress이라는 경로가 있고

영어
일본어
한국어

를 지원한다면

/en/compression
/ja/compression
/ko/compression

3개의 route가 필요합니다.

이를 위해 폴더 구조를 /compress에서 /[slug]/compress 형태로 변경했습니다.

Proxy.ts에서 언어 감지하기

사용자가 지원하지 않는 언어로 접근하거나 url에 언어(slug)가 포함이 안 돼있을 시를 처리하기 위해 next.js의 proxy를 사용했습니다.

사용자가 /[lang]/compress가 아닌 /compress로 접속했을 때는 요청 헤더의 accept-language를 파싱 하여

해당 언어를 지원하면 /[해당 언어]/compress로 리다이렉트 시키고,

지원하지 않는다면 /en/compress로 리다이렉트 시키도록 만들었습니다.

// proxy.ts

import { dictionaries } from '@/utils/dictionary';
import { type NextRequest, NextResponse } from 'next/server';

// 지원하지 않는 언어로 접속시 기본 언어
const DEFAULT_LANGUAGE = 'en';

// 지원하는 언어 목록
const localList = Object.keys(dictionaries);

export function proxy(request: NextRequest) {
	const { pathname } = request.nextUrl;
	const pathnameHasLocale = localList.some(
		(locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`,
	);

	// 사용자의 요청이 /lang/~ 일 때
	if (pathnameHasLocale) return;

	// 사용자의 요청이 /lang/~ 형식이 아닐 때
	const acceptLanguage = request.headers.get('accept-language') || '';
	const primaryLanguage = acceptLanguage
		.split(',')[0]
		.split(';')[0]
		.trim()
		.split('-')[0];

	const locale =
		localList.find((locale) => locale === primaryLanguage) || DEFAULT_LANGUAGE;

	request.nextUrl.pathname = `/${locale}${pathname}`;

	return NextResponse.redirect(request.nextUrl);
}

언어별 route에 static site generation 적용하기

Dictionary에 저희가 페이지에서 사용할 텍스트가 모두 정의돼 있으니 동적 렌더링을 할 이유가 전혀 없습니다.

SSG를 적용하기 위해 [lang] 폴더의 layout.tsx에 generateStaticparams를 선언하였습니다.

// src/app/[lang]/layout.tsx

export async function generateStaticParams() {
	return Object.keys(dictionaries).map((lang) => ({ lang }));
}

export default async function Layout({
	children,
	params,
}: LayoutProps<'/[lang]'>) {
	const locale = (await params).lang;

	if (!hasLocale(locale)) notFound();

	return (
		<html lang={(await params).lang}>
			<body className={bodyStyle}>
				<DictionaryProvider dictionary={await dictionaries[locale]()}>
					<Header lang={locale} />
					{children}
					<Footer lang={locale} />
				</DictionaryProvider>
			</body>
		</html>
	);
}

다음과 같이 지원하는 언어들에 대한 정적페이지를 생성하였습니다.

추가적으로 layout 컴포넌트에서 알아낸 딕셔너리 정보를 자식 컴포넌트에게 전달해야 하는데 저 같은 경우 Provider를 사용하여 전달했습니다.

언어에 따른 메타데이터 제공하기

저는 눈에 보이는 정보뿐만이 아니라 메타데이터도 국제화를 적용하고 싶어서 dictionary를 정의할 때 메타데이터도 각 국가의 언어로 작성했습니다.

generateMetadata 함수를 선언하여 언어에 따른 메타데이터를 생성하였습니다.

// src/app/[lang]/layout.tsx

type MetadataProps = {
	params: Promise<{ lang: string }>;
};

export async function generateMetadata({
	params,
}: MetadataProps): Promise<Metadata> {
	const locale = (await params).lang;

	if (!hasLocale(locale)) {
		return {};
	}

	const dictionary = await dictionaries[locale]();

	return {
		title: 'Runzipper',
		description: dictionary.meta.description,
		manifest: '/site.webmanifest',
		appleWebApp: {
			title: 'Runzipper',
		},
		icons: {
			icon: [
				{ url: '/favicon.ico' },
				{ url: '/favicon.svg', type: 'image/svg+xml' },
				{ url: '/favicon-96x96.png', sizes: '96x96', type: 'image/png' },
			],
			apple: { url: '/apple-touch-icon.png', sizes: '180x180' },
			shortcut: '/favicon.ico',
		},
	};
}

SEO를 위해 언어별 sitemap 정의하기

프로젝트 목표는 방문자수 확보이므로 SEO는 필수입니다.

이 사이트가 다양한 언어를 지원한다는 것을 검색엔진에게 알리기 위해서는 hreflang 태그를 html head에 설정해야하는데,

next.js에서는 sitemap 함수를 사용하여 설정할 수 있습니다.

// sitemap.ts

import type { MetadataRoute } from 'next';

export default function sitemap(): MetadataRoute.Sitemap {
	return [
		{
			url: 'https://runzipper.app/compress',
			lastModified: new Date(),
			changeFrequency: 'monthly',
			priority: 1,
			alternates: {
				languages: {
					ko: 'https://runzipper.app/ko/compress',
					de: 'https://runzipper.app/de/compress',
					pl: 'https://runzipper.app/pl/compress',
					fr: 'https://runzipper.app/fr/compress',
					it: 'https://runzipper.app/it/compress',
					ja: 'https://runzipper.app/ja/compress',
					zh: 'https://runzipper.app/zh/compress',
					es: 'https://runzipper.app/es/compress',
					en: 'https://runzipper.app/en/compress',
				},
			},
		},
	];
}

이렇게 할 경우 빌드 결과물로 다음과 같은 sitemap.xml이 생성됩니다.

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://acme.com</loc>
    <xhtml:link
      rel="alternate"
      hreflang="es"
      href="https://acme.com/es"/>
    <xhtml:link
      rel="alternate"
      hreflang="de"
      href="https://acme.com/de"/>
    <lastmod>2023-04-06T15:02:24.021Z</lastmod>
  </url>
  <url>
    <loc>https://acme.com/about</loc>
    <xhtml:link
      rel="alternate"
      hreflang="es"
      href="https://acme.com/es/about"/>
    <xhtml:link
      rel="alternate"
      hreflang="de"
      href="https://acme.com/de/about"/>
    <lastmod>2023-04-06T15:02:24.021Z</lastmod>
  </url>
  <url>
    <loc>https://acme.com/blog</loc>
    <xhtml:link
      rel="alternate"
      hreflang="es"
      href="https://acme.com/es/blog"/>
    <xhtml:link
      rel="alternate"
      hreflang="de"
      href="https://acme.com/de/blog"/>
    <lastmod>2023-04-06T15:02:24.021Z</lastmod>
  </url>
</urlset>

i18n 적용 후기

처음 다국어 지원을 구현했는데 next.js 공식문서에 설명이 잘 되어있어서 어려움 없이 구현할 수 있었습니다.

제가 만든 컴포넌트 라이브러리가 국제화를 고려하지 않고 만들어서, 텍스트가 하드코딩 되있어서 이를 수정하는데 시간이 걸렸습니다.

다음부터 컴포넌트 라이브러리를 만들때는 사용자가 국제화를 할 수 있다는 것도 고려해야할 것 같습니다.

[TroubleShooting] Vite Library mode로 빌드시 타입 파일이 포함 안되는 문제

월월월월 — Tue, 9 Dec 2025 00:57:34 +0900

2025.12.02 - [개발] - [vite] vite로 라이브러리 빌드하기

[vite] vite로 라이브러리 빌드하기

최근 제가 사이드 프로젝트로 진행하는 프로젝트에서 사용할 목적으로 UI 컴포넌트 라이브러리를 만들었습니다. UI 컴포넌트를 만들 때, 프로젝트를 vite의 react 템플릿을 사용하여 생성하였습니

bobostown.tistory.com

이전에 vite로 라이브러리를 빌드한 경험을 포스팅으로 남겼는데요,

라이브러리를 실제로 사용해 보니 다양한 버그에 부딪쳤습니다.

그중에서도 가장 심각했던 버그는 제네릭 컴포넌트에서 타입 추론이 제대로 동작하지 않는 것이었습니다.

문제상황

예를 들어, 다음과 같은 컴포넌트가 있습니다:

<Typography.Regular textType="span" className={textStyle}>
    이용약관
</Typography.Regular>

이 컴포넌트는 'p', 'span', 'label' 등 다양한 HTML 텍스트 엘리먼트를 textType으로 받을 수 있는 제네릭 컴포넌트입니다.

전달된 textType에 따라 해당 HTML 엘리먼트에 특화된 속성들을 props로 전달할 수 있도록 설계했습니다.

예를 들어:

textType="label"일 때는 htmlFor 속성 사용 가능
textType="span"일 때는 span의 고유 속성들 사용 가능

하지만 빌드된 라이브러리에서는 이러한 타입 추론이 정상적으로 작동하지 않았습니다.

그래서 빌드된 코드를 보니 textType을 정의한 Text 타입이 빌드 결과물에 포함되지 않고 있었습니다.

원인

원인은 TextType을 d.ts 파일에 정의한 것이었습니다.

text.d.ts에 다음과 같이 텍스트 element들을 정리해 놨습니다.

export type Text =
	| 'h1'
	| 'h2'
	| 'h3'
	| 'h4'
	| 'h5'
	| 'h6'
	| 'p'
	...

이 파일의 확장자를 .d.ts에서 .ts로 변경하니 정상적으로 빌드 결과물에 해당 타입이 포함되었습니다.

2025 DevFest Incheon 2025 후기 (feat. baseline)

월월월월 — Sun, 7 Dec 2025 23:26:10 +0900

2025년 12월 6일에 인천 송도에서 열린 DevFest에 다녀왔습니다.

이번 DevFest에서는 웹 프론트엔드, 백엔드, AI, 플러터 등 다양한 주제의 세션이 열렸습니다.

저는 오늘 열리는 세션중에 "<form/>의 추억", "모던 자바스크립트 패키지 개발하기", "이력서 첨삭 세션"을 청강하였습니다.

세션에 들어가기에 앞서 네트워킹 존에서 열리는 다양한 이벤트에 참여했습니다.

네트워킹 존에는 모두의 연구소, Upstage, Mondiran AI 등 기업들의 부스가 있어서 간단한 설명을 들으면 소정의 경품을 받을 수 있었습니다.

부스행사 참여후에 첫 번째 세션인 <form/>의 추억: HTML부터 RHF, Server Actions까지를 청강했습니다.

<form/>의 추억: HTML부터 RHF, Server Actions

해당 세션에서는 다른 HTML Tag와 구분되는 Form Tag의 특징, Ajax의 등장으로 대체된 form의 기본 동작부터 Server action에 대한 내용을 다루었습니다.

강사님이 프론트엔드에 대한 내용을 몰라도 쉽게 이해할 수 있도록 설명해 주신 것이 인상적이었습니다.

모던 자바스크립트 패키지 개발하기: ESM, Typescript, 의존성, 그리고 DX

이번 세션은 eslint와 react community에 기여하고 있는 개발자분께서 진행하셨습니다.

패키지를 개발할때 가장 중요한 모듈 시스템에 대한 설명부터,

유지보수를 위한 Typescript와 Package.json의 dev dependency와 dependecy에 대한 설명들을 해주셨습니다.

이번 세션에서 흥미로웠던 것은 구글(크롬 팀)의 webbase line 프로젝트입니다.

어떤 기술은 특정 버전의 브라우저나 node.js에서 지원하지 않아서 사용하지 못하는 경우가 있습니다.

그래서 저는 최신 기술을 사용할 때 caniuse 라는 사이트에 기술을 검색하여, 이 기술이 어떤 브라우저에서 지원하는지 확인하곤 합니다.

webbase line 프로젝트에서는 caniuse에서 제공하는 호환성 리스트를 보여주는 것에서 더 발전된 것 같습니다.

webbase line 프로젝트에서는 호환성을 2가지 단계로 표시합니다.

Limited availability : 주요 브라우저 전반에서 구현되지 않았습니다.
Newly available : 이 기능은 모든 주요 브라우저에서 지원되므로 상호 운용이 가능합니다.
Widely available : 새로 상호운용 가능한 날짜로부터 30개월이 지났습니다. 대부분의 사이트에서 지원 문제를 걱정하지 않고 이 기능을 사용할 수 있습니다.

따라서 최신 기술을 사용하고 싶으면 baseline에서 Widely available인 기술을 사용하면 호환성을 충족할 수 있습니다.

예를 들어 <dialog/> 태그는 Widely available 입니다.

❗️ baseline 프로젝트에서 주요 브라우저라고 정의하는 것은 다음과 같습니다.
- Chrome
- Edge
- Safari
- Firefox

이력서 첨삭 세션

이력서 첨삭 세션은 사전에 첨삭을 지원한 지원자를 추첨하여, 당첨된 지원자의 이력서를 공개 첨삭했습니다. (개인정보는 마스킹 처리했습니다)

첨삭은 파트별로 현직자분께서 나와서 진행했고, 지원자의 이력서를 첨삭한 뒤에는 현직자분의 이력서를 보여주셨습니다.

세션을 들으며, 내용도 중요하지만 구성의 순서와 가독성도 중요하다는 생각을 했습니다.

특히 현직자분의 이력서와 제 이력서를 비교하니 가독성 부분에서 떨어지는 것을 느낄 수 있었습니다.

DevFest 후기

저번 네이버 Dan을 시작으로, 이런 개발자 행사에 참여할 때마다 무언가 한 가지씩 배워가는 것 같습니다.

이번 행사에서는 webbase line이라는 프로젝트를 배울 수 있었습니다.

혼자 프로젝트나 취업준비를 하면 사용하던 기술만 사용하거나 자기 생각에 갇히는 등 발전이 힘든데 이런 행사에서 한 번씩 트렌드를 읽을 수 있으니 좋은 것 같습니다.

[vite] vite로 라이브러리 빌드하기

월월월월 — Tue, 2 Dec 2025 14:39:57 +0900

최근 제가 사이드 프로젝트로 진행하는 프로젝트에서 사용할 목적으로 UI 컴포넌트 라이브러리를 만들었습니다.

UI 컴포넌트를 만들 때, 프로젝트를 vite의 react 템플릿을 사용하여 생성하였습니다.

vite로 라이브러리를 빌드할 때는 react web app을 빌드할 때와 달리 추가적인 설정이 필요합니다.

아래 제가 vite로 라이브러리를 build 하며 겪었던 과정을 말씀드리겠습니다.

라이브러리 entry point 만들어주기

vite의 react 템플릿을 사용하여 프로젝트를 생성했을 때, vite는 index.html을 entry point로 하여 프로젝트를 빌드합니다.

하지만 저희는 UI 라이브러리를 만드는 것이기 때문에 index.html이 존재하지 않습니다.

그래서 저는 src 디렉토리 하위에 main.ts로 entry point를 만들어줬습니다.

// src/main.ts
export { default as Icon } from './components/base/icon';
export { default as Typography } from './components/base/typography';
export { default as UI } from './components/ui';
export { vars as Theme } from './styles/theme.css';

라이브러리 빌드를 위해 vite.config.js 설정하기

vite.config.js를 수정해서 entry point를 비롯한 설정을 추가해 줍니다.

/// <reference types="vitest/config" />
// import 구문들...
export default defineConfig({
	// ...
	build: {
		lib: {
			name:'ui',
			entry: ['src/main.ts'],
			cssFileName: 'ui-style',
			formats: ['es','umd'],
		},
		rollupOptions: {
			external: ['react', 'react-dom'],
			output: {
				globals: {
					react: 'React',
					'react-dom': 'ReactDOM',
				},
			},
		},
	},
});

build 옵션의 의미는 다음과 같습니다.

lib.name : 노출된 전역변수로 formats이 'umd' 혹은 'iife' 일 때 필요
lib.entry : entry point 지정, 여러 entry point 지정도 가능
lib.formats : 빌드 결과물의 형식, 'es', 'umd', 'cjs', 'iife', 'system' 중에 선택
lib.cssFileName : css 파일 출력 이름 지정

rollup 옵션의 의미는 다음과 같습니다.

rollupOptions.external : 라이브러리에 포함하지 않을 디펜던시 명시
rollupOptions.output : 라이브러리 외부에 존재하는 디펜던시를 위해 UMD 번들링 시 전역 변수 명시

저는 react를 빌드 패키지에 포함하지 않을 것이므로 'react'와 'react-dom'을 rollupOptions.external에 추가했습니다.

vite-config-dts 설치 (optional. typescript 프로젝트만 해당)

typescript 프로젝트에서 위에까지 설정하고 빌드를 하면 타입은 다 날아가고 자바스크립트 파일만 생성됩니다.

d.ts 파일을 생성하기 위해 vite-config-dts 플러그인을 설치해 줍니다.

npm i vite-config-dts -D

vite.config.js에 plugin에 vite-config-dts를 추가합니다.

export default defineConfig({
	plugins: [
		react(),
		dts({
			tsconfigPath: './tsconfig.json',
			outDir: 'dist',
			rollupTypes: false,
		}),
        // ...
	],
    // ... 다른 옵션들
})

tsconfigPath는 공식문서에서 보면, 공식 vite template인 프로젝트일 때 tsconfig.json의 경로를 작성하라고 명시되어 있습니다.

rollupTypes는 여러 d.ts 파일을 하나의 d.ts 파일로 만드는 옵션인데, 이 옵션을 켰을 때 저 같은 경우 타입이 이상해져서 껐습니다.

Package.json에 라이브러리 entry point 명시하기

# package.json
{
	"name": "@runzipper/ui",
	"version": "0.0.15",
	"author": {
		"name": "BHyeonKim",
		"email": "rlaqhguse@gmail.com",
		"url": "https://github.com/BHyeonKim"
	},
	"description": "UIkit for zipper app",
	"repository": {
		"type": "git",
		"url": "https://github.com/Runzipper/ui"
	},
	"packageManager": "yarn@4.10.3",
	"files": [
		"dist"
	],
	"exports": {
		".": {
			"types": "./dist/src/main.d.ts",
			"import": "./dist/main.mjs",
			"require": "./dist/main.umd.js"
		},
		"./styles": "./dist/ui-style.css"
	...
}

package.json의 exports 필드에 entry point를 명시합니다.

❗️ types 필드는 항상 첫 번째에 있어야 합니다.
"types" - can be used by typing systems to resolve the typing file for the given export. This condition should always be included first.

types 필드를 통해 생성된 타입의 위치를 지정하고, conditional exports를 통해 import 키워드와 require 키워드 모두 지원하도록 설정하였습니다.

추가적으로 files 필드를 설정하여 npm package에는 소스코드를 제외한 빌드 결과물만 올라가도록 설정하였습니다.

[npm] Github packages로 private package 배포하기

월월월월 — Mon, 1 Dec 2025 21:10:50 +0900

최근 개인적으로 사용할 UI 라이브러리를 개발해서 배포할 상황이 있었습니다.

이 라이브러리는 제가 특정 프로젝트에 사용할 용도로 만들었기 때문에 npm registry에 public으로 배포하는 것은 적절하지 않았습니다.

그렇다고 npm registry에 private으로 배포하자니, 유료 플랜(7$)를 사용해야 해서 이 또한 선택지에서 제외했습니다.

그래서 github packages를 사용하여 private package로 배포하기로 결정했습니다.

Github packages 란?

GitHub Packages는 컨테이너 및 기타 종속성을 포함한 패키지를 호스팅 하고 관리하는 플랫폼입니다.

GitHub Packages는 소스 코드와 패키지를 한 곳에 통합하여 권한 관리 및 결제를 제공하므로 GitHub에서 소프트웨어 개발을 중앙 집중화할 수 있습니다.

Github packages는 public packages에 대하여 무료이고, private packages는 github 계정의 plan에 따라 일정량의 무료 storage와 데이터 전송을 제공합니다.

저같은 경우 Github 무료 사용자여서 500MB의 storage와 1GB의 월당 데이터 전송을 사용할 수 있습니다.

요금제에 따른 사용량은 아래 문서에 명시되어 있습니다.

https://docs.github.com/en/billing/concepts/product-billing/github-packages#free-use-of-github-packages

GitHub Packages billing - GitHub Docs

Learn how usage of GitHub Packages is measured against your free allowance and how to pay for additional use.

docs.github.com

github packages는 무료지만, github packages의 registry는 npm registry를 사용할 때보다 패키지를 배포하는 쪽과 사용하는 쪽 모두 추가적인 설정이 필요합니다.

Github packages에 npm package 배포하기

github packages에 배포하는 방법은 사용자의 터미널에서 npm publish로 수동배포하는 방법과 github workflos을 통한 자동 배포가 있습니다.

보통 자동 배포를 하실 테니 자동 배포 방식으로 설명하겠습니다.

Github registry를 가리키도록 하기

먼저 배포할 패키지가 github registry를 가르키도록 해야 합니다.

여기에는 2가지 방법이 있습니다.

package.json의 publishConfig 필드에 github registry 명시
.npmrc에 github registry 명시

저 같은 경우 파일을 하나 더 추가하는 게 싫어서 1번 방법으로 진행했습니다.

# package.json
{
    ...
    "publishConfig": {
        "@runzipper:registry": "https://npm.pkg.github.com"
    },
    ...
}

이때 scope를 사용하지 않을 것이면

"registry": "https://npm.pkg.github.com"

로 작성하면 됩니다.

저 같은 경우 runzipper라는 organization에 포함된 프로젝트여서 스코프를 설정했습니다.

Github workflow 작성

배포를 자동화하기 위해 github workflow 스크립트를 작성했습니다.

이 스크립트의 registry-url에도 github registry의 url을 명시해 줍니다.

# .github/workflows/deploy.yml

name: Publish to github package registry

on:
  push:
    tags:
      - v*

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '22.20'
          cache: 'yarn'
          registry-url: 'https://npm.pkg.github.com'

      - name: Install dependencies
        run: yarn install --immutable

      - name: Build
        run: yarn build

      - name: Publish to GitHub Packages
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

여기서 secrets.GITHUB_TOKEN은 worflow 실행 시 자동으로 생성되는 토큰입니다.

사용자가 따로 github에서 토큰을 발급받지 않아도 됩니다.

관련 내용은 아래 문서에서 찾을 수 있습니다.

https://docs.github.com/en/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions#upgrading-a-workflow-that-accesses-a-registry-using-a-personal-access-token

Publishing and installing a package with GitHub Actions - GitHub Docs

GitHub Actions help you automate your software development workflows in the same place you store code and collaborate on pull requests and issues. You can write individual tasks, called actions, and combine them to create a custom workflow. With GitHub Act

docs.github.com

workflow 트리거하기

위에 작성한 workflow를 트리거하면 github의 클라우드에서 패키지가 빌드 후 배포됩니다.

저는 tag가 push 되면 트리거 되는 것을 조건으로 설정했으므로 태그를 업데이트 후 푸시합니다.

npm version patch

git push origin --tags

Github packages에 배포돼있는 패키지 다운로드 하기

github packages에 배포돼있는 패키지를 사용하는것은 배포하는 것보다 까다롭습니다. (저는 개인적으로 그렇게 느꼈습니다. )

Github token 발급하기

배포 때와는 달리 라이브러리를 다운로드 할 때는 github personal token이 필요합니다.

github developer setting에 들어가 personal token을 발급받아 한쪽에 잘 기억해둡시다.

발급할 때 read:packages 권한은 반드시 체크해야합니다.

Github token 환경변수에 등록하기

나중에 token을 패키지 매니저의 설정파일(.npmrc, yarnrc 등)에 넣어야하는데 여기에 하드코딩하여 코드를 github에 푸시하면 그대로 토큰이 노출됩니다.

그래서 저는 토큰 유출을 막기위해 토큰을 쉘의 환경변수로 등록하여 사용했습니다.

# zsh를 사용할 경우
echo 'export GITHUB_TOKEN="value"' >> ~/.zshrc
source ~/.zshrc

# bash를 사용할 경우
echo 'export GITHUB_TOKEN="value"' >> ~/.bashrc
source ~/.bashrc

Github registry 가르키기

제일먼저 배포할 때와 마찬가지로 Github registry를 가르켜야합니다.

Github registry를 가르키지 않고 패키지 설치 명령어를 실행하면 패키지를 찾을 수 없다고 나옵니다.

저희 패키지는 npm registry가 아닌 github registry에 있으니 당연합니다.

사용하는 패키지매니저의 설정파일에 registry의 url과 앞서 환경변수에 등록해놨던 토큰의 키(GITHUB_TOKEN)를 작성합니다.

# .yarnrc.yml
npmScopes:
  "runzipper":
    npmRegistryServer: 'https://npm.pkg.github.com'
    npmAuthToken: '${GITHUB_TOKEN}'
    
# .npmrc
@runzipper:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

패키지 다운로드 하기

패키지 매니저에 따른 명령어를 입력해 패키지를 다운로드 합니다.

yarn add <package>

후기

처음 github packages에 배포해봤는데 설정에 생각보다 시간이 많이 걸렸습니다.

배포된 라이브러리를 실제로 다른 프로젝트에서 돌아가는지 테스트하고, 고치고, 다시 배포하는 것이 생각보다 시간을 많이 잡아먹었습니다.

배포된 라이브러리가 실행되는지 테스트하는데 든 생각은, "나만 사용할 라이브러리이고 한 프로젝트에 종속적이라면 private package에 배포할 필요가 있을까? 수정하고 재배포하는 시간이 개발하는 시간보다 더 드는 것 같은데?" 였습니다.

제가 UI 부분을 라이브러리화 한게 UI와 비즈니스 로직 패키지로 분리하고 싶어서 였습니다. 근데 그 방식이 굳이 라이브러리로 배포하는것이 아니어도 괜찮지 않나 싶습니다.

이런 케이스 때문에 모노레포가 등장한것 같습니다.

[package.json] peer dependency (feat. UI 라이브러리)

월월월월 — Mon, 1 Dec 2025 17:07:58 +0900

peer dependency는 어떠한 상황에서 사용할까?

지금까지 개발하면서 peer dependency에 대해 몰랐는데, 최근 UI 라이브러리를 개발하면서 이에 대해 학습하였습니다.

UI 라이브러리는 React를 사용하여 개발했습니다. 그런데 이 라이브러리를 설치하는 프로젝트에도 이미 React가 설치되어 있다면, React가 중복으로 설치되는 문제가 발생합니다.

이 같은 문제를 해결하는 것이 peer dependency입니다.

peer dependency는 "이 라이브러리를 사용하려면 특정 패키지가 필요합니다"라고 명시하는 방법입니다. 패키지를 직접 포함하지 않고. 사용자가 이미 설치했을 것으로 기대하는 의존성을 표시합니다.

실제로 프로젝트에 적용한 방법을 통해 설명하겠습니다.

프로젝트 예시

peer dependency 적용 전

peer dependency를 적용하기 전에 제 UI 라이브러리의 package.json을 보면 다음과 같이 돼있습니다.

{
    ...
    "dependencies": {
        "@vanilla-extract/css": "^1.17.4",
        "@vanilla-extract/vite-plugin": "^5.1.1",
        "clsx": "^2.1.1",
        "react": "^19.2.0",
        "react-dom": "^19.2.0"
    },
    "devDependencies": {
     ...
    }
    ...
}

이 UI 라이브러리의 개발에 사용된 react와 react-dom이 dependencies 필드에 있습니다.

이 상태에서 누군가가 이 UI 라이브러리를 설치하면 어떻게 될까요?

node_modules/
  react@19.1.0          ← 프로젝트에 이미 있던 React
  react-dom@19.1.0
  @runzipper/ui/
    node_modules/
      react@19.2.0      ← UI 라이브러리가 설치한 React (중복!)
      react-dom@19.2.0  ← (중복!)

dependencies에 명시된 패키지는 라이브러리 설치 시 함께 설치되기 때문에, React가 중복으로 설치됩니다. 이는 디스크 공간 낭비는 물론, React의 여러 인스턴스로 인한 런타임 에러를 발생시킬 수 있습니다.

peer dependency 적용 후

{
    ...
    "dependencies": {
        "@vanilla-extract/css": "^1.17.4",
        "clsx": "^2.1.1"
    },
    "peerDependencies": {
        "react": "^19.2.0",
        "react-dom": "^19.2.0"
    },
    "devDependencies": {
        ...
        "react": "^19.2.0",
        "react-dom": "^19.2.0",
        ...
    }
    ...
}

이제 사용자가 라이브러리를 설치하면:

프로젝트/
node_modules/
  react@19.1.0          ← 하나만 설치됨!
  react-dom@19.1.0
  @runzipper/ui/        ← React를 포함하지 않음

React가 중복 설치되지 않고, 프로젝트의 React를 공유하여 사용합니다.

그런데 말입니다..?

peer dependency를 적용했을 때랑 하지 않았을 때랑 빌드 결과물의 차이가 나지 않았습니다.

# peer dependency 미적용
dist/ui-style.css  9,207.24 kB │ gzip: 6,850.07 kB
dist/main.mjs         23.58 kB │ gzip:     6.99 kB
dist/ui-style.css  9,207.24 kB │ gzip: 6,850.07 kB
dist/main.umd.js      18.00 kB │ gzip:     6.49 kB
✓ built in 4.03s


# peer dependency 적용
ist/ui-style.css  9,207.24 kB │ gzip: 6,850.07 kB
dist/main.mjs         23.58 kB │ gzip:     6.99 kB
dist/ui-style.css  9,207.24 kB │ gzip: 6,850.07 kB
dist/main.umd.js      18.00 kB │ gzip:     6.49 kB
✓ built in 4.01s

저는 peer dependency를 적용한 버전의 빌드 크기가 당연히 작을 줄 알아서 당황했습니다.

왜 peer dependency 적용 유무와 상관없이 결과물의 크기가 같지?

알고 보니 제가 이전에 vite 설정에서 build 옵션으로 react와 react-dom를 번들에서 제외하도록 설정해 놔서 peer dependency와 관계없이 빌드 결과물에서 제외됐던 겁니다.

rollupOptions: {
    # 이 부분
    external: ['react', 'react-dom'],
    output: {
        globals: {
            react: 'React',
            'react-dom': 'ReactDOM',
        },
    },
},

그래서 peer dependency의 역할에 대해 다시 생각해 보게 되었습니다.

peer dependency의 역할

처음에는 peer dependency가 빌드 크기를 줄여준다고 생각했지만, 실제로는 그렇지 않았습니다.

peer dependency에 라이브러리를 명시한다고 해당 라이브러리가 빌드에서 제외되는 게 아닙니다.

peer dependency와 빌드 설정은 서로 다른 목적을 가지고 있습니다:

Peer Dependency의 역할

패키지 설치 시 중복을 방지
호환되는 버전을 명시하여 버전 충돌 방지
사용자에게 "이 버전이 필요합니다"라고 알림

Vite의 external 설정 역할

빌드 시 번들에서 제외
번들 크기를 실제로 줄임
외부 패키지로 처리하여 런타임에 로드

따라서 번들 크기를 줄이는 것이 목적이면 적절한 번들러 설정과 peer dependency 명시 둘 다 필요합니다.

[React 19] <Activity> 컴포넌트를 사용하여 conditional rendering의 문제를 해결하기

월월월월 — Tue, 25 Nov 2025 23:10:07 +0900

React에서 어떤 요소를 상황에 따라 보여주거나 숨길 때 어떤 방식을 사용하나요?

다음과 같이 조건부 렌더링을 하지 않으신가요?

return (
	<>
    	{isShowing && <Compenent/>
    	<>
)

저도 위와 같은 방법을 많이 사용합니다,

그런데 위와 같은 방법은 시나리오에 따라 문제가 발생할 소지가 있습니다.

기존 조건부 렌더링의 문제

기존 조건부 렌더링의 문제를 설명하기 위해 예시 코드를 작성해 봤습니다.

이 예시에서는 숫자를 증가시키거나 줄일 수 있는 카운터가 있고, 이 카운터를 토글 할 수 있는 버튼이 있습니다.

자식 컴포넌트의 상태가 유지되지 않습니다.

카운터를 열고, 숫자를 증가시키거나 감소 후에 카운터를 닫습니다.

다시 카운터를 열면 카운터는 기존에 내가 조작했던 숫자가 아닌, 0으로 초기화가 되었을 겁니다.

조건부 렌더링을 하면 자식 컴포넌트가 언마운트 후에 다시 마운트 되어서, 언마운트 되기 전에 가지고 있던 상태를 잃어버립니다.

display 속성으로 자식 컴포넌트의 상태 유지하기

그렇다면 자식 컴포넌트의 상태를 유지하려면 어떻게 해야 할까요?

컴포넌트 전체를 조건부로 렌더링 하지 않고 display 속성을 이용하면 됩니다.

위 예제와 같이 display 속성을 사용하여 조건부 렌더링을 하면 Counter 컴포넌트의 내부 상태는 유지됩니다.

위 방법의 문제

하지만 위 방법도 시나리오에 따라 문제가 발생할 수 있습니다.

위 방법은 display 속성을 통해 화면에서 안 보이는 것이지, 완전히 언마운트를 한 것이 아니기 때문에 clean up 함수가 작동하지 않습니다.

따라서 조건부 렌더링마다 clean up 함수의 실행이 필요한 시나리오 경우, 위의 방법은 적절하지 않습니다.

<Activity />

조건부 렌더링에서 컴포넌트의 상태를 유지하면서, clean up 함수의 호출이 필요한 시나리오 경우,

React 19에서 도입 된 <Activity /> 컴포넌트를 사용하면 됩니다.

<Activity /> 컴포넌트는 display 속성을 사용해 조건부 렌더링을 하면서도 clean up 함수를 실행할 수 있게 해 줍니다.

<Activity /> 컴포넌트는 2개의 props를 가집니다

children: 표시하거나 숨길 UI
mode: 'visible' 또는 'hidden'입니다. 기본값은 'visible'입니다.

콘텐츠 사전 렌더링

<Activity /> 컴포넌트는 조건부 렌더링에 사용하는 것 외에 콘텐츠를 사전 렌더링 하는 데 사용할 수 있습니다.

<Activity />의 mode가 hidden인 상태에서는, 자식 컴포넌트는 페이지에 보이지 않지만 여전히 렌더링 됩니다.

이때, 보이는 콘텐츠보다 낮은 우선순위로 렌더링 되며, Effect는 마운트 되지 않습니다.

이러한 특성을 통해 자식 컴포넌트가 필요한 코드나 데이터를 미리 로드할 수 있습니다.

상호작용 속도 높이기

<Activity />를 사용하여 상호작용의 속도를 높일 수도 있습니다.

<Suspense /> 를 사용하여 상호작용 속도를 높일 수도 있지만,

<Suspense />는 UI가 변경되기 때문에 UI 변경을 원치 않는 경우 <Activity />를 사용하는 것이 방법이 될 수 있습니다.

https://ko.react.dev/reference/react/Activity#speeding-up-interactions-during-page-load

<Activity> – React

The library for web and native user interfaces

ko.react.dev

참고한 자료

https://ko.react.dev/reference/react/Activity

<Activity> – React

The library for web and native user interfaces

ko.react.dev

https://www.youtube.com/watch?v=IiGIoi8esXY&list=LL&index=3

[우테코 8기 프리코스] 오픈 미션 후기

월월월월 — Sun, 23 Nov 2025 17:47:15 +0900

초기 미션 목표

압축/압축해제 프로그램의 구현 방법에는 크게 2가지가 있습니다.

여러 파일 들을 각자 압축 후 하나의 파일로 합치기 (zip 방식)
여러 파일 들을 하나의 파일로 합치고, 이 파일을 압축하기 (tar.gz 방식)

처음 프로젝트를 구상할 때는 2번 방식으로 구상했지만,

제가 최종적으로 만들고 싶은 것은 zip 압축 프로그램이어서 1번 방식으로 선회했습니다.

여기서 저는 의문이 들었습니다.

여러 파일 들을 각자 압축하는 것은 쉽습니다.

하지만 압축된 파일들을 어떻게 하나로 합치고,

압축해제 시에 합쳐진 파일들은 어떻게 다시 여러 파일들을 나눌 수 있을까?

그래서 인터넷에 자료를 찾아보다가 ZIP의 specification에서 해답을 찾을 수 있었습니다.

여러 파일들을 하나의 파일로 합치는 법

ZIP 포맷을 만든 Pkware사의 specification에는 다음과 같이 나와있습니다.

ZIP 파일 내부

4.3.6 Overall .ZIP file format:

  [local file header 1]
  [encryption header 1]
  [file data 1]
  [data descriptor 1]
  . 
  .
  .
  [local file header n]
  [encryption header n]
  [file data n]
  [data descriptor n]
  [archive decryption header] 
  [archive extra data record] 
  [central directory header 1]
  .
  .
  .
  [central directory header n]
  [zip64 end of central directory record]
  [zip64 end of central directory locator] 
  [end of central directory record]

각 파일들의 헤더

4.3.7  Local file header:

  local file header signature     4 bytes  (0x04034b50)
  version needed to extract       2 bytes
  general purpose bit flag        2 bytes
  compression method              2 bytes
  last mod file time              2 bytes
  last mod file date              2 bytes
  crc-32                          4 bytes
  compressed size                 4 bytes
  uncompressed size               4 bytes
  file name length                2 bytes
  extra field length              2 bytes

  file name (variable size)
  extra field (variable size)

이 형식을 보고 비슷하게 구현하면 될 것 같았습니다.

.compressed

저는 ZIP파일의 형식보다 간소화된 .compressed의 포맷을 정의했습니다.

.compressed file format:

  [filecount] (4byte)
  [pathLength] (4byte)
  [pathBuffer] 
  [compressedLength] (4byte)
  [compressedContent]
  [pathLength] (4byte)
  [pathBuffer] 
  [compressedLength] (4byte)
  [compressedContent]
  . 
  .
  .

ZIP 형식이나 .compressed 형식같이 (데이터의 길이 - 데이터)로 나타내는 것을 TLV라고 합니다.

https://ko.wikipedia.org/wiki/%ED%98%95%EC%8B%9D-%EA%B8%B8%EC%9D%B4-%EA%B0%92

형식-길이-값 - 위키백과, 우리 모두의 백과사전

위키백과, 우리 모두의 백과사전. 형식-길이-값 또는 TLV(type-length-value 혹은 tag-length-value의 약자)는 통신 프로토콜에서 필수적이지 않은 항목의 자료를 부호화하는 방식이다. 항목의 형식(자료형)

ko.wikipedia.org

중간 구현 결과

위에 정의한 스펙을 따라서 구현한 결과는 다음과 같습니다.

압축 영상

압축 해제 영상

중간 구현에서 아쉬운 점

파일을 압축/압축해제를 한다는 1차 목표는 달성했지만 아쉬운점이 많았습니다.

우선 사용자가 제시된 선택지를 입력해서 압축할 파일과 폴더를 선택하는 것이 사용성이 떨어졌습니다.

처음 기획할 때는 사용자가 파일의 절대경로나 상대경로를 입력하는 것보다

프로그램에서 파일 탐색기를 제공하여 탐색하는 것이 사용성이 좋을 것이라고 생각했습니다.

근데 막상 구현을 해보니 생각보다 직관적이지 않고, 이 프로그램을 개발한 저조차 사용할 때 햇갈렸습니다.

사용자가 압축 진행률을 볼 수 없다는 점도 아쉬웠습니다.

큰파일을 압축할 때, 아무런 피드백이 없어서 저는 프로그램에 에러가 발생한 줄 알았습니다.

추가적으로, 이 프로그램을 사용하려면 해당 리포지토리를 클론하고, 빌드해서 실행해야 하는것도 불편했습니다.

[개선] 파일 선택 방식 변경

파일탐색기 형식의 방식이 불편하여 파일 경로를 입력하는 방식으로 바꾸기로 결정했습니다.

다만, 이 프로젝트를 진행하면서 많은 시간을 파일탐색기를 개발하는데 사용하였는데요,

이 코드를 싹다 지우는것은 아깝다고 느껴졌습니다. (~~나중에 변심해서 이 방식이 더 좋았다고 생각할 수 있잖아요?~~)

그래서 해당 코드를 지우기보다, 해당 코드에서 인터페이스를 추출후에 인터페이스의 구현체를 만드는, 전략패턴을 적용하기로 했습니다.

기존 InteractiveFileSelector 클래스에서 FileSelector 인터페이스를 추출했습니다.

export default interface FileSelector {
  selectTarget: () => Promise<string>;
  selectTargetDirectory: () => Promise<string>;
}

이 인터페이스를 구현하여 TextFileSelector를 만들었습니다.

import ERROR_MESSAGE from '../constants/errorMessage.js';
import Input from '../view/Input.js';
import FileSelector from './FileSelector.js';
import fs from 'node:fs';
import path from 'node:path';

class TextFileSelector implements FileSelector {
  async selectTarget() {
    const userInput = (await Input.readLineAsync()).trim();

    const resolvedPath = path.resolve(userInput);
    this.isExistFileOrDirectory(resolvedPath);

    return userInput;
  }
  async selectTargetDirectory() {
    const userInput = (await Input.readLineAsync()).trim();

    const resolvedPath = path.resolve(userInput);
    this.isExistDirectory(resolvedPath);

    return userInput;
  }

  private isExistFileOrDirectory(pathString: string) {
    if (!fs.existsSync(pathString)) {
      throw new Error(ERROR_MESSAGE.NOT_EXISTING_FILE_OR_DIRECTORY);
    }
  }

  private isExistDirectory(pathString: string) {
    if (!fs.existsSync(pathString)) {
      throw new Error(ERROR_MESSAGE.NOT_DIRECTORY(pathString));
    }
  }
}

export default TextFileSelector;

그리고 App.ts에서 TextFileSelector를 의존성으로 주입했습니다.

class App {
  ...

  constructor() {
    ...
    this.compressController = new CompressController(new TextFileSelector());
    ...
  }
	...
}

export default App;

이전 방식과 사용자가 경로를 넣는 방식을 비교했을 때 사용성이 개선되었습니다.

[개선] 빌드 & 배포

이 프로젝트를 실행하려면 프로젝트를 clone하고 빌드후에 실행해야해서 불편했습니다.

이를 개선하기 위해 npm에 프로젝트를 배포했습니다.

(npm에 어떻게 배포했는지는 아래 글을 봐주세요!)

https://bobostown.tistory.com/37

위 과정을 통해 사용자는 npx 명령어를 통해 제 프로그램을 실행할 수 있게 되었지만,

제가 배포를 위해 npm publish 명령어를 입력해야 한다는 불편함이 남아 있었습니다.

npm 배포 자동화

이를 자동화하기 위해 Github action을 사용하여 배포 자동화를 했습니다.

name: Deploy to NPM

on:
  push:
    tags:
      - v*

jobs:
  deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      id-token: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '22.19'
          cache: 'npm'
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: npm ci

      - name: Test package
        run: npm run test

      - name: Build package
        run: npm run build

      - name: Publish to NPM
        run: npm publish --provenance
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

tsup으로 빌드 결과물 용량 줄이기

추가적으로 배포에서 아쉬운점이 있었습니다.

tsc로 typescript를 javascript로 컴파일하다 보니 파일들이 번들링이 안되있고, minification과 tree-shaking이 안되있어서 빌드 결과물의 용량이 크다는 점에 있었습니다.

빌드 결과물의 용량이 크다는 것은 사용자가 프로그램을 실행할 때 npm registry에서 다운로드하는 시간이 길어진다는 것을 의미하기에 이를 개선해야된다고 생각했습니다.

tsc로 빌드했을때

tsc로 빌드했을때 용량

이를 개선하기 위해 tsup을 사용하여 프로젝트를 빌드했습니다.

tsup으로 빌드를 하니 빌드 결과물의 크기가 46% 감소했습니다.

tsup로 빌드했을때 용량

최종 결과물

https://www.npmjs.com/package/open-mission-compressor

느낀점 및 아쉬운점

사용성이 많이 개선이 되었지만

처음 프로젝트를 시작할 때 세운 계획과 비교하면 아쉬움이 많이 남습니다.

오픈미션을 계획할때는 ZIP을 압축하고 압축해제할 수 있는 프로그램을 만들고, 다양한 압축 포맷 지원, 그리고 이를 rust로 재 작성하여 node.js 프로그램과 rust 프로그램간의 성능 비교를 해볼 생각이었습니다.

그런데 아무래도 프론트엔드를 개발하는 입장로써 node.js를 상대적으로 깊게 사용해본 것이 이번이 처음이고,

압축/압축해제를 구현하기 위해 사전조사를 하느라 시간이 많이 소모되어서 node.js 압축 프로그램 개발까지만 끝낼 수 있었습니다.

제가 만든 압축 프로그램의 한계도 명확합니다.

표준이 아닙니다. 제 프로그램으로 압축한 파일만 압축 해제 할 수 있습니다.
경우에 따라 압축된 결과물의 용량이 더 클 수 있습니다.
압축 시간이 오래 걸립니다.
node.js의 filesystem과 path module을 사용하는 부분등 많은 부분을 테스트 하지 못했습니다.

결과물은 아쉽지만 개발 과정에서 압축/압축해제를 수행하는 다양한 알고리즘(inflate, lz77, huffman)들을 알 수 있었고, 알고리즘을 실제로 구현해볼 수 있는 기회가 되었습니다. (~~node.js의 zlib 사용없이 직접 구현해보고 싶었습니다.~~)

npm 배포도 이번에 처음 해봤는데, CLI 프로그램이나 라이브러리를 배포하는 방법을 배울 수 있었습니다.

또, node.js로 프로그램 개발하라고 하면 할 수 있는 자신감도 생겼습니다.

과제를 구현하며 조사한 자료

압축 알고리즘 정리

https://bobostown.tistory.com/32

[압축 알고리즘] LZ77 알고리즘 이란?

LZ77 알고리즘은 ZIP 압축에 사용되는 Deflate 알고리즘을 구성하는 압축 알고리즘입니다.Deflate 알고리즘은 LZ77 알고리즘으로 1차 압축 후에 2차로 허프만 코드 알고리즘을 사용하여 압축합니다. 현

bobostown.tistory.com

https://bobostown.tistory.com/33

[압축 알고리즘] LZ77 구현

압축 알고리즘을 Node.js로 구현해 봤습니다.Node.js의 Buffer와 LCS알고리즘을 사용하여 구현했습니다. LZ77 구현Search buffer size와 Look ahead buffer size는 임의의 값이 아닌 Deflate 알고리즘의 Spec인 32KB와 258

bobostown.tistory.com

node.js 모듈 및 클래스

https://bobostown.tistory.com/34

[node.js] node:fs

fs modulenode.js에서 파일 시스템에 접근할 수 있는 방법은 2가지입니다.promise-based API인 node:fs/promisescallback 및 sync API인 node:fs모든 파일 시스템 작업은 동기식, 콜백 방식, 프로미스 기반 형태로 제공

bobostown.tistory.com

https://bobostown.tistory.com/35

[node.js] node:path

path modulepath 모듈은 파일과 디렉터리 경로 작업을 위한 유틸리티를 제공합니다. path 모듈은 node.js가 실행되는 운영체제에 따라 기본 동작이 달라집니다.예를 들어, Windows 운영체제에서 path 모듈

bobostown.tistory.com

https://bobostown.tistory.com/

Bobostown

bobostown.tistory.com

npm에 CLI 프로그램 배포하기

https://bobostown.tistory.com/37

ZIP Specification

https://pkwaredownloads.blob.core.windows.net/pkware-general/Documentation/APPNOTE-6.3.9.TXT