본문으로 건너뛰기

Cursor에서 모노레포 관리: Turborepo, Nx 및 pnpm 워크스페이스

Cursor에서 모노레포 관리

모노레포를 사용하면 여러 패키지나 애플리케이션을 단일 저장소에서 관리하며 코드, 구성 및 툴링을 공유할 수 있습니다. AI 기반 IDE 에디터인 Cursor는 패키지 간 관계를 이해하고, 파이프라인 구성을 생성하며, 공유 API를 안전하게 리팩토링하여 모노레포 관리를 획기적으로 간소화합니다. 이 가이드는 AI 지원 종속성 관리와 패키지 간 리팩토링을 위한 실용적인 기법과 함께 Turborepo, Nx 및 pnpm 워크스페이스를 다룹니다.

사전 요구 사항​

시작하기 전에 다음이 있는지 확인하세요:

  • Cursor(최신 버전 권장)를 IDE 에디터로 사용
  • Node.js 18 이상
  • pnpm 전역 설치(npm install -g pnpm)
  • 패키지 관리자 및 워크스페이스에 대한 기본 지식
팁

Cursor의 내장 터미널과 멀티루트 워크스페이스 지원은 모노레포에 이상적입니다. Cursor에서 저장소 루트를 열면 AI가 모든 패키지를 한 번에 볼 수 있습니다. 이는 패키지 간 리팩토링 및 종속성 분석을 위한 전체 컨텍스트를 에디터에 제공합니다.

모노레포 도구 선택​

세 가지 도구가 JavaScript 및 TypeScript 모노레포 환경을 지배합니다. 각각 다른 강점이 있습니다:

도구가장 적합한 경우핵심 강점
pnpm 워크스페이스소규모~중규모 모노레포빠르고 디스크 효율적인 설치
Turborepo앱 중심 모노레포간단한 작업 캐싱 및 병렬 실행
Nx대규모, 플러그인 중심 모노레포강력한 코드 생성 및 종속성 그래프

Cursor의 AI에게 상황에 맞는 도구를 추천해 달라고 요청하세요:

2개의 Next.js 앱, 공유 React 컴포넌트 라이브러리 및 3개의
유틸리티 패키지가 있는 모노레포가 있습니다. Turborepo 또는
Nx를 사용해야 하나요? 비교해주세요.

Cursor는 트레이드오프를 설명하고 선택한 도구에 대한 스타터 구성을 생성합니다.

Cursor에서 pnpm 워크스페이스 설정​

pnpm 워크스페이스는 속도와 하드 링크 디스크 효율성으로 인해 대부분의 현대 모노레포의 기반입니다. Cursor는 워크스페이스를 정의하고 첫 번째 패키지를 부트스트랩하는 데 도움을 줍니다.

워크스페이스 루트 생성​

Cursor에서 새 폴더를 열고 AI에게 pnpm 워크스페이스를 스캐폴드해 달라고 요청하세요:

