콘텐츠로 이동
@aws/nx-plugin
Blog

로컬 개발

연결된 프로젝트는 로컬 머신에서 실행하기 위한 두 가지 타겟을 제공합니다: serve와 serve-local. 차이점은 범위입니다 — 애플리케이션의 얼마나 많은 부분이 로컬에서 실행되는지, 배포된 AWS 인프라를 가리키는지의 차이입니다.

다음과 같은 연결을 가진 워크스페이스를 고려해보세요: tRPC api를 호출하는 웹사이트가 있고, 또한 mcp 서버를 호출하는 agent를 호출합니다.

serve

섹션 제목: “serve”

serve 타겟은 대상 프로젝트만 로컬에서 실행합니다. 연결된 다른 모든 프로젝트는 배포된 상태여야 하며, 실제 AWS URL에서 접근됩니다.

Terminal window
pnpm nx serve website

대상 프로젝트가 배포된 리소스와 통신하기 때문에, 해당 리소스의 위치를 알아야 합니다. 웹사이트의 경우 이는 runtime-config.json을 통해 제공되며(Local Runtime Config 참조), 배포된 애플리케이션에서 로드합니다. Runtime Configuration을 읽는 서버 측 프로젝트(API 및 에이전트)의 경우, RUNTIME_CONFIG_APP_ID 환경 변수를 설정하여 배포된 AppConfig 애플리케이션을 가리키도록 합니다.

Diagram

단일 프로젝트가 의존하는 모든 것의 “실제” 배포된 버전에 대해 반복 작업을 하고 싶을 때 serve를 사용하세요.

serve-local

섹션 제목: “serve-local”

serve-local 타겟은 대상 프로젝트와 이에 전이적으로 연결된 모든 프로젝트를 모두 로컬 머신에서 실행합니다. 연결 생성기가 이를 자동으로 연결합니다 — 웹사이트에서 serve-local을 실행하면 api, agent, 그리고 에이전트를 통해 도달하는 mcp 서버에 대한 로컬 서버도 시작됩니다.

Terminal window
pnpm nx serve-local website

이 방식으로 실행하면, 웹사이트의 runtime-config.json이 자동으로 재정의되어(Vite의 MODE를 통해 serve-local로 설정됨) 배포된 URL 대신 로컬에서 실행 중인 서버를 가리키게 됩니다.

Diagram

모든 프로젝트가 로컬에서 실행되므로 배포된 종속성이 없습니다.

여러 연결된 프로젝트를 동시에 작업하고 인프라를 배포하지 않고 빠르게 반복 작업을 하고 싶을 때 serve-local을 사용하세요.

dev

섹션 제목: “dev”

dev는 로컬 개발을 위한 표준 명령입니다. serve-local 타겟이 있는 모든 프로젝트는 이에 대한 별칭으로 dev 타겟을 제공하므로, 다음과 같이 프로젝트(및 연결된 모든 것)를 시작할 수 있습니다:

Terminal window
pnpm nx dev website

serve-local보다 dev를 선호하세요 — 더 짧고, 모든 프로젝트 유형에서 일관되며, 여러 컴포넌트가 있는 프로젝트의 경우 모두 시작합니다(아래 참조). 단일 컴포넌트를 대상으로 해야 하는 경우 serve-local을 계속 사용할 수 있습니다.

여러 컴포넌트가 있는 프로젝트

섹션 제목: “여러 컴포넌트가 있는 프로젝트”

일부 프로젝트 유형은 단일 프로젝트에 여러 컴포넌트를 포함할 수 있습니다(예: 여러 에이전트와 MCP 서버를 포함하는 TypeScript 또는 Python 프로젝트). 이러한 경우:

  • 각 컴포넌트는 <component-name>-serve-local 타겟에 대한 별칭으로 <component-name>-dev를 제공하므로, 단일 컴포넌트를 독립적으로 실행할 수 있습니다:
Terminal window
pnpm nx run my-project:my-component-dev
  • 프로젝트 수준의 dev 타겟은 프로젝트의 모든 컴포넌트를 함께 시작합니다. 각 컴포넌트는 생성될 때 dev에 추가됩니다:
Terminal window
pnpm nx dev my-project

Nx는 작업을 project:target으로 식별하기 때문에, 컴포넌트 간에 공유되는 serve-local 타겟(예: 두 에이전트에 연결된 공통 MCP 서버)은 dev를 시작할 때 정확히 한 번만 실행됩니다.

각 프로젝트 유형의 로컬 개발 서버에 대한 자세한 내용은 관련 가이드를 참조하세요 — 예를 들어 React Website 가이드를 참조하세요.