JavaScript
PR

JavaScriptのimportとexport入門|モジュールの使い方とよくあるエラー

JavaScriptのimportとexport入門|モジュールの使い方とよくあるエラー
hr
記事内に商品プロモーションを含む場合があります

JavaScript のコードが長くなってくると、1 つのファイルに全部を書くのはつらくなります。そこで使うのが import と export、つまりモジュールの仕組みです。ところが書いてみると「Cannot use import statement outside a module と出る」「HTML をダブルクリックで開くと動かない」といったつまずきがよく起こります。

この記事では、ブラウザーで動く JavaScript のモジュールを、名前付き export と default export の違い、as と import * as、よくあるエラーの実際の文言と直し方、トップレベル await・動的 import() まで、実行結果つきで解説します。結果は Microsoft Edge 155(ヘッドレスモード)と Python 3.12 の簡易サーバーで、自分の PC(127.0.0.1)の中だけで動かして確かめたものです。仕様は MDN(Mozilla の公式リファレンス)の英語版で確認しました。

モジュールとは:ファイルを分けて「部品」にする仕組み

モジュールは、1 つのファイルを 1 つの部品として扱う仕組みです。部品を作る側のファイルは、外に見せたい関数や値に export(出す)を付けます。使う側のファイルは import(取り込む)で、必要なものだけを名前で受け取ります。

昔は <script> タグを何個も並べて、全部のファイルの変数を 1 つの場所(グローバル)で共有していました。これだと、別のファイルに同じ名前の変数があると上書きされてしまいます。モジュールなら、export したもの以外はファイルの中に閉じこもるので、名前のぶつかりを気にせず分割できます。

まず動かしてみる:3 つのファイルとローカルサーバー

練習用に、デスクトップなどに module-practice というフォルダーを作り、メモ帳で次の 3 つのファイルを保存します(「ファイルの種類」は「すべてのファイル (*.*)」、エンコードは UTF-8 のまま)。1 つ目は部品を出す側の math.js です。

// math.js:計算の部品
export const PI = 3.14;

export function add(a, b) {
  return a + b;
}

export default function multiply(a, b) {
  return a * b;
}

2 つ目は部品を使う側の main.js です。

import { PI, add } from "./math.js";
import multiply from "./math.js";

console.log(add(2, 3));
console.log(multiply(4, 5));
console.log(PI);
document.querySelector("#out").textContent = `2 + 3 = ${add(2, 3)}`;

3 つ目は、main.js を読み込む index.html です。<script> タグに type="module" を付けるのがポイントです。

<!doctype html>
<html lang="ja">
<head>
  <meta charset="utf-8">
  <title>モジュールの練習</title>
  <script type="module" src="./main.js"></script>
</head>
<body>
  <p id="out"></p>
</body>
</html>
index.html が type=module で main.js を読み込み、main.js が math.js を import する流れ。波かっこの中の PI と add は math.js の名前付き export に、波かっこなしの multiply は export default に対応する
図 1:index.html・main.js・math.js の関係と、import と export の対応

ここで index.html をダブルクリックして開いても、画面には何も表示されません(理由は後の「ダブルクリックで開くと CORS エラーになる」で説明します)。モジュールを試すときは、次の手順でローカルサーバー(自分の PC の中だけで動く Web サーバー)を通して開きます。Python が入っていれば、追加のインストールは要りません。

  1. エクスプローラーで module-practice フォルダーを開きます。
  2. ファイルのない場所を右クリックし、「ターミナルで開く」を選びます。
  3. 開いた画面に次のコマンドを貼り付けて、Enter キーを押します。
