Module Federation을 활용한 마이크로 프론트엔드 구현

Module Federation

 

이번 글에서는 Webpack 5에서 추가된 Module Federation은 여러 독립적인 프론트엔드 애플리케이션이 런타임에 모듈을 동적으로 공유할 수 있게 하는 기술입니다.

이를 통해 최근, 아니 이제는 보편화된 마이크로 프론트엔드 아키텍처와 Module Federation을 함께 사용하고 설정하는 방법에 대해 알아보겠습니다.

1. Module Federation이란?

Module Federation은 서로 별도의 빌드 프로세스를 가진 애플리케이션 간에 코드(모듈)를 동적으로 공유할 수 있게 합니다. 

다시 말해, 여러 개의 별도 빌드된 자바스크립트 애플리케이션들이 런타임에 모듈을 공유하고 불러올 수 있도록 해주는 기술입니다.

기존 방식은 공통 라이브러리를 NPM 패키지로 배포하여 각 앱이 개별적으로 설치하는 것이었으나, 이는 복잡한 배포 프로세스와 버전 관리의 어려움이 있었습니다. 

Module Federation은 이러한 문제를 해결하고 런타임에 바로 모듈을 불러오는 방식으로 더욱 효율적인 코드를 공유해 중복을 최소화하고 번들 크기를 일 수 있습니다.

 

또한 Module Federation은 마이크로 프론트엔드(Micro-Frontend) 아키텍처를 지원하기 위해 등장하였습니다.

이는 백엔드의 마이크로서비스 개념을 프론트엔드에 적용한 것으로,  거대한 프론트엔드 모놀리스를 잘게 나눈 각각의 애플리케이션들이 자신만의 배포 파이프라인을 가지면서도, 최종 사용자에게는 하나의 통합된 앱처럼 보이도록 만드는 아키텍처입니다.

Module Federation은 이러한 마이크로 프론트엔드 간 모듈 공유와 통합을 손쉽게 해주는 핵심 도구입니다.

Webpack 5에서 처음 선보였지만, 현재는 Vite 등 다른 번들러 환경에서도 플러그인을 통해 유사한 모듈 공유 기능을 사용할 수 있을 만큼 범용적인 개념으로 발전했습니다.

마이크로 프론트엔드(Micro-Frontend) 아키텍처

2. Module Federation의 핵심 개념

Module Federation은 여러 웹 앱들을 하나의 거대한 앱처럼 유기적으로 결합시키면서도, 각각은 개별적으로 개발 및 배포될 수 있게 해주는 메커니즘입니다.

Webpack이 제공하는 Module Federation 플러그인 또는 Vite 등의 플러그인을 통해 설정을 관리하며, 런타임에는 Host-Remote 간의 모듈 요청/공급과 의존성 조율을 담당하는 추가 JS 코드가 삽입되어 동작합니다.

2.1 Host와 Remote

모듈을 가져오는 앱을 Host, 모듈을 제공하는 앱을 Remote라고 합니다.

예를 들어 A앱이 B앱의 일부 모듈을 사용한다면, A가 Host이고 B가 Remote의 역할을 합니다.

(한 애플리케이션이 동시에 Host이면서 다른 모듈을 Remote로 노출하는 양방향 호스트 시나리오도 가능합니다.)

Host는 Remote 애플리케이션이 제공하는 모듈을 런타임에 동적으로 로드하여 자신의 코드처럼 사용하게 됩니다.

2.2 Exposes와 Remotes

Remote 측에서는 ModuleFederationPlugin 설정을 통해 외부에 공개(expose)할 모듈을 지정합니다.

예를 들어 exposes: { "./Button": "./src/components/Button" }과 같이 설정하면 Remote 애플리케이션의 Button 컴포넌트를 다른 애플리케이션에서 remoteApp/Button과 같은 경로로 임포트 할 수 있게 됩니다.

 

Host 측에서는 대응되는 remotes 설정을 통해 어떤 Remote 애플리케이션의 어떤 URL을 참조할지 지정합니다.

예를 들어 remotes: { remoteApp: "remoteApp@http://localhost:3001/remoteEntry.js" }과 같이 설정하면, Host 애플리케이션은 remoteApp이라는 이름으로 Remote의 엔트리 파일(remoteEntry.js)에 연결되어 그 안의 모듈들을 가져올 수 있습니다.

