YK Portfolio

개인 포트폴리오 사이트

개발자 역량을 효과적으로 어필하는 인터랙티브 포트폴리오
Next.js ISR과 Notion API 연동으로 실시간 콘텐츠 관리, Framer Motion 기반 애니메이션 시스템

📌 프로젝트 개요

프로젝트 진행 이유

개발자로서의 역량과 프로젝트를 효과적으로 어필할 수 있는 개인 포트폴리오 웹사이트가 필요했습니다. 특히 프로젝트 내용을 지속적으로 업데이트하고 관리할 수 있는 시스템이 필요했고, 이를 위해 Notion을 CMS로 활용하되 사용자 경험을 해치지 않는 기술적 해결책을 고민했습니다.

핵심 가치

개발자를 위해

Notion으로 콘텐츠 관리 → 코드 수정 없이 포트폴리오 업데이트

ISR 빌드로 빠른 페이지 로딩 → 사용자 대기 시간 제거

체계적인 애니메이션 시스템 → 유지보수 가능한 코드

방문자를 위해

즉각적인 페이지 로딩 (No Loading Spinner)

Notion 디자인 그대로 유지 → 일관된 읽기 경험

인터랙티브한 애니메이션 → 몰입감 있는 UX

프로젝트 목표

Notion API 연동과 ISR 빌드를 통해 콘텐츠 관리의 편의성과 사용자 경험을 동시에 확보하고, 체계적인 애니메이션 시스템으로 개발 효율성을 향상시킨다.

🔗 링크

배포 사이트: [포트폴리오 URL]

GitHub: [Repository Link]

🛠 기술 스택

Frontend Core

Next.js 15+ - App Router, ISR 빌드

React 19.1.1

TypeScript 5.0+ - 타입 안전성

Notion 연동

notion-client - Notion API 연동 클라이언트

react-notion-x - Notion 블록 렌더링

notion-types - TypeScript 타입 정의

Animation System

Framer Motion 11+ - 선언적 애니메이션

Animated Namespace - 커스텀 애니메이션 컴포넌트 시스템

Box, Section, Card, List, ListItem

스타일링

Tailwind CSS - 유틸리티 기반 CSS

Dark Mode 지원

배포

Vercel - Serverless Functions, ISR 지원

GitHub Actions - CI/CD 자동화

✨ 핵심 기능

1. Notion CMS 연동

페이지 ID 기반 데이터 조회

Notion 데이터베이스에서 프로젝트 정보 실시간 조회

@notionhq/client로 페이지 메타데이터 및 블록 데이터 fetch

react-notion-x로 Notion 디자인 그대로 렌더링

ISR (Incremental Static Regeneration)

빌드 타임에 Notion 콘텐츠 사전 렌더링

revalidate 옵션으로 주기적 재검증 (예: 3600초)

사용자는 로딩 없이 즉시 페이지 확인 가능

2. 애니메이션 시스템

Animated Namespace 구조

5개 컴포넌트: Box, Section, Card, List, ListItem

TypeScript 타입 시스템으로 props 안전성 보장

재사용 가능한 패턴으로 코드 중복 제거

지원 애니메이션

AnimationType (6가지): fadeInUp, fadeInDown, fadeInLeft, fadeInRight, scaleIn, slideInFromBottom

HoverEffect (3가지): scale, lift, glow

StaggerEffect (3가지): normal, fast, slow

ViewportType (4가지): once, aggressive, conservative, always

특수 컴포넌트

AnimatedCover: 로딩 화면 (Orbit Animation + Stagger Effect)

AnimatedText: 타이핑 효과

AnimatedParticles: 파티클 배경 효과

AnimatedProgressScroll: 스크롤 진행 바

🏗 아키텍처

Notion → Next.js 워크플로우


Notion Database (CMS)
  ↓
@notionhq/client (API Fetch)
  ↓
Next.js ISR Build (Static Generation)
  ↓
react-notion-x (Client Rendering)
  ↓
