@mdx-js/loader - npm Package Compare versions

Comparing version 2.3.0 to 3.0.0

lib/index.d.ts

@@ -7,20 +7,29 @@ /**
  * @this {LoaderContext}
+ *   Context.
  * @param {string} value
+ *   Value.
  * @param {LoaderContext['callback']} callback
+ *   Callback.
+ * @returns {undefined}
+ *   Nothing.
  */
-export function loader(this: LoaderContext, value: string, callback: LoaderContext['callback']): void;
+export function loader(this: LoaderContext, value: string, callback: LoaderContext['callback']): undefined;
 export type CompileOptions = import('@mdx-js/mdx').CompileOptions;
-export type VFileCompatible = import('vfile').VFileCompatible;
+export type Compatible = import('vfile').Compatible;
 export type VFile = import('vfile').VFile;
 export type VFileMessage = import('vfile-message').VFileMessage;
+export type WebpackCompiler = import('webpack').Compiler;
 export type LoaderContext = import('webpack').LoaderContext<unknown>;
-export type WebpackCompiler = import('webpack').Compiler;
-export type Defaults = Pick<CompileOptions, 'SourceMapGenerator'>;
 /**
- * Configuration.
+ * Configuration (TypeScript type).
+ *
+ * Options are the same as `compile` from `@mdx-js/mdx` with the exception
+ * that the `SourceMapGenerator` and `development` options are supported
+ * based on how you configure webpack.
+ * You cannot pass them manually.
  */
-export type Options = Omit<CompileOptions, 'SourceMapGenerator'>;
+export type Options = Omit<CompileOptions, 'SourceMapGenerator' | 'development'>;
 /**
  * Process.
  */
-export type Process = (vfileCompatible: VFileCompatible) => Promise<VFile>;
+export type Process = (vfileCompatible: Compatible) => Promise<VFile>;