2.3 Shared Dependencies

서로 다른 애플리케이션이 공유하는 의존성(예: React, lodash 같은 라이브러리)은 Module Federation 설정의 shared 필드를 통해 명시적으로 선언합니다.

이렇게 하면 Host와 Remote 모두 동일한 버전의 라이브러리를 가리키도록 조정되어, 번들에 해당 라이브러리가 중복 포함되지 않고 한 번만 로드됩니다. 

 

예컨대 Host와 Remote 모두 React 18을 공유하도록 shared: { react: { singleton: true, requiredVersion: '^18.2.0' } }로 지정하면, 두 앱은 런타임에 단일한 React 인스턴스를 사용하게 되어 버전 불일치로 인한 오류가 발생하지 않습니다.

singleton: true는 해당 모듈을 싱글턴으로 만들어 여러 버전이 생기지 않게 하며, requiredVersion를 사용하면 허용되는 버전 범위를 명시해 버전 충돌을 사전에 방지합니다.

2.4 Dynamic Runtime Loading

Module Federation의 가장 큰 특징은 모듈을 빌드 타임이 아닌 런타임에 동적으로 가져온다는 것입니다.

Remote 애플리케이션은 자체 번들을 생성할 때 remoteEntry.js라는 매니페스트 파일에 노출된 모듈 목록과 로딩 방법을 담아 배포합니다.

 

Host 애플리케이션은 이 파일을 가리키는 URL을 알고 있다가, 필요할 때 <script>로 불러들이거나 Webpack 런타임을 통해 해당 모듈을 가져옵니다.

이러한 동적 로딩 덕분에, 각 마이크로앱은 독립적으로 배포되면서도 Host에서 최신 모듈을 언제든 가져와 사용할 수 있습니다. 

예를 들어 쇼핑몰의 메인 앱이 “장바구니” 마이크로앱의 최신 장바구니 위젯을 실시간으로 가져와 보여주는 식으로 동작할 수 있습니다. 이 모든 과정은 Webpack 런타임이 처리해 주므로, 개발자는 마치 자신의 로컬 모듈을 import 하듯이 원격 모듈을 쉽게 불러올 수 있습니다.

3. Module Federation 설정하기

간단한 예제 애플리케이션을 만들어 Module Federation을 설정하는 방법을 알아보겠습니다.

 

시나리오는 다음과 같습니다:

• Home 애플리케이션(Host 역할): 메인 홈페이지를 제공하는 앱으로, 자체적으로 "Carousel (상품 캐러셀)" 컴포넌트를 가지고 있습니다. 이 컴포넌트를 외부에 공유하도록 설정합니다.
• Search 애플리케이션(Remote 역할): 상품 검색 페이지를 제공하는 별도의 앱으로, Home 앱의 Carousel 컴포넌트를 재사용하고 싶어 합니다 (자신이 Carousel을 따로 구현하지 않고 공유받아 사용).

// Home 애플리케이션의 webpack.config.js 일부
plugins: [
  new ModuleFederationPlugin({
    name: 'home', // 이 애플리케이션의 이름 (Host)
    filename: 'remoteEntry.js', // Remote에서 접근할 엔트리 파일 이름
    exposes: {
      './Carousel': './src/components/Carousel', // 외부에 공유할 모듈 경로
    },
    shared: ['react', 'react-dom'], // 공통 의존성 공유 설정 (버전 자동 조율)
  }),
],

// Search 애플리케이션의 webpack.config.js 일부
plugins: [
  new ModuleFederationPlugin({
    name: 'search', // 이 애플리케이션의 이름 (Remote 역할)
    remotes: {
      home: 'home@http://localhost:3000/remoteEntry.js', // Home 앱의 원격 모듈 위치
    },
    shared: ['react', 'react-dom'], // (필요에 따라 동일하게 공유 설정)
  }),
],

 

위 설정에서, Home 앱은 Carousel 컴포넌트를 exposes를 통해 공개하고, Search 앱은 remotes에서 Home 앱의 URL을 등록하여 그 컴포넌트를 가져올 준비를 합니다.

shared 배열에는 두 앱에서 공통으로 사용하는 라이브러리를 명시하여, 해당 라이브러리가 중복로드 되지 않도록 합니다 (위 예에서는 React와 ReactDOM을 공유).

