mason-log.

😠 1. 개요 : 업데이트 계기.

• masoneffect NPM 패키지를 개발한 이후, 오픈소스 라이브러리인 React Bits 패키지에 Masoneffect 컴포넌트를 기여해보려는 시도가 있었다. 하지만 여러 이유로 인해 결과적으로는 기여까지 이어지지 못했다 🥲 (지난 포스팅 참고)

• 시간을 들여 준비했던 만큼 아쉬움도 있었고, 이 경험을 계기로 외부 패키지에 기여하는 방향보다는 masoneffect 자체를 확장해보는 쪽을 고민하게 됐다.

• masoneffect를 단일 효과 라이브러리에 머무르게 하기보다는, 실제 프로젝트에서 자주 쓰는 애니메이션들을 하나로 묶은 멀티 애니메이션 패키지로 발전시키는 것이 더 의미 있겠다는 판단이 들었다.

• 그렇게 시작한 masoneffect v2.0은 단순한 기능 추가라기보다는, 방향성이 변경된 업데이트라고 볼 수 있다.

🔨 2. 재설계 : 주요 변경 사항.

패키지 구조 변화.

• masoneffect v2.0에서 가장 큰 변화는 패키지 구조 자체가 달라졌다는 점이다.

• v1.x에서는 TextToParticle 하나의 효과만 제공하는 단일 효과 라이브러리였다면, v2.x부터는 여러 애니메이션 효과를 독립적인 단위로 묶은 멀티 애니메이션 패키지 구조로 변경되었다.

[ v1.x 구조 ]
masoneffect/
  └── TextToParticle (단일 효과)

[ v2.x 구조 ]
masoneffect/
  ├── TextToParticle (기존 효과 유지)
  ├── Typing (신규)
  ├── Count (신규)
  ├── ScrollFadeIn (신규)
  └── ... (지속 추가 예정)

• 효과는 앞으로도 계속 추가될 예정이지만, 각 효과를 독립적인 모듈 단위로 분리하고 Tree Shaking이 가능한 구조로 설계해, 실제로 사용하는 효과만 번들에 포함되도록 관리할 계획이다.

🎛️ 3. 신규 효과 : 애니메이션 확장.

(1) Count (카운팅 효과)

• Number type의 시작값에서 목표값까지 부드럽게 증가하는 애니메이션.

주요 특징.

• 시작값/목표값 설정.

• 애니메이션 지속 시간 조절. (duration)

• 기타 이징 함수 지원.

• 실시간 값 조회 가능.

사용 예시. (react)

import Count from 'masoneffect/react/count';

<Count startValue={0} targetValue={1000} duration={2000} easing={easingFunctions.easeOutCubic} />;

(2) Typing (타이핑 효과)

• 텍스트가 한 글자씩 타이핑되는 것처럼 표시되는 애니메이션.

주요 특징.

• 타이핑 속도 조절 가능 (speed)

• 시작 지연 시간 설정 (delay)

• 반복 재생 옵션 (loop)

사용 예시. (react)

import Typing from 'masoneffect/react/typing';

<Typing text="Hello World" speed={100} delay={500} loop={false} />;

(3) ScrollFadeIn (스크롤 페이드인 효과)

• 스크롤 시 요소가 화면에 나타나면서 페이드인되는 애니메이션.

주요 특징.

• IntersectionObserver 기반.

• 스크롤 위치 기반 트리거.

• 페이드 지속 시간 조절.

사용 예시. (react)

import ScrollFadeIn from 'masoneffect/react/scrollFadeIn';

<ScrollFadeIn duration={1000} threshold={0.1} triggerOnce={true}>
  <YourContent />
</ScrollFadeIn>;

🌳 4. Version 2의 주요 장점.

(1) Tree Shaking 지원.

• 필요한 효과만 선택적으로 import하여 번들 크기를 최소화.

