typedoc

typedoc copied to clipboard

Search Terms

native ecmascript, esm, plugin

Problem

It would be nice to write TypeDoc plugins as ESM modules, using node's new native ESM support

Suggested Solution

typedoc can first try to require() the plugin, then if it gets an ERR_REQUIRE_ESM error, it can import() it instead. This will support both CJS and ESM and will also support CJS transpilers like ts-node. I'm not sure if the ts-node use-case is meant to be supported or not. If not, typedoc can merely import() the plugins.

import() is async; I don't know if typedoc's plugin loading can be async.

This would be a breaking change, since plugins are loaded in Application.bootstrap which is currently not async, but it seems like a reasonable approach to me.

Ok, I think the require-then-import approach could be used to keep bootstrap sync if wanted to preserve backwards-compat, and then a new bootstrapAsync could be added which supports ESM plugins. I suppose attempting to use any async plugin via the old bootstrap API would throw an error.

Not sure if the above is feasible of worthwhile, or if it's better to keep it simple and do the breaking change.

On Sun, Jul 18, 2021, 9:48 AM Gerrit Birkeland @.***> wrote:

This would be a breaking change, since plugins are loaded in Application.bootstrap which is currently not async, but it seems like a reasonable approach to me.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/TypeStrong/typedoc/issues/1635#issuecomment-882059043, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAC35OBH76GNW3JYKUOS653TYLLRLANCNFSM5AR232AA .

I like keeping it simple, this is a pretty minor breaking change.

So... I looked at doing this, and it's not something that I want to commit to in 0.22. I'm fine with the breaking change, but it seems that doing this properly either requires turning on allowJs so that TS doesn't transpile the import into Promise.resolve().then(() => require(...)) (ew), adding a dependency (double ew), or switching to emitting ESM (which is a rats nest that I don't want to get into right now)

If someone wants to use ESM plugins badly enough, and sends a PR, I'll definitely look at it, but this isn't as straightforward as I thought at first.

I've accomplished this by shipping a single, non-transpiled JS file. It shouldn't require allowJs.

I put in it exports.importHelper = function(specifier) {return import(specifier)} and then use it wherever I need a non-transpiled dynamic import().

On Fri, Aug 20, 2021, 12:22 AM Gerrit Birkeland @.***> wrote:

So... I looked at doing this, and it's not something that I want to commit to in 0.22. I'm fine with the breaking change, but it seems that doing this properly either requires turning on allowJs so that TS doesn't transpile the import into Promise.resolve().then(() => require(...)) (ew), adding a dependency (double ew), or switching to emitting ESM (which is a rats nest that I don't want to get into right now)

If someone wants to use ESM plugins badly enough, and sends a PR, I'll definitely look at it, but this isn't as straightforward as I thought at first.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/TypeStrong/typedoc/issues/1635#issuecomment-902419708, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAC35OFCO6QNXQ4EK7MQCBTT5XJ77ANCNFSM5AR232AA .