Next.js 16과 Three.js로 블로그를 구축하고 최적화한 기록

// src/app/feed/[slug]/page.tsx
export async function generateStaticParams() {
  const feeds = getSortedFeedData();
  return feeds.map((feed) => ({
    slug: feed.slug,
  }));
}

MDX 파일
→ gray-matter (frontmatter 파싱)
→ remark (Markdown AST 변환)
→ remark-gfm (GFM 지원)
→ rehype-highlight (코드 하이라이팅)
→ React Component 렌더링

content/
├── 2026-01-28-blog-system-building/
│   ├── index.mdx        # 본문
│   └── meta.json        # 메타데이터 (제목, 설명, 태그 등)

/* src/styles/variables.css */
:root {
  /* Color System */
  --bg-primary: #eaebea;
  --text-primary: #1a1a1a;
  --accent-primary: #0066cc;
 
  /* Typography Scale */
  --text-xs: 12px;
  --text-sm: 14px;
  /* ... */
 
  /* Spacing (8px Grid) */
  --space-1: 4px;
  --space-2: 8px;
  /* ... */
}

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: 'var(--bg-primary)',
        'text-primary': 'var(--text-primary)',
        accent: 'var(--accent-primary)',
      },
      fontSize: {
        'display-md': ['clamp(2.5rem, 6vw, 3.5rem)', { lineHeight: '1.2' }],
        'display-lg': ['clamp(4rem, 10vw, 6rem)', { lineHeight: '1.1' }],
      },
    },
  },
};

'use client';
import { Canvas } from '@react-three/fiber';
 
export function HeroScene() {
  return (
    <Canvas>
      <mesh>
        <sphereGeometry args={[1, 32, 32]} />
        <meshStandardMaterial color="#0066CC" />
      </mesh>
    </Canvas>
  );
}

src/
├── app/                    # Next.js App Router
│   ├── page.tsx           # 홈
│   ├── feed/              # 블로그 피드
│   │   ├── page.tsx       # 목록
│   │   └── [slug]/page.tsx  # 상세
│   ├── resume/            # 이력서
│   └── _components/       # 공유 컴포넌트
├── lib/                   # 유틸리티
│   └── mdx-feeds.ts       # MDX 파싱 로직
├── types/                 # 타입 정의
├── styles/                # 전역 스타일
└── data/                  # 정적 데이터

// Server Component
export default async function FeedPage() {
  const feeds = getSortedFeedData(); // 서버에서 실행
  return <FeedList feeds={feeds} />;
}

'use client';
import { useState } from 'react';
 
export function FeedList({ feeds }: Props) {
  const [filter, setFilter] = useState('All');
  // ...
}

// src/lib/mdx-feeds.ts
export function getSortedFeedData(): FeedData[] {
  const contentDir = path.join(process.cwd(), 'content');
  const slugs = fs.readdirSync(contentDir);
 
  const allFeedsData = slugs.map((slug) => {
    const metaPath = path.join(contentDir, slug, 'meta.json');
    const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
 
    // Zod 스키마로 검증
    const validated = FeedFrontmatterSchema.parse(meta);
 
    return {
      slug,
      ...validated,
    };
  });
 
  // 날짜 기준 내림차순 정렬
  return allFeedsData.sort(
    (a, b) => new Date(b.date).getTime() - new Date(a.date).getTime()
  );
}

// src/app/feed/[slug]/_components/MdxComponents.tsx
export const MdxComponents = {
  h1: ({ children }: any) => (
    <h1 className="text-4xl font-bold mb-6">{children}</h1>
  ),
  h2: ({ children }: any) => (
    <h2 className="text-3xl font-semibold mb-4 mt-8">{children}</h2>
  ),
  code: ({ children, className }: any) => {
    const isInline = !className;
    return isInline ? (
      <code className="bg-code-bg px-1 py-0.5 rounded text-sm">{children}</code>
    ) : (
      <code className={className}>{children}</code>
    );
  },
};

import { MDXRemote } from 'next-mdx-remote/rsc';
 
<MDXRemote source={feed.content} components={MdxComponents} />;

// src/lib/mdx-feeds.ts
export function parseHeadingsFromHtml(html: string): TocItem[] {
  const $ = cheerio.load(html);
  const headings: TocItem[] = [];
 
  $('h1, h2, h3, h4, h5, h6').each((i, elem) => {
    const level = parseInt(elem.tagName[1]);
    const text = $(elem).text();
    const id = slugify(text);
 
    // ID 자동 할당
    $(elem).attr('id', id);
 
    headings.push({ id, text, level });
  });
 
  return buildTocTree(headings);
}

