How to import JSON files in ES modules

If you're using ECMAScript modules, you probably know the problem — you can't "just" import JSON files. To import and load a JSON file in browser ES modules, you have to do a "window.fetch dance" and request the JSON file to parse it yourself. Obviously, not great...

There were multiple attempts to resolve this poor DX and make it easier to load JSON. Let's find out where we stand today!

Chrome started off with JSON Modules shipping in Chrome 91.

// Legacy: JSON modules
import data from "./resource.json"

The idea was to rely on the returned resource MIME type to evaluate how a module file should be handled. Imported resources of type application/json or text/json would then be parsed as JSON.

Unfortunately, this approach came with a hard-to-ignore security flaw. What if a harmless-looking resource.json returns the text/javascript MIME type, and the browser starts executing this static file? This approach is way too easy to exploit. Not great!

To not only rely on content types, the next iteration was Import Assertions. With them, developers were responsible for defining the module type.

// Legacy: Import Assertions
import data from "./resource.json" assert { type: "json" };

And again, this feature shipped in Chromium land.

MDN Compat Data (source)

Browser support info for Import attributes (`assert` syntax)

91	91	91	Nope	Non	Nö	Nope	16.0	91

But spec making is hard. Another discussion unveiled that bringing JSON loading to the web isn't only about parsing a resource in a script but also integrating the new functionality elsewhere.

For example, how could JSON requests be secured via CSP? And would a JSON import count as CSP connect-src or script-src?

Eventually, things got sorted, and spec makers landed on renaming Import Assertions to Import Attributes. Ufff...

// Current proposal: Import Attributes
import data from "./resource.json" with { type: "json" };

Where are we support-wise here?

After this back and forth, browsers don't really support the import attribute syntax at the time of writing.

MDN Compat Data (source)

Browser support info for Import attributes

Non	Nei	Nei	Non	Nope	Nope	Non	Nope	Nope

So, for now, we're still stuck on fetching and parsing JSON manually. Maybe in 2024, we can just import some juicy JSON. That would be something.