Node.jsでdocument is not definedを直す方法
ReferenceError: document is not defined は、ブラウザーにしかない document を、Node.js の上で動くコードが使ったときに出ます。Node.js には document も window もないからです。テストなら Vitest の環境を jsdom か happy-dom にし、node で直接実行するコードなら typeof document で分けると、エラーが消えます。
ブラウザー用に書いた画面の処理を node コマンドで試したときや、DOM を書き換える関数のテストを Vitest で書いたときに出ます。私は検証環境でどちらの場合もエラーを起こし、メッセージの全文と、直すと消えることを確かめました。
検証環境は Ubuntu 24.04、Node.js 22.23.4(npm 10.9.9)、Vitest 5.1.0、jsdom 31.0.0、happy-dom 21.0.4 です。Jest で出る同じエラー、Next.js などのサーバーサイドレンダリング(SSR)で出る同じエラー、Windows と macOS は試していません。
node で実行したときのエラーの全文
#app の要素にあいさつの文字を入れる、ブラウザー用の関数を用意しました。src/greet.js は次のとおりです。
export function renderGreeting(name) {
const el = document.querySelector('#app');
el.textContent = `こんにちは、${name}さん`;
return el.textContent;
}
これを呼び出す main.js は次のとおりです。
import { renderGreeting } from './src/greet.js';
renderGreeting('ねこ');
検証環境(Ubuntu 24.04、Node.js 22.23.4)で node main.js を実行すると、次のように出て止まりました(終了コードは1。パスは例示用の値に置き換えています)。
$ node main.js
file:///path/to/app/src/greet.js:2
const el = document.querySelector('#app');
^
ReferenceError: document is not defined
at renderGreeting (file:///path/to/app/src/greet.js:2:14)
at file:///path/to/app/main.js:3:1
at ModuleJob.run (node:internal/modules/esm/module_job:343:25)
at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:681:26)
at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:117:5)
Node.js v22.23.4
ReferenceError: document is not defined は「document という名前の変数は定義されていない」という意味です。いちばん上の greet.js:2 と ^ が、止まった場所を示しています。その下の at renderGreeting (...) から、main.js の3行目で呼んだ renderGreeting の中で起きたと分かります。
Node.js のグローバルオブジェクトの一覧には、document も window もありません。検証環境で typeof を調べると、次のようになりました。
$ node -e 'console.log(typeof document, typeof window, typeof navigator)'
undefined undefined object
navigator だけは object になっています。Node.js 21.0.0 から、ブラウザーの navigator の一部をグローバルな navigator として用意しているためです。navigator があるからといって、ブラウザーの API がそろっているわけではありません。window を使うコードも同じように止まり、ReferenceError: window is not defined が出ました。
関数を呼ばなくても、読み込んだだけで出る場合
ファイルの一番上(関数の外)で document を使っていると、import しただけでエラーになります。src/top.js は次のとおりです。
const root = document.getElementById('app');
export function show(text) {
root.textContent = text;
}
show を呼ばずに import だけして console.log('読み込み完了') する main-top.js を実行すると、「読み込み完了」は表示されずに止まりました(パスは例示用の値に置き換えています)。
$ node main-top.js
file:///path/to/app/src/top.js:1
const root = document.getElementById('app');
^
ReferenceError: document is not defined
at file:///path/to/app/src/top.js:1:14
at ModuleJob.run (node:internal/modules/esm/module_job:343:25)
at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:681:26)
at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:117:5)
Node.js v22.23.4
スタックに関数の名前がなく、top.js:1:14 だけが出ているのが目印です。document を使う行を show の中に移した src/top-fixed.js を作り、main-top.js の import 先を ./src/top-fixed.js に変えた main-top-fixed.js で、同じように import だけして実行すると、エラーは出ずに「読み込み完了」と表示されました。
export function show(text) {
const root = document.getElementById('app');
root.textContent = text;
}
$ node main-top-fixed.js
読み込み完了
show の中で document を使うことは変わらないので、これで直るのは「読み込んだだけで止まる」ところまでです。node で show も呼ぶなら、後の「node でも動かしたいコードは typeof で分ける」の節の形にします。
Vitest のテストで出る場合
Vitest は、何も指定しなければテストを Node.js の環境で動かします。Vitest の設定項目 environment の説明でも、既定値は 'node' です。そのため、DOM を使うテストをそのまま書くと同じエラーになります。
TypeScript で書いた src/greet.ts と、そのテストの src/greet.test.ts を用意しました。
export function renderGreeting(name: string): string {
const el = document.querySelector<HTMLElement>('#app');
if (!el) throw new Error('#app がありません');
el.textContent = `こんにちは、${name}さん`;
return el.textContent;
}
import { beforeEach, expect, test } from 'vitest';
import { renderGreeting } from './greet';
beforeEach(() => {
document.body.innerHTML = '<div id="app"></div>';
});
test('名前を入れたあいさつを #app に表示する', () => {
expect(renderGreeting('ねこ')).toBe('こんにちは、ねこさん');
expect(document.querySelector('#app')?.textContent).toBe('こんにちは、ねこさん');
});
設定ファイル(vitest.config.ts)を置かずに実行すると、テストが失敗しました(終了コードは1。パスは例示用の値に置き換えています)。
$ npx vitest run src/greet.test.ts
RUN v5.1.0 /path/to/app
❯ src/greet.test.ts (1 test | 1 failed) 5ms
× 名前を入れたあいさつを #app に表示する 4ms
⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯
FAIL src/greet.test.ts > 名前を入れたあいさつを #app に表示する
ReferenceError: document is not defined
❯ src/greet.test.ts:5:3
3|
4| beforeEach(() => {
5| document.body.innerHTML = '<div id="app"></div>';
| ^
6| });
7|
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯
Test Files 1 failed (1)
Tests 1 failed (1)
Start at 19:01:57
Duration 218ms (transform 58%, import 23%, tests 10%, worker 9%)
止まった場所は、テストファイルの5行目、beforeEach の中の document.body でした。
設定ファイルで environment を jsdom にする
プロジェクトのテストの多くが DOM を使うなら、vitest.config.ts で環境を jsdom にします。すべてのテストファイルに効きます。
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
environment: 'jsdom',
},
});
検証環境では、Vitest を入れただけでは jsdom は入っていませんでした。Vitest の package.json でも、jsdom は省略できる(optional な)peerDependencies になっています。jsdom を入れないまま実行すると、document is not defined の代わりに MISSING DEPENDENCY Cannot find dependency 'jsdom' と Error: Cannot find package 'jsdom' imported from ... が出て、テストは1つも動きませんでした(Test Files no tests)。
npm install -D jsdom(検証では jsdom 31.0.0)で入れてから実行すると、テストが通りました。
$ npx vitest run --reporter=verbose src/greet.test.ts
RUN v5.1.0 /path/to/app
✓ src/greet.test.ts > 名前を入れたあいさつを #app に表示する 13ms
Test Files 1 passed (1)
Tests 1 passed (1)
Start at 19:02:01
Duration 790ms (environment 89%, transform 5%, tests 2%, import 2%, worker 1%)
一部のテストファイルだけ jsdom にする
DOM を使うテストが一部だけなら、そのファイルの先頭に // @vitest-environment jsdom と書きます。Vitest のガイドにある、ファイルごとに環境を指定する方法です。設定ファイルを消し、greet.test.ts の1行目にこのコメントだけを足して実行すると、同じようにテストが通りました。
// @vitest-environment jsdom
import { beforeEach, expect, test } from 'vitest';
import { renderGreeting } from './greet';
jsdom の代わりに happy-dom も使えます。npm install -D happy-dom(検証では 21.0.4)で入れ、コメントを // @vitest-environment happy-dom に変えても、このテストは通りました。Vitest のガイドでは、happy-dom は jsdom より速いとされる一方で、一部の API がないと説明されています。
node でも動かしたいコードは typeof で分ける
テストではなく、同じコードをブラウザーと Node.js の両方で動かしたいときは、document があるかどうかを先に確かめます。このとき if (document) と書くと、検証環境ではその行で ReferenceError: document is not defined が出て止まりました。document がない環境では、名前を読んだだけでエラーになります。
typeof を使うと止まりません。MDN の typeof の説明にあるとおり、宣言されていない名前に typeof を付けると、エラーにならずに "undefined" が返ります。src/safe.js は次のとおりです。
export function renderGreeting(name) {
const text = `こんにちは、${name}さん`;
if (typeof document === 'undefined') {
return text;
}
document.querySelector('#app').textContent = text;
return text;
}
この関数を呼んで戻り値を console.log する main-safe.js を実行すると、エラーは出ずに、あいさつの文字が表示されました。
$ node main-safe.js
こんにちは、ねこさん





