When does the order of .use() invocations matter?

[NickSto]

I've read as much documentation as I can find and I'm still confused about how unified().use() actually works.

To be clear, I'm talking about this pattern:

const remarkParse = require('remark-parse');
const remarkFrontmatter = require('remark-frontmatter');
const remarkStringify = require('remark-stringify');

const processor = unified()
  .use(remarkParse)
  .use(remarkFrontmatter)
  .use(remarkStringify);

I've run into situations where it does matter which plugin comes first in the .use() chain. But then sometimes it doesn't?

I tried investigating how it works by writing my own plugin, spy.js:

module.exports = function(options) {
  function transformer(tree, file) {
    console.log(tree.children[0]);
  }
  return transformer
}

Then I inserted it into the chain:

const process = require('process');
const unified = require('unified');
const unifiedStream = require('unified-stream');
const remarkParse = require('remark-parse');
const remarkFrontmatter = require('remark-frontmatter');
const remarkStringify = require('remark-stringify');
const spy = require('./spy.js');

const processor = unified()
  .use(remarkParse)
  .use(remarkFrontmatter)
  .use(spy)
  .use(remarkStringify);

process.stdin.pipe(unifiedStream(processor)).pipe(process.stdout);

And ran it on this input:

---
title: It's a Title!
---
Some *Markdown*.

And my spy received a tree with this as the first node, as expected:

{
  type: 'yaml',
  value: "title: It's a Title!",
  position: {
    start: { line: 1, column: 1, offset: 0 },
    end: { line: 3, column: 4, offset: 28 }
  }
}

But then I moved .use(spy) to before .use(remarkFrontmatter) and saw the same thing! So that makes it seem like the order doesn't matter.

But sometimes order does seem to matter. If I replace remark-frontmatter with remark-rehype (and remark-stringify with rehype-stringify), then if my spy is before remark-rehype, it receives an mdast tree, and if it's after, it receives a hast tree.

So how does this work? When does order matter, and how does it decide which plugin gets applied when?

[wooorm]

heya!

The order does matter. Basically always.
But: there are three slots where things go into.

To start things off: “attachers” run: the functions that materialize as plugins, in order they were attached (or “.used”).

Some plugins add syntax extensions: remark-frontmatter adds a tiny thing so that micromark knows how to handle YAML.
And it adds something so that YAML can be compiled as well.

Most plugins returns a transformer.

So everything is attached and syntax extensions are defined.
Then all the transformers run and change the tree.

And finally, that tree is turned into markdown again.

Sooo: Assume order does matter, but understand that there are “slots” for parsing, transforming, and compiling!

[NickSto]

Ah okay, I was wondering if it was something like that. So there's basically 3 stacks: parsers, transformers, and compilers, and each .use() invocation adds things to the top of one or more stacks? Then the parsers are run in order (bottom to top in my analogy), then transformers, then compilers?

So my spy plugin receives the same thing no matter where it's placed because remark-frontmatter defines a parser, which always runs before transformers (which is what my spy is)?

[wooorm]

Exactly!