next-forge 딥다이브
— "빈 종이"가 아니라 "이미 배선된 집" : 20여 개 최고급 서비스가 타입으로 연결된 Next.js 모노레포 표본

1한 줄 정체

next-forge는 "Next.js로 SaaS를 만들 때 필요한 골격 전체를 미리 조립해 둔, 명령어 하나로 내 저장소에 복제되는 프로덕션급 모노레포 템플릿"이다. 마케팅 사이트, 로그인 뒤의 본 앱, 웹훅·크론을 받는 API 서버, 문서 사이트, 이메일 템플릿, 컴포넌트 작업실(Storybook)까지 — 실무 SaaS가 결국 갖게 되는 앱들을 처음부터 나눠 두고, 인증·결제·DB 같은 기능은 갈아끼울 수 있는 패키지로 분리해 둔다.

기술적으로 더 정확히 말하면, next-forge는 Turborepo가 관리하는 Bun 워크스페이스 모노레포다. apps/ 폴더에는 배포 가능한 앱 7개가, packages/ 폴더에는 앱들이 공유하는 패키지 20개가 들어 있다. 각 패키지는 @repo/이름 형태로 import되며(예: @repo/auth, @repo/database), 자기 환경변수를 Zod 스키마로 검증하는 keys.ts를 품고 있다. 즉 "기능 = 패키지 = 갈아끼울 수 있는 부품"이라는 등식이 프로젝트 전체를 관통한다.

2왜 주목받는가 — 스타터가 아니라 "참조 아키텍처"

첫째, Vercel 공식 프로젝트로 편입됐다. 원래 Hayden Bleasel 개인이 만든 next-forge가 지금은 Next.js를 만든 회사 Vercel의 공식 저장소(vercel/next-forge)로 관리된다. "Next.js 팀이 직접 권장하는 SaaS 구조"라는 신뢰가 붙는다. Vercel은 자체 아카데미에 "next-forge 프로덕션 패턴" 강의까지 두고 있다.

둘째, "설치하는 라이브러리"가 아니라 "복제되는 코드"다. 대부분의 프레임워크는 node_modules에 숨어 있어 내부를 못 고친다. next-forge는 init 순간 create-next-app의 --example 기능으로 저장소 전체를 내 프로젝트로 복사한다. 그 뒤로는 100% 내 코드 — 마음대로 뜯어고칠 수 있다. 이걸 요즘은 "fork-and-own(복제해서 소유)" 방식이라 부르고, shadcn/ui가 대중화한 흐름이다.

셋째, "의견이 강하지만(opinionated), 갈아끼울 수 있다". 각 기능이 최고급 프로바이더 하나로 기본 선택되어 있어 초보자는 고민 없이 시작한다. 동시에 각 프로바이더가 @repo/* 패키지 뒤에 캡슐화돼 있어, 나중에 "Clerk 대신 다른 인증", "Resend 대신 다른 이메일"로 바꾸는 마이그레이션 가이드까지 문서로 제공한다. "빠른 시작"과 "장기 유연성"을 동시에 노린 설계다.

넷째, 타입 안전이 "선택"이 아니라 "강제"다. 환경변수조차 문자열로 대충 읽지 않고 @t3-oss/env-nextjs + Zod로 빌드 시점에 검증한다. 예컨대 Clerk 비밀키는 반드시 sk_로 시작해야 한다는 규칙까지 스키마에 박혀 있어, 오타 난 키로 배포되는 사고를 컴파일 단계에서 잡는다. 이런 "실무에서 실제로 데는 부분"을 미리 막아 둔 게 인기의 본질이다.

3기술 스택 전체 지도

① 모노레포 뼈대 (빌드 · 언어 · 품질)

② 앱 7종 (apps/ — 각각 독립 배포 가능)

③ 패키지 20종 (packages/ — @repo/* 로 공유)

4아키텍처 심화 — 타입세이프 env·우아한 성능저하·Turbo 파이프라인

next-forge의 아키텍처를 한 문장으로 요약하면 "앱(apps)은 여러 패키지(packages)를 레고처럼 조립하고, 각 패키지는 외부 서비스를 감싸 타입세이프한 문 하나로 노출한다"이다. 그림으로 보면 이렇다.

핵심 패턴 ① — 타입세이프 환경변수 (keys.ts + Zod)

next-forge에서 가장 자주 마주치는 파일이 keys.ts다. 각 패키지가 자기가 필요한 환경변수를 Zod 스키마로 선언하고, @t3-oss/env-nextjs가 이를 검증한다. 문자열을 그냥 process.env.X로 읽는 게 아니라, "이 값은 sk_로 시작해야 한다" 같은 규칙까지 코드에 박는다.

// packages/auth/keys.ts — 인증 패키지의 env 계약서
import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const keys = () =>
  createEnv({
    // 키가 없어도 앱이 죽지 않게 검증 건너뛰기 스위치
    skipValidation: process.env.SKIP_ENV_VALIDATION === "true",
    server: {
      // 서버 전용 비밀키 — 반드시 sk_ 로 시작(optional=없어도 됨)
      CLERK_SECRET_KEY: z.string().startsWith("sk_").optional(),
    },
    client: {
      // NEXT_PUBLIC_ 접두사 = 브라우저에 노출되는 공개키(pk_)
      NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().startsWith("pk_").optional(),
    },
    runtimeEnv: { /* 실제 process.env 매핑 */ },
  });