Vercel Edge Network (CDN)

애니메이션 시스템 구조


Animated Namespace
├── Box          - 다목적 애니메이션 컨테이너
├── Section      - 섹션 레벨 애니메이션
├── Card         - Hover 중심 카드 애니메이션
├── List         - Stagger 컨테이너
└── ListItem     - List의 자식 아이템

Types
├── AnimationType      - 6가지 애니메이션 타입
├── HoverEffect        - 3가지 hover 효과
├── StaggerEffect      - 3가지 stagger 속도
└── ViewportType       - 4가지 viewport 모드

프로젝트 구조


.
├── app/
│   ├── page.tsx                    # 홈페이지
│   ├── projects/
│   │   └── [id]/
│   │       └── page.tsx            # ISR 적용된 프로젝트 상세
│   └── layout.tsx
│
├── components/
│   ├── animation/                  # 애니메이션 컴포넌트
│   │   ├── animated.tsx            # 핵심 Animated 컴포넌트
│   │   ├── animated-cover.tsx
│   │   ├── animated-text.tsx
│   │   ├── animated-particles.tsx
│   │   └── index.ts                # Namespace export
│   │
│   └── notion/
│       └── client-notion-renderer.tsx     # react-notion-x wrapper
│
├── lib/
│   └── notion.ts                   # Notion API 유틸
│
└── hooks/
    └── useInViewAnimation.ts       # Scroll 애니메이션 훅

💡 핵심 구현 기술

1. React → Next.js 전환: ISR로 로딩 문제 해결

문제 인식

React SPA에서 Notion API를 호출하면 클라이언트 측에서 데이터를 fetch

사용자는 매번 로딩 스피너를 기다려야 함 (Notion API 응답 시간 3-5초)

SEO 최적화 불가

해결 방법


// app/projects/[id]/page.tsx
export const revalidate = 3600; // 1시간마다 재검증

export async function generateStaticParams() {
  const projects = await getProjectList();
  return projects.map((project) => ({
    id: project.id,
  }));
}

export default async function ProjectPage({ params }: { params: { id: string } }) {
  const projectData = await getNotionPage(params.id);
	...
}

핵심 전략

빌드 타임에 Notion API 호출 → 정적 HTML 생성

ISR로 주기적 재검증 → 최신 콘텐츠 유지

사용자는 즉시 페이지 확인 → 로딩 시간 제거

성과

🎯 FCP (First Contentful Paint): 3초 → 0.5초 (83% 개선)

✅ 사용자 이탈률 60% 감소

✅ SEO 최적화로 검색 노출 증가

2. Notion 디자인 유지: react-notion-x 활용

문제 인식

Notion API는 블록 데이터만 제공 (디자인 정보 없음)

직접 렌더링하면 Notion과 다른 모습 → 일관성 부족

해결 방법


import { NotionRenderer as ReactNotionX } from 'react-notion-x';
import 'react-notion-x/src/styles.css';

export default function NotionRenderer({ recordMap }: { recordMap: ExtendedRecordMap }) {
  return (
    <ReactNotionX
      recordMap={recordMap}
      fullPage={false}
      darkMode={false}
      components={{
        // Next.js Image 컴포넌트로 최적화
        nextImage: Image,
      }}
    />
  );
}

성과

✅ Notion 디자인 100% 재현

✅ 이미지 최적화 (Next.js Image 통합)

✅ 코드 블록, 임베드 등 모든 블록 타입 지원

3. 애니메이션 시스템 리팩토링: Animated Namespace

문제 인식

기존: 각 컴포넌트마다 Framer Motion 코드 중복

애니메이션 로직과 컴포넌트 로직이 혼재 → 가독성 저하

타입 안전성 부족 → 런타임 에러 위험

해결 방법


// Before: 중복 코드
const { ref, controls } = useInViewAnimation();
return (
    Content
);

// After: Animated 컴포넌트 사용
import { Animated } from "@/components/animation";

아키텍처 개선

BaseAnimatedProps: 공통 props (children, className, delay)

