feat: allow accessing named exports (#114)

Co-authored-by: Adam Laycock <[email protected]>
Co-authored-by: Kent C. Dodds <[email protected]>

BREAKING CHANGE: This updates xdm to the latest version (which is [a major version bump](https://github.com/wooorm/xdm/releases/tag/3.0.0)). No breaking changes are expected, but we're being cautious.

Author: xoumi

README.md

@@ -189,6 +189,9 @@ the esbuild version mdx-bundler uses.
   - [Options](#options)
   - [Component Substitution](#component-substitution)
   - [Frontmatter and const](#frontmatter-and-const)
+  - [Accessing named exports](#accessing-named-exports)
+  - [Image Bundling](#image-bundling)
+  - [bundleMDXFile](#bundlemdxfile)
   - [Known Issues](#known-issues)
 - [Inspiration](#inspiration)
 - [Other Solutions](#other-solutions)
@@ -527,6 +530,36 @@ export const exampleImage = 'https://example.com/image.jpg'
 <img src={exampleImage} alt="Image alt text" />
 ```
 
+### Accessing named exports
+
+You can use `getMDXExport` instead of `getMDXComponent` to treat the mdx file as a module instead of just a component.
+It takes the same arguments that `getMDXComponent` does.
+
+```mdx
+---
+title: Example Post
+---
+
+export const toc = [
+  { depth: 1, value: 'The title' }
+]
+
+# The title
+```
+
+```js
+import * as React from 'react'
+import {getMDXExport} from 'mdx-bundler/client'
+
+function MDXPage({code}: {code: string}) {
+  const mdxExport = getMDXExport(code)
+  console.log(mdxExport.toc) // [ { depth: 1, value: 'The title' } ]
+
+  const Component = React.useMemo(() => mdxExport.default, [code])
+
+  return <Component />
+}
+```
 ### Image Bundling
 
 With the [cwd](#cwd) and the remark plugin

package.json

@@ -44,33 +44,33 @@
     "@esbuild-plugins/node-resolve": "^0.1.4",
     "@fal-works/esbuild-plugin-global-externals": "^2.1.2",
     "gray-matter": "^4.0.3",
-    "remark-frontmatter": "^4.0.0",
+    "remark-frontmatter": "^4.0.1",
     "remark-mdx-frontmatter": "^1.0.1",
     "uuid": "^8.3.2",
-    "xdm": "^2.1.0"
+    "xdm": "^3.2.0"
   },
   "peerDependencies": {
     "esbuild": "0.11.x || 0.12.x || 0.13.x"
   },
   "devDependencies": {
-    "@testing-library/react": "^12.0.0",
+    "@testing-library/react": "^12.1.2",
     "@types/jsdom": "^16.2.13",
     "@types/mdx": "^2.0.1",
-    "@types/react": "^17.0.17",
-    "@types/react-dom": "^17.0.9",
+    "@types/react": "^17.0.34",
+    "@types/react-dom": "^17.0.11",
     "@types/uuid": "^8.3.1",
-    "c8": "^7.8.0",
+    "c8": "^7.10.0",
     "cross-env": "^7.0.3",
-    "esbuild": "^0.12.20",
-    "jsdom": "^17.0.0",
-    "kcd-scripts": "^11.2.0",
+    "esbuild": "^0.13.12",
+    "jsdom": "^18.0.1",
+    "kcd-scripts": "^11.2.2",
     "left-pad": "^1.3.0",
     "mdx-test-data": "^1.0.1",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
     "remark-mdx-images": "^1.0.3",
     "typescript": "^4.4.3",
-    "uvu": "^0.5.1"
+    "uvu": "^0.5.2"
   },
   "eslintConfig": {
     "extends": "./node_modules/kcd-scripts/eslint.js",

src/__tests__/index.js

@@ -8,7 +8,7 @@ import rtl from '@testing-library/react'
 import leftPad from 'left-pad'
 import {remarkMdxImages} from 'remark-mdx-images'
 import {bundleMDX, bundleMDXFile} from '../index.js'
-import {getMDXComponent} from '../client.js'
+import {getMDXComponent, getMDXExport} from '../client.js'
 
 const {render} = rtl
 
@@ -394,6 +394,38 @@ test('should output assets', async () => {
   )
 })
 
+test('should support importing named exports', async () => {
+  const mdxSource = `
+---
+title: Example Post
+published: 2021-02-13
+description: This is some meta-data
+---
+
+export const uncle = 'Bob'
+
+# {uncle} was indeed the uncle
+`.trim()
+
+  const result = await bundleMDX(mdxSource)
+
+  /** @type {import('../types').MDXExport<{uncle: string}, {title: string, published: Date, description: string}>} */
+  const mdxExport = getMDXExport(result.code)
+
+  // remark-mdx-frontmatter exports frontmatter
+  assert.equal(mdxExport.frontmatter, {
+    title: 'Example Post',
+    published: new Date('2021-02-13'),
+    description: 'This is some meta-data',
+  })
+
+  assert.equal(mdxExport.uncle, 'Bob')
+
+  const {container} = render(React.createElement(mdxExport.default))
+
+  assert.equal(container.innerHTML, `<h1>Bob was indeed the uncle</h1>`)
+})
+
 test('should support mdx from node_modules', async () => {
   const mdxSource = `
 import MdxData from 'mdx-test-data'

src/client.js

@@ -17,10 +17,23 @@ import * as ReactDOM from 'react-dom'
  * @return {React.FunctionComponent<MDXContentProps>}
  */
 function getMDXComponent(code, globals) {
+  const mdxExport = getMDXExport(code, globals)
+  return mdxExport.default
+}
+
+/**
+ * @template ExportedObject
+ * @template Frontmatter
+ * @type {import('./types').MDXExportFunction<ExportedObject, Frontmatter>}
+ * @param {string} code - The string of code you got from bundleMDX
+ * @param {Record<string, unknown>} [globals] - Any variables your MDX needs to have accessible when it runs
+ *
+ */
+function getMDXExport(code, globals) {
   const scope = {React, ReactDOM, _jsx_runtime, ...globals}
   // eslint-disable-next-line
   const fn = new Function(...Object.keys(scope), code)
   return fn(...Object.values(scope))
 }
 
-export {getMDXComponent}
+export {getMDXComponent, getMDXExport}

src/index.js

@@ -195,7 +195,7 @@ async function bundleMDX(
     const code = decoder.write(Buffer.from(bundled.outputFiles[0].contents))
 
     return {
-      code: `${code};return Component.default;`,
+      code: `${code};return Component;`,
       frontmatter: matter.data,
       errors: bundled.errors,
       matter,
@@ -214,7 +214,7 @@ async function bundleMDX(
     await unlink(path.join(buildOptions.outdir, fileName))
 
     return {
-      code: `${code};return Component.default;`,
+      code: `${code};return Component`,
       frontmatter: matter.data,
       errors: bundled.errors,
       matter,

src/types.d.ts

@@ -136,3 +136,19 @@ type BundleMDXOptions = {
     options: GrayMatterOption<I, any>,
   ) => GrayMatterOption<I, any>
 }
+
+type MDXExport<
+  ExportObject extends {},
+  Frontmatter = {[key: string]: unknown},
+> = {
+  default: React.FunctionComponent<MDXContentProps>
+  frontmatter: Frontmatter
+} & ExportObject
+
+type MDXExportFunction<
+  ExportedObject extends {},
+  Frontmatter extends Record<string, unknown>,
+> = (
+  code: string,
+  globals?: Record<string, unknown>,
+) => MDXExport<ExportedObject, Frontmatter>