다음과 같은 pnpm 워크스페이스 모노레포를 만들어주세요:
- pnpm 워크스페이스 구성이 있는 루트 package.json
- apps/* 및 packages/*를 나열하는 pnpm-workspace.yaml
- 공유 TypeScript 구성 패키지
- 공유 캐시 설정이 있는 .npmrc

Cursor가 루트 파일을 생성합니다:

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
// package.json
{
  "name": "cursor-monorepo",
  "private": true,
  "scripts": {
    "dev": "pnpm -r --parallel run dev",
    "build": "pnpm -r run build",
    "lint": "pnpm -r run lint",
    "test": "pnpm -r run test"
  },
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}
# .npmrc
shared-cache-max-age=86400
auto-install-peers=true
strict-peer-dependencies=false

첫 번째 패키지 생성​

Cursor에게 공유 UI 패키지와 이를 사용하는 웹 앱을 생성해 달라고 요청하세요:

packages/ui React 컴포넌트 라이브러리와 apps/web Next.js 앱을
만들어주세요. 웹 앱은 workspace:* 프로토콜을 사용하여 ui 패키지에
종속되어야 합니다.

Cursor가 패키지 구조를 생성합니다:

monorepo/
  apps/
    web/
      package.json
      src/
        app/page.tsx
  packages/
    ui/
      package.json
      src/
        index.ts
        Button.tsx
  pnpm-workspace.yaml
  package.json

packages/ui/package.json:

{
  "name": "@cursor-monorepo/ui",
  "version": "0.1.0",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "scripts": {
    "lint": "eslint .",
    "build": "tsc"
  },
  "peerDependencies": {
    "react": "^18.0.0"
  }
}

apps/web/package.json은 워크스페이스 프로토콜을 사용하여 공유 패키지를 참조합니다:

{
  "name": "@cursor-monorepo/web",
  "version": "0.1.0",
  "dependencies": {
    "@cursor-monorepo/ui": "workspace:*",
    "next": "^14.0.0",
    "react": "^18.0.0"
  }
}

Cursor의 터미널에서 루트에서 모든 것을 설치하세요:

pnpm install

pnpm은 종속성을 하드 링크하므로 설치가 빠르고 디스크 효율적입니다.

경고

내부 패키지를 참조할 때 항상 workspace:* 프로토콜(또는 workspace:^)을 사용하세요. 1.0.0과 같은 버전 번호를 고정하면 pnpm이 로컬 패키지를 해결하는 대신 레지스트리에서 패키지를 가져오려고 하여 설치 중 혼란스러운 "package not found" 오류가 발생합니다.

Cursor에서 Turborepo 통합​

Turborepo는 pnpm 워크스페이스 위에 캐싱과 병렬 작업 실행을 추가합니다. Cursor는 파이프라인 구성을 생성하고 튜닝을 도와줍니다.

기존 워크스페이스에 Turborepo 추가​

Cursor에게 모노레포에 Turborepo를 추가해 달라고 요청하세요:

내 pnpm 워크스페이스에 Turborepo를 추가해주세요. build, dev, lint
및 test 파이프라인이 있는 turbo.json을 만들어주세요. 빌드 종속성과
캐싱을 구성해주세요.

Cursor가 종속성을 설치하고 turbo.json을 생성합니다:

pnpm add -Dw turbo
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "inputs": [
        "src/**",
        "package.json",
        "tsconfig.json"
      ]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": ["src/**", "test/**", "package.json"]
    }
  }
}

dependsOn: ["^build"] 지시문은 패키지 자체를 빌드하기 전에 패키지의 종속성을 먼저 빌드하도록 Turborepo에 지시하며, 이는 앱이 공유 라이브러리에 종속되는 모노레포에 중요합니다.

Turbo로 작업 실행​

Cursor의 터미널에서 전체 모노레포에 걸쳐 작업을 실행하세요:

# 위상 정렬 순서로 모든 패키지 빌드
pnpm turbo run build

# 개발 서버 병렬 실행
pnpm turbo run dev --parallel

# 단일 패키지와 그 종속 항목으로 필터링
pnpm turbo run build --filter=@cursor-monorepo/web...

... 접미사는 "이 패키지와 이에 종속된 모든 것"을 의미하며, 공유 라이브러리를 변경할 때 영향 분석에 유용합니다.

팁

^ 접두사와 함께 --filter 플래그를 사용하여 패키지와 그 종속성에 대해서만 작업을 실행하세요. 예를 들어 pnpm turbo run build --filter=^@cursor-monorepo/web은 웹 앱에 필요한 패키지만 빌드하고 관련 없는 작업을 건너뜁니다. 이는 빠른 로컬 피드백 루프에 매우 유용합니다.

원격 캐싱 구성​

원격 캐싱을 사용하면 팀이 빌드 결과를 공유할 수 있습니다. Cursor에게 Vercel 원격 캐시를 설정해 달라고 요청하세요:

내 모노레포에 Turborepo 원격 캐싱을 구성해주세요. .nenv 예제를
생성하고 캐시를 연결하는 방법을 설명해주세요.

Cursor가 단계를 설명합니다:

npx turbo login
npx turbo link

캐시 키에 올바른 변수가 포함되도록 turbo.json 환경 힌트를 추가하세요:

{
  "globalEnv": ["NODE_ENV", "CI"]
}

Cursor에서 Nx 통합​

Nx는 코드 생성기, 종속성 그래프 및 많은 프레임워크에 대한 플러그인 지원을 갖춘 더 강력한 모노레포 도구입니다. Cursor는 Nx 프로젝트를 부트스트랩하고 확장하는 데 도움을 줍니다.

Nx 워크스페이스 생성​

Cursor에게 Nx 워크스페이스를 생성해 달라고 요청하세요:

다음과 같은 Nx 통합 모노레포를 만들어주세요:
- storefront라는 React 앱
- api라는 Node API 앱
- 공유 타입 라이브러리
- pnpm을 패키지 관리자로 사용

Cursor가 스캐폴드를 실행하고 결과를 설명합니다:

npx create-nx-workspace@latest cursor-nx --preset=apps --packageManager=pnpm

결과 구조:

cursor-nx/
  apps/
    storefront/
    api/
  libs/
    types/
  nx.json
  project.json

Nx 플러그인으로 코드 생성​

Nx 플러그인은 일관된 스캐폴딩을 위한 생성기를 제공합니다. Cursor에게 React 컴포넌트 라이브러리를 생성해 달라고 요청하세요:

@nx/react 플러그인을 사용하여 buildable true 및 Storybook 구성으로
ui라는 React 라이브러리를 생성해주세요.
npx nx g @nx/react:library ui --buildable --storybook --directory=libs/ui

종속성 그래프 시각화​

Nx는 그래프 시각화 도구를 제공합니다. Cursor의 터미널에서 실행하세요:

npx nx graph

이는 브라우저에서 패키지가 서로 어떻게 종속되는지 보여주는 대화형 그래프를 엽니다. Cursor의 AI는 요청하면 그래프를 텍스트로 설명할 수도 있습니다:

libs/types에 종속된 모든 패키지를 나열하고 기본 내보내기의
이름을 바꾸면 깨질 패키지를 표시해주세요.

Cursor는 워크스페이스 구성을 읽고 영향 분석을 반환하며, 이는 공유 코드를 리팩토링하기 전에 필수적입니다.

경고

Nx 통합 워크스페이스는 가져오기를 위해 tsconfig.base.json에서 경로 매핑을 사용합니다. 새 라이브러리를 추가하면 paths 매핑을 업데이트해야 하며, 그렇지 않으면 TypeScript가 가져오기를 해결할 수 없습니다. "Cannot find module" 오류가 보이면 Cursor의 AI가 누락된 경로 매핑을 감지하고 수정을 제안할 수 있습니다.

AI 지원 종속성 관리​

모노레포 전체에서 종속성을 일관되게 유지하는 것은 가장 어려운 유지 관리 작업 중 하나입니다. Cursor의 AI는 이 작업에 탁월합니다.

버전 불일치 감사​

Cursor에게 종속성 불일치를 찾아달라고 요청하세요:

내 모노레포의 모든 package.json 파일을 스캔하고 패키지 간에
버전이 일관되지 않은 종속성을 보고해주세요. 각각에 대해 단일
고정 버전을 제안해주세요.

Cursor는 모든 package.json을 읽고 불일치를 나열하며, 이를 정렬하는 스크립트를 생성할 수 있습니다:

# react를 모든 곳에서 18.2.0으로 정렬
pnpm -r exec pnpm add [email protected] [email protected]

미사용 종속성 감지​

Cursor는 package.json에 선언되었지만 가져오지 않은 패키지를 감지할 수 있습니다. 요청하세요:

모든 소스 파일의 가져오기를 확인하여 apps/web 패키지에서 사용하지
않는 종속성을 찾아주세요.

Cursor가 미사용 항목을 보고하고 제거 명령을 제안합니다:

pnpm --filter @cursor-monorepo/web remove unused-package-name

공유 개발 종속성 관리​

버전 드리프트를 방지하기 위해 공유 개발 도구(ESLint, Prettier, TypeScript)를 워크스페이스 루트로 올리세요. Cursor가 공유 구성 패키지를 생성합니다:

다른 패키지가 확장할 수 있도록 공유 ESLint, TypeScript 및
Prettier 구성을 내보내는 packages/config 패키지를 만들어주세요.
// packages/config/package.json
{
  "name": "@cursor-monorepo/config",
  "version": "0.1.0",
  "files": ["eslint", "tsconfig", "prettier"],
  "devDependencies": {
    "eslint": "^8.57.0",
    "prettier": "^3.2.0"
  }
}
// packages/config/eslint/base.js
module.exports = {
  extends: ['next', 'prettier'],
  rules: {
    'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
    'no-console': ['warn', { allow: ['warn', 'error'] }],
  },
};

다른 패키지는 공유 구성을 확장합니다:

{
  "eslintConfig": { "extends": "@cursor-monorepo/config/eslint" }
}
팁

pnpm의 catalog 기능(또는 Renovate)을 사용하여 버전 번호를 한 곳에 중앙화하세요. Cursor에게 "모든 공유 종속성 버전에 대한 pnpm 카탈로그를 설정해 달라"고 요청하면 pnpm-workspace.yaml 카탈로그 블록을 생성하여 단일 버전 업데이트가 모든 곳에 자동으로 전파됩니다.

Cursor로 패키지 간 리팩토링​

공유 API를 리팩토링하면 모든 소비자에게 영향을 미칩니다. Cursor의 코드베이스 인덱싱을 통해 AI는 전체 모노레포에서 사용을 추적할 수 있어 대규모 리팩토링을 안전하게 만듭니다.

공유 내보내기 이름 변경​

packages/ui에서 Button 컴포넌트의 이름을 ActionButton으로 바꾸려 한다고 가정해 보겠습니다. Cursor의 Agent에게 요청하세요:

전체 모노레포에서 Button 컴포넌트의 이름을 ActionButton으로
변경해주세요. 내보내기, 타입, 모든 가져오기 및 Storybook
스토리를 업데이트해주세요. 빌드를 실행하여 아무것도 깨지지
않았는지 확인해주세요.

Cursor가 다중 파일 편집을 한 번에 수행합니다:

// packages/ui/src/ActionButton.tsx
import React from 'react';

export interface ActionButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

export const ActionButton = ({ label, onClick, variant = 'primary' }: ActionButtonProps) => (
  <button className={`btn btn-${variant}`} onClick={onClick}>
    {label}
  </button>
);
// packages/ui/src/index.ts
export { ActionButton } from './ActionButton';
export type { ActionButtonProps } from './ActionButton';
// apps/web/src/app/page.tsx
import { ActionButton } from '@cursor-monorepo/ui';

export default function Home() {
  return <ActionButton label="Get Started" onClick={() => alert('hi')} />;
}

공유 유틸리티 추출​

패키지 간에 중복된 로직을 발견하면 Cursor에게 추출을 요청하세요:

apps/web과 apps/api에 중복된 날짜 형식 지정 로직을 @cursor-monorepo/format이라는
새 공유 패키지로 추출해주세요. 모든 호출 사이트를 새 패키지에서
가져오도록 업데이트해주세요.

Cursor가 패키지를 만들고, 코드를 이동하고, 가져오기를 업데이트하고, 영향을 받는 빌드를 실행하여 성공을 확인합니다.

경고

패키지 간 리팩토링 후에는 항상 전체 테스트 스위트와 전체 워크스페이스에 대한 타입 검사를 실행하세요. 누락된 단일 가져오기는 개별적으로는 컴파일되지만 패키지가 조합될 때 실패할 수 있습니다. 루트에서 pnpm -r run build && pnpm -r run test를 실행하여 이러한 문제를 조기에 발견하세요.

워크스페이스 구성 및 툴링​

패키지 간의 일관된 툴링은 모노레포를 건강하게 유지합니다. Cursor는 TypeScript, ESLint 및 CI에 대한 공유 구성을 생성할 수 있습니다.

공유 TypeScript 구성​

packages/config/tsconfig/base.json에 엄격 모드, 경로 별칭 및
최신 lib 설정이 있는 공유 tsconfig 기반을 만들어주세요.
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "moduleResolution": "bundler",
    "module": "ESNext",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  }
}

각 패키지는 이를 확장합니다:

{
  "extends": "@cursor-monorepo/config/tsconfig/base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

GitHub Actions로 CI 파이프라인​

Cursor에게 Turborepo 캐싱을 활용하는 CI 파이프라인을 생성해 달라고 요청하세요:

다음과 같은 GitHub Actions 워크플로를 만들어주세요:
- pnpm 및 Node 설치
- pnpm 스토어 캐시 복원
- 캐싱으로 turbo run lint build test 실행
- Pull Request에서 영향을 받는 작업만 실행
# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v3
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - uses: actions/cache@v4
        with:
          path: .turbo
          key: turbo-${{ runner.os }}-${{ github.sha }}
          restore-keys: turbo-${{ runner.os }}-
      - run: pnpm turbo run lint build test

모범 사례 요약​

Cursor에서 모노레포를 관리할 때 다음 원칙을 명심하세요:

  • 워크스페이스 루트를 열어 패키지 간 컨텍스트를 위해 Cursor가 모든 패키지를 볼 수 있게 하세요.
  • 워크스페이스 프로토콜(workspace:*)을 내부 패키지 참조에 사용하세요.
  • 공유 개발 도구를 구성 패키지로 올려 버전 드리프트를 방지하세요.
  • 작업 캐싱을 활용하여 Turborepo 또는 Nx로 CI를 빠르게 유지하세요.
  • 공유 API를 리팩토링하기 전에 영향 분석을 실행하세요.
  • 버전을 중앙화하세요. pnpm 카탈로그 또는 Renovate를 사용하여.

견고한 모노레포 도구와 Cursor의 AI 기반 코드베이스 이해를 결합하면 공유 코드를 자신 있게 리팩토링하고, 종속성을 정렬하며, 많은 패키지에 걸쳐 일관된 툴링를 배포할 수 있습니다. 의도를 명확히 설명하고, Cursor가 보일러플레이트와 패키지 간 편집을 처리하게 한 다음, 커밋하기 전에 생성된 diff를 검토하세요.