Added "exports"-field to package.json so import/require loads the appropriate file without any additional user-input

[KilianKilmister]

Marked version: @latest

Markdown flavor: n/a

Description

• adresssing documentation to show ESM import and usage #1692
• added "export"-filed to package.json
• adjusted rollup.config.esm.js to output .mjs
• built and committed lib/marked.esm.mjs

I did a superficial test to ensure the paths are correct.
VSCode debugger showed that import marked from 'marked' will only load lib/marked.esm.mjs

citing my comment

cjs-require/esm-import can be automatically handled by specifying an "exports" field in the package.json.
This way node will load the appropriate files without the user having to worry about in-module paths.

Short explanation

{
  "exports": {
    [exportPath]: {
      "import": "./path/to/file.mjs",
      "require": "./path/to/file.cjs"
    }
  }
}

So for marked it would be:

{
  "exports": {
    ".": {
      "import": "./lib/marked.esm.mjs", // `.mjs`-extention is needed
      "require": "./src/marked.js"
    }
  }
}

I'll file a PR for that shortly

Contributor

• Test(s) exist to ensure functionality and minimize regression (if no tests added, list tests covering this PR); or,
• no tests required for this PR.
• If submitting new feature, it has been documented in the appropriate places.

Committer

In most cases, this should be a different person than the contributor.

• Draft GitHub release notes have been updated.
• CI is green (no forced merge required).
• Merge PR

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/markedjs/markedjs/j688ptxsg
✅ Preview: https://markedjs-git-fork-kiliankilmister-master.markedjs.vercel.app

[KilianKilmister]

#1692

[UziTech]

According to Node:

Warning: Introducing the "exports" field prevents consumers of a package from using any entry points that are not defined, including the package.json (e.g. require('your-package/package.json'). This will likely be a breaking change.

So we will need to do a major version bump for this.

[UziTech]

why are these extra dependencies on here?

[KilianKilmister]

nodejs typings and a linter that doesn't croak on encountering stage3 ES-features. this was a rather hasty PR so i forgot to remove my devDeps.
There's little use for the linter if you don't use features released in after 2018.
node typings are always usefull. i don't think you use any builtins in the main code, but the tests do. i honestly recommend adding them to any project.

[UziTech]

I also don't believe we should implement this until es modules are not experimental as the interface could still change.

It seems this is only supported in node v14+ so we should probably wait until v14 becomes LTS.

[KilianKilmister]

According to Node:

Warning: Introducing the "exports" field prevents consumers of a package from using any entry points that are not defined, including the package.json (e.g. require('your-package/package.json'). This will likely be a breaking change.

So we will need to do a major version bump for this.

Is importing a package.json a "common" occurance? Just screams bad practice to me. But if that's something that people do, then it's certainly a point to consider.

LTS for node v14 is shockingly close already i just realised (scheduled for late october as always). I think this can wait till then

[KilianKilmister]

nodejs typings and a linter that doesn't croak on encountering stage3 ES-features. this was a rather hasty PR so i forgot to remove my devDeps.
There's little use for the linter if you don't use features released in after 2018.
node typings are always usefull. i don't think you use any builtins in the main code, but the tests do. i honestly recommend adding them to any project.

[UziTech]

Is importing a package.json a "common" occurance?

Not package.json, but I know there are some dependents that import just certain files like require('marked/lib/marked.js') or require('marked/src/Renderer.js'). We would need to define all valid entry points in the "exports" field not just ".".

[KilianKilmister]

Is importing a package.json a "common" occurance?

Not package.json, but I know there are some dependents that import just certain files like require('marked/lib/marked.js') or require('marked/src/Renderer.js'). We would need to define all valid entry points in the "exports" field not just ".".

This would be the files in src and lib, right? We could list those folders and expose them as a whole

[evanplaice]

It seems this is only supported in node v14+ so we should probably wait until v14 becomes LTS.

This isn't true. ESM was introduced in Node 13.x and back ported to 12.x LTS. With 10.x being EOL'd there is no longer an officially supported version of Node that doesn't work with modules.

For the issue of direct path imports being unavailable after pkg.exports is introduced. Instead of defining an export for every file you can provide a facade instead that re-exports all of the modules. Like this (https://github.com/vanillaes/absurdum/blob/main/src/arrays/index.js) but using default exports because none of the existing components are written in ESM.

If you don't want to support 2 copies (ie CJS and ESM), you can always use RollupJS or ESBuild to convert from ESM to CJS. ESM -> CJS conversion is a LOT cleaner than CJS -> ESM.

[UziTech]

If this PR was rebased I would be fine with including the exports field now 👍

[benmccann]

you should also export package.json as some bundlers will want to read it

Suggested change

	}
	},
	"./package.json": "./package.json"

[benmccann]

If this file is going to be added then the old lib/marked.esm.js should be removed, but it shouldn't be necessary to name it with an .mjs extension

[UziTech]

closing this in favor of #2227