'use client';
export function InlineTableOfContents({ toc }: Props) {
  const [activeId, setActiveId] = useState('');
 
  useEffect(() => {
    const observer = new IntersectionObserver(
      (entries) => {
        entries.forEach((entry) => {
          if (entry.isIntersecting) {
            setActiveId(entry.target.id);
          }
        });
      },
      { rootMargin: '-100px 0px -66%' }
    );
 
    // 모든 heading 관찰
    document.querySelectorAll('h1, h2, h3').forEach((elem) => {
      observer.observe(elem);
    });
 
    return () => observer.disconnect();
  }, []);
 
  return (
    <nav>
      {toc.map((item) => (
        <a
          href={`#${item.id}`}
          className={activeId === item.id ? 'active' : ''}
        >
          {item.text}
        </a>
      ))}
    </nav>
  );
}

'use client';
import { useEffect, useRef } from 'react';
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
 
export function ReadingProgress() {
  const progressRef = useRef(null);
 
  useEffect(() => {
    gsap.registerPlugin(ScrollTrigger);
 
    gsap.to(progressRef.current, {
      scaleX: 1,
      ease: 'none',
      scrollTrigger: {
        trigger: 'article',
        start: 'top top',
        end: 'bottom bottom',
        scrub: 0.3,
      },
    });
  }, []);
 
  return (
    <div className="fixed top-0 left-0 w-full h-1 bg-accent-tertiary">
      <div
        ref={progressRef}
        className="h-full bg-accent origin-left scale-x-0"
      />
    </div>
  );
}

- <hr className="bg-[#5b504c]" />
+ <hr className="bg-border" />

- className="bg-[var(--bg-primary)] text-[var(--text-primary)]"
+ className="bg-primary text-text-primary"

// Before
'use client';
export function FeedListItem({ feed }: Props) {
  return <Link href={`/feed/${feed.slug}`}>...</Link>;
}
 
// After (Server Component)
export function FeedListItem({ feed }: Props) {
  return <Link href={`/feed/${feed.slug}`}>...</Link>;
}

// tailwind.config.js
fontSize: {
  'display-sm': ['clamp(2rem, 4vw, 2.5rem)', { lineHeight: '1.2' }],
  'display-md': ['clamp(2.5rem, 6vw, 3.5rem)', { lineHeight: '1.2' }],
  'display-lg': ['clamp(4rem, 10vw, 6rem)', { lineHeight: '1.1' }],
  'display-xl': ['clamp(6rem, 15vw, 10rem)', { lineHeight: '1.05' }],
}

- className="text-[clamp(2.5rem,6vw,3.5rem)] max-md:text-[2rem] max-[480px]:text-[1.75rem]"
+ className="text-display-md max-md:text-[2rem]"

// src/app/_components/PageLayout.tsx
export function PageLayout({ title, children }: Props) {
  return (
    <div className="min-h-screen p-8 bg-primary max-md:p-4">
      <header className="max-w-[800px] mx-auto pb-8">
        <BackLink href="/" text="← Home" />
        <h1 className="text-display-lg font-bold">{title}</h1>
      </header>
      <main className="max-w-[800px] mx-auto">{children}</main>
    </div>
  );
}

// Before: 18 lines
export default function FeedPage() {
  return (
    <div className="min-h-screen p-8 bg-primary max-md:p-4">
      <header className="max-w-[800px] mx-auto pb-8">
        <BackLink href="/" text="← Home" />
        <h1 className="text-display-md font-bold">Feed</h1>
      </header>
      <main className="max-w-[800px] mx-auto">
        <FeedList feed={allFeedData} />
      </main>
    </div>
  );
}
 
// After: 12 lines
export default function FeedPage() {
  return (
    <PageLayout title="Feed">
      <FeedList feed={allFeedData} />
    </PageLayout>
  );
}

나: "MDX 기반 블로그 시스템을 만들고 싶어. SSG로 구현하려고 하는데 구조를 어떻게 잡을까?"
AI: [파일 구조 제안, 데이터 fetching 전략, 타입 정의 예시]
나: "좋아, 근데 meta.json을 분리한 이유가 뭐야?"
AI: [YAML frontmatter 이슈 설명, Zod 검증 이점]

나: "TOC를 자동 생성하고 싶은데 어떻게 구현할까?"
AI: [cheerio 활용 방안, IntersectionObserver 예시 코드]
나: "이 코드 동작은 하는데 성능이 걱정되는데?"
AI: [최적화 포인트 제안, rootMargin 조정, debounce 추가]

나: "이 페이지들 레이아웃 코드가 중복인데 어떻게 정리할까?"
AI: [PageLayout 컴포넌트 추상화 제안]
나: "근데 너무 일찍 추상화하는 거 아닌가?"
AI: [중복이 3번 이상일 때 추상화 권장, 현재 2번이므로 보류 가능]
→  결국 2개 페이지지만 패턴이 명확해서 추상화 진행