Conditional content / MDX content inside JSX?

[egnor]

Root problem: I want to write MDX content which has occasional conditional branches, like (pseudocode)

~~ if props.foo ~~
## Foo is true!
So you can rely on foo.
~~ else ~~
## There's no foo here!
So don't even think about using it.
~~ endif ~~

Anyhoo, let's talk about some other non foo related stuff

Logically, I'd want something like this

{props.foo ? <>
  ## Foo is true!
  So you can rely on foo.
</> : <>
  ## Foo is false!
  So don't even think about using it.
</>}

...but that doesn't work of course, you get "## Foo is true! So you can rely on foo." without MDX interpretation.

Now, I do know various ways to do this with MDX/JSX, like (untested)

{props.foo
  ? <><h2>Foo is true!</h2> <p>So you can rely on foo.</p></>
  : <><h2>There's no foo here!</h2> <p>So don't even think about using it.</p></>}

But now within the conditional block we no longer have the benefit of MDX which is super sad. A different alternative is to make several MDX components, like

foo_true.mdx:

## Foo is true!
So you can rely on foo.

foo_false.mdx:

## There's no foo here!
So don't even think about using it.

page.mdx:

import FooTrue from "./foo_true.mdx";
import FooFalse from "./foo_false.mdx";

{props.foo ? <FooTrue/> : <FooFalse/>}

...but that leads to a proliferation of little files. Or, I could do this:

export function Maybe({ when, children }) {
  return when ? <>{children}</> : <></>; 
}

<Maybe when={props.foo}>
  ## Foo is true!
  So you can rely on foo.
</Maybe>

<Maybe when={!props.foo}>
  ## There's no foo here!
  So don't even think about using it.
</Maybe>

But that seems like I'm re-inventing an if-statement which must be wrong?? Also it's not great because both branches are processed regardless of the condition, which can lead to errors. And this seems like a very basic thing one might want to do in content, so I imagine I'm just missing some idiom here??

Other references

• This seems relevant, but lonnnng and I'm not sure where the dust settled? RFC: Interleaving Markdown in JSX #628
• Almost exactly my question, but is unanswered (except for a suggestion to do the many-component-files thing)
• A similar question, mentions MDX template literals? But I don't think those exist?

[wooorm]

Hi!

Right, so these are your options: a) write as JSX, b) move things to a component, c) some sort of <if>.

That seems like enough options to me.
The problem with a) you describe, namely loosing markdown, is solved by b)
The problem with b) you describe, namely little files, is solved by a) — if they are so little, you can write a couple tags

For c):

both branches are processed regardless of the condition

Everything is “processed”. Not entirely sure what you mean by that word. This approach c) is the only one that would be a good fit for not processing: if there are static conditions, then you can write a plugin to drop the non-matching branch.

---

Anyway, yeah, https://github.com/orgs/mdx-js/discussions/2276 holds up

[egnor]

Is there a standard plugin that implements <If> and similar utilities, avoiding the issue below? Not even sure exactly which type of plugin would be best for that? (An alternative would be an @if like pseudo-property on elements rather than a wrapper element.)

everything is "processed"

Sorry I was imprecise, I meant something closer to "evaluated" I think. What I mean is that if I do something like this...

export function If({ when, children }) {
  return when ? <> {children} </> : <> </>;
}

<If when={foo}>
  # Hi! Foo is defined
  Its bar is {foo.bar}
</If>

...then if foo is null or undefined this results in an error at whatever point the outer component is instantiated, because the children are still fully instantiated and all substitutions evaluated for passing to the <If> component even though it's going to ignore them, and thus foo.bar is evaluated which is an error. The similar JSX code does not have this problem:

{foo ? <> <h1> Hi! Foo is defined </h1> <p> Its bar is {foo.bar} </p> </> : <> </> }

One can write code to dodge this but it's clunky, and "if thing is available, use thing, otherwise don't" is an extraordinarily common pattern.

Anyway @wooorm I politely disagree that the first two solutions (break out components, or use JSX) are acceptable for all use cases -- there are places where one really wants to preserve the flow of content while adding a conditional, but dropping to JSX is jarring and obnoxious -- but that's obviously subjective. Plugins are the usual answer for "I think this is important but you don't" so that's why I'm exploring this route...

[remcohaszing]

Just adding my 2 cents: I strongly recommend one of @wooorm’s original suggestions. Either three of them could be great depending on the situation. Personally I especially like the <If condition={…}> component. You don’t need to compile this away. I think the React compiler can optimize this for you.