py -m http.server 8000 --bind 127.0.0.1
Serving HTTP on 127.0.0.1 port 8000 (http://127.0.0.1:8000/) ...

この表示が出たら待ち受け中です。画面はそのままにして、Edge か Chrome のアドレス欄に次の URL を入れて開きます。

http://127.0.0.1:8000/

画面に「2 + 3 = 5」と表示され、F12 キーで開いた開発者ツールの「Console(コンソール)」タブには次のように出ます。

5
20
3.14

終わったら、コマンドを入れた画面で Ctrl+C キーを押すとサーバーが止まります。--bind 127.0.0.1 は「この PC の中からだけ接続を受け付ける」という指定で、同じネットワークのほかの PC からフォルダーの中身を見られないようにしています。待ち受けの番号(8000)の意味は「ポート番号とは?」で解説しています。

なお、main.js は <head> の中で読み込んでいるのに、#out の要素を見つけられています。MDN のとおり、モジュールは自動で defer(HTML を読み終えてから実行)になるためです。普通の <script> を head に書いて要素が null になる問題は「JavaScriptのDOM操作入門」で扱っています。

名前付き export と default export の違い

MDN によると、export には名前付き exportとdefault exportの 2 種類があり、名前付きは 1 つのファイルにいくつでも書けますが、default は 1 つだけです。いちばんの違いは、import するときの波かっこ { } の有無です。

名前付き exportdefault export
書き方export function add() {}export default function multiply() {}
1 ファイルにいくついくつでも1 つだけ
import の書き方import { add } from "./math.js"import multiply from "./math.js"
受け取る名前export と同じ名前(変えるなら as)好きな名前を付けられる

default export は受け取る側が名前を決めるので、import kakeru from "./math.js"; と書いても multiply 関数を受け取れます。反対に、名前付き export は名前が合っていないとエラーになります(後の「よくある間違い」で実際の文言を紹介します)。どちらを使うかはチームの決まりに合わせますが、迷ったら「名前付きを基本にし、ファイルの主役が 1 つだけのときに default」と考えると分かりやすいです。

関数の宣言に export を付ける代わりに、ファイルの最後でまとめて書くこともできます。次の例は tax 関数を withTax という名前で外に出しています。

function toYen(price) {
  return `${price.toLocaleString("ja-JP")} 円`;
}
function tax(price) {
  return Math.floor(price * 1.1);
}

export { toYen, tax as withTax };

これを utils/format.js として保存し、別のファイルで import { toYen, withTax } from "./utils/format.js"; として console.log(toYen(withTax(1980))); を実行すると「2,178 円」と表示されました。

as で別名を付ける・import * as でまとめて受け取る

import するときも as で別名を付けられます。自分のファイルにすでに同じ名前があるときに便利です。また import * as 名前 と書くと、そのファイルの export を全部まとめた 1 つのオブジェクトとして受け取れます。

import { add as plus } from "./math.js";
import * as math from "./math.js";

console.log(plus(1, 2));
console.log(math.add(10, 20));
console.log(math.default(3, 3));
console.log(math.PI);
console.log(Object.keys(math));
3
30
9
3.14
PI,add,default

default export は、まとめたオブジェクトの中では default という名前で入っています。

モジュールならではの 4 つの性質

モジュールとして読み込んだファイルは、普通の <script>(以下「通常のスクリプト」)とは動きが少し違います。同じコードを両方で動かして比べました。

1. 自動で strict mode になる

strict mode(厳格モード)は、間違いやすい書き方をエラーにしてくれるモードです。モジュールでは、何も書かなくても自動でこのモードになります。let や const を付け忘れた代入で確かめます。

console.log(this);
total = 100;
console.log(total);

通常のスクリプトでは this === window が true になり、total は勝手にグローバル変数になって「100」と表示されました。モジュールでは this が undefined になり、2 行目で Uncaught ReferenceError: total is not defined が出て止まりました。宣言忘れにすぐ気付けるのは良いことです。

2. トップレベルの変数がグローバルにならない

ファイルのいちばん外側で var count = 1; と const message = "こんにちは"; を宣言し、そのあとに読み込んだ別のファイルから window.count と typeof message を調べました。

読み込み方window.counttypeof message
通常のスクリプト1string(見える)
モジュールundefinedundefined(見えない)

モジュールの変数はそのファイルの中だけで有効です。ほかのファイルで使いたいものは export して import します。そのため、開発者ツールのコンソールからモジュールの変数を直接のぞくこともできません。

3. 何回 import しても 1 回だけ実行される

次の counter.js を、a.js と b.js の両方から import し、HTML には a.js・b.js・a.js の順に 3 つの <script type="module"> を書きました。a.js と b.js は、それぞれ increment() を呼んでから count を表示します。

console.log("counter.js を実行しました");
export let count = 0;
export function increment() {
  count++;
}
counter.js を実行しました
a.js: 1
b.js: 2

counter.js も、2 回書いた a.js も、実行は 1 回だけでした。そして b.js では count が 2 になっています。import した変数は値のコピーではなく、元のファイルの変数をのぞく窓のようなもの(MDN では live binding と呼びます)なので、a.js が増やした結果が b.js からも見えます。ただし、受け取った側からの書き換えはできません(後述)。

4. import はファイルの先頭に引き上げられる

MDN によると import は「巻き上げ(hoisting)」され、読み込んだファイルはそのファイルの本体より先に実行されます。console.log("order.js の最初の行"); の次の行に import を書いても、表示は「order-dep.js を実行」→「order.js の最初の行」の順でした。読みやすさのため、import はファイルの先頭にまとめて書きましょう。

よくある間違いとエラーの文言

ここからは、はじめのうちによく出会うエラーを、Edge のコンソールに表示された文言のまま紹介します。

type=”module” の付け忘れ:Cannot use import statement outside a module

index.html の type="module" を消して <script src="./main.js"></script> にすると、次のエラーが出ました。

Uncaught SyntaxError: Cannot use import statement outside a module

「モジュールの外では import 文を使えない」という意味です。MDN にあるとおり、import 文はモジュールの中でしか書けません。最初に読み込む <script> に type="module" を付ければ直ります。main.js から import される math.js 側には、何も付ける必要はありません。

ダブルクリックで開くと CORS エラーになる

index.html をダブルクリックで開くと、アドレス欄は file:///C:/…/index.html になります。この状態でコンソールを見ると、次のエラーが出ていました(パスの途中は省略しています)。

Access to script at 'file:///C:/…/main.js' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: chrome-experimental-site-token-provider, chrome-extension, chrome-untrusted, data, edge, http, https, isolated-app.
Failed to load resource: net::ERR_FAILED

モジュールのファイルは、通常のスクリプトと違って CORS(オリジンをまたぐ読み込みのルール)に従って読み込まれます。ところが file:// で開いたページのオリジンは null 扱いで、ブラウザーは file:// からの CORS 読み込みを許していません。MDN も「HTML ファイルを file:// URL で開くと、モジュールのセキュリティ上の要件により CORS エラーになる。サーバーを通して試す必要がある」と説明しています。

ダブルクリックで file から開いたページはオリジンが null になり、main.js の読み込みが CORS エラーで止められる。py -m http.server で http://127.0.0.1:8000/ から開くと、同じオリジンから main.js を読み込めて実行される
図 2:ダブルクリックで開いた場合とローカルサーバーで開いた場合

直し方は、最初に紹介した py -m http.server などのローカルサーバーで開くことです。CORS の仕組みや「オリジン」の意味は「CORSとは?」で詳しく解説しています。

パスの ./ を省略する

import { add } from "math.js"; のように ./ を書かないと、次のエラーになりました。

Uncaught TypeError: Failed to resolve module specifier "math.js". Relative references must start with either "/", "./", or "../".

「相対パスは / か ./ か ../ で始めなければならない」という意味です。"math.js" のような書き方は「ベア指定子」と呼ばれ、npm のパッケージ名を指すのに使われます。ブラウザーでこの形を使うには import map という別の設定が必要です。同じフォルダーなら ./、1 つ上なら ../ を付けます。

拡張子 .js を省略する

import { add } from "./math"; と拡張子を省くと、コンソールには Failed to load resource: the server responded with a status of 404 (File not found) と出て、何も実行されませんでした。サーバー側の記録には "GET /math HTTP/1.1" 404 とあり、ブラウザーは書かれたとおり「math」という名前のファイルを探しています。MDN によると、ブラウザーは .js や index.js を補って何度も探すことはしません。拡張子まで正確に書きましょう。

default export を波かっこで受け取る

multiply は default export なのに import { multiply } from "./math.js"; と書くと、次のエラーになりました。

Uncaught SyntaxError: The requested module './math.js' does not provide an export named 'multiply'

「math.js は multiply という名前付き export を出していない」という意味です。波かっこを外して import multiply from "./math.js"; にします。名前付き export のつづり間違いでも同じエラーになります。

export default に const を付ける・受け取った値に代入する

export default const NAME = "math"; は Uncaught SyntaxError: Unexpected token 'const' になりました。default にできるのは式・関数・クラスなので、const NAME = "math"; と宣言してから export default NAME; と書きます。

また、import した PI に PI = 3; と代入すると Uncaught TypeError: Assignment to constant variable. になりました。MDN のとおり、import した値は読み取り専用です。値を変えたいときは、元のファイルに変更用の関数(counter.js の increment のようなもの)を用意します。

トップレベル await と動的 import()

トップレベル await:関数の外で await を書ける

通常のスクリプトでは await は async 関数の中でしか使えませんが、モジュールではファイルのいちばん外側でも使えます。同じフォルダーに data.json(中身は { "siteName": "ENG LIFE BLOG", "version": 3 })を置き、設定を読み込むモジュールを作りました。

// config.js
console.log("config.js:読み込み開始");
const res = await fetch("./data.json");
export const config = await res.json();
console.log("config.js:読み込み完了");
// app.js(index.html から type="module" で読み込む)
import { config } from "./config.js";
console.log("app.js:", config.siteName, config.version);
config.js:読み込み開始
config.js:読み込み完了
app.js: ENG LIFE BLOG 3

app.js は、config.js の await がすべて終わってから実行されました。そのため、使う側は「まだ読み込み中かも」と気にせず config を使えます。await の基本は「JavaScriptの非同期処理入門」、JSON の扱いは「JavaScriptのJSON.parseとstringify」を参照してください。

動的 import():必要になったときに読み込む

import("./ファイル名.js") と関数のように書くと、好きなタイミングでモジュールを読み込めます。結果は Promise で、中身は import * as と同じ「export をまとめたオブジェクト」です。ボタンを押したときだけ重い機能を読み込む、といった使い方をします。

// heavy.js
console.log("heavy.js を読み込みました");
export function hello(name) {
  return `こんにちは、${name}さん`;
}
import("./heavy.js").then((module) => {
  console.log(module.hello("JavaScript"));
});
console.log("import() の直後の行");
import() の直後の行
heavy.js を読み込みました
こんにちは、JavaScriptさん

読み込みを待たずに次の行が先に実行されているのが分かります。このコードは type="module" のない通常のスクリプトでも動きました(MDN も、モジュールでない場所でモジュールを読み込むには動的 import を使うよう案内しています)。モジュールの中で await import("./heavy.js") を 2 回実行すると、2 回とも同じオブジェクトが返り、heavy.js の実行は 1 回だけでした。

Node.js の require(CommonJS)との違い

サンプルコードを探していると、import の代わりに require を使ったコードを見かけます。これは Node.js(ブラウザーの外で JavaScript を動かす環境)で昔から使われている CommonJS という別のモジュールの仕組みです。この記事の検証用 PC には Node.js を入れていないため、以下は実行しておらず、Node.js 公式ドキュメントの説明を紹介するだけです。

// CommonJS の書き方(Node.js 公式ドキュメントの例)
const circle = require('./circle.js');

// circle.js 側
const { PI } = Math;
exports.area = (r) => PI * r ** 2;
ES モジュール(この記事)CommonJS
読み込みimportrequire()
書き出しexportexports.名前 / module.exports
ブラウザーそのまま使えるそのままでは使えない
拡張子の省略できないできる(.js・.json・.node の順に探す)

Node.js 公式ドキュメントによると、Node.js では拡張子 .mjs や package.json の "type": "module" を指定するとファイルが ES モジュールとして扱われ、.cjs や "type": "commonjs" なら CommonJS として扱われます。Node.js でも ES モジュールの import では拡張子が必須です。これから覚えるなら、ブラウザーと共通の import / export から始めるのがおすすめです。

よくある質問

.mjs という拡張子は必要ですか?

ブラウザーでは不要です。この記事の例はすべて .js で動いています。MDN によると、大事なのは拡張子ではなく、サーバーが Content-Type: text/javascript のような JavaScript の種類(MIME タイプ)で返すことです。今回の Python 3.12 の簡易サーバーは、.js を text/javascript で返していました。

開発者ツールのコンソールで import を試せますか?

動的 import なら試せます。ローカルサーバーで開いたページ(この記事では練習用の index.html)のコンソールで import("./math.js").then((m) => console.log(m.add(1, 2))) と入力すると、「3」と表示されました。パスは開いているページの場所が基準になります。また、モジュールの変数はグローバルにならないので、コンソールから直接は見えません。

まとめ

モジュールは export で部品を出し、import で受け取る仕組みです。名前付きは波かっこあり、default は波かっこなし。HTML からは type="module" を付けて読み込み、パスは ./ と .js まで書き、ダブルクリックではなくローカルサーバーで開く。この 3 点を押さえれば、はじめのつまずきはほとんど避けられます。

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました