Exordium

개인 엔지니어링 블로그 플랫폼

English · 日本語

---

소개

Exordium은 GitHub OAuth 기반 인증을 사용하는 개인 엔지니어링 블로그 플랫폼입니다. Lexical 기반 리치 텍스트 에디터로 게시글을 작성하고, 방문자는 댓글과 이모지 리액션으로 소통할 수 있습니다. Owner(운영자) 1인 체제로 설계되어 있으며 한국어·영어·일본어 UI를 지원합니다.

주요 기능

• 게시글 — Lexical 기반 리치 텍스트 에디터, 이미지 업로드, 태그, 무한 스크롤, 30초 자동 임시저장
• 댓글 & 리액션 — GitHub 계정으로 로그인한 누구나 참여 가능, 1-depth 답글, 이모지 리액션
• 오픈소스 프로젝트 — 드래그 앤 드롭으로 순서 변경 가능한 프로젝트 목록
• 테마 — 라이트/다크 모드 + 6가지 컬러 팔레트 (localStorage 유지)
• i18n — 한국어 / 영어 / 일본어 UI 전환
• SSR — TanStack Start 기반 서버사이드 렌더링과 공개 글 본문 HTML 출력

기술 스택

분류	기술
프레임워크	TanStack Start (React 19)
라우팅	TanStack Router
서버 상태	TanStack Query v5
에디터	@jikjo/core (Lexical 기반)
스타일	Tailwind CSS v4 + tailwind-variants
UI 컴포넌트	Base UI + basecn 레지스트리
백엔드	Supabase (PostgreSQL + Auth + Storage)
폼 검증	TanStack Form + Valibot
패키지 매니저	Bun

시작하기

1. 저장소 클론

git clone https://github.com/your-username/exordium.git
cd exordium
bun install

2. 환경 변수 설정

.env.example을 참고해 .env.local을 생성합니다.

cp .env.example .env.local

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=sb_publishable_your-key
VITE_SITE_URL=http://localhost:3000

VITE_SUPABASE_PUBLISHABLE_KEY에 Publishable key를 설정합니다. 기존 배포를 위해 VITE_SUPABASE_ANON_KEY도 fallback으로 지원하며, 둘 다 설정하면 새 변수명이 우선합니다. 운영자 권한은 환경변수가 아니라 Supabase 사용자 app_metadata.role = "owner"로 판별합니다. VITE_SITE_URL은 배포 빌드에서 실제 공개 도메인으로 설정하세요.

아래 SQL은 새 프로젝트를 초기화할 때 실행합니다. 이미 사용 중인 데이터베이스에 다시 실행하지 마세요. seed.sql의 프로필은 본인 정보로 수정한 뒤 적용하세요.

3. Supabase 마이그레이션

Supabase 대시보드 → SQL Editor에서 아래 파일을 순서대로 실행합니다.

supabase/migrations/001_schema.sql
supabase/seed.sql

기존 운영 DB에는 supabase/migrations/20260911084300_atomic_open_source_ordering.sql만 추가 적용하세요. 이 함수는 프로젝트 순서를 한 트랜잭션으로 저장하며, 새 프로젝트도 초기 스키마 이후 적용해야 합니다. PR 머지는 운영 DB migration을 자동 실행하지 않습니다.

4. GitHub OAuth 설정

Supabase 대시보드 → Authentication → URL Configuration:

• Site URL: https://your-domain.com
• Redirect URLs에 아래 두 URL 추가:
  • https://your-domain.com/auth/callback
  • http://localhost:3000/auth/callback

5. 개발 서버 실행

bun run dev

6. 프로덕션 빌드 & 실행

bun run build
bun run start

7. Docker로 실행 (선택)

docker build -t exordium .
docker run -p 3000:3000 --env-file .env.local exordium

프로젝트 구조

Feature-Sliced Design(FSD) 아키텍처를 따릅니다.

src/
├── entities/      # 도메인 엔티티 (post, comment, user, owner, open-source, reaction)
├── features/      # 사용자 인터랙션 단위 (create-post, toggle-reaction, manage-open-source, ...)
├── widgets/       # 복합 UI 블록 (header, footer, post-list, comment-section, ...)
├── shared/        # 공용 유틸, 훅, UI 컴포넌트, i18n, 설정
└── routes/        # 라우트 파일 (라우팅 로직만, UI 구현 없음)

supabase/
└── migrations/    # SQL 마이그레이션 파일

스크립트

bun run dev        # 개발 서버 실행
bun run build      # 프로덕션 빌드
bun run start      # 프로덕션 서버 실행
bun run lint       # oxlint 정적 분석
bun run fmt        # oxfmt 코드 포맷
bun run test       # vitest 테스트 실행

---

_{Built with TanStack Start}

로컬 전용 Supabase와 반복 테스트의 설치·실행 명령은 로컬 테스트 환경을 참고하세요.