If such a plugin was made, I do see @egnor’s point this isn’t ideal to do in a rehype plugin, nor in a recma plugin that runs after compiling the JSX. For transforming JSX in a plugin, it’s simplest to deal with only one type of ESTree node. Given that a user may specify jsx: true, those would be JSX expressions, not jsx() / jsxs() / _jsx(), customPragma() function calls.

[egnor]

It's not worth arguing much, use cases are always subjective, and I do have a workaround which is to set jsx: true and postprocess the output of the MDX pipeline, so we can consider this closed.

---

For posterity, this is where I'm coming from:

I want to have certain somewhat ad-hoc conditionals and basic loops in the flow of friendly content (Markdown) based on various data inputs. This may be weird but I don't think it's that weird, most "template" languages offer something like this. In particular, in my world it's very common to say "if this optional sub-block of input data exists, we want to include sub-blocks of content in various places, which reference it", which makes a simple <If> component a little awkward. You consider that awkwardness no big deal, but I feel like it adds a non-obvious gotcha when someone is casually editing the content. Reasonable people can disagree, and you're the project owners so it's totally your call.

So I figured I'd try to go write a plugin so I can meet my weird needs without bothering you (that's why plugins exist!) and I ran into the stuff above. Again, you consider the awkwardness of asymmetry between the markdown world and the curly-brace world to be no big deal, and again for me it's another non-obvious gotcha for casual content editors, and again reasonable people can disagree, and again you're the project owners so it's totally your call.

Mentally I think about MDX as "compile MDX to JSX, then compile JSX to JS" so it seemed very logical to want to do operations on that "intermediate" JSX, but that's clearly not how you think about the pipeline. But hey at least you have a flag to emit that JSX without compiling it down, so that's what I use, and rollup is perfectly capable of compiling JSX to JS.

Philosophically, the strength and also the weirdness of MDX (and JSX which it builds on) is that it blurs and mixes the conventional layering of "human-edited content in a CMS, data in a database, logic in code, templates to generate UI" into a more flexible world where human-edited prose, data, logic, and UI presentation can intermix and interweave while still providing friendly building blocks (components). It's a less opinionated system, allowing more flexible structures, which works well for my particular needs, but also means that different people can end up thinking about how it "should" be used very differently.

[wooorm]

I spent some time making the plugin I envisioned. Here it is. With the MDX that @egnor previously provided:

/**
 * @import {JSXAttribute} from 'estree-jsx'
 * @import {ConditionalExpression} from 'estree'
 * @import {Root} from 'hast'
 * @import {MdxJsxAttribute} from 'mdast-util-mdx-jsx'
 */

import assert from 'node:assert/strict'
import {compile} from '@mdx-js/mdx'
import {walk} from 'estree-walker'
import {toEstree} from 'hast-util-to-estree'
import {visit} from 'unist-util-visit'

const document = `inline text {1} <$if test={x < 1}>inline text {2}</$if>

<$if test={x > 1}>
  # nested markdown
  <div>nested JSX-HTML</div>
  <Component>nested component</Component>
  {foo(<span>arg 1</span>, <$if test={x > 2}>arg 2</$if>)}
</$if>`

