본문 바로가기
카테고리 없음

ReferenceError: require is not defined 에러 원인과 해결 방법

바이브C 2026. 9. 24. 18:27

ReferenceError: require is not defined 에러 원인과 해결 방법

자바스크립트에서 require()로 모듈을 불러오려는데 갑자기 ReferenceError: require is not defined라는 오류가 나타날 때가 있습니다. 다른 예제에서는 멀쩡하게 사용하는 코드인데 내 프로젝트에서만 실행되지 않으면 require 문법 자체가 잘못된 것처럼 느껴질 수 있는데요.

 
하지만 require is not defined는 대부분 문법보다 현재 실행 환경과 모듈 시스템이 맞지 않아서 발생합니다. 브라우저에서 실행하는지, Node.js의 CommonJS인지 ES Module인지에 따라 해결 방법도 달라집니다. 원인부터 하나씩 알아보겠습니다.
 
 

ReferenceError: require is not defined 뜻은?

require()는 전통적으로 Node.js의 CommonJS 모듈 시스템에서 다른 모듈을 불러올 때 사용하는 방식입니다.

const fs = require("fs");

 

그런데 현재 실행 환경에 require라는 함수가 제공되지 않는다면 자바스크립트는 해당 이름을 찾을 수 없습니다. 그 결과 ReferenceError: require is not defined가 발생합니다.

 
쉽게 말하면 “현재 환경에서는 require라는 기능을 바로 사용할 수 없다”는 의미입니다. 따라서 require 철자를 수정하기보다 어떤 환경에서 코드를 실행하고 있는지 먼저 확인해야 합니다.
 
 

브라우저에서 require is not defined가 발생하는 이유

HTML에 연결한 일반적인 브라우저 JavaScript에서 Node.js의 CommonJS 방식인 require()를 그대로 사용하면 오류를 만날 수 있습니다.

<script src="app.js"></script>
// app.js
const module = require("./module.js");

 

브라우저가 기본적으로 Node.js의 CommonJS require 함수를 제공하는 것은 아니기 때문입니다. 브라우저에서 모듈을 직접 사용하려면 ES Module의 import와 export를 사용하는 방법을 고려할 수 있습니다.

 

<script type="module" src="app.js"></script>
import { sum } from "./math.js";
console.log(sum(1, 2));

 

이 경우 HTML의 script 태그에 type="module"이 지정되어 있는지도 함께 확인해야 합니다.

 
 

Node.js에서도 require 오류가 나는 이유

require는 Node.js에서 사용하는 방식인데 왜 Node.js에서도 오류가 발생할까요? 대표적인 이유는 현재 파일이 ES Module(ESM)로 실행되고 있기 때문입니다.
 

예를 들어 프로젝트의 package.json에 다음과 같은 설정이 있다면 해당 package 범위의 .js 파일은 ES Module 방식으로 처리될 수 있습니다.

{
  "type": "module"
}

 

이 환경에서 CommonJS 예제처럼 다음 코드를 작성하면 require를 바로 사용할 수 없어 오류가 발생할 수 있습니다.

const fs = require("fs");

 

ES Module 프로젝트라면 import 문법으로 맞추는 것이 일반적인 해결 방향입니다.

import fs from "node:fs";

 
 

CommonJS와 ES Module 차이를 알아두세요

CommonJS와 ES Module은 모듈을 가져오고 내보내는 방식이 다릅니다. 이 차이를 모르고 인터넷 예제를 그대로 복사하면 require 또는 import 관련 오류를 반복해서 만나기 쉽습니다.
 

구분CommonJSES Module
가져오기require()import
내보내기module.exportsexport
대표 확장자.cjs.mjs
package.json 예"type": "commonjs""type": "module"

 
쉽게 기억하면 require / module.exports는 CommonJS, import / export는 ES Module이라고 생각하면 됩니다.

다만 실제 프로젝트에서는 Node.js 버전과 package 설정, 빌드 도구에 따라 세부 동작이 달라질 수 있으므로 프로젝트 구성을 함께 확인해야 합니다.
 
 

require를 import로 바꾸는 방법

현재 프로젝트가 ES Module을 사용한다면 require 코드를 import 형태로 변경할 수 있습니다.

// CommonJS
const express = require("express");
// ES Module
import express from "express";

 
내가 만든 파일을 불러오는 경우에도 같은 원리입니다.

// CommonJS
const math = require("./math");
// ES Module
import * as math from "./math.js";

 
그렇다고 require 코드를 기계적으로 import로 치환하면 항상 해결되는 것은 아닙니다. 해당 패키지가 어떤 방식으로 export하고 있는지, default export와 named export 중 무엇을 제공하는지도 확인해야 합니다.
 
 

CommonJS를 유지하고 싶다면 어떻게 할까?

기존 프로젝트가 CommonJS를 기준으로 만들어졌다면 반드시 ES Module로 변경할 필요는 없습니다. 프로젝트 전체의 구조와 사용하는 라이브러리를 고려해 기존 모듈 시스템을 유지하는 방법도 있습니다.
 