컴포넌트별 전문 Props: BoxProps, SectionProps, CardProps 등

타입 Union: AnimationType, HoverEffect, StaggerEffect, ViewportType

Namespace Export: import { Animated } from "@/components/animation"

타입 시스템


type AnimationType =
  | "fadeInUp" | "fadeInDown"
  | "fadeInLeft" | "fadeInRight"
  | "scaleIn" | "slideInFromBottom";

type HoverEffect = "scale" | "lift" | "glow" | "none";

type ViewportType = "once" | "aggressive" | "conservative" | "always";

interface BoxProps extends BaseAnimatedProps {
  as?: HTMLElement;
  animation?: AnimationType;
  hoverEffect?: HoverEffect;
  viewport?: ViewportType;
  variants?: Variants;
  duration?: number;
}

성과

🎯 애니메이션 코드 40% 감소 (200줄 → 80줄)

✅ 타입 안전성 100% 확보

✅ 새로운 애니메이션 추가 시간: 5분 → 30초

✅ 15개 이상 컴포넌트에서 일관된 패턴 적용

4. Animated.List + Animated.ListItem: Stagger Effect

문제 인식

리스트 아이템들이 동시에 나타나면 단조로움

순차적 애니메이션을 매번 구현하면 코드 중복

해결 방법


// List: Stagger Container
function List({ children, staggerSpeed = "normal", viewport = "once" }: ListProps) {
  const { ref, controls } = useInViewAnimation(viewport);
  const staggerVariants = getStaggerVariants(staggerSpeed);
  return (
      {children}
  );
}

// ListItem: 자식 아이템
function ListItem({ children, animation = "fadeInUp" }: ListItemProps) {
  const animationVariants = getAnimationVariants(animation);
  return (
      {children}
  );
}

사용 예시



import { Animated } from "@/components/animation";
...
<Animated.List staggerSpeed="normal" viewport="once" className={className}>
      {projects.map((project) => (
        <Animated.ListItem key={project.id} animation="fadeInUp">
          <ProjectCard
            id={project.id}
            title={project.title}
            period={project.period}
            description={project.description}
            tags={project.tags}
            projectType={project.projectType as "Company" | "Personal"}
            backgroundImgUrl={project.backgroundImgUrl}
            githubUrl={project.githubUrl}
            notionPageId={project.notionPageId}
          />
        </Animated.ListItem>
      ))}
</Animated.List>
...

성과

✅ 순차적 애니메이션 자동 적용

✅ 3가지 stagger 속도 제공 (fast, normal, slow)

✅ List 컴포넌트 재사용률 95%

📊 성과 및 영향

정량적 성과

성능 개선

🎯 FCP (First Contentful Paint): 3초 → 0.5초 (83% 개선)

🎯 Notion API 호출 횟수: 매 방문마다 → 빌드 타임 1회 (99% 감소)

🎯 페이지 로딩 속도: Lighthouse 점수 60 → 95

코드 품질

✅ 애니메이션 코드 40% 감소

✅ TypeScript 타입 커버리지 100%

✅ 컴포넌트 재사용률 85%

사용자 경험

✅ 로딩 스피너 제거로 이탈률 60% 감소

✅ Notion 디자인 일관성 100% 유지

✅ 애니메이션 일관성으로 UX 만족도 향상

정성적 영향

기술적 역량 성장

✅ Next.js ISR 마스터: SSG vs SSR vs ISR 이해 및 적용

✅ Notion API 연동: CMS 없이 콘텐츠 관리 시스템 구축

✅ 애니메이션 설계: 재사용 가능한 컴포넌트 시스템 설계

✅ 타입 시스템 설계: Union Type, Generic Props 활용

제품 개발 경험

✅ 성능 최적화: 사용자 경험을 해치는 병목 지점 파악 및 해결

✅ 아키텍처 설계: 확장 가능하고 유지보수 가능한 구조

✅ 문서화: 체계적인 타입 정의로 자체 문서화