lib/index.js

 /**
  * @typedef {import('@mdx-js/mdx').CompileOptions} CompileOptions
- * @typedef {import('vfile').VFileCompatible} VFileCompatible
+ * @typedef {import('vfile').Compatible} Compatible
  * @typedef {import('vfile').VFile} VFile
  * @typedef {import('vfile-message').VFileMessage} VFileMessage
+ * @typedef {import('webpack').Compiler} WebpackCompiler
  * @typedef {import('webpack').LoaderContext<unknown>} LoaderContext
- * @typedef {import('webpack').Compiler} WebpackCompiler
  */
 
 /**
- * @typedef {Pick<CompileOptions, 'SourceMapGenerator'>} Defaults
- * @typedef {Omit<CompileOptions, 'SourceMapGenerator'>} Options
- *   Configuration.
+ * @typedef {Omit<CompileOptions, 'SourceMapGenerator' | 'development'>} Options
+ *   Configuration (TypeScript type).
  *
+ *   Options are the same as `compile` from `@mdx-js/mdx` with the exception
+ *   that the `SourceMapGenerator` and `development` options are supported
+ *   based on how you configure webpack.
+ *   You cannot pass them manually.
+ *
  * @callback Process
  *   Process.
- * @param {VFileCompatible} vfileCompatible
+ * @param {Compatible} vfileCompatible
  *   Input.
@@ -23,9 +27,8 @@ * @returns {Promise<VFile>}
 
+import {Buffer} from 'node:buffer'
 import {createHash} from 'node:crypto'
 import path from 'node:path'
+import {createFormatAwareProcessors} from '@mdx-js/mdx/internal-create-format-aware-processors'
 import {SourceMapGenerator} from 'source-map'
-import {createFormatAwareProcessors} from '@mdx-js/mdx/lib/util/create-format-aware-processors.js'
 
-const own = {}.hasOwnProperty
-
 // Note: the cache is heavily inspired by:
@@ -43,24 +46,29 @@ // <https://github.com/TypeStrong/ts-loader/blob/5c030bf/src/instance-cache.ts>
  * @this {LoaderContext}
+ *   Context.
  * @param {string} value
+ *   Value.
  * @param {LoaderContext['callback']} callback
+ *   Callback.
+ * @returns {undefined}
+ *   Nothing.
  */
 export function loader(value, callback) {
-  /** @type {Defaults} */
-  const defaults = this.sourceMap ? {SourceMapGenerator} : {}
-  const options = {
+  const options = /** @type {CompileOptions} */ (this.getOptions())
+  const hash = getOptionsHash(options)
+  const config = {
+    SourceMapGenerator: this.sourceMap ? SourceMapGenerator : undefined,
     development: this.mode === 'development',
-    .../** @type {CompileOptions} */ (this.getOptions())
+    ...options
   }
-  const config = {...defaults, ...options}
-  const hash = getOptionsHash(options)
-  // Some loaders set `undefined` (see `TypeStrong/ts-loader`).
-  /* c8 ignore next */
+  /* c8 ignore next -- some loaders set `undefined` (see `TypeStrong/ts-loader`). */
   const compiler = this._compiler || marker
 
-  /* Removed option. */
-  /* c8 ignore next 5 */
+  // To do: next major: remove.
   if ('renderer' in config) {
-    throw new Error(
-      '`options.renderer` is no longer supported. Please see <https://mdxjs.com/migrating/v2/> for more information'
+    callback(
+      new Error(
+        '`options.renderer` is no longer supported. Please see <https://mdxjs.com/migrating/v2/> for more information'
+      )
     )
+    return
   }
@@ -82,10 +90,23 @@
 
-  process({value, path: this.resourcePath}).then(
-    (file) => {
-      // @ts-expect-error: `webpack` is not compiled with `exactOptionalPropertyTypes`,
-      // so it does not allow `file.map` to be `undefined` here.
-      callback(null, file.value, file.map)
+  const context = this.context
+  const filePath = this.resourcePath
+
+  process({value, path: filePath}).then(
+    function (file) {
+      callback(
+        undefined,
+        Buffer.from(file.value),
+        // @ts-expect-error: `webpack` is not compiled with `exactOptionalPropertyTypes`,
+        // so it does not allow `sourceRoot` in `file.map` to be `undefined` here.
+        file.map || undefined
+      )
     },
-    (/** @type VFileMessage */ error) => {
-      const fpath = path.relative(this.context, this.resourcePath)
+    /**
+     * @param {VFileMessage} error
+     *   Error.
+     * @returns {undefined}
+     *   Nothing.
+     */
+    function (error) {
+      const fpath = path.relative(context, filePath)
       error.message = `${fpath}:${error.name}: ${error.message}`
@@ -98,3 +119,6 @@ callback(error)
 /**
- * @param {Options} options
+ * @param {Readonly<Options>} options
+ *   Configuration.
+ * @returns {string}
+ *   Hash.
  */
@@ -107,3 +131,3 @@ function getOptionsHash(options) {
   for (key in options) {
-    if (own.call(options, key)) {
+    if (Object.hasOwn(options, key)) {
       const value = options[key]
@@ -110,0 +134,0 @@

package.json

 {
   "name": "@mdx-js/loader",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "description": "Webpack loader for MDX",
   "license": "MIT",
   "keywords": [
+    "jsx",
+    "markdown",
     "mdx",
-    "markdown",
-    "jsx",
-    "webpack",
+    "preact",
+    "react",
     "remark",
-    "react",
-    "preact",
-    "vue"
+    "vue",
+    "webpack"
   ],
@@ -20,3 +20,3 @@ "homepage": "https://mdxjs.com",
     "url": "https://github.com/mdx-js/mdx",
-    "directory": "packages/loader"
+    "directory": "packages/loader/"
   },
@@ -39,4 +39,3 @@ "bugs": "https://github.com/mdx-js/mdx/issues",
   "sideEffects": false,
-  "main": "index.cjs",
-  "types": "index.d.ts",
+  "exports": "./index.cjs",
   "files": [
@@ -49,37 +48,20 @@ "lib/",
   "dependencies": {
-    "@mdx-js/mdx": "^2.0.0",
+    "@mdx-js/mdx": "^3.0.0",
     "source-map": "^0.7.0"
   },
   "peerDependencies": {
-    "webpack": ">=4"
+    "webpack": ">=5"
   },
-  "devDependencies": {
-    "@types/loader-utils": "^2.0.0",
-    "@types/react": "^18.0.0",
-    "@types/react-dom": "^18.0.0",
-    "@vue/babel-plugin-jsx": "^1.0.0",
-    "@vue/server-renderer": "^3.0.0",
-    "babel-loader": "^9.0.0",
-    "preact": "^10.0.0",
-    "preact-render-to-string": "^5.0.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
-    "vue": "^3.0.0",
-    "webpack": "^5.0.0"
-  },
+  "devDependencies": {},
   "scripts": {
-    "prepack": "npm run build",
-    "build": "tsc --build --clean && tsc --build && type-coverage",
-    "test-api": "uvu test \"\\.js$\"",
-    "test-coverage": "c8 --check-coverage --100 --reporter lcov npm run test-api",
-    "test": "npm run build && npm run test-coverage"
+    "test": "npm run test-coverage",
+    "test-api": "node --conditions development test/index.js",
+    "test-coverage": "c8 --100 --reporter lcov npm run test-api"
   },
-  "xo": false,
-  "typeCoverage": {
-    "atLeast": 100,
-    "detail": true,
-    "strict": true,
-    "ignoreCatch": true
-  },
-  "gitHead": "bf7deab69996449cb99c2217dff75e65855eb2c1"
+  "xo": {
+    "prettier": true,
+    "rules": {
+      "n/file-extension-in-import": "off"
+    }
+  }
 }

readme.md

@@ -16,11 +16,16 @@ # `@mdx-js/loader`
 
-*   [What is this?](#what-is-this)
-*   [When should I use this?](#when-should-i-use-this)
-*   [Install](#install)
-*   [Use](#use)
-*   [API](#api)
-*   [Types](#types)
-*   [Security](#security)
-*   [Contribute](#contribute)
-*   [License](#license)
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+  * [`mdx`](#mdx)
+  * [`Options`](#options)
+* [Examples](#examples)
+  * [Combine with Babel](#combine-with-babel)
+* [Types](#types)
+* [Compatibility](#compatibility)
+* [Security](#security)
+* [Contribute](#contribute)
+* [License](#license)
 
@@ -36,5 +41,4 @@ ## What is this?
 
-This integration can be combined with the Babel loader to support nonstandard
-JSX runtimes (such as Vue) or compile modern JavaScript features to ones your
-users support.
+This integration can be combined with the Babel loader to compile modern
+JavaScript features to ones your users support.
 
@@ -46,7 +50,5 @@ If you want to evaluate MDX code then the lower-level compiler (`@mdx-js/mdx`)
 
-This package is [ESM only][esm]:
-Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
+This package is [ESM only][esm].
+In Node.js (version 16+), install with [npm][]:
 
-[npm][]:
-
 ```sh
@@ -56,8 +58,2 @@ npm install @mdx-js/loader
 
-[yarn][]:
-
-```sh
-yarn add @mdx-js/loader
-```
-
 ## Use
@@ -67,4 +63,5 @@
 
-```js
-module.exports = {
+```tsx
+/** @type {import('webpack').Configuration} */
+const webpackConfig = {
   module: {
@@ -80,3 +77,3 @@ // …
             /** @type {import('@mdx-js/loader').Options} */
-            options: {}
+            options: {/* jsxImportSource: …, otherOptions… */}
           }
@@ -88,36 +85,61 @@ ]
 }
+
+export default webpackConfig
 ```
 
-See also [¶ Create React App (CRA)][cra], [¶ Next.js][next], and
-[¶ Vue CLI][vue-cli], if you’re using webpack through them, for more info.
+See also [¶ Next.js][next] and [¶ Vue CLI][vue-cli], if you’re using webpack
+through them, for more info.
 
 ## API
 
+This package exports no identifiers.
+The default export is [`mdx`][api-mdx].
+
+### `mdx`
+
 This package exports a [webpack][] plugin as the default export.
+Configuration (see [`Options`][api-options]) are passed separately through
+webpack.
 
-Source maps are supported based on how you configure webpack.
-You do not need to pass `options.SourceMapGenerator`.
+### `Options`
 
-###### `options`
+Configuration (TypeScript type).
 
-`options` are the same as [`compile` from `@mdx-js/mdx`][options].
+Options are the same as [`CompileOptions` from `@mdx-js/mdx`][compile-options]
+with the exception that the `SourceMapGenerator` and `development` options are
+supported based on how you configure webpack.
+You cannot pass them manually.
 
-###### Note: Babel
+## Examples
 
+### Combine with Babel
+
 If you use modern JavaScript features you might want to use Babel through
-[`babel-loader`][babel-loader] to compile to code that works:
+[`babel-loader`][babel-loader] to compile to code that works in older browsers:
 
-```js
-// …
-use: [
-  // Note that Webpack runs right-to-left: `@mdx-js/loader` is used first, then
-  // `babel-loader`.
-  {loader: 'babel-loader', options: {}},
-  {
-    loader: '@mdx-js/loader',
-    /** @type {import('@mdx-js/loader').Options} */
-    options: {},
-  },
-];
-// …
+```tsx
+/** @type {import('webpack').Configuration} */
+const webpackConfig = {
+  module: {
+    // …
+    rules: [
+      // …
+      {
+        test: /\.mdx?$/,
+        use: [
+          // Note that Webpack runs right-to-left: `@mdx-js/loader` is used first, then
+          // `babel-loader`.
+          {loader: 'babel-loader', options: {}},
+          {
+            loader: '@mdx-js/loader',
+            /** @type {import('@mdx-js/loader').Options} */
+            options: {}
+          }
+        ]
+      }
+    ]
+  }
+}
+
+export default webpackConfig
 ```
@@ -128,6 +150,15 @@
 This package is fully typed with [TypeScript][].
+It exports the additional type [`Options`][api-options].
 See [§ Types][types] on our website for information.
 
-An `Options` type is exported, which represents acceptable configuration.
+## Compatibility
 
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line, `@mdx-js/loader@^3`,
+compatible with Node.js 16.
+
 ## Security
@@ -174,4 +205,2 @@
 
-[yarn]: https://classic.yarnpkg.com/docs/cli/add/
-
 [contribute]: https://mdxjs.com/community/contribute/
@@ -187,11 +216,11 @@
 
-[webpack]: https://webpack.js.org
-
 [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
 
+[security]: https://mdxjs.com/getting-started/#security
+
 [types]: https://mdxjs.com/getting-started/#types
 
-[security]: https://mdxjs.com/getting-started/#security
+[webpack]: https://webpack.js.org
 
-[options]: https://mdxjs.com/packages/mdx/#compilefile-options
+[compile-options]: https://mdxjs.com/packages/mdx/#compileoptions
 
@@ -202,6 +231,8 @@ [typescript]: https://www.typescriptlang.org
 
-[cra]: https://mdxjs.com/getting-started/#create-react-app-cra
-
 [next]: https://mdxjs.com/getting-started/#nextjs
 
 [vue-cli]: https://mdxjs.com/getting-started/#vue-cli
+
+[api-mdx]: #mdx
+
+[api-options]: #options

No alert changes

Improved metrics

Total package byte prevSize

14114

4.93%

Dev dependency count

0

-100%

Lines of code

182

14.47%

Number of lines in readme file

228

15.74%

Worsened metrics

Number of package files

7

-12.5%