Node 에서 require is not defined in ES module scope 가 날 때: 파일이 ESM 으로 판정되는 경로와 고치는 방법을 노드 18~26 에서 직접 시험한 결과When Node says require is not defined in ES module scope: the ways a file gets treated as ESM and how to fix it, tested directly on Node 18 to 26
node 로 스크립트를 돌렸다가 require is not defined in ES module scope 로 멈춘 독자가, 그 파일이 왜 ESM 으로 판정됐는지 알고 자기 상황에 맞는 수정 방법을 고르게 돕는다.
이 오류는 require 가 사라진 게 아니라 Node 가 그 파일을 ESM 으로 읽는다는 뜻이다. .mjs, type: module 인 package.json, 그리고 type 이 없는 .js 에 든 import 구문이 그 이유가 되며, import 로 바꾸거나 createRequire 를 만들거나 파일 이름을 .cjs 로 바꾸면 노드 18~26 시험 버전 모두에서 풀렸다.
오류 화면의 파일 경로를 열어 확장자와 가장 가까운 package.json 의 type 줄을 먼저 확인하고, 아래 표에서 해당하는 경로의 수정 방법을 하나 골라 적용해 보라.
한 줄 요약: 이 오류는 Node 가 그 파일을 ESM 으로 읽는다는 뜻이니,
import로 바꾸거나createRequire를 쓰거나 파일을.cjs로 바꾸면 된다.
node app.js 를 쳤더니 ReferenceError: require is not defined in ES module scope, you can use import instead 로 멈췄다면, 파일의 require 가 고장 난 게 아니라 Node 가 그 파일을 ESM(import 와 export 를 쓰는 자바스크립트 모듈 방식, require 를 쓰는 옛 방식은 CommonJS)으로 읽고 있다는 신호다. 이 글은 파일이 ESM 으로 판정되는 경로, 고치는 방법, 고친 뒤 이어서 만나는 오류를 노드 18.20.8, 20.20.2, 22.23.4, 24.22.2, 26.7.0 에서 임시 폴더로 직접 쟀다. 시험은 macOS 26.6.2 (arm64)에서 했고, 각 사례를 두 번 돌려 출력이 같음을 확인했다.
오류는 같고 이유는 셋이다
가장 단순한 파일은 한 줄이다.
const fs = require('fs'); console.log('OK')이 한 줄을 a.mjs 로 저장해 다섯 버전으로 돌리면 모두 종료 코드 1 이다. 오류 화면 맨 위에는 파일 위치와 문제의 줄이 찍히고, 오류 문구는 이렇다.
ReferenceError: require is not defined in ES module scope, you can use import instead같은 한 줄을 .js 로 저장해도 아래 두 경우에는 같은 오류가 난다.
| 파일 | 같은 폴더의 package.json | 결과 |
|---|---|---|
a.mjs |
없음 | 다섯 버전 모두 같은 오류, 종료 코드 1 |
d.js |
{"type":"module"} |
다섯 버전 모두 같은 오류, 종료 코드 1 |
f.js(import os from 'os' 도 들어 있음) |
없음 | 20.20.2 이상 네 버전은 같은 오류, 18.20.8 은 다른 오류(아래) |
세 번째 줄이 이 글에서 가장 헷갈리는 경우다. type 을 쓴 적도 없고 확장자도 .js 인데 같은 오류가 난다. 파일 안에 import 구문이 있으면 Node 가 “이건 ESM 이다”라고 판정하기 때문이다. Node 문서는 이 동작을 구문 감지(syntax detection)라 부르고, 확장자가 .js 이거나 없고 type 이 없는 파일을 대상으로 한다고 적는다. 문서의 변경 이력은 이 감지가 v22.7.0, v20.19.0 부터 기본으로 켜진다고 적고 있다. 시험한 20.20.2 와 22.23.4 는 모두 그 뒤라서 켜져 있었다. 20.020.18 과 22.022.6 은 시험하지 않았다.
type: module 이 이유일 때만 오류 화면에 안내 줄이 하나 더 붙는다.
This file is being treated as an ES module because it has a '.js' file extension and '<경로>/package.json' contains "type": "module". To treat it as a CommonJS script, rename it to use the '.cjs' file extension.a.mjs 와 type 이 없는 f.js 의 화면에는 이 줄이 없었다. 그러니 오류 화면에 이 줄이 있으면 가장 가까운 package.json 의 type 을 보고, 없으면 확장자나 파일 안의 import 구문을 본다. 이 줄은 다섯 버전 모두에서 type: module 파일에만 붙었다.
같은 f.js 가 18.20.8 에서는 오류가 달랐다. 구문 감지가 없어서 import 줄에서 먼저 멈춘다. 같은 파일이 18.20.8 에서는 Cannot use import statement outside a module, 20.20.2 이상에서는 require is not defined in ES module scope 로 끝나는 셈이다.
SyntaxError: Cannot use import statement outside a modulerequire 줄이 없는 import fs from 'fs' 만 든 .js 도 18.20.8 은 같은 SyntaxError(종료 코드 1)이고 20.20.2 이후 네 버전은 종료 코드 0 으로 돌았다. 26.7.0 에서 --no-experimental-detect-module 로 감지를 끄면 이 파일도 SyntaxError: Cannot use import statement outside a module 로 종료 코드 1 이었다. import 만 든 .js 가 type 이 없는 package.json 이 있는 폴더에 있으면 20.20.2 이상 네 버전이 MODULE_TYPELESS_PACKAGE_JSON 경고를 내고 코드는 실행됐다. 감지에만 기대면 파일 하나가 어느 버전에서 어떻게 읽히는지 헷갈리므로, Node 문서도 모호한 파일에 ESM 문법을 쓰면 성능 비용이 들어 명시를 권한다고 적는다.
고치는 길은 네 가지다
아래 길은 임시 폴더에서 다섯 버전 모두 통과했다. 예외는 import.meta.dirname 하나이고 본문에 따로 적었다.
1. 파일 전체를 ESM 으로 쓴다. const path = require('path') 를 import path from 'path' 로 바꾼다. 같은 방향으로 module.exports 도 ESM 에서는 쓰지 못한다. module.exports = { a: 1 } 는 ReferenceError: module is not defined in ES module scope 로 다섯 버전 모두 종료 코드 1 이었다.
2. require 를 직접 만든다. 파일은 그대로 ESM 으로 두고 필요한 자리에서만 require 를 만든다. 문서도 필요하면 module.createRequire() 로 만들 수 있다고 적는다.
import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const fs = require('fs');type: module 폴더의 .js 에서 이 세 줄은 다섯 버전 모두 fs.readFileSync 가 함수로 나왔다.
3. 파일 이름을 .cjs 로 바꾼다. type: module 인 패키지 안에서도 .cjs 파일은 CommonJS 로 읽힌다. require('fs') 와 __dirname 이 다섯 버전 모두 동작했다. 오류 화면의 안내 줄이 권하는 방법이 이것이다.
4. CommonJS 전용 변수를 바꾼다. __dirname 은 ESM 에서 ReferenceError: __dirname is not defined in ES module scope 로 종료 코드 1 이다(.mjs 와 type: module 모두, 다섯 버전). 문서는 “These CommonJS variables are not available in ES modules.” 라 적고 import.meta.dirname 으로 같은 일을 할 수 있다고 한다. 이 값은 v21.2.0, v20.11.0 에서 들어왔다. 그래서 18.20.8 에서 console.log(import.meta.dirname) 은 에러 없이 undefined 를 찍고 종료 코드 0 이다. 그 값을 path.join(import.meta.dirname, 'x') 에 넣으면 TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received undefined 로 터진다. 20.20.2 이상 네 버전은 같은 줄이 <폴더>/x 를 돌려줬다. 18 까지 맞추려면 이렇게 쓴다.
import { fileURLToPath } from 'url';
import path from 'path';
const __dirname = path.dirname(fileURLToPath(import.meta.url));이 방식은 다섯 버전 모두 폴더 이름을 정확히 찍었다.
고치고 나면 다음 오류가 기다린다
require 를 import 로 바꾸면 ESM 규칙이 한꺼번에 적용된다. type: module 인 폴더에서 아래 표의 줄이 나왔고, 오른쪽이 고친 뒤 다섯 버전에서 모두 종료 코드 0 이었던 형태다.
| 쓴 코드 | 오류(첫 줄) | 고친 코드 |
|---|---|---|
import { x } from './lib' |
ERR_MODULE_NOT_FOUND: Cannot find module ‘<폴더>/lib’ imported from … |
from './lib.js' |
import { x } from './lib'(lib 은 폴더, 안에 index.js) |
ERR_UNSUPPORTED_DIR_IMPORT: Directory import … is not supported |
from './lib/index.js' |
import data from './data.json' |
18.20.8·20.20.2: ERR_IMPORT_ASSERTION_TYPE_MISSING, 22.23.4·24.22.2·26.7.0: ERR_IMPORT_ATTRIBUTE_MISSING |
import data from './data.json' with { type: 'json' } |
문서도 import 에는 확장자와 폴더 index 를 모두 적어야 하고 “The type: 'json' attribute is mandatory when importing JSON modules.” 라고 말한다. 확장자를 지우는 CommonJS 습관이 ESM 에서는 그대로 오류가 된다. JSON 오류의 이름은 버전에 따라 ASSERTION 과 ATTRIBUTE 로 갈리므로 검색할 때는 이름 앞부분이 아니라 needs an import attribute 문구를 쓴다.
반대 방향: CommonJS 가 ESM 을 부를 때
반대로 type: commonjs 인 폴더의 h.js 가 require('./lib.mjs')(안에 export const x = 42)를 부르면 18.20.8 은 Error [ERR_REQUIRE_ESM]: require() of ES Module … not supported. 로 종료 코드 1 이었고, 20.20.2 이상 네 버전은 42 를 찍으며 종료 코드 0 이었다. 문서의 이력상 require() 로 ESM 을 읽는 기능은 v20.19.0, v22.12.0, v23.0.0 부터 플래그 없이 돌고, 대상 모듈에 최상위 await 가 없어야 한다. 최상위 await 를 쓴 .js 는 type 이 없어도 18.20.8 에서는 SyntaxError: await is only valid in async functions and the top level bodies of modules 였고 20.20.2 이상에서는 돌았다. 최상위 await 가 있는 ESM 을 require 로 부르는 경우는 시험하지 못했다.
시험하지 못한 것
노드 20.020.18, 22.022.6, 홀수 버전(21·23·25)은 시험하지 않았다. 본문의 “20” 은 모두 20.20.2 이다. TypeScript(ts-node, tsx), 번들러, Jest, AWS Lambda 같은 호스팅 환경, Deno·Bun, Windows 는 시험하지 않았다. 이미 import 와 require 가 섞인 프로젝트에서 package.json 의 type 줄을 지웠을 때의 영향도 시험하지 못했다. 공개 질문 글 제목은 검색에서 확인했지만 검색량은 모른다.
세 줄 요약
- 원인은 파일이 ESM 으로 판정된 것이고, 이유는
.mjs,package.json의type: module,type없는.js안의import구문(20.20.2 이상) 셋이다. - 고치는 길은
import,createRequire(import.meta.url),.cjs,fileURLToPath(import.meta.url)이고 시험한 다섯 버전 모두 통과했다. - ESM 으로 넘어오면 확장자·폴더 index·JSON attribute 오류가 이어서 나오므로
./lib.js,./lib/index.js,with { type: 'json' }형태를 미리 적는다.
To help a reader whose script stopped with require is not defined in ES module scope understand why Node treated the file as ESM and choose a fix that fits their situation.
The error does not mean require disappeared; it means Node reads that file as ESM. A .mjs extension, a package.json with type: module, and an import statement in a .js file with no type can each cause it, and switching to import, building a require with createRequire, or renaming the file to .cjs worked on every Node version I tested from 18 to 26.
Open the file path shown in the error, check its extension and the type line of the nearest package.json, then pick one fix from the table below that matches your path and apply it.
Contents
One-line summary: This error means Node reads that file as ESM, so switch to
import, build arequirewithcreateRequire, or rename the file to.cjs.
If node app.js stopped with ReferenceError: require is not defined in ES module scope, you can use import instead, your require is not broken. It is a sign that Node is reading that file as ESM (the JavaScript module system that uses import and export; the older one that uses require is CommonJS). This article measures, on Node 18.20.8, 20.20.2, 22.23.4, 24.22.2 and 26.7.0 in temporary folders, how a file ends up being treated as ESM, how to fix it, and which errors come next. I ran the tests on macOS 26.6.2 (arm64) and ran each case twice to confirm the output was identical.
One error, three reasons
The simplest file is one line.
const fs = require('fs'); console.log('OK')Saved as a.mjs and run on all five versions, it ended with exit code 1 every time. The top of the error screen shows the file location and the offending line, and the error text is this.
ReferenceError: require is not defined in ES module scope, you can use import insteadSaving the same line as .js gives the same error in two more cases.
| File | package.json in the same folder | Result |
|---|---|---|
a.mjs |
none | same error on all five versions, exit code 1 |
d.js |
{"type":"module"} |
same error on all five versions, exit code 1 |
f.js (also contains import os from 'os') |
none | same error on the four versions from 20.20.2 up, a different error on 18.20.8 (below) |
The third row is the most confusing case in this article. You never wrote type, and the extension is .js, yet you get the same error. That happens because Node decides “this is ESM” when the file contains an import statement. The Node documentation calls this behavior syntax detection and says it applies to files whose extension is .js or missing and that have no type. The change history in the documentation says this detection is on by default from v22.7.0 and v20.19.0. The 20.20.2 and 22.23.4 I tested are both after that, so it was on. I did not test 20.0 to 20.18 or 22.0 to 22.6.
Only when type: module is the reason does the error screen get one more hint line.
This file is being treated as an ES module because it has a '.js' file extension and '<path>/package.json' contains "type": "module". To treat it as a CommonJS script, rename it to use the '.cjs' file extension.The screens for a.mjs and for f.js with no type did not have this line. So if the line is on your screen, look at the type in the nearest package.json; if it is not, look at the extension or at an import statement inside the file. The line appeared only for the type: module file, on all five versions.
The same f.js produced a different error on 18.20.8. It has no syntax detection, so it stops at the import line first. The same file therefore ends with Cannot use import statement outside a module on 18.20.8 and with require is not defined in ES module scope from 20.20.2 up.
SyntaxError: Cannot use import statement outside a moduleA .js that contains only import fs from 'fs' with no require line also gave the same SyntaxError (exit code 1) on 18.20.8, and ran with exit code 0 on the four versions from 20.20.2 up. Turning detection off on 26.7.0 with --no-experimental-detect-module made this file end with SyntaxError: Cannot use import statement outside a module and exit code 1 as well. When an import-only .js sat in a folder with a package.json that has no type, the four versions from 20.20.2 up printed a MODULE_TYPELESS_PACKAGE_JSON warning and still ran the code. Relying on detection alone makes it confusing how one file is read on which version, and the Node documentation also says that writing ES module syntax in ambiguous files costs performance and encourages being explicit.
Four ways to fix it
The ways below all passed on all five versions in temporary folders. The one exception is import.meta.dirname, described separately.
1. Write the whole file as ESM. Change const path = require('path') to import path from 'path'. In the same direction, module.exports cannot be used in ESM either. module.exports = { a: 1 } ended with ReferenceError: module is not defined in ES module scope and exit code 1 on all five versions.
2. Build require yourself. Leave the file as ESM and create require only where you need it. The documentation also says a require can be constructed with module.createRequire() when needed.
import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const fs = require('fs');In a .js file in a type: module folder, these three lines gave fs.readFileSync as a function on all five versions.
3. Rename the file to .cjs. Even inside a type: module package, a .cjs file is read as CommonJS. require('fs') and __dirname both worked on all five versions. This is what the hint line on the error screen recommends.
4. Replace the CommonJS-only variables. In ESM, __dirname ends with ReferenceError: __dirname is not defined in ES module scope and exit code 1 (both for .mjs and for type: module, on all five versions). The documentation says “These CommonJS variables are not available in ES modules.” and says import.meta.dirname can do the same job. That value arrived in v21.2.0 and v20.11.0. So on 18.20.8, console.log(import.meta.dirname) prints undefined without any error and exits with code 0. Pass that value to path.join(import.meta.dirname, 'x') and it blows up with TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received undefined. On the four versions from 20.20.2 up, the same line returned <folder>/x. To cover 18 as well, write it like this.
import { fileURLToPath } from 'url';
import path from 'path';
const __dirname = path.dirname(fileURLToPath(import.meta.url));This printed the folder name correctly on all five versions.
After you fix it, the next errors are waiting
Once you change require to import, ESM rules apply all at once. In a type: module folder, the lines in the table below appeared, and the right column is the form that exited with code 0 on all five versions after the fix.
| Code you wrote | Error (first line) | Fixed code |
|---|---|---|
import { x } from './lib' |
ERR_MODULE_NOT_FOUND: Cannot find module ‘ |
from './lib.js' |
import { x } from './lib' (lib is a folder with index.js inside) |
ERR_UNSUPPORTED_DIR_IMPORT: Directory import … is not supported |
from './lib/index.js' |
import data from './data.json' |
18.20.8 and 20.20.2: ERR_IMPORT_ASSERTION_TYPE_MISSING, 22.23.4, 24.22.2 and 26.7.0: ERR_IMPORT_ATTRIBUTE_MISSING |
import data from './data.json' with { type: 'json' } |
The documentation also says import needs the extension and the folder index spelled out, and “The type: 'json' attribute is mandatory when importing JSON modules.” The CommonJS habit of dropping the extension becomes an error as it is in ESM. The JSON error name splits into ASSERTION and ATTRIBUTE depending on the version, so when you search, use the phrase needs an import attribute rather than the start of the name.
The opposite direction: CommonJS calling ESM
In the other direction, when h.js in a type: commonjs folder calls require('./lib.mjs') (which contains export const x = 42), 18.20.8 ended with Error [ERR_REQUIRE_ESM]: require() of ES Module … not supported. and exit code 1, while the four versions from 20.20.2 up printed 42 and exited with code 0. According to the history in the documentation, loading ESM with require() runs without a flag from v20.19.0, v22.12.0 and v23.0.0, and the target module must not use top-level await. A .js that uses top-level await ended with SyntaxError: await is only valid in async functions and the top level bodies of modules on 18.20.8 even without a type, and ran from 20.20.2 up. I could not test calling an ESM that has top-level await through require.
What I did not test
I did not test Node 20.0 to 20.18, 22.0 to 22.6, or the odd-numbered versions (21, 23, 25). Every “20” in this article is 20.20.2. I did not test TypeScript (ts-node, tsx), bundlers, Jest, hosting environments such as AWS Lambda, Deno and Bun, or Windows. I also could not test what happens when you delete the type line of package.json in a project that already mixes import and require. I confirmed public question titles in a search but do not know the search volume.
Three-line summary
- The cause is that the file was treated as ESM, for one of three reasons:
.mjs,type: moduleinpackage.json, or animportstatement in a.jswith notype(20.20.2 and up). - The fixes are
import,createRequire(import.meta.url),.cjs, andfileURLToPath(import.meta.url), and all of them passed on the five versions I tested. - Moving to ESM brings extension, folder-index and JSON-attribute errors next, so write
./lib.js,./lib/index.jsandwith { type: 'json' }up front.