Node.js에서는 CommonJS 파일임을 명확하게 구분하기 위해 .cjs 확장자를 사용할 수 있습니다. 프로젝트의 package.json 설정도 현재 의도한 모듈 시스템과 일치하는지 확인하세요.

// example.cjs
const fs = require("fs");
console.log("CommonJS 실행");

 
중요한 것은 오류 하나를 없애기 위해 설정을 무작정 변경하기보다 프로젝트가 CommonJS와 ESM 중 어느 방식을 기준으로 만들어졌는지 파악하는 것입니다.
 
 

require is not defined 주요 원인 6가지

1. 브라우저에서 Node.js용 require 코드를 실행한 경우
2. Node.js 프로젝트가 ES Module로 설정된 경우
3. package.json에 "type": "module"이 지정된 경우
4. .mjs 파일에서 CommonJS 방식의 require를 사용한 경우
5. CommonJS와 ES Module 코드를 혼용한 경우
6. 다른 실행 환경을 기준으로 작성된 예제를 그대로 사용한 경우
 
결국 대부분의 원인은 코드에서 사용하는 모듈 문법과 실제 실행 환경의 모듈 방식이 서로 다르다는 데 있습니다. 따라서 require 한 줄만 보기보다 프로젝트 전체의 모듈 설정을 확인하는 것이 중요합니다.
 
 

React·Vite 프로젝트에서 require 오류가 난다면?

React나 Vite처럼 최신 프론트엔드 개발 환경에서 예전 Node.js 또는 CommonJS 예제를 가져와 require()를 작성하면 환경에 따라 오류가 발생할 수 있습니다. 이런 프로젝트에서는 우선 기존 코드가 어떤 import 방식을 사용하고 있는지 확인하세요.

import MyComponent from "./MyComponent.jsx";

 
프로젝트의 다른 파일이 대부분 import/export를 사용하고 있다면 새 코드도 같은 모듈 방식에 맞추는 편이 자연스럽습니다. 오래된 블로그나 라이브러리 예제를 참고할 때는 현재 사용하는 도구와 버전에 맞는 문서인지도 확인하는 것이 좋습니다.
 
 

브라우저에서 fs를 import하면 해결될까?

여기서 주의할 점이 하나 있습니다. require 오류를 해결했다고 해서 Node.js 전용 기능을 브라우저에서 그대로 사용할 수 있는 것은 아닙니다.

const fs = require("fs");

fs처럼 Node.js 런타임에서 제공하는 기능은 일반적인 브라우저 환경에서 같은 방식으로 사용할 수 없습니다. 따라서 이런 경우에는 require를 import로 바꾸는 것만으로 해결하려 하지 말고 해당 기능 자체가 브라우저에서 사용할 수 있는 기능인지부터 확인해야 합니다.

 
 

require is not defined 해결 순서 7단계

오류를 만났다면 가장 먼저 현재 코드가 브라우저에서 실행되는지 Node.js에서 실행되는지 확인하세요.

그다음 프로젝트가 CommonJS와 ES Module 중 어느 방식을 사용하고 있는지 판단하면 해결 방향이 훨씬 명확해집니다.

순서확인할 내용
1단계브라우저인지 Node.js인지 실행 환경 확인
2단계package.json의 type 설정 확인
3단계.js, .mjs, .cjs 파일 확장자 확인
4단계프로젝트의 기존 import/require 방식 확인
5단계ESM이라면 적절한 import 문법 검토
6단계CommonJS라면 실행 설정과 파일 형식 확인
7단계변경 후 개발 서버나 Node.js 프로세스 재실행

 
 

Cannot use import statement 오류와의 관계

require is not defined와 Cannot use import statement outside a module은 서로 반대 상황처럼 나타나는 경우가 있습니다.
 
전자는 ESM이나 브라우저 환경에서 CommonJS의 require를 사용했을 때 만날 수 있고, 후자는 모듈로 처리되지 않는 환경에서 import를 사용했을 때 발생할 수 있습니다.
 

두 오류 모두 문법 하나만 수정하기보다 현재 파일이 어떤 모듈 시스템으로 실행되고 있는지를 확인해야 한다는 공통점이 있습니다. package.json과 파일 확장자, 브라우저의 type="module" 설정을 함께 살펴보세요.

 
 

require 오류를 예방하는 가장 쉬운 방법

새로운 예제 코드를 가져오기 전에 그 예제가 브라우저용인지 Node.js용인지, CommonJS인지 ES Module인지 확인하는 습관을 들이면 좋습니다. 오래된 예제와 최신 프로젝트 코드를 섞을 때 모듈 방식이 달라지는 경우가 많습니다.
 
 

ReferenceError: require is not defined는 결국 현재 실행 환경에서 require가 정의되어 있지 않다는 뜻입니다. 브라우저라면 ES Module 사용 여부를 확인하고, Node.js라면 package.json의 type과 파일 확장자를 먼저 살펴보세요.

 
무조건 require를 import로 바꾸거나 package.json 설정을 삭제하는 것보다 현재 프로젝트의 모듈 시스템을 먼저 파악하는 것이 핵심입니다. 이 기준을 이해해두면 require와 import 관련 오류를 훨씬 빠르게 해결할 수 있습니다.
 
 
 
 

티스토리툴바