Documentation flaw?

[agutenkunst]

Hi! I am pretty new to node and wanted to play around with rehype so wanted to play with the example from the readme: https://github.com/rehypejs/rehype-document#use

I immediatly got:

import {readSync} from 'to-vfile'
^^^^^^

SyntaxError: Cannot use import statement outside a module
    at Object.compileFunction (node:vm:352:18)

I have node version v16.7.0.

Pretty sure that this only relevant for node beginners like me but I think it would be nice to have an example that is working right out of the box.

I got it to work by naming the example example.mjs since the enables some mysterious ;-) ESM support. In addition obviously(!) the dependencies had the be installed (into the nearest node_modules folder).

Since I know that grasping the beginner difficulties is hard if you are deep into the topic I hope this input is useful for you.

greetings!

[ChristianMurphy]

Hey @agutenkunst! 👋
Sorry you ran into a spot of trouble.
The section above the example tries to give guidance here:

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

The linked document (https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) introduces ESM and how to use it with a number of different tools.

Using the .mjs extension is one option.
Another, is adding "type": "module", to package.json, which enables ESM for .js files in Node.

[agutenkunst]

Hi @ChristianMurphy thanks for the answer!

I think the package.json option is only relevant if you working on a node package not if you just started playing around and run plain node.js scripts using node example.js. But I guess it boils down to the level of knowledge you expect a reader of this doc to have. If you can expect them to know the implications of ESM only everything is fine.