$3

If you find recma-mdx-escape-missing-components useful in your projects, consider supporting my work.
Your sponsorship means a lot 💖

Be the first sponsor and get featured here and on my sponsor wall.
Thank you for supporting open source! 🙌

recma-mdx-escape-missing-components

[![npm version][badge-npm-version]][url-npm-package]
[![npm downloads][badge-npm-download]][url-npm-package]
[![publish to npm][badge-publish-to-npm]][url-publish-github-actions]
[![code-coverage][badge-codecov]][url-codecov]
[![type-coverage][badge-type-coverage]][url-github-package]
[![typescript][badge-typescript]][url-typescript]
[![license][badge-license]][url-license]

This package is a [unified][unified] ([recma][recma]) plugin which allows you to escape MDX components that are either missing or not provided in an MDX document.

[unified][unified] is a project that transforms content with abstract syntax trees (ASTs) using the new parser [micromark][micromark]. [recma][recma] adds support for producing a javascript code by transforming [esast][esast] which stands for EcmaScript Abstract Syntax Tree (AST) that is used in production of compiled source for the [MDX][MDX].

When should I use this?

recma-mdx-escape-missing-components is useful for escaping MDX components that are missing or not explicitly provided in your MDX document.

You won’t encounter errors for missing or undefined MDX components because recma-mdx-escape-missing-components assigns a default value of () => null for them.

Installation

This package is suitable for ESM only. In Node.js (version 18+), install with npm:

``bash
npm install recma-mdx-escape-missing-components
`

or

`bash
yarn add recma-mdx-escape-missing-components
`

Usage

Say we have the following file, example.mdx, which consists some mdx components.

`mdx


Hi


`

And our module, example.js, looks as follows:

`javascript
import { read } from "to-vfile";
import { compile } from "@mdx-js/mdx";
import recmaMdxEscapeMissingComponents from "recma-mdx-escape-missing-components";

main();

async function main() {
const source = await read("example.mdx");

const compiledSource = await compile(source, {
recmaPlugins: [recmaMdxEscapeMissingComponents],
});

return String(compiledSource);
}
`

Now, running node example.js produces the compiled source which contains the statement below:

`js
// ...
const _EmptyComponent = () => null;
function _createMdxContent(props) {
// ...
const {Component1 = _EmptyComponent, Component2 = _EmptyComponent} = _components;
// ...
}
`

Without recma-mdx-escape-missing-components, you’d not get any Empty Component definition and default value for the components:

`js
// ...
function _createMdxContent(props) {
// ...
const {Component1, Component2} = _components;
// ...
}
`

Basically, recma-mdx-escape-missing-components;

🟩 inserts an Empty Component definition into the code above the function _createMdxContent(props){}

const _EmptyComponent = () => null;

🟩 looks for a declaration statement in an object pattern initiated by the _components

const {Component1, Component2} = _components;

🟩 converts it as the destructed components have a default value _EmptyComponent

const {Component1 = _EmptyComponent, Component2 = _EmptyComponent} = _components;

Options

`typescript
type TestFunction = (componentName: string) => boolean | undefined | null;

function recmaMdxEscapeMissingComponents(test?: string | string[] | TestFunction)
`

#### test
+ if "undefined", all components pass the check.
+ if "string", check the component name matches with the string.
+ if "string[]", check the component name is included in the string array.
+ if "TestFunction", check the test function returns true.
+ if check is true/pass, set the default value () => null for that component.

Examples:

`markdown


Hi

Wellcome


`

#### Without the test option

`javascript
use(recmaMdxEscapeMissingComponents);
`

is going to produce the compiled source has the statement for all components have the default value:

const {Component1 = _EmptyComponent, Component2 = _EmptyComponent} = _components;

#### With the test option (string)

`javascript
use(recmaMdxEscapeMissingComponents, "Component1");
`

is going to produce the compiled source has the statement for only the Component1 has the default value:

const {Component1 = _EmptyComponent, Component2} = _components;

#### With the test option (string array)

`javascript
use(recmaMdxEscapeMissingComponents, ["Component1"]);
`
is going to produce the compiled source has the statement for only the Component1 has the default value:

const {Component1 = _EmptyComponent, Component2} = _components;

#### With the test option (function)

`javascript
use(recmaMdxEscapeMissingComponents, ((name) => name.endsWith("2")) as TestFunction);
`
is going to produce the compiled source has the statement for only the Component2 has the default value:

const {Component1, Component2 = _EmptyComponent} = _components;

Syntax tree

This plugin only modifies the ESAST (Ecma Script Abstract Syntax Tree) as explained.

Types

This package is fully typed with [TypeScript][url-typescript]. Test function in the option is exported as type TestFunction.

Compatibility

This plugin works with unified version 6+. It is compatible with mdx version 3+.

Security

Use of recma-mdx-escape-missing-components doesn't involve user content so there are no openings for cross-site scripting (XSS) attacks.

My Plugins

I like to contribute the Unified / Remark / MDX ecosystem, so I recommend you to have a look my plugins.

$3

- remark-flexible-code-titles
– Remark plugin to add titles or/and containers for the code blocks with customizable properties
- remark-flexible-containers
– Remark plugin to add custom containers with customizable properties in markdown
- remark-ins
– Remark plugin to add ins element in markdown
- remark-flexible-paragraphs
– Remark plugin to add custom paragraphs with customizable properties in markdown
- remark-flexible-markers
– Remark plugin to add custom mark element with customizable properties in markdown
- remark-flexible-toc
– Remark plugin to expose the table of contents via vfile.data or via an option reference
- remark-mdx-remove-esm
– Remark plugin to remove import and/or export statements (mdxjsEsm)

$3

- rehype-pre-language
– Rehype plugin to add language information as a property to pre element
- rehype-highlight-code-lines
– Rehype plugin to add line numbers to code blocks and allow highlighting of desired code lines
- rehype-code-meta
– Rehype plugin to copy code.data.meta to code.properties.metastring
- rehype-image-toolkit
– Rehype plugin to enhance Markdown image syntax ![]() and Markdown/MDX media elements (,