이제 각 애플리케이션을 빌드하면 Home 쪽은 remoteEntry.js 파일을 출력하게 되며, Search 쪽 번들에는 원격 모듈을 가져오기 위한 메타정보가 포함됩니다.

 

Search 앱에서 이제 Home 앱의 Carousel을 자기 화면에서 사용해 보겠습니다.

Remote 모듈은 일반 import가 아니라 동적 import 형태로 불러와야 하므로, React의 lazy와 Suspense를 활용할 수 있습니다.

예를 들어 Search 앱의 어떤 컴포넌트에서 다음과 같이 원격 Carousel을 import 하여 사용할 수 있습니다

// Search 앱의 임의의 컴포넌트 파일
import React, { Suspense } from 'react';

// React.lazy를 이용하여 Remote 컴포넌트를 지연 로딩
const RemoteCarousel = React.lazy(() => import('home/Carousel'));

function SearchPage() {
  return (
    <div>
      {/* 필요한 위치에서 Remote 컴포넌트 사용 */}
      <Suspense fallback={<div>Loading...</div>}>
        <RemoteCarousel someProp={...} />
      </Suspense>
    </div>
  );
}

export default SearchPage;

위 코드에서 import('home/Carousel') 구문은 Webpack Module Federation이 인터셉트하여 Home 애플리케이션의 원격 엔트리로부터 Carousel 모듈을 가져오는 역할을 합니다.

React.lazy와 Suspense를 함께 사용하여 원격 모듈이 로드되는 동안 로딩 UI를 표시할 수 있습니다.

이렇게 함으로써, Search 앱은 마치 자신의 컴포넌트를 쓰듯이 Home 앱의 Carousel 컴포넌트를 렌더링 하게 됩니다.

(Next.js의 경우에도 비슷하게 next/dynamic으로 SSR을 끄고 remote 컴포넌트를 동적으로 불러오는 패턴을 사용할 수 있습니다.)

4. 마이크로 프론트엔드 아키텍처 설계 팁

Module Federation을 활용해 마이크로 프론트엔드 구조를 도입할 때는, 단순히 기술 설정뿐 아니라 애플리케이션 아키텍처 전반에 대한 전략이 필요합니다.

4.1 도메인 기반 분리 및 팀 자율성

애플리케이션을 분해할 때는 비즈니스 도메인 혹은 bounded context 단위로 나누는 것이 좋습니다.

각 마이크로 프론트엔드는 자신만의 독립된 UI, 상태, 데이터를 소유하며, 해당 도메인에 집중된 기능을 제공합니다.

이렇게 분리하면 각 팀이 자신이 맡은 마이크로앱을 독립적으로 개발 및 배포할 수 있어 개발 속도가 향상됩니다.

 

팀 간 의존성을 최소화하기 위해, 공통 계약(API)만 잘 정의하고 각자의 영역에서 자유롭게 기술 스택이나 릴리즈 주기를 운영하도록 할 수 있습니다.

4.2 Host/Shell 애플리케이션의 역할

여러 개의 마이크로앱으로 나누더라도, 보통은 공통으로 묶어주는 셸(shell) 또는 호스트 애플리케이션이 필요합니다.

이 Host 앱은 전체 애플리케이션의 글로벌한 책임(예: 라우팅, 사용자 인증, 공통 레이아웃 등)을 맡고, 개별 마이크로앱(Remote)을 적절한 위치에 로드하여 조립하는 역할을 합니다.

Host 앱은 가능한 가벼운 상태로 두고, 실제 기능은 Remote 마이크로 앱들이 채우는 구조가 이상적입니다.

4.3 공통 의존성과 라이브러리 전략

여러 마이크로앱이 존재하면 React, UI 라이브러리, 유틸리티 등 공통으로 사용하는 패키지들이 생깁니다.

Module Federation의 shared 설정으로 이러한 의존성을 싱글턴으로 공유하되, 모든 마이크로앱에서 해당 라이브러리의 버전이 호환되는지 신중히 관리해야 합니다.

모노레포(monorepo)를 사용한다면 루트에서 의존성 버전을 통일하거나 npm workspace 또는 resolutions를 사용해 버전을 강제로 일치시키는 방법도 있습니다.

 

