diff --git a/README.md b/README.md index 421e5955211be9..346d0ef6c52be4 100644 --- a/README.md +++ b/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 diff --git a/scripts/release/build.js b/scripts/release/build.js index a26d5babc7f2b2..b1d88e1a5390f5 100644 --- a/scripts/release/build.js +++ b/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');