핵심 패턴 ② — 우아한 성능 저하 (옵셔널 체이닝)

모든 프로바이더 클라이언트는 키가 없으면 null이 되고, 호출은 옵셔널 체이닝(?.)으로 감싼다. 그래서 Stripe 키를 안 넣어도 결제 기능만 조용히 꺼질 뿐, 앱 전체는 멀쩡히 돈다.

// 키가 있으면 Stripe 인스턴스, 없으면 undefined
export const stripe = env.STRIPE_SECRET_KEY
  ? new Stripe(env.STRIPE_SECRET_KEY)
  : undefined;

// 호출부: stripe가 없으면 그냥 아무 일도 안 일어남(에러 X)
const prices = await stripe?.prices.list();

핵심 패턴 ③ — 서버 컴포넌트 우선 (Server Components First)

Next.js App Router 규칙을 그대로 따른다. page.tsx·layout.tsx는 항상 서버 컴포넌트라, DB·비밀키·서버 전용 API를 브라우저로 내보내지 않고 직접 다룰 수 있다. 버튼 클릭 같은 상호작용이 필요한 부분만 'use client'를 붙인 별도 파일로 분리한다.

핵심 패턴 ④ — Turborepo 파이프라인 (캐시 + 의존성 순서)

turbo.json이 "무엇을 어떤 순서로, 무엇을 캐시하며 돌릴지"를 정의한다. 예컨대 build는 의존 패키지의 build가 먼저 끝나야(^build) 하고, test도 통과해야 실행된다. 한 번 돌린 결과는 캐시돼, 안 바뀐 패키지는 다시 빌드하지 않는다 — 모노레포가 커져도 빌드가 느려지지 않는 비결이다.

// turbo.json (요약)
{
  "tasks": {
    "build": {
      "dependsOn": ["^build", "test"], // 의존성 build + 자기 test 후
      "outputs": [".next/**", "!.next/cache/**"]  // 캐시할 산출물
    },
    "dev": { "cache": false, "persistent": true }  // dev는 캐시 X, 계속 실행
  }
}

핵심 패턴 ⑤ — init CLI (복제 → env 세팅 → ORM → git)

npx next-forge@latest init의 속을 열어 보면 의외로 담백하다. commander로 명령을 파싱하고 @clack/prompts로 예쁜 대화형 질문을 던진 뒤, 실제 복제는 create-next-app의 --example에 next-forge 저장소 URL을 넘겨 처리한다. 그 후 패키지매니저 설정 보정 → .env 파일 생성 → 의존성 설치 → Prisma 빌드 → git 초기화를 순서대로 밟는다.

흥미로운 건 update 명령도 있다는 점이다. 특정 버전 사이의 파일 변경분을 가져와 이미 만든 프로젝트를 최신 next-forge 구조로 따라잡게 돕는다. "복제해서 소유"의 약점(원본이 발전해도 내 프로젝트는 낡음)을 보완하는 장치다.

5디렉토리 구조 해부

패키지 하나의 해부 — @repo/auth 예시

패키지는 대개 세 조각이면 충분하다. 기능을 내보내는 index.ts(x), env를 검증하는 keys.ts, 정체를 밝히는 package.json. 이 패턴이 20개 패키지 전체에 반복되므로 하나만 이해하면 나머지는 자동으로 읽힌다.

