Next.js로 블로그 개발

0. 프로젝트 기획 의도

2025년 상반기 취업을 준비하며 다양한 방식으로 회사에 지원했는데 결과가 좋지 않았습니다. 면접까지 간 회사도 있었지만 최종합격까지는 가지 못했습니다. 이러한 상황에서 "어떻게 하면 내가 조금 더 발전된 모습을 어떻게 어필할 수 있을까?" 하는 생각이 들었고, 나의 성장을 보여주기 위해 내가 주도적으로 진행하고 많은 기여를 한 프로젝트가 필요하다고 판단했고, Tech 블로그 개발이 저의 부족한 부분을 채워줄 수 있다고 생각해서 개발을 시작하게 되었습니다.

1. 기획 과정

1-1. 기능 정리

• 우선 블로그에 꼭 필요한 필수 기능을 우선적으로 구현하기로 했습니다.
• 댓글 기능 같은 부가적인 기능은 추후에 업데이트할 예정입니다.

메인 페이지

• 🔹간단한 소개 영역
• 🔹추천 게시글 목록

글 목록 페이지

• 🔹태그 별 목록 띄우기
• 🔹특정 태그에 속한 게시글 필터링

글 상세 페이지

• 🔹MDX 기반 콘텐츠 렌더링
• 🔹제목, 태그, 작성일 표시
• 🔹목차 사이드바(TOC)

콘텐츠 관리

• 🔹posts/ 폴더에서 .mdx 파일로 글 작성
• 🔹글마다 메타데이터(title, date, tags 등) 설정

부가 기능

• 🔹태그 필더링
• 🔹다크/라이트 모드 전환(next-theme)
• 🔹반응형 UI

1-2. 기술 스택 선정

블로그 개발 프로젝트를 계획하며 기술 스택 선정 과정을 가졌습니다. 개인 프로젝트인 만큼 내가 부족한 부분을 채우는 것이 목적이었기 때문에, 그동안 사용해보지 않은 Next.js를 기반으로 개발하기로 마음 먹었습니다. 이후 Next.js와 궁합이 좋은 기술들을 선택하여 기술 스택을 선정하였습니다.

현재 Next.js는 React 생태계에서 가장 인기 있는 프레임워크 중 하나입니다.

• -> 정적 생성(SSG), 서버 사이드 렌더링(SSR), 동적 라우팅 등 다양한 렌더링 방식을 지원해 콘텐츠 중심의 블로그에 적합합니다.
• -> 또한, Vercel로 배포할 예정이라 해당 플랫폼과 궁합이 좋은 Next.js를 선택하게 되었습니다.
• -> 마지막으로 처음 사용해보는 기술을 개인 프로젝트에서 적용해 보며 자유롭게 실험하고 학습할 수 있는 기회가 될 것 같아 선택하게 되었습니다.

최근 프론트엔드 개발에서는 TypeScript가 사실상 기본으로 요구되고 있습니다.

• -> 정적 타입 지정을 통해 코드를 작성할 때 오류를 미리 방지할 수 있으며, 이는 리팩토링 과정에서 코드 안정성을 높이는 데 도움이 됩니다.
• -> 특히 Next.js가 TypeScript를 공식 지원하며, 전용 타입 정의(AppProps, GetStaticprops 등) 및 다양한 기능(MDX 등)에 타입 적용이 가능해 높은 개발 효율을 기대할 수 있습니다.
• -> 추가로 사용하는 UI 라이브러리인 shadcn/ui 역시 TypeScript 기반이기 때문에 선택하게 되었습니다.

최근 프론트엔드에서는 CSS-in-JS보다 Utility-First CSS 방식이 주목 받고 있으며, 그 중심에 Tailwind CSS가 있씁니다.

• -> Tailwind는 클래스 단위로 스타일을 조합하는 방식이라 컴포넌트 기반 UI 개발에 매우 적합하고, 복잡한 CSS 구조 없이도 빠르게 UI를 구현할 수 있습니다.
• -> 또한 반응형, 디자인, 다크모드, 커스텀 테마 설정 등 모던 웹 UI에 필요한 기능들이 기본적으로 내장되어 있어 생상성을 높여줍니다.