const result = String(
  await compile(document, {
    rehypePlugins: [
      function () {
        /**
         * @param {Root} tree
         * @returns {undefined}
         */
        return function (tree) {
          visit(tree, function (node, index, parent) {
            if (!parent || typeof index !== 'number') return
            if (
              (node.type === 'mdxJsxFlowElement' ||
                node.type === 'mdxJsxTextElement') &&
              node.name === '$if'
            ) {
              const attribute = /** @type {MdxJsxAttribute | undefined} */ (
                node.attributes.find(function (d) {
                  return d.type === 'mdxJsxAttribute' && d.name === 'test'
                })
              )
              assert(attribute)
              assert(attribute.value)
              assert(typeof attribute.value === 'object')
              assert(attribute.value.type === 'mdxJsxAttributeValueExpression')
              const statement = attribute.value.data?.estree?.body.at(-1)
              assert(statement)
              assert(statement.type === 'ExpressionStatement')
              const test = statement.expression

              const result = toEstree({type: 'root', children: node.children})
              const child = result.body.at(-1)
              assert(child)
              assert(child.type === 'ExpressionStatement')
              const consequent = child.expression
              assert(consequent.type === 'JSXFragment')

              parent.children[index] = {
                type: 'mdxFlowExpression',
                value: '',
                data: {
                  estree: {
                    type: 'Program',
                    body: [
                      {
                        type: 'ExpressionStatement',
                        expression: {
                          type: 'ConditionalExpression',
                          test,
                          consequent,
                          alternate: {type: 'Identifier', name: 'undefined'}
                        }
                      }
                    ],
                    sourceType: 'module'
                  }
                }
              }

              return
            }

            if (
              (node.type === 'mdxFlowExpression' ||
                node.type === 'mdxTextExpression' ||
                node.type === 'mdxjsEsm') &&
              node.data &&
              node.data.estree
            ) {
              walk(node.data.estree, {
                enter(node) {
                  if (
                    node.type === 'JSXElement' &&
                    node.openingElement.name.type === 'JSXIdentifier' &&
                    node.openingElement.name.name === '$if'
                  ) {
                    const attribute = /** @type {JSXAttribute | undefined} */ (
                      node.openingElement.attributes.find(function (d) {
                        return (
                          d.type === 'JSXAttribute' &&
                          d.name.type === 'JSXIdentifier' &&
                          d.name.name === 'test'
                        )
                      })
                    )
                    assert(attribute)
                    assert(attribute.value)
                    assert(typeof attribute.value === 'object')
                    assert(attribute.value.type === 'JSXExpressionContainer')
                    const test = attribute.value.expression
                    assert(test.type !== 'JSXEmptyExpression')

                    /** @type {ConditionalExpression} */
                    const replacement = {
                      type: 'ConditionalExpression',
                      test,
                      consequent: {
                        type: 'JSXFragment',
                        openingFragment: {type: 'JSXOpeningFragment'},
                        children: node.children,
                        closingFragment: {type: 'JSXClosingFragment'}
                      },
                      alternate: {type: 'Identifier', name: 'undefined'}
                    }

                    this.replace(replacement)
                  }
                }
              })
            }
          })
        }
      }
    ]
  })
)

console.log(result)

There are some assertions. Some of them are 100% certain that they never happen, some of them could happen if the author made mistakes. A plugin for users would need to be expanded to provide nice error messages.

While not ideal, 2 different algos doing the same, I think it is small enough to be a viable solution.

---

So I figured I'd try to go write a plugin so I can meet my weird needs without bothering you (that's why plugins exist!) and I ran into the stuff above.

This is indeed correct. Plugins are great. Super useful skills.
But I do not think AST transforms will ever be very easy; I think they will always require knowledge of internals. There will be non-obvious gotchas. It’s not “casual”.

it seemed very logical to want to do operations on that "intermediate" JSX

There is a divide between the “markdown” syntax (*this*) and the JSX syntax (<em>this</em>). Most plugins deal with the markdown stuff—adding syntax extensions, changing it—not on JSX.

[egnor]

Fascinating. A few questions, if you don't mind

• you said the assertions aren't great practice. in general to what degree should a plugin deal with ill-formed trees?
• technically where you insert an mdxFlowExpression, replacing an mdxJsx(Flow/Text)Element it should be an mdxTextExpression if replacing an mdxJsxTextElement?
• I wasn't sure if there were corner cases or options to be worried about with hast-util-to-estree

[wooorm]

you said the assertions aren't great practice

I do think assertions are good. But they are good for things that, as a programmer, you know never happen. Not for problems with how user write markup. file.message is the API for that.
Some of the assertions are here because you may be the only person using this; if this gets more users, or you want to publish it, things should be handled better.

to what degree should a plugin deal with ill-formed trees?

Ill-formed is a vague word. Generally, the thing that needs solving, would be the thing that produces ill-formed trees. But it’s nice when plugins don’t crash. Some grace is nice.

it should be an

Sure! I‘d say could; you can do that; in rehype/hast/html it doesn’t really matter.

I wasn't sure if there were corner cases or options to be worried about with hast-util-to-estree

I can’t think of corner cases; The elementAttributeNameCase and stylePropertyNameCase may be of interest, depending on what framework you (or your users) use

[egnor]

Ok, to deal with the various issues (lack of plugin points, mainly) described above, I ended up having MDX emit JS with JSX tags still in it, and having my bundler (rollup) do the JSX-to-JS conversion. That way I can write the <$if> (and <$for>) conversion more or less "cleanly", though it would have been nicer to run inside recma and get the benefit of an existing parse tree.

I ended up writing this to do the translation: https://github.com/egnor/rollup-plugin-jsx-if-for