packages/auth/
├─ package.json      # name: "@repo/auth", deps: @clerk/nextjs …
├─ keys.ts           # CLERK_SECRET_KEY 등 env를 Zod로 검증
├─ index.ts          # auth(), currentUser() 등 기능 export
├─ client.ts         # 'use client' — 브라우저용 훅/컴포넌트
└─ components/        # 로그인 버튼 등 UI

6학습 포인트 — 기술별 배울 것

① 모노레포 설계 (Turborepo + Bun 워크스페이스)

여러 앱이 공용 코드를 어떻게 나눠 갖는지, 순환 참조 없이 의존성을 어떻게 계층화하는지 배운다. turbo.json의 dependsOn·outputs를 읽으며 "빌드 캐시"가 실제로 어떻게 작동하는지 감을 잡을 수 있다.

실습 아이디어: packages/에 @repo/utils를 새로 만들어 앱 두 곳에서 import해 보기. 그 후 turbo run build를 두 번 돌려 "두 번째는 캐시로 즉시 끝남"을 눈으로 확인.

② 타입세이프 환경변수 (t3-env + Zod)

실무에서 "키 오타 하나로 프로덕션이 죽는" 사고를 구조적으로 막는 법. keys.ts를 여러 개 열어 보며 server / client / runtimeEnv 3분할과 NEXT_PUBLIC_ 접두사의 의미를 익힌다.

실습 아이디어: 새 패키지에 keys.ts를 만들고, 일부러 규칙에 안 맞는 값을 넣어 빌드가 막히는 걸 확인.

③ 프로바이더 캡슐화 (교체 가능한 아키텍처)

왜 Clerk를 앱 곳곳에서 직접 부르지 않고 @repo/auth로 한 번 감쌌는지 이해하면, "의존성 역전"과 "결합도 낮추기"를 실물로 체득한다. 이게 나중에 프로바이더를 갈아끼울 수 있게 하는 핵심이다.

실습 아이디어: @repo/analytics가 PostHog를 어떻게 감쌌는지 읽고, 호출부가 프로바이더 이름을 전혀 모른다는 점을 확인.

④ 서버 컴포넌트 / 서버 액션 (Next.js App Router)

app/ 안에서 서버 컴포넌트가 DB를 직접 조회하고, 폼 제출을 서버 액션으로 처리하는 최신 패턴을 실제 코드로 본다. "언제 'use client'를 붙여야 하는가"의 감을 잡는 데 최고의 교재다.

⑤ 디자인 시스템 중앙화 (shadcn/ui)

버튼·다이얼로그 같은 UI를 앱마다 만들지 않고 @repo/design-system 한 곳에 모아 모든 앱이 같은 룩앤필을 공유하는 법. components.json(new-york 스타일, neutral 베이스, lucide 아이콘)을 읽으며 shadcn 구성을 익힌다.

실습 아이디어: npx shadcn@latest add [컴포넌트] -c packages/design-system로 새 컴포넌트를 추가하고 두 앱에서 동시에 써 보기.

⑥ 서버리스 DB + ORM (Prisma + Neon)

schema.prisma로 모델을 정의하고 bun run migrate(format→generate→push)로 DB에 반영하는 흐름. 서버리스 환경에서 connection pooling을 어댑터(@prisma/adapter-neon)로 어떻게 푸는지도 볼 수 있다.

7시스템 요구사항 & 배포

next-forge는 특별한 하드웨어가 필요 없다. 계산·저장·분석 같은 무거운 일은 전부 외부 서비스(Neon·Vercel·Sentry…)가 클라우드에서 처리하므로, 개발자 컴퓨터는 코드를 편집하고 개발 서버를 띄울 정도면 된다.

배포 — 앱마다 별도 Vercel 프로젝트

배포의 핵심 개념은 "앱 하나 = Vercel 프로젝트 하나"다. app·web·api를 각각 별도 프로젝트로 만들고, 각 프로젝트의 루트 디렉토리를 apps/app·apps/web·apps/api로 지정한다. 환경변수는 프로젝트별로 넣거나 Vercel의 팀 공용 환경변수를 쓴다. 그러면 app.내도메인.com, www.내도메인.com, api.내도메인.com처럼 서브도메인으로 나뉜 실서비스가 된다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

10핵심 키워드 사전

11참고 링크