recma-mdx-html-override 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ipikuka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# recma-mdx-html-override
+
+[![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 **that ensures selected html raw elements overridable via MDXComponents in MDX**.
+
+**[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 Ecma Script Abstract Syntax Tree (AST) that is used in production of compiled source for the **[MDX][MDX]**.
+
+## When should I use this?
+
+**Use this plugin to be able to override selected html raw elements via MDXComponents**.
+
+You can find the keys (JSX identifiers, `wrapper` and html tags) can be passed in MDXComponents and the rules whether a key is a `Literal` or a `Reference to an Identifier` in [@mdx-js/mdx docs](https://mdxjs.com/docs/using-mdx/#components).
+
+**`recma-mdx-html-override`** focuses the `Literal` ones (the names that start with a lowercase or is not a valid JS identifier) to make them overridable via MDXComponents.
+
+Basically, **`recma-mdx-html-override`** changes the `Literal` parameters into **`_components.[literal]`** in the `jsx`/`jsxs` call expressions making approppriate changes in the compiled source; and ensures them overridable via mdx components.
+
+## Installation
+
+This package is suitable for ESM only. In Node.js (version 18+), install with npm:
+
+```bash
+npm install recma-mdx-html-override
+```
+
+or
+
+```bash
+yarn add recma-mdx-html-override
+```
+
+## Usage
+
+Say we have the following file, `example.mdx`,
+
+```mdx
+# Hi
+
+<img src="image.png" alt="picture" />
+```
+
+And our module, `example.js`, looks as follows:
+
+```javascript
+import { read } from "to-vfile";
+import { compile } from "@mdx-js/mdx";
+import recmaMdxHtmlOverride from "recma-mdx-html-override";
+
+main();
+
+async function main() {
+  const source = await read("example.mdx");
+
+  const compiledSource = await compile(source, {
+    recmaPlugins: [[recmaMdxHtmlOverride, {tags: "img"}]],
+  });
+
+  return String(compiledSource);
+}
+```
+
+Now, running `node example.js` produces the `compiled source` like below:
+
+```js
+function _createMdxContent(props) {
+  const _components = {
+    h1: "h1",
++   img: "img",
+    ...props.components
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx(_components.h1, {
+      children: "Hi"
+-   }), "\\n", _jsx("img", {
++   }), "\\n", _jsx(_components.img, {
+      src: "image.png",
+      alt: "picture"
+    })]
+  });
+}
+```
+
+And, this provides us to override **`img`** components via mdx components `{ img: () => {/* */} }`
+
+## Options
+
+There is one option, which is `undefined` by default.
+
+```typescript
+export type HtmlOverrideOptions = {
+  tags?: string | string[]; // default is undefined
+};
+```
+
+### Tags
+
+It is a **`string | string[]`** option to set the tag names of html raw elements to be made overridable in MDX.
+
+```javascript
+use(recmaMdxHtmlOverride, {tags: "video"} as HtmlOverrideOptions);
+```
+
+Now, `<video />` html elements in MDX will be overridable via mdx 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]. The plugin options is exported as `HtmlOverrideOptions`.
+
+## Compatibility
+
+This plugin works with `unified` version 6+. It is compatible with `mdx` version 3+.
+
+## Security
+
+Use of `recma-mdx-html-override` does not 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.
+
+### My Remark Plugins
+
+- [`remark-flexible-code-titles`](https://www.npmjs.com/package/remark-flexible-code-titles)
+  – Remark plugin to add titles or/and containers for the code blocks with customizable properties
+- [`remark-flexible-containers`](https://www.npmjs.com/package/remark-flexible-containers)
+  – Remark plugin to add custom containers with customizable properties in markdown
+- [`remark-ins`](https://www.npmjs.com/package/remark-ins)
+  – Remark plugin to add `ins` element in markdown
+- [`remark-flexible-paragraphs`](https://www.npmjs.com/package/remark-flexible-paragraphs)
+  – Remark plugin to add custom paragraphs with customizable properties in markdown
+- [`remark-flexible-markers`](https://www.npmjs.com/package/remark-flexible-markers)
+  – Remark plugin to add custom `mark` element with customizable properties in markdown
+- [`remark-flexible-toc`](https://www.npmjs.com/package/remark-flexible-toc)
+  – Remark plugin to expose the table of contents via `vfile.data` or via an option reference
+- [`remark-mdx-remove-esm`](https://www.npmjs.com/package/remark-mdx-remove-esm)
+  – Remark plugin to remove import and/or export statements (mdxjsEsm)
+
+### My Rehype Plugins
+
+- [`rehype-pre-language`](https://www.npmjs.com/package/rehype-pre-language)
+  – Rehype plugin to add language information as a property to `pre` element
+- [`rehype-highlight-code-lines`](https://www.npmjs.com/package/rehype-highlight-code-lines)
+  – Rehype plugin to add line numbers to code blocks and allow highlighting of desired code lines
+- [`rehype-code-meta`](https://www.npmjs.com/package/rehype-code-meta)
+  – Rehype plugin to copy `code.data.meta` to `code.properties.metastring`
+
+### My Recma Plugins
+
+- [`recma-mdx-escape-missing-components`](https://www.npmjs.com/package/recma-mdx-escape-missing-components)
+  – Recma plugin to set the default value `() => null` for the Components in MDX in case of missing or not provided so as not to throw an error
+- [`recma-mdx-change-props`](https://www.npmjs.com/package/recma-mdx-change-props)
+  – Recma plugin to change the `props` parameter into the `_props` in the `function _createMdxContent(props) {/* */}` in the compiled source in order to be able to use `{props.foo}` like expressions. It is useful for the `next-mdx-remote` or `next-mdx-remote-client` users in `nextjs` applications.
+- [`recma-mdx-change-imports`](https://www.npmjs.com/package/recma-mdx-change-imports)
+  – Recma plugin to convert import declarations for assets and media with relative links into variable declarations with string URLs, enabling direct asset URL resolution in compiled MDX.
+- [`recma-mdx-import-media`](https://www.npmjs.com/package/recma-mdx-import-media)
+  – Recma plugin to turn media relative paths into import declarations for both markdown and html syntax in MDX.
+- [`recma-mdx-import-react`](https://www.npmjs.com/package/recma-mdx-import-react)
+  – Recma plugin to ensure getting `React` instance from the arguments and to make the runtime props `{React, jsx, jsxs, jsxDev, Fragment}` is available in the dynamically imported components in the compiled source of MDX.
+- [`recma-mdx-html-override`](https://www.npmjs.com/package/recma-mdx-html-override)
+  – Recma plugin to ensure selected html raw elements overridable via mdx components in MDX.
+
+## License
+
+[MIT License](./LICENSE) © ipikuka
+
+[unified]: https://github.com/unifiedjs/unified
+[micromark]: https://github.com/micromark/micromark
+[recma]: https://mdxjs.com/docs/extending-mdx/#list-of-plugins
+[esast]: https://github.com/syntax-tree/esast
+[estree]: https://github.com/estree/estree
+[MDX]: https://mdxjs.com/
+
+[badge-npm-version]: https://img.shields.io/npm/v/recma-mdx-html-override
+[badge-npm-download]:https://img.shields.io/npm/dt/recma-mdx-html-override
+[url-npm-package]: https://www.npmjs.com/package/recma-mdx-html-override
+[url-github-package]: https://github.com/ipikuka/recma-mdx-html-override
+
+[badge-license]: https://img.shields.io/github/license/ipikuka/recma-mdx-html-override
+[url-license]: https://github.com/ipikuka/recma-mdx-html-override/blob/main/LICENSE
+
+[badge-publish-to-npm]: https://github.com/ipikuka/recma-mdx-html-override/actions/workflows/publish.yml/badge.svg
+[url-publish-github-actions]: https://github.com/ipikuka/recma-mdx-html-override/actions/workflows/publish.yml
+
+[badge-typescript]: https://img.shields.io/npm/types/recma-mdx-html-override
+[url-typescript]: https://www.typescriptlang.org/
+
+[badge-codecov]: https://codecov.io/gh/ipikuka/recma-mdx-html-override/graph/badge.svg?token=6UIKn4z8lc
+[url-codecov]: https://codecov.io/gh/ipikuka/recma-mdx-html-override
+
+[badge-type-coverage]: https://img.shields.io/badge/dynamic/json.svg?label=type-coverage&prefix=%E2%89%A5&suffix=%&query=$.typeCoverage.atLeast&uri=https%3A%2F%2Fraw.githubusercontent.com%2Fipikuka%2Frecma-mdx-html-override%2Fmaster%2Fpackage.json

package/dist/esm/index.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from "unified";
+import type { Program } from "estree";
+export type HtmlOverrideOptions = {
+    tags?: string | string[];
+};
+/**
+ *
+ * It is a recma plugin which makes selected html raw elements overridable.
+ *
+ */
+declare const plugin: Plugin<[HtmlOverrideOptions?], Program>;
+export default plugin;

package/dist/esm/index.js

@@ -0,0 +1,186 @@
+import { CONTINUE, EXIT, SKIP, visit } from "estree-util-visit";
+const DEFAULT_SETTINGS = {
+    tags: undefined,
+};
+/**
+ *
+ * It is a recma plugin which makes selected html raw elements overridable.
+ *
+ */
+const plugin = (options = {}) => {
+    const settings = Object.assign({}, DEFAULT_SETTINGS, options);
+    const componentMap = {};
+    let functionNode;
+    let functionPropsName = "props";
+    let targetVariableDeclarator;
+    function containsHyphen(name) {
+        return name.includes("-");
+    }
+    return (tree) => {
+        // console.dir(tree, { depth: 16 });
+        if (!settings.tags)
+            return;
+        // finds the function _createMdxContent(){}
+        visit(tree, (node, _, index) => {
+            if (index === undefined)
+                return;
+            if (node.type !== "FunctionDeclaration")
+                return SKIP;
+            if (node.id.name === "_createMdxContent") {
+                functionNode = node;
+                const param = node.params[0];
+                if (param.type === "Identifier") {
+                    functionPropsName = param.name;
+                }
+                return EXIT;
+            }
+            /* istanbul ignore next */
+            return CONTINUE;
+        });
+        /* istanbul ignore next */
+        if (!functionNode)
+            return;
+        // trace call expressions to change _jsx("xxx", {}) to _jsx(_components.xxx, {})
+        visit(functionNode, (node) => {
+            if (node.type !== "CallExpression")
+                return CONTINUE;
+            if ("name" in node.callee) {
+                if (node.callee.name !== "_jsx" &&
+                    node.callee.name !== "_jsxDEV" &&
+                    node.callee.name !== "_jsxs") {
+                    return;
+                }
+            }
+            // First child of a CallExpression is a Literal or Identifier to a reference
+            const firstArgument = node.arguments[0];
+            if (firstArgument.type === "Literal" &&
+                typeof firstArgument.value === "string" &&
+                ((typeof settings.tags === "string" && firstArgument.value === settings.tags) ||
+                    settings.tags.includes(firstArgument.value))) {
+                node.arguments[0] = {
+                    type: "MemberExpression",
+                    object: { type: "Identifier", name: "_components" },
+                    property: {
+                        type: "Identifier",
+                        name: containsHyphen(firstArgument.value)
+                            ? '"' + firstArgument.value + '"'
+                            : firstArgument.value,
+                    },
+                    computed: containsHyphen(firstArgument.value),
+                    optional: false,
+                };
+                if (!componentMap[firstArgument.value]) {
+                    componentMap[firstArgument.value] = firstArgument.value;
+                }
+            }
+            return CONTINUE;
+        });
+        // trace jsx elements to change <xxx /> to <__components.xxx />
+        visit(functionNode, (node) => {
+            if (node.type !== "JSXElement")
+                return CONTINUE;
+            // First child of a CallExpression is a Literal or Identifier to a reference
+            const openingElement = node.openingElement;
+            if (openingElement.name.type === "JSXIdentifier") {
+                const jsxIdentifier = openingElement.name;
+                if ((typeof settings.tags === "string" && jsxIdentifier.name === settings.tags) ||
+                    settings.tags.includes(jsxIdentifier.name)) {
+                    node.openingElement.name = {
+                        type: "JSXMemberExpression",
+                        object: { type: "JSXIdentifier", name: "_components" },
+                        property: {
+                            type: "JSXIdentifier",
+                            name: jsxIdentifier.name,
+                            // TODO: fix <_components["hypened-name"]></>
+                            // name: containsHyphen(jsxIdentifier.name)
+                            //   ? '"' + jsxIdentifier.name + '"'
+                            //   : jsxIdentifier.name,
+                            // computed: containsHyphen(jsxIdentifier.name) // proposal to "estree-jsx" for JSXMemberExpression
+                        },
+                    };
+                    if (!componentMap[jsxIdentifier.name]) {
+                        componentMap[jsxIdentifier.name] = jsxIdentifier.name;
+                    }
+                }
+            }
+            return CONTINUE;
+        });
+        if (!Object.keys(componentMap).length)
+            return;
+        // find "const _components = {}" variable declarator; and add the components inside, if not exist.
+        visit(functionNode, (node) => {
+            if (node.type !== "VariableDeclarator")
+                return CONTINUE;
+            if (node.id.type === "Identifier" && node.id.name === "_components") {
+                targetVariableDeclarator = node;
+                if (node.init?.type === "ObjectExpression") {
+                    const properties = node.init.properties;
+                    const existingComponentMap = {};
+                    for (const property of properties) {
+                        if (property.type === "Property") {
+                            if (property.key.type === "Identifier" &&
+                                property.value.type === "Literal" &&
+                                typeof property.value.value === "string") {
+                                existingComponentMap[property.key.name] = property.value.value;
+                            }
+                        }
+                    }
+                    const diffComponentMap = Object.entries(componentMap).filter(([key]) => !existingComponentMap[key]);
+                    if (diffComponentMap.length) {
+                        node.init.properties.splice(node.init.properties.length - 1, 0, ...diffComponentMap.map(([key, value]) => ({
+                            type: "Property",
+                            kind: "init",
+                            key: containsHyphen(key)
+                                ? { type: "Literal", value: key }
+                                : { type: "Identifier", name: key },
+                            value: { type: "Literal", value },
+                            method: false,
+                            shorthand: false,
+                            computed: false,
+                        })));
+                    }
+                }
+            }
+            return CONTINUE;
+        });
+        if (targetVariableDeclarator)
+            return;
+        // There is no "_components" declarator; so we will add VariableDeclaration ourself
+        functionNode.body.body.unshift({
+            type: "VariableDeclaration",
+            kind: "const",
+            declarations: [
+                {
+                    type: "VariableDeclarator",
+                    id: { type: "Identifier", name: "_components" },
+                    init: {
+                        type: "ObjectExpression",
+                        properties: [
+                            ...Object.entries(componentMap).map(([key, value]) => ({
+                                type: "Property",
+                                kind: "init",
+                                key: { type: "Identifier", name: key },
+                                value: { type: "Literal", value },
+                                method: false,
+                                shorthand: false,
+                                computed: false,
+                            })),
+                            {
+                                type: "SpreadElement",
+                                argument: {
+                                    type: "MemberExpression",
+                                    object: { type: "Identifier", name: functionPropsName },
+                                    property: { type: "Identifier", name: "components" },
+                                    computed: false,
+                                    optional: false,
+                                },
+                            },
+                        ],
+                    },
+                },
+            ],
+        });
+    };
+};
+export default plugin;
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../../src/index.ts"],"version":"5.8.2"}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "recma-mdx-html-override",
+  "version": "1.0.0",
+  "description": "Recma plugin to ensure selected html raw elements overridable via mdx components in MDX.",
+  "type": "module",
+  "exports": "./dist/esm/index.js",
+  "main": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "scripts": {
+    "build": "rimraf dist && tsc --build && type-coverage",
+    "format": "npm run prettier && npm run lint",
+    "prettier": "prettier --write .",
+    "lint": "eslint .",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --config ./jest.config.cjs --coverage",
+    "test:file": "NODE_OPTIONS=--experimental-vm-modules jest --config ./jest.config.cjs test1.jsx.spec.ts",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test && npm run format"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ipikuka/recma-mdx-html-override.git"
+  },
+  "keywords": [
+    "unified",
+    "estree",
+    "esast",
+    "mdx",
+    "mdxjs",
+    "plugin",
+    "recma",
+    "recma plugin",
+    "recma mdx",
+    "html override",
+    "html raw",
+    "recma mdx html override"
+  ],
+  "author": "ipikuka <talatkuyuk@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/ipikuka/recma-mdx-html-override#readme",
+  "bugs": {
+    "url": "https://github.com/ipikuka/recma-mdx-html-override/issues"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.20.0",
+    "@mdx-js/mdx": "^3.1.0",
+    "@types/dedent": "^0.7.2",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.13.9",
+    "dedent": "^1.5.3",
+    "eslint": "^9.21.0",
+    "eslint-config-prettier": "^10.0.2",
+    "eslint-plugin-jest": "^28.11.0",
+    "eslint-plugin-prettier": "^5.2.3",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.3",
+    "prettier-2": "npm:prettier@^2.8.8",
+    "rimraf": "^5.0.10",
+    "ts-jest": "^29.2.6",
+    "type-coverage": "^2.29.7",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.26.0",
+    "unified": "^11.0.5"
+  },
+  "dependencies": {
+    "@types/estree": "^1.0.6",
+    "@types/estree-jsx": "^1.0.5",
+    "estree-util-visit": "^2.0.0"
+  },
+  "peerDependencies": {
+    "unified": "^11"
+  },
+  "sideEffects": false,
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "ignoreAsAssertion": true,
+    "strict": true
+  }
+}

package/src/index.ts

@@ -0,0 +1,243 @@
+import type { Plugin } from "unified";
+import type { FunctionDeclaration, Node, Program, Property, VariableDeclarator } from "estree";
+import type { JSXIdentifier, JSXOpeningElement } from "estree-jsx";
+import { CONTINUE, EXIT, SKIP, visit } from "estree-util-visit";
+
+export type HtmlOverrideOptions = {
+  tags?: string | string[];
+};
+
+const DEFAULT_SETTINGS: HtmlOverrideOptions = {
+  tags: undefined,
+};
+
+/**
+ *
+ * It is a recma plugin which makes selected html raw elements overridable.
+ *
+ */
+const plugin: Plugin<[HtmlOverrideOptions?], Program> = (options = {}) => {
+  const settings = Object.assign(
+    {},
+    DEFAULT_SETTINGS,
+    options,
+  ) as Required<HtmlOverrideOptions>;
+
+  const componentMap: Record<string, string> = {};
+  let functionNode: FunctionDeclaration | undefined;
+  let functionPropsName: string = "props";
+  let targetVariableDeclarator: VariableDeclarator;
+
+  function containsHyphen(name: string): boolean {
+    return name.includes("-");
+  }
+
+  return (tree: Node) => {
+    // console.dir(tree, { depth: 16 });
+    if (!settings.tags) return;
+
+    // finds the function _createMdxContent(){}
+    visit(tree, (node, _, index) => {
+      if (index === undefined) return;
+
+      if (node.type !== "FunctionDeclaration") return SKIP;
+
+      if (node.id.name === "_createMdxContent") {
+        functionNode = node;
+
+        const param = node.params[0];
+        if (param.type === "Identifier") {
+          functionPropsName = param.name;
+        }
+
+        return EXIT;
+      }
+
+      /* istanbul ignore next */
+      return CONTINUE;
+    });
+
+    /* istanbul ignore next */
+    if (!functionNode) return;
+
+    // trace call expressions to change _jsx("xxx", {}) to _jsx(_components.xxx, {})
+    visit(functionNode, (node) => {
+      if (node.type !== "CallExpression") return CONTINUE;
+
+      if ("name" in node.callee) {
+        if (
+          node.callee.name !== "_jsx" &&
+          node.callee.name !== "_jsxDEV" &&
+          node.callee.name !== "_jsxs"
+        ) {
+          return;
+        }
+      }
+
+      // First child of a CallExpression is a Literal or Identifier to a reference
+      const firstArgument = node.arguments[0];
+
+      if (
+        firstArgument.type === "Literal" &&
+        typeof firstArgument.value === "string" &&
+        ((typeof settings.tags === "string" && firstArgument.value === settings.tags) ||
+          settings.tags.includes(firstArgument.value))
+      ) {
+        node.arguments[0] = {
+          type: "MemberExpression",
+          object: { type: "Identifier", name: "_components" },
+          property: {
+            type: "Identifier",
+            name: containsHyphen(firstArgument.value)
+              ? '"' + firstArgument.value + '"'
+              : firstArgument.value,
+          },
+          computed: containsHyphen(firstArgument.value),
+          optional: false,
+        };
+
+        if (!componentMap[firstArgument.value]) {
+          componentMap[firstArgument.value] = firstArgument.value;
+        }
+      }
+
+      return CONTINUE;
+    });
+
+    // trace jsx elements to change <xxx /> to <__components.xxx />
+    visit(functionNode, (node) => {
+      if (node.type !== "JSXElement") return CONTINUE;
+
+      // First child of a CallExpression is a Literal or Identifier to a reference
+      const openingElement: JSXOpeningElement = node.openingElement;
+
+      if (openingElement.name.type === "JSXIdentifier") {
+        const jsxIdentifier: JSXIdentifier = openingElement.name;
+
+        if (
+          (typeof settings.tags === "string" && jsxIdentifier.name === settings.tags) ||
+          settings.tags.includes(jsxIdentifier.name)
+        ) {
+          node.openingElement.name = {
+            type: "JSXMemberExpression",
+            object: { type: "JSXIdentifier", name: "_components" },
+            property: {
+              type: "JSXIdentifier",
+              name: jsxIdentifier.name,
+              // TODO: fix <_components["hypened-name"]></>
+              // name: containsHyphen(jsxIdentifier.name)
+              //   ? '"' + jsxIdentifier.name + '"'
+              //   : jsxIdentifier.name,
+              // computed: containsHyphen(jsxIdentifier.name) // proposal to "estree-jsx" for JSXMemberExpression
+            },
+          };
+
+          if (!componentMap[jsxIdentifier.name]) {
+            componentMap[jsxIdentifier.name] = jsxIdentifier.name;
+          }
+        }
+      }
+
+      return CONTINUE;
+    });
+
+    if (!Object.keys(componentMap).length) return;
+
+    // find "const _components = {}" variable declarator; and add the components inside, if not exist.
+    visit(functionNode, (node) => {
+      if (node.type !== "VariableDeclarator") return CONTINUE;
+
+      if (node.id.type === "Identifier" && node.id.name === "_components") {
+        targetVariableDeclarator = node;
+
+        if (node.init?.type === "ObjectExpression") {
+          const properties = node.init.properties;
+
+          const existingComponentMap: Record<string, string> = {};
+
+          for (const property of properties) {
+            if (property.type === "Property") {
+              if (
+                property.key.type === "Identifier" &&
+                property.value.type === "Literal" &&
+                typeof property.value.value === "string"
+              ) {
+                existingComponentMap[property.key.name] = property.value.value;
+              }
+            }
+          }
+
+          const diffComponentMap = Object.entries(componentMap).filter(
+            ([key]) => !existingComponentMap[key],
+          );
+
+          if (diffComponentMap.length) {
+            node.init.properties.splice(
+              node.init.properties.length - 1,
+              0,
+              ...diffComponentMap.map(
+                ([key, value]) =>
+                  ({
+                    type: "Property",
+                    kind: "init",
+                    key: containsHyphen(key)
+                      ? { type: "Literal", value: key }
+                      : { type: "Identifier", name: key },
+                    value: { type: "Literal", value },
+                    method: false,
+                    shorthand: false,
+                    computed: false,
+                  }) as Property,
+              ),
+            );
+          }
+        }
+      }
+
+      return CONTINUE;
+    });
+
+    if (targetVariableDeclarator) return;
+
+    // There is no "_components" declarator; so we will add VariableDeclaration ourself
+    functionNode.body.body.unshift({
+      type: "VariableDeclaration",
+      kind: "const",
+      declarations: [
+        {
+          type: "VariableDeclarator",
+          id: { type: "Identifier", name: "_components" },
+          init: {
+            type: "ObjectExpression",
+            properties: [
+              ...Object.entries(componentMap).map(
+                ([key, value]) =>
+                  ({
+                    type: "Property",
+                    kind: "init",
+                    key: { type: "Identifier", name: key },
+                    value: { type: "Literal", value },
+                    method: false,
+                    shorthand: false,
+                    computed: false,
+                  }) as Property,
+              ),
+              {
+                type: "SpreadElement",
+                argument: {
+                  type: "MemberExpression",
+                  object: { type: "Identifier", name: functionPropsName },
+                  property: { type: "Identifier", name: "components" },
+                  computed: false,
+                  optional: false,
+                },
+              },
+            ],
+          },
+        },
+      ],
+    });
+  };
+};
+
+export default plugin;