Turborepo + Vite + React 모노레포 세팅하기 (TanStack Router, Tailwind, shadcn 포함)

계속 같은 프로젝트를 진행 중인데,

유사한 UI의 시스템 2개를 동시에 관리해야 하는 경우 어떻게 해야할지에 대해 계속 고민됐었다.

 

이 경우 turborepo 사용을 많이 추천 받았는데,

모노레포 구조가 익숙하지 않아 기존 방식대로 계속 작업하다가 이제야 도입해봤다.

 

Turborepo + Vite + React + TanStack Router + TailwindCSS 세팅 과정

 

1. Turborepo 프로젝트 생성

먼저 Turborepo 기본 뼈대를 만들어준다.

npx create-turbo@latest cms-monorepo
cd cms-monorepo

 

생성된 구조는 다음과 같다.

cms-monorepo/
  apps/        # 실제 실행할 앱들
    docs/
    web/
  packages/    # 공통 UI, 설정
  package.json # 루트 package.json (공통 deps)
  turbo.json   # Turborepo 설정

 

2. Vite + React 앱 생성

이제 apps/ 폴더 안에 실제 앱을 만든다.
여기서 중요한 건 반드시 apps/ 안에서 생성해야 한다는 점이다.

cd apps

# CMS 내부관리자용
npm create vite@latest cms -- --template react-ts

# client-CMS 고객용
npm create vite@latest client-cms -- --template react-ts

 

아래와 같이 두 프로젝트가 생성된다.

cms-monorepo/
  apps/
    cms/       # vite + react 프로젝트
    client-cms/   # vite + react 프로젝트
  packages/

 

3. 공통 패키지 생성

공유할 UI 컴포넌트나 config는 packages/에 넣어 관리한다.

cd ../packages
mkdir ui config
cd ui
npm init -y

 

예시(packages/ui/Button.tsx):

import React from "react";

export const Button = ({ children }: { children: React.ReactNode }) => {
  return (
    <button className="px-4 py-2 bg-blue-500 text-white rounded">
      {children}
    </button>
  );
};

 

package.json 이름을 정해주면 앱에서 불러올 수 있다.

{
  "name": "@acme/ui",
  "version": "0.0.1"
}

 

4. 라이브러리 설치 (루트에서)

cms와 client-cms 두 앱 모두 같은 라이브러리를 쓴다면,
항상 루트(cms-monorepo/)에서 설치

cd cms-monorepo

# 라우터
npm install @tanstack/react-router

# 스타일
npm install tailwindcss postcss autoprefixer

# UI 컴포넌트
npm install lucide-react

# 코드 스타일
npm install -D @biomejs/biome

-w 옵션은 뭘까?
루트에서 실행하면 기본적으로 루트에 설치되기 때문에 -w는 필수가 아니다ㅣ.
하지만, 앱 디렉토리(apps/cms) 안에서 설치하되 루트에 기록하고 싶다면 -w 옵션을 붙이면 된다.

 

5. TanStack Router 기본 세팅

apps/cms/src/main.tsx 예시

import ReactDOM from "react-dom/client";
import { RouterProvider, createRouter } from "@tanstack/react-router";
import { routeTree } from "./routeTree.gen";

const router = createRouter({ routeTree });

ReactDOM.createRoot(document.getElementById("root")!).render(
  <RouterProvider router={router} />
);

 

6. Turbo 설정 (turbo.json)

루트의 turbo.json은 빌드 파이프라인을 정의한다.
예시

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "outputs": []
    }
  }
}

 

7.  실행

개별 앱 실행:

npm run dev --workspace=apps/cms
npm run dev --workspace=apps/apt-cms

 

모든 앱 실행:

turbo run dev

 

---

정리

• apps/ → Vite + React 앱(cms, client-cms)
• packages/ → 공통 UI, config, utils
• 공통 라이브러리는 루트에서 설치 (npm install 라이브러리명)
• 특정 앱 전용 라이브러리라면 workspace 옵션 사용 (--workspace=apps/cms)

이렇게 하면 두 앱은 독립적으로 실행되면서도,
공통 UI와 라이브러리를 한 번만 관리할 수 있는 구조가 완성된다.