Node.jsでdocument is not definedを直す方法

​​Node.js​JavaScript,jsdom,Vitest,トラブルシュート

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 は次のとおりです。

js
export function renderGreeting(name) {
  const el = document.querySelector('#app');
  el.textContent = `こんにちは、${name}さん`;
  return el.textContent;
}

これを呼び出す main.js は次のとおりです。

js
import { renderGreeting } from './src/greet.js';

renderGreeting('ねこ');

検証環境(Ubuntu 24.04、Node.js 22.23.4)で node main.js を実行すると、次のように出て止まりました(終了コードは1。パスは例示用の値に置き換えています)。

text
$ 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 を調べると、次のようになりました。

text
$ 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 は次のとおりです。

js
const root = document.getElementById('app');

export function show(text) {
  root.textContent = text;
}

show を呼ばずに import だけして console.log('読み込み完了') する main-top.js を実行すると、「読み込み完了」は表示されずに止まりました(パスは例示用の値に置き換えています)。

text
$ 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 だけして実行すると、エラーは出ずに「読み込み完了」と表示されました。

js
export function show(text) {
  const root = document.getElementById('app');
  root.textContent = text;
}
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 を用意しました。

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;
}
ts
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。パスは例示用の値に置き換えています)。

text
$ 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 にします。すべてのテストファイルに効きます。

ts
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)で入れてから実行すると、テストが通りました。

text
$ 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行目にこのコメントだけを足して実行すると、同じようにテストが通りました。

ts
// @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 は次のとおりです。

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 を実行すると、エラーは出ずに、あいさつの文字が表示されました。

text
$ node main-safe.js
こんにちは、ねこさん

​Posted by 86