Next.js부터 GitHub 연동까지: JIRA 클론 기술 해부 Phase 1: 기반 구축

 

 

사내에서 사용하는 지라를 직접 만들어보자고 파일럿 프로젝트를 제안주셔서 진행해본다.

 

바이브 코딩을 하다보면 내가 알지도 못하는 기술을 커서 IDE가 다 해주지만, 추후 운영을 위해서는 기술에 대한 스터디가 필요하기 때문에 Phase별로 쪼개서 스터디를 하고자한다. 플러터 개발하는 동안 뭐이리 새로운 기술이 많이 등장했는지 헷갈리는게 너무 많다..

 

Phase는 우선 ver1로는 총 9단계 까지가있다. 

 

Phase 1: 기반 구축

• Next.js 14 + TypeScript 프로젝트 초기화
• Prisma + PostgreSQL 설정
• tRPC 설정
• shadcn/ui 컴포넌트 설정
• Docker + docker-compose 환경 구성 (PostgreSQL, Redis

 

1. Next.js란 무엇인가 

한 줄 정의

Next.js는 React 기반의 풀스택 웹 프레임워크로,
이 프로젝트에서는 UI + API + 인증 + 서버 로직을 하나의 코드베이스로 관리하기 위해 사용한다.

---

기존 React(Vite, CRA)와의 핵심 차이

                             단독                                            Next.js

 

구분	React 단독	Next.js
렌더링	CSR만	CSR + SSR + SSG
라우팅	직접 설정	파일 기반 라우팅
API	별도 서버 필요	API Routes 내장
인증	외부 서버 연동	서버 컴포넌트에서 직접 처리
배포	프론트만	풀스택 배포 가능

JIRA 같은 서비스는

• 인증
• 권한
• API
• UI
  가 tightly-coupled 되어 있기 때문에 Next.js가 구조적으로 유리하다.

 

이 JIRA 클론 프로젝트에서 Next.js의 역할

이 프로젝트에서 Next.js는 단순한 “프론트엔드”가 아니다.

• 화면(UI)
  • 대시보드, 칸반보드, 이슈 상세, 위키
• 서버 로직
  • 이슈 CRUD, 권한 체크
• API 레이어
  • tRPC 기반 타입 안전 API
• 인증 처리
  • NextAuth.js 서버 연동
• 배포 단위
  • Docker/ECS로 하나의 서비스로 배포

 

 

5년 전에 내가 리액트로 개발할때와 달라진 점

예전 (React + Redux 시절)

 

React (UI) ↓ fetch Spring / Node 서버 (API) ↓ DB

• 프론트: React
• 백엔드: 따로 필요
• API 서버 필수

 

지금 (Next.js)

Next.js 하나
 ├─ 화면(UI)
 ├─ 서버 코드(API)
 ├─ 인증
 └─ DB 연결​

한 프로젝트 안에 프론트 + 백이 같이 있음

 

 

Next.js 프로젝트를 생성하면 다음이 자동으로 만들어진다. 서비스의 기본 뼈대 즉 디렉토리 구조, 빌드 시스템, 런타임 환경을 만드는 작업이다.

 

 

Next.js 프로젝트 생성

“프론트 + 백엔드가 같이 들어있는 서비스 뼈대를 만든 것”

그래서 자동으로 생긴 것들:

• React 쓸 수 있는 환경
• 서버 코드 쓸 수 있는 환경
• API 만들 수 있는 구조
• 빌드/실행 설정

jira-clone/
├── src/
│   ├── app/
│   │   ├── layout.tsx        # 전체 레이아웃
│   │   ├── page.tsx          # 메인 페이지 (/)
│   │   ├── globals.css       # 전역 스타일
│   │   └── api/              # API Routes
│   ├── components/           # 공통 UI 컴포넌트
│   ├── lib/                  # 공용 유틸
│   └── types/                # 타입 정의
├── public/                   # 정적 파일
├── package.json              # 의존성/스크립트
├── tsconfig.json             # TypeScript 설정
└── next.config.js             # Next.js 설정

 

 

• Next.js → 프론트엔드 중심의 풀스택 프레임워크
  •  브라우저에 보여줄 화면을 직접 만든다
  • 동시에 서버 코드도 쓸수있어서 프론트 개발자가 백까지 같이 할때 사용
• NestJS → 백엔드 전용 서버 프레임워크
  • API만 제공, 화면은 따로 리액트나 뷰가 필요, 백엔드 개발자용

 

구분	Next.js	NestJS
정체	React 기반 풀스택 프레임워크	Node.js 백엔드 프레임워크
주 역할	UI + 서버 로직	API 서버
UI 렌더링	가능 (React)	불가
DB 접근	가능	가능
API 제공	가능	핵심 역할
프론트 포함 여부	포함	없음

 

Next.js의 핵심장점

 

1. 프론트 백 경계가 물리적으로 가까움.  같은 타입 타입스크립트로. 프론트와 백이 같은 Git저장소에 있기에 같은 레포. 즉 협업 유지보스가 쉬움

같은 레포의 예시)