또한 디자인 시스템이나 공용 컴포넌트 라이브러리는 별도의 npm 패키지로 관리하며, 각 마이크로앱이 이를 가져다 쓰도록 하는 경우도 있습니다.

핵심은 중복을 최소화하면서도 버전 충돌을 피하는 것이며, 공유 설정과 일관된 패키지 관리 전략을 활용해야 합니다.

4.4 마이크로앱 간 통신 및 상태 관리

마이크로 프론트엔드들은 기본적으로 분리된 리액트 트리이기 때문에, 서로 직접적인 상태 공유나 함수 호출을 하지 않는 것이 원칙입니다.

그러나 현실적으로 사용자 인증 정보 공유나 공통 이벤트 전파 등이 필요할 수 있습니다.

이를 해결하기 위해 명확한 인터페이스를 정의한 상호 작용 방법을 설계합니다. 

예를 들어, Host 애플리케이션이 글로벌 이벤트 버스를 제공하고 Remote들이 window.dispatchEvent와 addEventListener를 통해 이벤트로 통신하게 하거나, 공통으로 사용할 전역 상태 관리 도구(예: Redux)를 하나 두고 이를 각 앱에서 공유(access)하도록 할 수 있습니다.

 

다만, 전역 상태 공유는 앱 간 결합도를 높일 위험이 있으므로, 꼭 필요한 경우에 최소한으로 사용하고 가능하면 props 전달, URL 쿼리, 브라우저 이벤트 등의 느슨한 연결을 선호하는 것이 좋습니다.

4.5 스타일 충돌 방지와 디자인 일관성

서로 다른 마이크로앱이 한 화면에 공존할 경우 전역 CSS 충돌에 유의해야 합니다.

예를 들어 두 앱이 모두 .button 이라는 CSS 클래스를 정의했다면 예기치 않게 스타일이 섞여 UI가 깨질 수 있습니다.

이를 피하려면 각 팀이 CSS 격리 전략을 써야 합니다.

방법으로는 CSS Module이나 CSS-in-JS를 사용하여 클래스명이 충돌하지 않도록 하거나, Tailwind CSS 같은 유틸리티 프레임워크를 쓴다면 prefix 옵션으로 마이크로앱마다 고유한 prefix를 붙이는 방식이 있습니다.

 

예를 들어 Remote 앱의 Tailwind 설정에 prefix: 'remote-'를 주어 모든 클래스가 remote-btn, remote-text-lg처럼 출력되게 함으로써 Host의 클래스 (host-btn, host-text-lg)와 구분할 수 있습니다.

 

이렇게 하면 스타일 충돌을 방지하면서도 각 앱이 공통 디자인 시스템의 원칙 하에 UI를 일관성 있게 유지할 수 있습니다.

4.6 성능 최적화 고려사항

마이크로 프론트엔드로 앱을 분리하면 잘만 하면 각 부분만 필요할 때 로드하여 초기 번들 크기를 줄이는 이점이 있지만, 반대로 너무 쪼개면 여러 번 네트워크 요청과 추가 로딩이 발생해 성능이 나빠질 수 있습니다.

너무 세분화된 페더레이션(Over-Federation)은 피하고, 사용자에게 의미 있는 단위로 기능을 그룹화하여 로드하도록 설계합니다.

예를 들어 작은 버튼 컴포넌트 하나까지 전부 별도 마이크로앱으로 뽑기보다는, 관련된 UI와 기능을 가진 모듈들을 적절히 모아 한 개의 Remote로 제공하는 편이 효율적입니다.

 

또한 원격 모듈 로딩에 따른 지연을 줄이기 위해 Webpack의 프리페치/프리로드 설정이나 import(/* webpackPrefetch: true */ 'remote/Module') 등의 기법으로 미리 로드해 둘 수 있습니다.

Remote의 remoteEntry.js 파일 및 관련 자산들은 CDN에 호스팅 하여 전 세계 사용자가 빠르게 받을 수 있게 하고, 파일 이름에 해시를 붙여 배포 시 캐시 갱신이 원활히 이루어지도록 할 수 있습니다.

 

실제 운영 환경에서는 각 마이크로앱별로 독립적인 CI/CD 파이프라인을 구축하여 자주 배포하되, 배포 직후에 Host앱이 최신 원격을 불러올 수 있게 캐시 무효화 전략(예: [hash] 사용)을 잘 설계해야 합니다.

