freeCodeCamp 딥다이브
— 45만 ★ '실서비스 풀스택 모노레포'를 통째로 뜯어보기

1프로젝트 한줄 요약

한 문장으로 이 프로젝트가 뭘 하는지부터.

freeCodeCamp = "수백만 명이 쓰는 무료 코딩 학습 플랫폼의 전체 소스 + 수천 개 강의를, 하나의 모노레포에 담아 누구나 기여하게 만든 비영리 오픈소스." 단순히 강의를 보여주는 사이트가 아니다. 인터랙티브 코드 에디터, 진도·인증서 관리, 결제(기부), 다국어, 시험 환경까지 갖춘 완결된 풀스택 웹 서비스이고, 그 코드 전부가 공개돼 있다.

규모 감각을 잠깐 — 이 저장소는 git에 약 1만 9천 개 이상의 파일을 담고 있고, README가 밝히듯 freeCodeCamp 커뮤니티는 이미 10만 명 이상이 첫 개발자 일자리를 얻도록 도왔다. 코드 자체도 GitHub에서 가장 많은 별(★449k)과 포크(45k)를 가진 저장소 중 하나다. 즉 "학습 자료"인 동시에 "초대형 오픈소스 협업의 표본"이다.

2왜 주목받는가

TrendShift 일간 8위 — 늘 상위권에 머무는 '스테디셀러'의 이유.

freeCodeCamp는 반짝 트렌드가 아니라 수년째 GitHub 최상위권을 지키는 스테디셀러다. 2014년 시작해 지금도 매일 커밋이 쌓인다(이 분석 시점 기준 마지막 푸시도 하루 전). 왜 개발자들이 계속 이 저장소로 모이는지를 다섯으로 정리한다.

① "기여하기 가장 좋은 OSS" — first-timers-only 친화

README 최상단에 first-timers-only friendly 배지가 붙어 있다. 오픈소스 기여가 처음인 사람도 커리큘럼의 오타 수정·번역·새 챌린지 추가처럼 진입 장벽 낮은 일부터 시작할 수 있게 설계됐다. 실제 기여 가이드(contribute.freecodecamp.org)가 별도 사이트로 잘 정리돼 있다.

② 학습 자료이자, 실서비스 코드 그 자체

대부분의 '학습용 레포'는 장난감 예제다. freeCodeCamp는 반대로 진짜 수백만 명이 쓰는 프로덕션 서비스의 코드다. 인증(Auth0), 결제(Stripe), 모니터링(Sentry), 기능 플래그(GrowthBook), 검색(Algolia) 같은 실무에서 진짜 쓰는 도구들의 통합 사례를 한곳에서 볼 수 있다.

③ 풀스택 모노레포의 모범 답안

프론트(Gatsby/React)·백(Fastify)·콘텐츠(마크다운 커리큘럼)·테스트(Playwright)가 pnpm 워크스페이스 + Turborepo로 깔끔하게 분리·연결돼 있다. "여러 팀이 하나의 큰 코드베이스를 어떻게 나눠 갖고 빌드를 캐싱하는가"를 배우기에 더없이 좋은 표본이다.

④ 콘텐츠를 '코드처럼' 다루는 설계

수천 개의 강의가 전부 마크다운 파일 + 프론트매터로 저장되고, 빌드 파이프라인이 이를 curriculum.json으로 변환한다. "교육 콘텐츠를 Git으로 버전 관리하고, PR로 리뷰하고, 테스트로 검증한다"는 발상은 그 자체로 배울 거리다(이른바 Docs/Content-as-Code).

⑤ 거대한 다국어·접근성 운영

플랫폼과 커리큘럼이 수십 개 언어로 번역된다. i18next(클라이언트), Crowdin 연동(tools/crowdin), i18n-curriculum 서브모듈까지 — 국제화(i18n)를 대규모로 굴리는 실전 구조를 통째로 보여준다.

3기술 스택 전체 지도

루트·각 워크스페이스의 package.json에서 직접 확인한 실제 구성.

freeCodeCamp는 처음부터 끝까지 TypeScript/JavaScript 기반이다. 한 언어로 프론트·백·도구·테스트를 모두 작성해, 공통 코드(packages/shared)를 양쪽에서 재사용한다. 레이어별로 끊어 보자.

ⓐ 모노레포 기반 — 빌드·패키지 관리

ⓑ 프론트엔드 — client/ (Gatsby + React)

ⓒ 백엔드 — api/ (Fastify + MongoDB)

ⓓ 콘텐츠 & 도구 — curriculum/, tools/, packages/

ⓔ 테스트 & 인프라

4아키텍처 심화 분석

소스가 어떻게 짜여 한 서비스가 되는가 — 모노레포 구조 + 두 갈래 흐름.

freeCodeCamp의 아키텍처는 세 가지 큰 그림으로 이해하면 된다 — ① 모노레포가 어떻게 묶여 빌드되는가, ② 사용자가 강의를 풀 때 요청이 어떻게 흐르는가, ③ 마크다운 강의가 어떻게 화면이 되는가. 차례로 본다.

그림 1 — 모노레포 전체 구조

핵심은 turbo.json의 의존 그래프다. 예컨대 build는 setup에 의존하고 setup은 ^build(상위 의존 패키지의 build)에 의존한다. 그래서 shared가 먼저 빌드되고, 그걸 쓰는 api·client가 나중에 빌드되도록 순서가 자동으로 정렬된다. 한 번 빌드한 결과는 캐싱돼, 안 바뀐 워크스페이스는 다시 빌드하지 않는다.