jira-clone-repo
 ├─ app/        ← 화면 (프론트)
 ├─ server/     ← 서버 로직 (백엔드)
 ├─ prisma/     ← DB 스키마
 └─ types/      ← 공통 타입

 

Next.js + TypeScript에서 말하는 “같은 타입”

같은 레포니까 가능한 구조

 

types/issue.ts

export type Issue = { id: string title: string status: "TODO" | "IN_PROGRESS" | "DONE" }

 

서버에서 사용

function getIssue(): Issue { ... }

 

프론트에서 사용

const issue: Issue = data

 

 

서버와 프론트가 같은 파일의 타입을 씀

이게 “같은 타입”의 정확한 의미다.

예전엔

예전 방식: 타입이 분리됨 (문제의 근원)

 

백엔드

 

{ "id": "1", "title": "로그인 구현", "status": "TODO" }

 

프론트 (추측)

type Issue = { id: number // ❌ 틀림 title: string status: string }

문제:

• 문서 안 보면 모름
• 런타임에서 터짐
• QA에서 발견

tRPC까지 오면

API 응답 타입을 사람이 안 만든다 -> 타입을 서버 코드에서 자동 추론 함. 타입 정의 따로 필요 없ㅇ므

 

2. API 명세 관리 지옥에서 해방! tRPC쓰면 프론트 <-> 백엔드 타입 자동 공유. 이 필드 뭐였지? 할 필요가 업음

3. 서버에서 바로 DB접근 가능 -> 불필요한 API 레이어 감소

4. 빌드 한번만하면 서버 프론트 다 배포되니까 배포가 단순화 되어서 좋음

 

---...

 

 

근데 다음 경우엔 NestJS 같은 순수 백엔드가 필요해진다.

• 모바일 앱 API
• 외부 파트너 API
• 대규모 트래픽
• 복잡한 도메인 로직
• 여러 클라이언트(Web, App, 외부)

 

 

왜 Neon을 쓰는가

 

Neon으로 무료 PostgreSQL을 만들고, .env 파일의 DATABASE_URL만 변경하여 실행함

 

선택지                                                                                    단점

로컬 PostgreSQL 설치	환경 세팅 귀찮음, 팀 공유 불편
AWS RDS	비용 + 설정 과함
Neon	무료, 즉시 사용, URL 하나로 끝

 

 

 

tRPC / Server Component / Server Action 역할·왜 생겼는지·API랑 뭐가 다른지 기준

 

브라우저
  ↓
Client Component (프론트 UI)
  ↓
Server Component / Server Action / tRPC
  ↓
DB (Prisma)
DB는 절대 브라우저가 직접 접근 안 함

“API 레이어 감소” = HTTP 엔드포인트를 직접 설계하는 단계가 줄어듦

 

 

구분	Server Component	Server Action	tRPC
용도	화면 렌더링	데이터 변경	API 대체
호출 방식	페이지 로딩	사용자 액션	JS 함수 호출
fetch 필요	❌	❌	❌
DB 접근	⭕	⭕	⭕
캐싱/상태	제한적	제한적	강함

 

 

불필요한 API 레이어 감소”의 정확한 의미

예전 구조

 

UI ↓ fetch REST API ↓ Service ↓ DB

---

Next.js + tRPC 구조

 

UI ↓ 함수 호출 tRPC / Server Action ↓ DB

사라진 것

• URL 설계
• HTTP 메서드
• DTO
• Swagger
• 중복 타입

API는 여전히 존재하지만, 사람이 관리할 게 줄어듦

---

그렇다고 REST API가 이제 사용되지 않는 것이 아니다.

다음 경우엔 여전히 필요하다.

• 모바일 앱
• 외부 공개 API
• 다른 서비스 연동

 이때는 NestJS 같은 백엔드 필요