[go: up one dir, main page]

Skip to content

ADR: Create helper module for requiring user code

There are several places in Antora where the software components need to require code provided by the user (with more on the way). The location of this code is specified either as an installed module or a loose script on the filesystem. Currently, the logic in Antora to locate and require the user's code is replicated each time it is needed. This approach is not maintainable and introduces risk that it's not done consistently. This logic should be extracted into a helper module so it can be reused, centrally maintained, and thoroughly tested.

The purpose of this helper function is to require a JavaScript module (specified as either a module name or path request) from the user's environment. The require function in Node.js resolves module names and paths in the environment of the calling script (i.e., the application code). That means it will not find modules in the local node_modules folder (unless the calling script is also located inside that folder) or local relative paths. This assumption is not well suited for user-supplied code. This behavior can be altered using require.resolve, which is precisely the functionality the proposed helper will encapsulate.

Antora should only have to provide the context for the augmented require.resolve call. The rest should be done by the helper.

Edited by Dan Allen
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information