4.7 장애 격리와 안정성

Micro Frontend 환경에서는 한 Remote에서 오류가 발생해도 전체 애플리케이션이 죽지 않도록 하는 게 중요합니다.

React의 Error Boundary를 Remote 컴포넌트 주위에 배치하여, 원격 모듈 로딩 실패나 런타임 오류 시 대체 UI를 보여주도록 합니다.

예를 들어 React.lazy로 로드한 Remote 컴포넌트를 Error Boundary로 감싸 두면, 해당 Remote가 일시적으로 내려갔거나 오류가 있어도 Host 애플리케이션은 자체 에러 UI를 표시하고 나머지 기능은 계속 동작하게 할 수 있습니다.

 

이처럼 페일-세이프 전략을 도입하면 각 마이크로앱의 문제가 전체로 전이되는 것을 막아줄 수 있습니다.

5. 자주 발생하는 문제와 해결 방법

마이크로 프론트엔드를 도입하면 생각보다 많은 문제를 마주치게 됩니다.

그때를 대비해 문제 상황과 해결책을 정리해 보겠습니다.

5.1 라이브러리 버전 충돌

Host와 Remote 애플리케이션이 사용하는 React 등의 라이브러리 버전이 일치하지 않으면, 번들에 중복된 라이브러리 인스턴스가 실려 예기치 않은 문제가 발생합니다.

예를 들어 Host는 React 18, Remote는 React 17을 사용한다면 둘 다 로드되어 훅(hook)이 동작하지 않거나 컨텍스트 공유가 깨질 수 있습니다.

 

해결

Module Federation 설정에서 shared 항목에 해당 라이브러리를 singleton으로 지정하고 requiredVersion을 명시하여 단일 버전만 로드되도록 강제합니다.

그리고 가급적이면 모든 마이크로앱에서 라이브러리 버전을 동일하게 유지하는 게 좋습니다.

모노레포일 경우 루트 package.json에 resolutions를 사용해 React 버전을 통일할 수도 있습니다.

이렇게 하면 런타임에 딱 한 개의 React가 로드되어 훅 등이 정상 작동합니다.

5.2 전역 스타일 충돌

여러 앱이 한 페이지에 렌더링 될 때, CSS 전역 클래스 이름이 겹치면 스타일이 꼬이는 문제가 생길 수 있습니다.

예를 들어 Remote 앱에서 .button { color: red }로 정의하고 Host 앱에서도 .button { color: blue }를 정의하면 한쪽 스타일이 다른 쪽을 덮어써서 의도치 않은 색으로 표시될 수 있습니다.

 

해결

각 애플리케이션의 스타일을 격리 및 네임스페이스하세요.

앞서 언급했듯이 CSS Module이나 CSS-in-JS를 도입하거나, 전역 클래스 작명을 서로 충돌 없도록 약속해야 합니다.

특히 Tailwind CSS를 함께 쓴다면 tailwind.config.js에 각 프로젝트별 prefix를 설정해 클래스 이름에 접두사를 붙입니다

(예: prefix: 'app1-').

그 결과 Remote의 .button이 .app1-button으로 출력되어 Host의 .button과 충돌하지 않게 됩니다.

5.3 라우팅 경로 충돌

서로 다른 마이크로앱이 중복된 URL 경로를 정의하면 사용자 내비게이션에 혼란이 생깁니다.

예를 들어 Host와 Remote 모두 /settings 경로를 갖고 있으면, 어느 쪽 페이지가 보일지 예측하기 어렵고 잘못된 화면이 나올 수 있습니다.

 

해결

라우팅은 Host에서 중앙 관리하거나, 각 애플리케이션에 고유한 경로 프리픽스를 부여하는 것이 안전합니다.

Host 앱의 설정 페이지는 /app1/settings, Remote 앱의 설정 페이지는 /app2/settings처럼 네임스페이스를 달리하면 충돌을 완전히 피할 수 있습니다. 

 

또는 Module Federation을 활용해 Lazy Routing을 구현할 수도 있습니다.

Host에서는 자기 라우터에 Remote의 라우트들을 lazy load 하도록 설정하고, Remote는 자신의 Routes 모듈을 노출하여 Host가 특정 경로 접근 시에만 해당 Remote의 라우트를 로드하게 할 수 있습니다.

