Function npmPluginSetup

Parameters

• config: {
      specifiers?: string[];
      sideEffects?: boolean | "auto" | "defaultFalse" | "defaultTrue";
      autoInstall?:
          | boolean
          | "npm"
          | "auto-cli"
          | "auto"
          | "dynamic"
          | "deno"
          | "deno-noscript"
          | "bun"
          | "pnpm"
          | {
              dir?: NodeModuleDirFormat;
              command?: (package_name_and_version: string) => string;
              log?: boolean | LoggerFunction;
          };
      peerDependencies?: | EsbuildEntryPointType[]
      | { [key: string]: undefined
      | string };
      acceptNamespaces?: (undefined | string)[];
      nodeModulesDirs?: NodeModuleDirFormat[];
      log?: boolean | LoggerFunction;
  } = {}

  • Optionalspecifiers?: string[]

    provide a list of prefix specifiers used for npm packages.

    Default Value

    ["npm:"]

  • OptionalsideEffects?: boolean | "auto" | "defaultFalse" | "defaultTrue"

    specify the side-effects potential of all npm-packages.

    • true: this would mark all packages as having side-effects, resulting in basically no tree-shaking (large bundle size).
    • false: this would mark all packages being side-effects free, allowing for tree-shaking to take place and reducing bundle size.
    • "auto": this would let esbuild decide which packages are side-effect free, by probing into the package's package.json file and searching for the "sideEffects" field. however, since many unseasoned package authors do not know about this field (i.e. me), the lack of it makes esbuild default to false. which is in effect results in a larger bundled code size.

    TODO: in the future, I would like to probe into the package.json file of the package myself (by deriving its path from the resolved_path), and then determine weather or not the "sideEffects" field is actually present. if it isn't then we will default to false if this config option is set to "defaultFalse", or default to true if this config option is set to "defaultTrue". (esbuild exhibits the "defaultTrue" behavior by default anyway, so this specific option selection will be kind of redundant). TODO: since in effect the "auto" option is equivalent to "defaultTrue", I'm uncertain whether I should even keep the "auto" option.

    Default Value

    "auto"

  • OptionalautoInstall?:
        | boolean
        | "npm"
        | "auto-cli"
        | "auto"
        | "dynamic"
        | "deno"
        | "deno-noscript"
        | "bun"
        | "pnpm"
        | {
            dir?: NodeModuleDirFormat;
            command?: (package_name_and_version: string) => string;
            log?: boolean | LoggerFunction;
        }

    auto install missing npm-package (the executed action/technique will vary based on the js-runtime-environment).

    options

    • 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:

      • for Deno, the cli-command of the "deno" option will be executed.
      • for Bun, the cli-command of the "bun" option will be executed.
      • for Nodejs, the cli-command of the "npm" option will be executed.

    • "auto": the technique picked will depend on your js-runtime:

      • for Deno and Bun, the "dynamic" option will be chosen.
      • for Nodejs, the "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.

      Warning

      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:

      • for Deno, your project's "deno.json" file's "nodeModulesDir" should be set to "auto", so that a local "./node_modules/" folder will be created for installed packages.
      • for Bun, your project's directory, or one of its ancesteral directory, must contain a "./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.

      Note

      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.

      Note

      • deno cache installs the package, but without modifying (or creating) the "deno.json" file.
      • the --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.
      • the --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).
      • the --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.

      Note

      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.

      Note

      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.

      Caution

      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.

    Default Value

    true

  • OptionalpeerDependencies?: EsbuildEntryPointType[] | { [key: string]: undefined | string }

    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.

    Default Value

    {} (no peer-dependencies)

  • OptionalacceptNamespaces?: (undefined | string)[]

    specify which namespaces should be intercepted by the npm-specifier-plugin. all other namespaces will not be processed by this plugin.

    if you have a plugin with a custom loader that works under some "custom-namespace", you can include your "custom-namespace" here, so that if it performs an npm-specifier import, that import path will be captured by this plugin, and then consequently fetched by the http-loader plugin. but do note that the namespace of the loaded resource will switch to the http-plugin's loader namespace (which defaults to PLUGIN_NAMESPACE.LOADER_HTTP), instead of your "custom-namespace".

    Default Value

    [undefined, "", "file"] (also this plugin's namespace gets added later on)

  • OptionalnodeModulesDirs?: NodeModuleDirFormat[]

    specify which directories should be used for scanning for npm-packages inside of various node_modules folders.

    here, you may provide a collection of:

    • absolute filesystem paths (string).
    • paths relative to your current working directory (string beginning with "./" or "../").
    • file-uris which being with the "file://" protocol (string or URL).
    • or one of the accepted special directory enums in DIRECTORY.

    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.

    Tip

    to understand how the scanning works, and to defer for inefficient redundant scanning, refer to the underlying scanner function's documentation: findResolveDirOfNpmPackageFactory.

    Default Value

    [DIRECTORY.ABS_WORKING_DIR] (equivalent to [DIRECTORY.ABS_WORKING_DIR, DIRECTORY.CWD])

  • Optionallog?: boolean | LoggerFunction

    enable logging of resolved npm-package's path, 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.

    Default Value

    false