CAPTCHA 기능을 구현하기 위해 react-simple-captcha를 설치했는데, 페이지를 새로고침할 때 다음과 같은 오류가 발생했습니다

digest: undefined
}
error - C:\Users\Desktop\파일명\node_modules\react-simple-captcha\react-simple-captcha.js:1
import { Component } from 'react';
^^^^^^
SyntaxError: Cannot use import statement outside a module

조사해본 결과, 이 오류는 CommonJS 환경에서 ES 모듈을 사용하려고 할 때 발생하는 문제라는 것을 알게 되었습니다.
react-simple-captcha는 CommonJS 모듈로 작성되어 있으며, ES 모듈을 사용하는 환경에서는 CommonJS가 제대로 동작하지 않기 때문입니다.

🔗 참고 : [https://ellajang.github.io/frontendCoreTech/captcha/]

1. ES 모듈과 CommonJS란?

 문제를 해결하기 앞서 CommonJS와 ES모듈이 어떤 것이길래 에러가 발생한건지 알아보겠습니다.

ES 모듈

: ES 모듈(ECMAScript Modules)은 최신 JavaScript 표준에서 모듈화를 지원하는 방식입니다.
ES6(ES2015)에서 도입된 이 모듈 시스템은 import와 export 키워드를 사용하여 다른 파일에서 모듈을 가져오거나 내보낼 수 있습니다. 이 모듈 시스템은 브라우저에서도 기본적으로 지원되며, 자바스크립트의 모듈화와 코드 분할을 더욱 깔끔하게 관리할 수 있게 합니다.

예시

export const myFunction = () => {
  console.log('ES Modules!')
}

import { myFunction } from './myModule.js'

CommonJS

: CommonJS는 ES 모듈이 등장하기 이전부터 Node.js에서 사용하던 모듈 시스템입니다.
module.exports와 require 키워드를 사용하여 모듈을 내보내고 가져올 수 있습니다. 주로 서버 사이드에서 많이 사용되며, 브라우저 환경에서는 ES 모듈이 기본적으로 지원되기 때문에 일부 호환성 문제가 발생할 수 있습니다.

예시

const myFunction = () => {
  console.log('CommonJS!')
}

module.exports = myFunction

const myFunction = require('./myModule')

2. 에러 해결 방법

 이 문제를 해결하기 위해, 특정 노드 모듈을 Transpiling할 수 있는 패키지인 next-transpile-modules을 설치 후 next.comfig.js에 아래 코드를 추가했습니다.

npm install --save next-transpile-modules

또는

yarn add next-transpile-modules

다음으로, next.config.js 파일에 react-simple-captcha를 트랜스파일링할 수 있도록 설정합니다.

const path = require('path')
const withTM = require('next-transpile-modules')(['react-simple-captcha']) //추가해줍니다.

/** @type {import('next').NextConfig} */

module.exports = withTM({})

 이 설정을 통해 CommonJS로 작성된 react-simple-captcha 모듈을 ES 모듈로 변환하여 사용할 수 있게 됩니다.

a. Transpiler란

: Transpiler는 코드를 변환하는 도구를 말합니다. 쉽게 말해, 이는 특정 환경에서 사용 가능한 라이브러리를 다른 환경에서도 호환되도록 도와주는 도구입니다.
예를 들어, JavaScript의 ES6 문법을 ES5로 변환하거나, React의 JSX 및 TypeScript 코드를 브라우저가 이해할 수 있는 JavaScript로 변환하는 도구입니다. 대표적인 transpiler로는 Babel과 SWC가 있습니다.

b. next-transpile-modules란

: Next.js에서 외부 라이브러리의 소스 코드를 ES 모듈로 Transpiling(변환)해주는 도구입니다.
기본적으로 Next.js는 ES 모듈을 사용하는데, 일부 외부 라이브러리는 여전히 CommonJS 형식으로 작성된 경우가 있습니다. 이때 발생하는 호환성 문제를 해결하기 위해 next-transpile-modules을 사용하여 CommonJS 형식의 라이브러리를 ES 모듈로 변환하여 사용할 수 있게 합니다.

3. 마무리

 이 문제를 해결하면서 자바스크립트의 모듈 시스템에 대한 이해도를 높일 수 있었고, 앞으로 다른 라이브러리나 패키지를 사용할 때에도 모듈 형식에 주의를 기울여야 한다는 점을 알게 되었습니다.
이를 통해 프로젝트 환경에 맞는 도구와 설정을 선택하는 것이 중요하다는 것과 특히, 다양한 모듈 시스템을 사용하는 여러 라이브러리들이 공존하는 환경에서는 이와 같은 호환성 문제를 사전에 방지하기 위해 모듈 형식을 확인하고 적절한 트랜스파일링 도구를 적용하는 것이 매우 중요하다는 것을 깨달았습니다.