Skip to main content

nodejs_build

Runs a Node.js build tool, such as a bundler, as a build action, and outputs the directory it writes. The tool runs with the nodejs toolchain's node_exec in a writable copy of the directory nodejs_binary stages as [dir]: srcs, main, resources and data deps at their paths, and a node_modules composed from deps, library and node_modules as for nodejs_binary. Files outside node_modules are copied; each entry of node_modules is a symlink to its staged copy, so a tool that resolves symlinks, as Node and Vite do by default, finds packages there rather than in the copy, and writes under node_modules (such as a tool's cache) stay in the copy.

Details​

Exactly one of these runs, with node_args before it and args after it: main, a file that is staged; library with entry_point, as for nodejs_binary; or tool, the path of a file under the composed node_modules, such as "vite/bin/vite.js" for a third-party tool, which then needs srcs. The working directory is the copy's root, so relative paths in args and in the tool's config name staged files. $(location) macros in args and env expand to absolute paths.

out is the relative, /-separated path of the directory the tool writes, such as "dist" or "out/renderer"; it cannot be under node_modules. That directory, with symlinks copied as the files they resolve to, is the default output. The build fails if the tool exits non-zero or writes no directory at out. A tool that records the paths of the packages it reads, as source maps do, records their staged location.

The output is a built artifact, like a binary, not a package: a bundler's output cannot be composed further as a dependency, so this rule belongs at or near the top of a build graph. It provides no NodejsLibraryInfo, so it never joins another target's node_modules. Consume it as a resource: in resources, or as a deps entry, which stages it as a data dep at its package path.

Function Signature​

def nodejs_build(
*,
name: str,
default_target_platform: None | str = None,
target_compatible_with: list[str] = [],
compatible_with: list[str] = [],
exec_compatible_with: list[str] = [],
visibility: list[str | target_name_glob] = [],
within_view: list[str | target_name_glob] = ["PUBLIC"],
metadata: OpaqueMetadata = {},
tests: list[str] = [],
modifiers: OpaqueMetadata = [],
_nodejs_toolchain: str = "gh_facebook_buck2_shims_meta//:nodejs",
_package_tree_tool: str = "prelude//nodejs/tools:package_tree",
args: list[str] = [],
contacts: list[str] = [],
deps: list[str] = [],
entry_point: None | str = None,
env: dict[str, str] = {},
labels: list[str] = [],
library: None | str = None,
main: None | str = None,
node_args: list[str] = [],
node_modules: None | list[str] = None,
out: str,
resources: list[str] | dict[str, str] = [],
srcs: list[str] = [],
tool: None | str = None,
) -> None

Parameters​

  • name: (required)

    name of the target

  • default_target_platform: (defaults to: None)

    specifies the default target platform, used when no platforms are specified on the command line

  • target_compatible_with: (defaults to: [])

    a list of constraints that are required to be satisfied for this target to be compatible with a configuration

  • compatible_with: (defaults to: [])

    a list of constraints that are required to be satisfied for this target to be compatible with a configuration

  • exec_compatible_with: (defaults to: [])

    a list of constraints that are required to be satisfied for this target to be compatible with an execution platform

  • visibility: (defaults to: [])

    a list of visibility patterns restricting what targets can depend on this one

  • within_view: (defaults to: ["PUBLIC"])

    a list of visibility patterns restricting what this target can depend on

  • metadata: (defaults to: {})

    a key-value map of metadata associated with this target

  • tests: (defaults to: [])

    a list of targets that provide tests for this one

  • modifiers: (defaults to: [])

    an array of modifiers associated with this target

  • contacts: (defaults to: [])

    A list of organizational contacts for this rule. These could be individuals who you would contact in the event of a failure or other issue with the rule.

    contacts = [ 'Joe Sixpack', 'Erika Mustermann' ]
  • labels: (defaults to: [])

    Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query().