Optionalinitial{@inheritDoc InitialPluginData}
auto install missing npm-package (the executed action/technique will vary based on the js-runtime-environment).
false: missing npm-packages are not installed.
this will result in esbuild's build process to terminate, since the missing package will not be resolvable.
true: equivalent to the "auto-cli" option.
"auto-cli": a cli-command will be picked depend on your js-runtime:
"deno" option will be executed."bun" option will be executed."npm" option will be executed."auto": the technique picked will depend on your js-runtime:
"dynamic" option will be chosen."npm" option will be chosen."dynamic": a dynamic "on-the-fly" import will be performed,
forcing your runtime to cache the npm-package in a local "./node_modules/" directory.
the underlying technique for the "dynamic" option used will only work for Deno and Bun, but not Nodejs.
moreover, you will need to have a certain configurations for this option to work on Deno and Bun:
"nodeModulesDir" should be set to "auto",
so that a local "./node_modules/" folder will be created for installed packages."./node_modules/" folder,
so that bun will opt for node-package-resolution instead of its default bun-style-resolution.
TODO: I haven't actually tried it on bun, and I'm only speculating based on the information here:
link"npm": this will run the npm install "${pkg}" --no-save cli-command in your absWorkingDir.
the --no-save flag warrants that your package.json file will not be modified (nor created if lacking) when a package is being installed.
"deno": this will run the deno cache --no-config --node-modules-dir="auto" --allow-scripts "npm:${pkg}" cli-command in your absWorkingDir.
deno cache installs the package, but without modifying (or creating) the "deno.json" file.--no-config option prevents deno from reading the "deno.json" (and "deno.lock") config file that may exist in an ancesteral directory of the desired installation directory,
thereby changing the location where the "./node_modules/" installation occurs.
moreover, giving deno access to the config file makes it reload all dependency modules listed in the "deno.json", not just our requested module alone.
this can be extremely annoying at times, and especially annoying when verifying the behavior of the plugins.--node-modules-dir="auto" flag ensures that the package is installed under the absWorkingDir directory's "./node_modules/" subdirectory,
instead of the global cache directory (which uses a non-node-module compatible layout).--allow-scripts flag permits preinstall and postinstall lifecycle scripts to run."deno-noscript": this will run the deno cache --no-config --node-modules-dir="auto" "${pkg}" cli-command in your absWorkingDir.
this is different from the "deno" option because it does not permit the execution of preinstall and postinstall lifecycle scripts.
lifecycle scripts could pose a security thread, but some popular packages that bind to native binaries (such as npm:sqlite3) require it.
"bun": this will run the bun install "${pkg}" --no-save cli-command in your absWorkingDir.
the --no-save flag warrants that your package.json file will not be modified (nor created if lacking) when a package is being installed.
"pnpm": this will run the pnpm install "${pkg}" cli-command in your absWorkingDir.
since the --no-save flag is not supported in pnpm (see issue#1237),
your package.json file will either get modified, or a new one will get created if it does not exist.
for any other custom cli-command, or to use an alternate installation directory, you may provide an object that adheres to the NpmAutoInstallCliConfig interface.
specify implicit peer-dependencies that your project requires, or it can even serve as a dependency aliasing import-map.
when autoInstall is enabled, these peer-dependencies will be the first thing to get installed in bulk (during esbuild's build.onStart phase).
moreover, an npm: prefix will always be ensured in your collection of peer-dependencies.
this means you cannot use this field to route a package to anywhere other than an npm-package.
for instance { "react": "react@18" } will be converted to { "react": "npm:react@18" }.
TODO: currently, I'm not inserting peerDependencies as an import-map for all resolved npm-packages.
this is because, if the user had intended to use an npm-package alias, they could've set an entry in the globalImportMap,
and it would have sufficed in most cases.
but I may implement it in the future, since the user may only wish to expose this alias to npm-packages captured by this plugin,
rather the global scope (which includes entities from http, jsr, etc...).
moreover, since dynamic-import-based installations cannot be aliased,
injecting the peerDependencies as an import-map inside the pluginData would be needed for the package to be discoverable.
specify which directories should be used for scanning for npm-packages inside of various node_modules folders.
here, you may provide a collection of:
string).string beginning with "./" or "../")."file://" protocol (string or URL).each directory that you provide here will be used by esbuild's native resolver as a starting point for scanning for node_modules npm-packages,
and it will work upwards from there until the root of your drive is reached,
and until all "./node_modules/" folders up the directory tree have been scanned.
to understand how the scanning works, and to defer for inefficient redundant scanning, refer to the underlying scanner function's documentation: findResolveDirOfNpmPackageFactory.
provide an optional function (or a static string) that returns the absolute path to the current working directory.
make sure that it always returns a posix-style path (i.e. uses "/" for directory separator, and not "\").
if this is left undefined, then we will leave it up to your runtime-environment's working-directory/path (provided by defaultGetCwd).
here is a summary of what that would entail:
process.cwd() or Deno.cwd().window.location.href or globalThis.runtime.getURL("").
note that if you will be bundling code that imports from npm-packages,
you must have your ./node_modules/ folder directly under the working-directory that you provide in this field.
TODO: this option is currently not respected by npmPlugin's DIRECTORY.CWD, since it uses the actual cwd (acquired via defaultGetCwd).
specify which namespaces should be intercepted by this suite of plugins.
all other namespaces will not be processed.
adding your custom plugin's namespace here could be useful if you would like your plugin to receive pre-resolved absolute paths,
instead of having to resolve the paths yourself by joining paths and inspecting pluginData.
specify which subset of plugins should log when log is enabled.
specify a global import-map for aliases to resources.
the full import-map within the body of the resolver function will be a merger between this global import-map, and the import-map acquired from the plugin data (i.e. CommonPluginData.importMap). the plugin data's import-map will take a higher priority in case of conflicting key (i.e. same alias key but different absolute path values).
the resolve function will always look for a match for args.path inside of the import-map,
before resolving it with respect to the current importer or resolve-directory (i.e. args.importer or args.resolveDir).
enable logging of the input arguments and resolved paths, when DEBUG.LOG is ennabled.
when set to true, the logs will show up in your console via console.log().
you may also provide your own custom logger function if you wish.
the configuration interface for the deno esbuild plugins suite denoPlugins.