이렇게 하면 각 마이크로앱의 라우팅이 철저히 독립되어 경로 충돌이 제거됩니다.

5.4 원격 모듈 로딩 오류

Host에서 Remote 모듈을 가져올 때 경로나 호스트 설정이 잘못되면 404 오류 등으로 모듈을 불러오지 못하는 상황이 발생합니다.

예를 들어 remotes에 설정한 URL이 틀렸거나, Webpack publicPath 설정이 맞지 않으면 Remote의 번들을 찾지 못해 앱이 죽을 수 있습니다. 

 

해결

우선 Webpack 출력 설정에서 output.publicPath를 'auto'로 지정하여 동적 import 경로를 자동 인식하도록 합니다.

이렇게 하면 Host 번들이 자신의 정적 리소스 경로를 기준으로 remoteEntry 등을 알아서 가져오려고 시도합니다.

또한 Remote의 remoteEntry.js 경로를 정확히 가리키도록 remotes 설정을 꼼꼼히 확인해야 합니다.

(개발 중 브라우저 네트워크 탭에서 remoteEntry 요청이 성공하는지, 또 remoteEntry 안에 노출된 모듈명이 맞는지 확인하면 도움이 됩니다.)

 

그리고 React에서는 Remote 컴포넌트를 불러올 때 반드시 Suspense fallback을 사용하여 로딩 중 UI를 표시하고, 로딩 실패 시 에러를 boundary로 처리하는 등의 대비를 하여 UX 저해를 막습니다.

5.5 중복된 리소스 로드

각 마이크로앱이 자기 번들에 공통 자산(예: 폰트, 아이콘, 유틸 함수)을 포함하고 있다면, 최종 사용자 입장에서는 동일한 리소스를 여러 번 내려받게 되어 불필요한 대역폭 사용과 성능 저하가 발생합니다.

 

해결

공용으로 쓰는 정적 자산은 중앙 CDN이나 공유 경로에서 제공하도록 구조를 잡습니다.

예를 들어 모든 마이크로앱에서 필요한 회사 로고 이미지나 공통 폰트 파일이 있다면 이를 한 곳(예: S3/CloudFront 같은 CDN)에 호스팅 하고 <img src>나 @font-face로 참조하게 합니다.

이렇게 하면 브라우저 캐시도 공유되어 한 번 받은 리소스를 재사용할 수 있습니다.

 

그리고 중복 코드 문제를 줄이기 위해 유틸리티 함수 등은 아예 별도 공유 라이브러리로 분리하여 패키지로 관리하는 것도 방법입니다.

예를 들어 날짜 포맷터 함수 formatDate를 여러 앱에서 쓴다면, 이를 @my-org/utils 같은 패키지로 만들어 모든 앱이 해당 패키지를 참조하게 하면 코드 일관성과 재사용성이 높아집니다.

Module Federation 자체도 이러한 코드 공유를 지원하지만, 경우에 따라 아예 빌드 타임에 공통 패키지를 묶어 쓰는 편이 나을 때도 있으므로 상황에 맞게 결합도를 조절해야 합니다.

6. 결론

Module Federation은 프론트엔드 모듈 공유와 팀 단위 개발에 새로운 가능성을 열어준 강력한 기능입니다.

이를 통해 대규모 애플리케이션에서도 부분적인 독립 배포가 가능해지고, 중복 코드를 줄여 효율적이고 유연한 프론트엔드 아키텍처를 구축할 수 있습니다.

하지만, Module Federation이 만병통치약은 아니므로 도입에 앞서 신중한 판단이 필요합니다.

애플리케이션이 충분히 커서 부분 분리가 필요하고, 팀별 병렬 개발이 이루어지는 상황에 어울리는 기술입니다.

 

상황에 따라서는 Yarn Workspace나 Turborepo와 같은 툴을 이용해 Monorepo를 구성하는 게 더 효율적일 수 있습니다.

Webpack, 환경설정, CDN 등 도입 복잡도도 높은 편이기 때문에 서비스의 규모가 너무 크거나 독립 배포가 꼭 필요한 경우와 같이 꼭 필요한 상황에 맞춰 잘 활용하시길 바라겠습니다.