React Module Federation 기반 마이크로프론트엔드

개요

마이크로프론트엔드란 대형 프론트엔드 애플리케이션을 독립적인 작은 단위로 나누어 개발·배포하는 아키텍처다. Module Federation은 Webpack이 제공하는 기능으로 런타임에 다른 빌드의 모듈을 불러온다. React와 결합하면 서로 다른 팀이 독립적으로 UI를 배포하면서도 런타임에 통합된 사용자 경험을 제공할 수 있다.

왜 Module Federation을 선택해야 하는가

모노리식 SPA의 빌드 시간과 배포 부담을 줄인다. 팀 간 코드 충돌을 낮춘다. 필요한 모듈만 런타임에 가져오므로 초기 로드 최적화에 도움이 된다. 또한 서로 다른 프레임워크로 작성된 부분을 점진적으로 통합하는 데 유리하다.

기본 개념

Host와 Remote

Host는 다른 번들에서 모듈을 소비하는 애플리케이션이다. Remote는 노출(expose)된 모듈을 제공하는 애플리케이션이다. 두 역할을 명확히 나누면 배포와 권한 관리가 쉬워진다.

공유(Shared)와 노출(Expose)

공유는 여러 앱이 같은 라이브러리를 하나의 인스턴스로 사용하게 한다. React, React DOM 같은 핵심 라이브러리는 반드시 공유하는 것이 안정적이다. 노출은 Remote가 제공할 컴포넌트나 유틸을 지정한다.

webpack Module Federation 설정 예시

아래 예시는 간단한 Remote와 Host의 webpack 설정이다. 실제 프로젝트에서는 빌드 도구와 환경에 따라 추가 설정이 필요하다.

Remote webpack.config.js

const { ModuleFederationPlugin } = require('webpack').container;
module.exports = {
  mode: 'production',
  entry: './src/index',
  output: { publicPath: 'https://remote.example.com/' },
  plugins: [
    new ModuleFederationPlugin({
      name: 'remoteApp',
      filename: 'remoteEntry.js',
      exposes: {
        './Button': './src/components/Button'
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' }
      }
    })
  ]
};

Host webpack.config.js

const { ModuleFederationPlugin } = require('webpack').container;
module.exports = {
  mode: 'production',
  entry: './src/index',
  output: { publicPath: 'https://host.example.com/' },
  plugins: [
    new ModuleFederationPlugin({
      name: 'hostApp',
      remotes: {
        remoteApp: 'remoteApp@https://remote.example.com/remoteEntry.js'
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' }
      }
    })
  ]
};

호스트에서 원격 컴포넌트 사용하기

런타임에 원격 모듈을 가져오는 방법은 동적 import와 호스트의 설정에 따라 달라진다. 아래는 간단한 사용 예시다.

// src/App.jsx
import React, { Suspense } from 'react';
const RemoteButton = React.lazy(() => import('remoteApp/Button'));

export default function App() {
  return (
    <div>
      <h1>Host Application</h1>
      <Suspense fallback={<div>로딩 중...</div>}>
        <RemoteButton />
      </Suspense>
    </div>
  );
}

공유 라이브러리 관리 전략

• 핵심 라이브러리(React, React DOM)는 singleton으로 설정해 중복 로드를 방지한다.
• 서로 다른 버전 충돌이 우려되는 라이브러리는 범위를 좁혀서 공유하거나 각 앱에 번들링한다.
• 버전 호환성을 유지하기 위해 package.json에 버전 정책을 문서화한다.

라우팅과 상태 관리

마이크로프론트엔드에서는 각 앱이 자체 라우팅을 가질 수 있다. 전역 라우터를 두고 서브앱을 포인트로 마운트하는 방식이 안전하다. 상태 관리는 중앙 저장소를 공유하거나 각 앱의 경계 내에서 로컬 상태를 유지하는 방법을 혼합해서 쓴다.

배포와 캐싱

Remote의 remoteEntry.js는 캐시 정책을 신중히 다뤄야 한다. 파일 이름에 해시를 붙이거나 버전 경로를 사용하면 롤링 업데이트 중에도 안정적인 로딩이 가능하다. CDN에 배포하면 전역 가용성이 좋아진다.

디버깅과 문제 해결

• console에서 remoteEntry 로딩 실패를 먼저 확인한다.
• 공유 라이브러리의 멀티 인스턴스 생성 여부를 검사한다.
• 브라우저 네트워크 탭으로 파일 경로와 CORS 오류를 점검한다.

주의할 점

런타임 통합은 런타임 의존성 문제를 야기할 수 있다. 동일한 라이브러리의 다른 버전이 섞이면 예기치 않은 동작이 발생한다. 따라서 공유 설정과 의존성 정책을 팀 차원에서 합의한다. 또한 초기 설계 단계에서 라우팅, 스타일 충돌, 폴리필 요구사항을 검토한다.

결론

module federation react 기반의 마이크로프론트엔드는 대규모 팀과 복잡한 배포 환경에서 효과적이다. webpack module federation 설정을 통해 각 애플리케이션은 독립적으로 개발되면서도 런타임에 통합될 수 있다. 초기 설정과 공유 전략에 시간을 투자하면 유지보수성과 배포 속도 모두 개선된다.