Allow ESM imports of the data

README.md

@@ -14,20 +14,62 @@ Read how this project is [governed](GOVERNANCE.md).
 
 Chat on [chat.mozilla.org#mdn](https://chat.mozilla.org/#/room/#mdn:mozilla.org).
 
-## Installation
+## Installation and Import
+
+### NodeJS
 
 You can install `@mdn/browser-compat-data` as a node package.
 
-```
+```bash
 npm install @mdn/browser-compat-data
+# ...or...
+yarn add @mdn/browser-compat-data
 ```
 
-## Usage
+Then, you can import BCD into your project with either `import` or `require()`:
 
 ```js
+// ESM with Import Assertions (NodeJS 16+)
+import bcd from '@mdn/browser-compat-data' assert { type: 'json' };
+
+// ...or...
+
+// ESM Wrapper for older NodeJS versions (NodeJS v12+)
+import bcd from '@mdn/browser-compat-data/forLegacyNode';
+
+// ...or...
+
+// CommonJS Module (Any NodeJS)
 const bcd = require('@mdn/browser-compat-data');
-bcd.css.properties.background;
+```
+
+### Deno/Browsers
+
+You can import `@mdn/browser-compat-data` using a CDN.
+
+```js
+import bcd from 'https://unpkg.com/@mdn/browser-compat-data' assert { type: 'json' };
+```
+
+### Other Languages
+
+You can obtain the raw compatibility data for `@mdn/browser-compat-data` using a CDN and loading the `data.json` file included in releases.
+
+```py
+https://unpkg.com/@mdn/browser-compat-data/data.json
+```
+
+## Usage
+
+Once you have imported BCD, you can access the compatibility data for any feature by accessing the properties of the dictionary.
+
+```js
+// Grab the desired support statement
+const support = bcd.css.properties.background.__compat;
 // returns a compat data object (see schema)
+
+// You may use any syntax to obtain dictionary items
+const support = bcd['api']['Document']['body']['__compat'];
 ```
 
 ## Package contents

scripts/release/build.js

@@ -26,9 +26,13 @@ async function writeData() {
   await fs.writeFile(dest, data);
 }
 
-async function writeIndex() {
-  const dest = path.resolve(directory, 'index.js');
-  const content = `module.exports = require("./data.json");\n`;
+async function writeWrapper() {
+  const dest = path.resolve(directory, 'legacynode.mjs');
+  const content = `// A small wrapper to allow ESM imports on older NodeJS versions that don't support import assertions
+import fs from 'node:fs';
+const bcd = JSON.parse(fs.readFileSync(new URL('./data.json', import.meta.url)));
+export default bcd;
+`;
   await fs.writeFile(dest, content);
 }
 
@@ -43,7 +47,13 @@ async function copyFiles() {
 
 function createManifest() {
   const full = require('../../package.json');
-  const minimal = { main: 'index.js' };
+  const minimal = {
+    main: 'data.json',
+    exports: {
+      '.': './data.json',
+      './forLegacyNode': './legacynode.mjs',
+    },
+  };
 
   const minimalKeys = [
     'name',
@@ -91,7 +101,7 @@ async function main() {
 
   await writeManifest();
   await writeData();
-  await writeIndex();
+  await writeWrapper();
   await copyFiles();
 
   console.log('Data bundle is ready');