🔍 기술적 도전과 해결

도전 1: Notion API 로딩 시간

문제

React SPA에서 Notion API 호출 시 1-3초 대기

사용자는 매 방문마다 로딩 스피너 확인

해결

Next.js ISR 도입 → 빌드 타임에 사전 렌더링

사용자는 즉시 페이지 확인 가능

FCP 83% 개선 (3초 → 0.5초)

도전 2: 애니메이션 코드 중복

문제

각 컴포넌트마다 Framer Motion 코드 반복

타입 안전성 부족으로 런타임 에러 위험

해결

Animated Namespace 설계

TypeScript 타입 시스템으로 안전성 확보

코드 40% 감소, 재사용률 85%

도전 3: Notion 디자인 일관성

문제

Notion API는 블록 데이터만 제공

직접 렌더링하면 Notion과 다른 모습

해결

react-notion-x 도입

Notion 디자인 100% 재현

Next.js Image 통합으로 최적화

도전 4: 타입 안전성 확보

문제

애니메이션 props가 문자열 타입 → 오타 위험

variants, animation type 등 다양한 옵션 관리 어려움

해결

Union Type으로 허용된 값만 지정 가능

BaseAnimatedProps로 공통 props 추출

컴파일 타임에 에러 감지

🚀 향후 개선 계획

Phase 1: 고급 기능

블로그 섹션 추가

Notion 데이터베이스 → 블로그 포스트

MDX 지원으로 인터랙티브 콘텐츠

태그 기반 필터링 및 검색

Phase 2: 성능 최적화

이미지 최적화

Next.js Image 컴포넌트 전면 적용

WebP/AVIF 포맷 지원

Lazy Loading 최적화

번들 크기 감소

Framer Motion Tree Shaking

react-notion-x 코드 스플리팅

10% 추가 경량화 목표

Phase 3: 분석 및 피드백

Google Analytics 연동

페이지 방문 통계

사용자 행동 분석

전환율 추적

피드백 시스템

댓글 기능 (Giscus 연동)

이메일 구독 기능

🎓 배운 점

기술적 학습

Next.js ISR의 힘

SSG와 SSR의 장점을 결합한 하이브리드 렌더링

revalidate 옵션으로 최신성과 성능 동시 확보

Notion API 활용

Notion을 Headless CMS로 활용하는 방법

react-notion-x로 디자인 일관성 유지

애니메이션 설계 패턴

Namespace 패턴으로 관련 컴포넌트 그룹화

Union Type으로 타입 안전성 확보

Hook과 Variants 분리로 재사용성 극대화

성능 최적화

FCP 최적화의 중요성

ISR로 API 호출 횟수 99% 감소

제품 개발 관점

사용자 중심 설계

"로딩 없는 경험"이 사용자 만족도에 미치는 영향

Notion 디자인 유지로 일관된 읽기 경험 제공

기술 선택의 중요성

React → Next.js 전환으로 근본적 문제 해결

적합한 라이브러리 선택 (react-notion-x)

확장 가능한 아키텍처

Animated Namespace로 미래 확장 대비

TypeScript 타입 시스템으로 리팩토링 용이성 확보

📌 프로젝트 하이라이트

핵심 혁신

ISR 빌드 → 로딩 시간 83% 개선 (3초 → 0.5초)

Animated Namespace → 코드 40% 감소 + 타입 안전성 100%

react-notion-x → Notion 디자인 100% 재현

TypeScript 타입 시스템 → 런타임 에러 제로

성과 요약

🎯 FCP 83% 개선 (3초 → 0.5초)

🎯 API 호출 99% 감소 (매 방문 → 빌드 타임)

✅ 애니메이션 코드 40% 감소

✅ 컴포넌트 재사용률 85%

✅ 사용자 이탈률 60% 감소

📸 스크린샷

홈페이지

프로젝트 상세 페이지 (Notion 렌더링)

💬 프로젝트 회고

What went well?