그림 2 — 강의를 풀고 제출할 때의 요청 흐름

이 그림에서 배울 패턴은 라우트의 공개/보호 분리다. routes/public/(로그인·상태·기부 등 누구나)와 routes/protected/(진도·설정 등 로그인 필요)가 폴더로 나뉘고, auth·bouncer 플러그인이 보호 라우트 앞에서 "이 사람이 누구인지(인증)"와 "이 작업을 할 권한이 있는지(인가)"를 차례로 검사한다.

// api/src/app.ts — 플러그인 조립 순서(개념 요약)
await app.register(cors);
await app.register(cookies);
await app.register(auth);      // JWT 쿠키 → req.user 채움
await app.register(bouncer);   // 비로그인 차단(인가 게이트)
await app.register(csrf);
await app.register(prismaPlugin); // req.server.prisma 로 DB 접근
// 그리고 라우트 등록
await app.register(publicRoutes,    { prefix: '/' });
await app.register(protectedRoutes, { prefix: '/' });

그림 3 — 마크다운 강의 → 화면이 되는 빌드 파이프라인

freeCodeCamp에서 가장 독창적인 부분. 강의 하나하나가 코드가 아니라 구조화된 마크다운 파일이다. 실제 챌린지 파일은 이렇게 생겼다.

# curriculum/challenges/english/blocks/react/...md
---
id: 5a24c314108439a4d4036183
title: Use Advanced JavaScript in React Render Method
challengeType: 6
dashedName: use-advanced-javascript-in-react-render-method
---

# --description--      # 설명 (학습자에게 보여줄 본문)
... 마크다운 설명 ...

# --instructions--     # 지시문 (무엇을 하라)
... 할 일 ...

# --hints--            # 채점 테스트 (통과해야 완료)
```js
assert.strictEqual(Enzyme.mount(...).length, 1);
```

이 설계의 묘미 — 콘텐츠와 코드가 분리돼 있다. 강의를 고치는 사람은 마크다운만 건드리면 되고(번역가·교육자 친화), 플랫폼 개발자는 파서·빌더만 다루면 된다. 그리고 강의의 --hints-- 블록(채점 테스트)이 곧 콘텐츠의 일부라, "강의가 제대로 작동하는지"를 자동 테스트로 검증할 수 있다(test-content).

핵심 설계 패턴 정리

5디렉토리 구조 해부

저장소를 열었을 때 어느 폴더부터 봐야 하는가.

처음 열면 폴더가 많아 압도된다. 핵심만 추리면 네 개의 큰 워크스페이스(client·api·curriculum·e2e) + 두 개의 공용 묶음(packages·tools)이다. 나머지는 설정·인프라다.

6학습 포인트 (기술별)

이 레포에서 실제로 무엇을 배울 수 있는가 — 기술별 + 실습 아이디어.

7하드웨어 / 시스템 요구사항

로컬에서 띄우려면 무엇이 필요한가 — 솔직한 난이도와 권장 경로.

먼저 솔직하게 — freeCodeCamp 전체를 로컬에서 띄우는 건 가벼운 작업이 아니다. Node 24, pnpm 10, 그리고 Docker(MongoDB)가 필요하고, 빌드 단계에서 메모리도 꽤 먹는다(클라이언트 빌드는 --max-old-space-size=7168, 즉 약 7GB 힙을 잡는다). 공식 권장의 핵심을 정리한다.

로컬 셋업의 큰 그림 (개념)

# 0) Node 24 + pnpm 10 준비 (nvm 권장)
nvm install 24 && nvm use 24
npm i -g pnpm@10

# 1) 의존성 설치 (모든 워크스페이스 한 번에)
pnpm install

# 2) DB·메일 인프라 띄우기 (MongoDB 레플리카셋 + Mailpit)
docker compose -f docker/docker-compose.yml up -d

# 3) 환경변수 견본 복사 후 채우기
cp sample.env .env

# 4) 데모 데이터 시드 (설문·시험·데모 사용자)
pnpm seed

# 5) 개발 서버 가동 (turbo가 client+api 동시 구동)
pnpm develop   # client :8000, api :3000

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

난이도별로 — '실행'보다 '읽고 추적'이 먼저인 거대 레포다.

이 레포는 규모가 커서, 코드를 읽고 구조를 추적하는 과제부터 시작하는 게 효율적이다. 아래로 갈수록 난이도가 올라간다.

9관련 기술 심화 학습 로드맵

freeCodeCamp를 발판으로 '대형 풀스택 모노레포'를 제대로 — 6주 계획.

10핵심 키워드 사전

문서·코드·설정에 자주 나오는 용어 — 한 줄 정의.

11참고 링크

원문으로 더 깊이 — 공식 소스 위주.

• GitHub 저장소: github.com/freeCodeCamp/freeCodeCamp
• 기여 가이드(필독): contribute.freecodecamp.org
• 로컬 셋업 문서: how-to-setup-freecodecamp-locally
• 학습 플랫폼(실서비스): freecodecamp.org/learn
• 기술 출판물(뉴스): freecodecamp.org/news
• 커뮤니티 포럼: forum.freecodecamp.org
• 핵심 기술 문서: Fastify · Turborepo · Gatsby · Prisma
• TrendShift 페이지: trendshift.io/repositories/1778