How to inject a tree into another tree without getting hydration errors?

[hahnbeelee]

I'm altering my mdast tree by injecting another tree into it. It's pretty simple and straight forward code. Here is how it looks like:

import type { Root } from 'mdast';
import visit from 'unist-util-visit';

const withReplaceSnippets = (snippetTreeMap: Record<string, Root>) => {
  return (tree: Root) => {
    visit(tree, ['mdxJsxFlowElement', (node: any) => node.name === 'Snippet'], (node: any) => {
      if (!node?.attributes) return;
      const fileValue = node.attributes.find((attr: any) => attr.name === 'file')?.value;
      if (!fileValue) return;
>      const desiredSnippetTree = snippetTreeMap[fileValue];
>      node.name = undefined;
>      node.type = desiredSnippetTree.type;
>      node.children = desiredSnippetTree.children;
    });
  };
};

The desiredSnippetTree is another tree I've created utilizing the following code:

const tree = fromMarkdown(snippets[property], {
    extensions: [mdxjs()],
    mdastExtensions: [mdxFromMarkdown()],
});

I realized that this is causing react hydration issues

Does the mdx team have tips for injecting trees? My sneaking suspicion is that it's the position property that is causing the hydration issue although I am not sure.

[wooorm]

First, you’re using TypeScript but casting everything as any? That removes all the benefits from TypeScript. Refactored as pseudo code (btw, important: also see https://mdxjs.com/packages/remark-mdx/#types).

import type { Root } from 'mdast'
import visit from 'unist-util-visit'

const withReplaceSnippets = (snippetTreeMap: Record<string, Root>) => {
  return (tree: Root) => {
    visit(tree, (node) => {
      if (node.type === 'mdxJsxFlowElement' && node.name === 'Snippet') {
          const file = node.attributes.find((attr) => attr.name === 'file')
          if (file && typeof file.value === 'string') {
            const desiredSnippetTree = snippetTreeMap[file.value]
            node.name = undefined
            node.type = desiredSnippetTree.type
            node.children = desiredSnippetTree.children
          }
      }
    })
  }
}

Second, you’re replacing the node wrongly: a) root nodes are not allowed in other nodes, b) mutating nodes by settings some fields to undefined and renaming some fields is a bad idea.
For some more info, see:

• https://unifiedjs.com/learn/recipe/tree-traversal/
• https://unifiedjs.com/learn/recipe/find-node/
• https://unifiedjs.com/learn/recipe/remove-node/#replacing-a-node-with-its-children
• https://unifiedjs.com/learn/recipe/tree-traversal-typescript/

Taking that code, and using the return values as documented in unist-util-visit/unist-util-visit-parents:

import {visit, SKIP} from 'unist-util-visit'

    visit(tree, (node, index, parent) => {
      if (parent && index !== null && node.type === 'mdxJsxFlowElement' && node.name === 'Snippet') {
          const file = node.attributes.find((attr) => attr.name === 'file')
          if (file && typeof file.value === 'string') {
            const desiredSnippetTree = snippetTreeMap[file.value]
            parent.children.splice(index, 1, ...desiredSnippetTree.children)
            return [SKIP, index]
          }
      }
    })

We still have some problems:
a) you should not inject the same nodes into different places of the tree, that’s happening above
b) you’re not handling missing snippets, you should warn about that
c) this looks a lot like a plugin, you should use a name that suits that type
d) this might not be a problem, but it is indeed good to remove positional info on nodes from other documents: you could do that in this plugin (shown below) but you could also do that when making snippetTreeMap

import type {Root} from 'mdast'
import {visit, SKIP} from 'unist-util-visit'
import {removePosition} from 'unist-util-remove-position'

const remarkMdxInjectSnippets: Plugin<[Record<string, Root>], Root> = (snippetTreeMap) => {
  return (tree, file) => {
    visit(tree, (node, index, parent) => {
      if (parent && index !== null && node.type === 'mdxJsxFlowElement' && node.name === 'Snippet') {
          const file = node.attributes.find((attr) => attr.name === 'file')
          const name = file?.value
          if (typeof name === 'string') {
            if (Object.hasOwn(snippetTreeMap, name)) {
                const fragment = removePosition(structuredClone(snippetTreeMap[name]))
                parent.children.splice(index, 1, ...fragment.children)
                return [SKIP, index]
            } else {
                file.message(
                  'Cannot expand missing snippet `' + name + '`', node, 'remark-mdx-inject-snippets'
                )
            }
          }
      }
    })
  }
}

[hahnbeelee]

Thank you for calling me out for the any type 😭 I need to be better about not doing that.

I've built a decent amount of plugins and have gotten around doing it without knowing al the best practices, but it's clear if I want to continue to progress and do more complex things with asts I need to get my fundamentals down. I really appreciate your thorough explanation and I'll read up more on the unified documentation - I've solely been looking at mdx documentation/utility packages.

[wooorm]

Thanks and don’t worry about it! Syntax trees are a tough concept to grasp and work with, and in this case MDX also does so many things, you’re lacking experience working with these things and tools, and you’ll get that experience by working more with it all :)

[hahnbeelee]

@wooorm Any reason why you used structuredClone()? I'm having issues with it in production. Reference this PR description

[wooorm]

Oh, struxturedClone is the future, but it doesn't work everywhere yet. JSON.parse(JSON.stringify(x)) should do the trick otherwise

[wooorm]

Similar with Object.hasOwn btw!