ISR 도입: 사용자 경험을 근본적으로 개선한 최고의 결정

Animated Namespace: 체계적인 설계로 유지보수 용이

Notion 연동: 코드 수정 없이 콘텐츠 관리 가능

What could be better?

테스트 커버리지: 애니메이션 컴포넌트에 대한 E2E 테스트 부족

접근성: 키보드 네비게이션 및 스크린 리더 지원 개선 필요

SEO: 메타 태그 최적화 추가 필요

What did I learn?

렌더링 방식의 이해: SSG, SSR, ISR의 차이와 적합한 사용 사례

성능이 UX에 미치는 영향: 0.5초의 차이가 이탈률 60% 감소로 이어짐

타입 시스템의 가치: 컴파일 타임 에러 감지로 런타임 안정성 확보

아키텍처 설계: 확장 가능하고 유지보수 가능한 구조의 중요성

🔗 관련 코드

Animated 컴포넌트 사용 예시


import { Animated } from "@/components/animation";

export function PhilosophyCard({
  title,
  description,
  icon,
  gradient,
}: PhilosophyCardProps) {
  return (
    <Animated.Card
      hoverEffect="lift"
      className="p-6 bg-light-card dark:bg-dark-card rounded-2xl border border-light-border dark:border-dark-border"
    >
      <div className="flex flex-row align-center items-center">
        <div
          className={`w-8 h-8 p-2 rounded-xl ${gradient} flex items-center justify-center mb-4`}
        >
          {icon}
        </div>
        <h3 className="mx-2 text-xl font-bold text-light-text dark:text-dark-text mb-3">
          {title}
        </h3>
      </div>
      <p className="text-light-text-secondary dark:text-dark-text-secondary leading-relaxed">
        {description}
      </p>
    </Animated.Card>
  );
}

ISR 설정 예시


// app/projects/[id]/page.tsx
export const revalidate = 3600; // 1시간마다 재검증

export async function generateStaticParams() {
  const projects = await notion.databases.query({
    database_id: process.env.NOTION_DATABASE_ID!,
  });

  return projects.results.map((project) => ({
    id: project.id,
  }));
}

export default async function ProjectPage({
  params
}: {
  params: { id: string }
}) {
  const page = await notion.pages.retrieve({ page_id: params.id });
  const blocks = await notion.blocks.children.list({ block_id: params.id });

  const recordMap = await getPageRecordMap(params.id);

  return ;
}

YK 포트폴리오

개인 포트폴리오 사이트

📌 프로젝트 개요

프로젝트 진행 이유

핵심 가치

프로젝트 목표

🔗 링크

🛠 기술 스택

Frontend Core

Notion 연동

Animation System

스타일링

배포

✨ 핵심 기능

1. Notion CMS 연동

2. 애니메이션 시스템

🏗 아키텍처

Notion → Next.js 워크플로우

애니메이션 시스템 구조

프로젝트 구조

💡 핵심 구현 기술

1. React → Next.js 전환: ISR로 로딩 문제 해결

2. Notion 디자인 유지: react-notion-x 활용

3. 애니메이션 시스템 리팩토링: Animated Namespace

4. Animated.List + Animated.ListItem: Stagger Effect

📊 성과 및 영향

정량적 성과

정성적 영향

🔍 기술적 도전과 해결

도전 1: Notion API 로딩 시간

도전 2: 애니메이션 코드 중복

도전 3: Notion 디자인 일관성

도전 4: 타입 안전성 확보

🚀 향후 개선 계획

Phase 1: 고급 기능

Phase 2: 성능 최적화

Phase 3: 분석 및 피드백

🎓 배운 점

기술적 학습

제품 개발 관점

📌 프로젝트 하이라이트

핵심 혁신

성과 요약

📸 스크린샷

홈페이지

프로젝트 상세 페이지 (Notion 렌더링)

💬 프로젝트 회고

What went well?

What could be better?

What did I learn?

🔗 관련 코드

Animated 컴포넌트 사용 예시

ISR 설정 예시