How to import JSON files in ES modules (Node.js)

ES modules are still reasonably new in Node.js land (they're stable since Node 14). Modules come with a built-in module system, and features such as top-level await.

I read an informative post on ES modules by Pawel Grzybek and learned that you can't import JSON files in ES modules today.

/* 
  Experimental JSON import in Node.js
  $ node index.mjs
*/

// An import assertion in a static import
import info from `./package.json` assert { type: `json` };

// An import assertion in a dynamic import
const { default: info } = await import("./package.json", {
  assert: {
    type: "json",
  },
});

That's a real bummer because I'm pretty used to doing require calls such as const data = require('./some-file.json') in Node.js.

But can you use import assertions in Node.js today?

At the time of writing, the current Node.js LTS (v18.12) still marks import assertions as experimental.

import obj from "mod" with { "type": "json" }

This post explains ways to deal with JSON in ES modules if you don't want to use the experimental features yet.

The Node.js documentation advises to use the fs module and do the work of reading the files and parsing it yourself.

import { readFile } from 'fs/promises';
const json = JSON.parse(
  await readFile(
    new URL('./some-file.json', import.meta.url)
  )
);

The documentation also states that you can use createRequire to load JSON files. This approach is the way Pawel advises in his blog post.

createRequire allows you to construct a CommonJS require function to use typical CommonJS features such as reading JSON in your Node.js EcmaScript modules.

import { createRequire } from "module";
const require = createRequire(import.meta.url);
const data = require("./data.json");

For the future, import assertions are the way to go!

As for the alternatives, neither option feels great, but I'll probably stick to the first option because it's more understandable.