shadcn/ui는 최근 빠르게 인기를 얻고 있는 Tailwind 기반의 오픈소스 UI 컴포넌트 라이브러리입니다.

• -> Button, Card, Dialog 등 다양한 컴포넌트를 제공하면서, 모든 코드를 직접 가져와 사용하는 구조이기 때문에 자유로운 커스터마이징이 가능합니다.
• -> 내부적으로는 Radix UI와 Tailwind CSS를 기반으로 하여 접근성과 디자인의 일관성을 모두 갖추고 있으며, 필요한 컴포넌트만 선택적으로 추가할 수 있어 번들 크기를 최소화할 수 있다는 장점도 있습니다.

Vercel은 Next.js의 공식 배포 플랫폼으로, Next.js 프로젝트를 가장 쉽고 안정적으로 배포할 수 있는 환경을 제공합니다.

• -> GitHub와 연동해 커밋만으로 자동 배포가 가능해 CI/CD 구성이 간편하며, 개발-배포 사이클을 빠르게 반복할 수 있습니다.
• -> 전 세계에 분산된 CDN을 통해 빠른 응답 속도를 제공하며, 정적 파일과 이미지 최적화도 자동으로 처리됩니다.
• -> 특히 Next.js와 궁합이 뛰어나 SSR, SSG 등의 렌더링 방식도 지원합니다.
• -> 또한 무료 요금제가 제공되기 때문에, 사이드 프로젝트에 적합하다고 판단했습니다.

2. 개발 환경 세팅

• 개발 초기에는 프로젝트 구조 설계와 기본 도구 설치 및 세팅을 진행했습니다.
• 참고로 윈도우로 진행했습니다!

2-1. 기본 패키치 설치

npx create-next-app@latest --typescript

• -> TypeScript 기반의 Next.js 프로젝트 생성

이후 필요한 주요 패키치 설치

npm install tailwindcss postcss autoprefixer
npx tailwindcss init -p

npm install classnames gray-matter next-mdx-remote
npm install @tailwindcss/typography
npm install rehype-slug rehype-autolink-headings
npm install next-themes

• -> gray-matter: mdx의 frontmatter 파싱
• -> next-mdx-remote: MDX 파일 렌더링
• -> rehype-slug, rehype-autolink-headings: 목차 자동 생성
• -> next-themes: 다크모드 적용

2-2. CSS 설정

tailwind.config.ts에서 다음과 같이 커스텀 설정을 적용했습니다.

theme: {
  extend: {
    fontFamily: {
      sans: ["Pretendard", "sans-serif"],
    },
    typography: {
      DEFAULT: {
        css: {
          a: { color: "#2563eb", fontWeight: "500" },
          h1: { fontSize: "2.25rem", fontWeight: "700" },
          h2: { fontSize: "1.875rem", fontWeight: "600" },
        },
      },
    },
  },
},
plugins: [require("@tailwindcss/typography")],

globals.css 파일에 Tailwind 기본 스타일과 추가적인 전역 스타일을 정의했습니다.

@tailwind base;
@tailwind components;
@tailwind utilities;

html {
  scroll-behavior: smooth;
}

body {
  font-family: "Pretendard", sans-serif;
}
//...

2-3. 폴더 구조 정리

폴더 구조는 다음과 같이 정리했습니다.

public/
├── images          #favicon 및 썸네일 이미지 저장
src/
├── components/     # 공통 컴포넌트
├── pages/          # 라우팅 경로
├── posts/          # MDX 파일 저장
├── styles/         # 글로벌 스타일 및 테마
├── lib/            # 유틸 함수들 (toc, post 처리 등)
├── types/          # TypeScript 타입

2-4. MDX 렌더링 설정

• -> next.config.js는 별도로 mdx loader를 설치하지 않고 next-mdx-remote를 통해 서버에서 직렬화
• -> getStaticProps와 getStaticPaths를 활용한 정적 생성

3. 기능 구현