// 사용하는 효과만 번들에 포함. (ex. TextToParticle)
import { TextToParticle } from 'masoneffect/textToParticle';
import { Count } from 'masoneffect/count';

• 개별 export 경로: 각 효과가 독립적인 경로로 제공되어 번들러가 정확히 필요한 코드만 포함.

• 자동 최적화: Webpack, Vite, Rollup처럼 ESM과 tree-shaking을 지원하는 번들러에서 미사용 효과를 제거하기 쉬운 구조.

• 작은 번들 크기: 전체 패키지를 설치해도 실제 사용하는 효과만 번들에 포함.

(2) 렌더링 최적화.

• 성능을 고려한 최적화 로직 적용.

• IntersectionObserver 활용: 요소가 뷰포트에 보일 때만 애니메이션 실행.

• Page Visibility API: 브라우저 탭이 숨겨지면 자동으로 애니메이션 일시정지.

• requestAnimationFrame: requestAnimationFrame 기반 재생으로 부드러운 프레임 전환을 목표로 함.

• ResizeObserver: 컨테이너 크기 변경 시 자동 리사이징.

• Debouncing: 리사이즈, 업데이트 등 빈번한 이벤트 최적화.

(3) 의존성 없는 패키지.

• 프레임워크 의존성 없이 순수 JavaScript로 구현된 핵심 로직.

• Zero Runtime Dependencies: 외부 라이브러리 의존성 없음.

• 경량 패키지: 불필요한 의존성으로 인한 번들 크기 증가 방지.

• 안정성: 의존성 업데이트로 인한 breaking change 걱정 없음.

(4) 범용 호환성.

• React, Vue, Svelte, Vanilla JavaScript 모든 환경에서 동일한 API로 사용 가능.

// React
import TextToParticle from 'masoneffect/react/textToParticle';

// Vue
import TextToParticle from 'masoneffect/vue/textToParticle';

// Svelte
import TextToParticle from 'masoneffect/svelte/textToParticle';

// Vanilla JS
import { TextToParticle } from 'masoneffect/textToParticle';

• 프레임워크별 래퍼 제공: 각 프레임워크의 관례에 맞는 컴포넌트 제공.

• 일관된 API: 프레임워크를 바꿔도 동일한 옵션과 메서드 사용.

• 타입 안정성: TypeScript로 모든 프레임워크에서 완전한 타입 지원.

• 유연한 마이그레이션: 프로젝트 프레임워크 변경 시 코드 수정 최소화.

(5) AI 기반 지원.

• llms.txt

  • AI 에이전트가 프로젝트 구조와 사용 환경을 자동으로 파악할 수 있도록 최소한의 가이드를 제공한다.

  • 이를 통해 React, Vue, Svelte, Vanilla 등 사용 중인 환경에 맞는 설정과 예제 코드를 보다 정확하게 안내받을 수 있도록 했다.

• context7.json 메타데이터.

  • masoneffect의 패키지 구조, 제공되는 효과, 프레임워크별 진입 경로 등을 구조화된 메타데이터 형태로 정리했다.

  • AI 에이전트가 라이브러리를 더 잘 이해하고, 상황에 맞는 효과를 추천하거나 적절한 사용 예시를 제시하는 데에 도움을 주는 역할을 한다.

✍️ 5. 마무리 : 회고.

• masoneffect v2.0은 단순히 효과 몇 개를 추가한 업데이트라기보다는, 이 라이브러리를 어떤 방식으로 운영해 나갈지 방향성을 정리한 업데이트가 되었다고 생각한다.

• 아직 부족하고 보완해야 할 부분도 많지만, 급하게 확장하기보다는 천천히 꼼꼼하게 다듬어갈 예정이다.

• 앞으로는 개수를 채우기보다 실제 사용 과정에서 의미가 확인된 효과를 중심으로 추가할 생각이다.

🔗 6. 프로젝트 링크.

• masoneffect 소개 사이트

• masoneffect npm

• masoneffect GitHub