NeedCash 시작하기: 로컬 개발 환경부터 블로그 작성까지

시작하기 전에

NeedCash 프로젝트를 로컬에서 실행하려면 다음 도구가 설치되어 있어야 합니다:

• Node.js 18+: JavaScript 런타임. nodejs.org에서 LTS 버전을 설치하세요.
• pnpm: 빠르고 효율적인 패키지 매니저. Node.js 설치 후 corepack enable 명령어로 활성화할 수 있습니다.
• Git: 버전 관리 시스템. 소스 코드를 클론하기 위해 필요합니다.

로컬 개발 환경 설정

1. 저장소 클론

git clone https://github.com/needcash/needcash.git
cd needcash

2. 의존성 설치

프로젝트 루트에서 아래 명령어를 실행하면 모든 패키지가 설치됩니다:

pnpm install

3. 개발 서버 시작

cd apps/web
pnpm dev

브라우저에서 http://localhost:3000으로 접속하면 사이트를 확인할 수 있습니다. 파일을 수정하면 실시간으로 반영되는 Hot Module Replacement(HMR)가 활성화되어 있어 개발이 편리합니다.

프로젝트 구조 상세 안내

apps/web/
  app/            → Next.js App Router 기반 페이지 라우팅
    blog/         → 블로그 목록 및 상세 페이지
    game/         → 게임 허브 및 각 게임 페이지
    about/        → 사이트 소개 페이지
    privacy/      → 개인정보처리방침
    terms/        → 이용약관
  components/     → 재사용 가능한 React 컴포넌트
    blog/         → 블로그 관련 (MDX 렌더링, TOC, 관련 글)
    design/       → 디자인 시스템 (테마, 디자인 전환)
    game/         → 게임 컴포넌트 (각 게임별 단일 파일)
    layout/       → 헤더, 푸터, 네비게이션
    ui/           → 공용 UI (버튼, 카드, 모달 등)
  content/blog/   → MDX 블로그 콘텐츠 파일
  lib/            → 유틸리티 함수 (MDX 파싱, 상수 등)
  public/         → 정적 파일 (폰트, 이미지)

각 디렉토리의 역할을 이해하면 새로운 페이지나 컴포넌트를 추가하는 것이 쉬워집니다.

블로그 글 작성 가이드

NeedCash의 블로그는 MDX 형식을 사용합니다. MDX는 마크다운 안에서 React 컴포넌트를 사용할 수 있는 확장 포맷입니다.

새 글 만들기

content/blog/ 디렉토리에 .mdx 파일을 생성합니다. 파일명이 URL 슬러그가 됩니다.

예시: content/blog/my-first-post.mdx → /blog/my-first-post

Frontmatter 작성

모든 블로그 글은 상단에 frontmatter를 포함해야 합니다:

---
title: "포스트 제목"
description: "검색 결과와 미리보기에 표시되는 설명"
date: "2026-02-25"
updatedAt: "2026-02-25"   # 수정일 (선택사항)
category: "tech"           # tech, dev, review, etc, science
tags: ["nextjs", "guide"]
published: true            # false로 설정하면 비공개
---

title, description, date는 필수 항목이고, updatedAt은 글을 수정할 때 추가하면 수정일이 표시됩니다.

마크다운 문법

일반적인 마크다운 문법(제목, 목록, 코드 블록, 링크, 이미지 등)을 모두 지원합니다. 코드 블록은 Shiki 코드 하이라이터를 통해 구문 강조가 적용됩니다.

게임 추가 가이드

새 게임을 추가하는 흐름은 다음과 같습니다:

1. 게임 컴포넌트 작성: components/game/{name}-game.tsx 파일 생성 ("use client" 선언 필수)
2. 아이콘 등록: components/ui/icons.tsx에 게임 아이콘 추가
3. 상수 등록: lib/constants.ts의 GAMES 배열에 게임 정보 추가
4. 페이지 생성: app/game/{name}/page.tsx에서 dynamic import로 게임 컴포넌트 로드

이 패턴을 따르면 일관된 구조로 게임을 추가할 수 있습니다.

디자인/테마 시스템

NeedCash는 4가지 디자인 스타일(Editorial, Bento, Brutalist, Glass)과 각 디자인별 4가지 테마를 지원합니다. CSS 커스텀 프로퍼티(var(--accent), var(--bg) 등)를 활용하여 테마 전환이 이루어지며, data-design과 data-theme HTML 속성으로 현재 활성화된 디자인과 테마가 관리됩니다.

빌드 및 배포

프로덕션 빌드

cd apps/web
pnpm build

빌드가 성공하면 out/ 디렉토리에 정적 HTML 파일이 생성됩니다. 이 파일들을 Cloudflare Pages, Vercel, Netlify 등 정적 호스팅 서비스에 배포할 수 있습니다.

린트 검사

pnpm lint

코드 품질을 유지하기 위해 ESLint를 사용합니다. 커밋 전에 린트 검사를 실행하는 것을 권장합니다.

기여하기

프로젝트에 기여하고 싶으시다면 GitHub에서 Issue를 생성하거나 Pull Request를 보내주세요. 코드 스타일은 프로젝트의 기존 패턴을 따라주시면 됩니다.