간단하게 어떤 기능을 구현했는지 위주로 작성하겠습니다. 트러블 슈팅이나 보다 디테일한 내용은 따로 빼서 정리할 예정입니다.

3-1. 글 상세 페이지 렌더링

블로그에서 가장 핵심이 되는 글 상세 페이지를 먼저 구현했습니다. Markdown 기반이 아니라 MDX를 사용해, JSX 컴포넌트도 함께 사용할 수 있도록 했습니다.

• -> /posts/*.mdx 파일로 콘텐츠를 작성하고 gray-matter로 frontmatter(titlte, date, tags 등) 파싱
• -> getStaticPaths로 모든 글 경로를 미리 생성
• -> next-mdx-remote로 .mdx 파일을 직렬화하여 SSR 렌더링
• -> MdxContentLayout로 통일된 스타일 적용

const mdxSource = await serialize(content, {
  mdxOptions: {
    rehypePlugins: [rehypeSlug, rehypeAutolinkHeadings],
  },
});

3-2. 다크/라이트 모드 전환 기능

next-themes를 사용해 블로그에 다크/라이트모드를 적용했습니다. 다크모드 여부에 따라 배경색, 텍스트 색상이 달라지도록 했습니다.

• -> 사용자 환경에 따라 자동으로 다크/라이트 테마 적용
• -> 토글 버튼으로 수동 전환도 가능하게 함

• -> ThemeProvider를 _app.tsx에 감싸고 attribute="class" 옵션 사용
• -> document.documentElement.classList 기반으로 Tailwind에서 dark: prefix가 작동

<ThemeProvider attribute="class">
  <Component {...pageProps} />
</ThemeProvider>

• -> 헤더에 간단한 다크모드 토글 스위치 추가
• -> useTheme() 훅으로 현재 테마 확인 및 토글 가능

3-3. 태그 기반 필터링

글 목록 페이지에서 태그 필터링 기능을 구현하여 주제 별로 글을 모아볼 수 있게 구현했습니다.

• -> 태그를 클릭하면 해당 태그에 속한 글만 필터링해서 보여주기

• -> 모든 글의 메타데이터에 tags 포함
• -> URL 파라미터 또는 useState 기반으로 필터 상태 관리
• -> 필터된 글만 리스트에 렌더링

const filtered = tag
  ? allPosts.filter((post) => post.tags.includes(tag))
  : allPosts;

4. 앞으로

일단 블로그에 글을 작성하고 띄우는 기본적인 필수 기능들은 완성을 해서 계속해서 기술 블로그를 작성할 예정입니다. 그러나 아직 완벽한 코드가 아니라고 생각이 돼서 조금 리팩토링을 하려고 합니다. 대표적으로 코드 블럭에 `` 태그가 안써지더라구요? 그래서 오류도 해결하고 보다 더 깔끔하게 리팩토링 할 예정입니다. 이후 댓글 기능과 about 파트에 간단한 포트폴리오도 작성 등 블로그의 퀄리티를 높일 수 있는 기능들을 추가할 예정입니다.

5. 마치며

• 처음에는 포트폴리오를 채우려는 마음으로 시작했지만 하다보니 새로운 기술을 학습하고 적용하는 것에 대한 흥미를 느꼈던 프로젝트였습니다.

• Next.js를 사용하는 것에 대해 아직 React도 완벽하게 하지 못하는데 이걸 하는 게 맞나? 하는 생각이 들었는데, 해보니까 React의 프레임워크이기 때문에 비슷한 점이 있었고 오히려 새로운 부분을 많이 알아갈 수 있었습니다.

• Tailwind도 솔직히 사용하기 전에는 기존 CSS나 CSS-in-JS 코딩 방식과 차이가 있었기 때문에 반감이 있었는데 익숙해지니까 사용하기에 편리한 CSS 기술인 것 같다고 느꼈습니다.

• 역시 기술 스택을 익히는 데에는 프로젝트만한게 없는 것 같습니다. 앞으로도 말한 것처럼 블로그 프로젝트 리팩토링과 기능을 추가하며 계속 기술에 적응해 나가겠습니다.

• 긴글 읽어주셔서 감사합니다!!