nodejs_library

A Node.js library that packages code as a regular node_modules package loadable by Node without custom loaders. The package's content comes from at most one of: uncompiled srcs, srcs with tsconfig, module or prebuilt, each described below. resources and package_json may accompany any of them or stand alone. A library with only deps or node_modules is an aggregate (see the end). src_root (default "") is the directory that staged and emitted paths are relative to. For srcs and a resources list it applies to each artifact's short path (a source file's path inside its BUCK package, a generated artifact's path inside its rule's output), and every entry must be under it; for module it applies inside the module root. package_subdir (default "", the package root, beside package.json) is the directory inside the package that compiled output, the module emit, uncompiled srcs and resources list entries are staged in, e.g. "dist". Both are relative paths with / separators, no : and no ., .. or node_modules segments. A prebuilt package has neither compiled output nor srcs: package_subdir fails with it, and its resources list entries are staged relative to the package root. Without tsconfig, the artifacts it is given are packaged as-is (no compilation): whatever produced them (plain JavaScript sources, generated files, another rule's output) feeds srcs, and each entry is staged at <package_subdir>/<path> inside the package, where <path> is its short path relative to src_root (repeating the same source is allowed). With tsconfig, srcs are compiled with the toolchain's tsc before staging: sources are staged by short path next to the tsconfig, the package.json (whose "type" decides the emitted module format) and a node_modules composed from the packages of the transitive deps and the third-party trees (see node_modules), so cross-package type imports resolve, compiled with --outDir, --rootDir (src_root inside that staging directory), --declaration, --noEmit false and --emitDeclarationOnly false, into package_subdir. srcs replace the tsconfig's files and include. .ts, .tsx, .mts and .cts sources are compiled; .js, .jsx, .mjs, .cjs and .json sources go to tsc too, and the tsconfig's allowJs and resolveJsonModule decide what happens to them. Declarations and sources with other extensions fail. Only the tsconfig is staged, so an extends pointing at a sibling config file does not resolve. A source whose first path segment is tsconfig.json, tsconfig.buck.json, package.json or a staged node_modules fails. prebuilt, when set, is a directory that already is the package, package.json included: a source directory or another rule's directory output, used as the package directory as it is. It cannot be combined with srcs, tsconfig or module. package_json adds or replaces its package.json and resources add to it, in a copy; one that collides with a file or directory in it fails the build with an error naming both. resources ship non-code files and directories with the package, whatever its content: source files and directories, generated files, and other rules' directory outputs. A list entry is staged like an uncompiled source, at <package_subdir>/<path> where <path> is its short path relative to src_root, so it keeps its place relative to code compiled from the same package and lookups through __dirname resolve as they do in the source tree. The module emit mirrors the module root instead, so a list entry lines up with it only when the entry's short path matches its place in the module root, as a source of a filegroup module's own package does; otherwise use a dict. A dict maps package-relative paths to entries staged at exactly those paths. Every path a resource is staged at is relative and /-separated, with no : and no ., .. or node_modules segments; package.json is reserved for package_json. Two distinct entries (uncompiled srcs, resources or package_json) that map to the same staged path fail, and staged paths must not nest, e.g. a and a/b fail. With compiled content, resources may be staged inside the compiled output and merge into its directories, but one that collides with an emitted file or directory fails the build with an error naming both. deps must be nodejs_library targets; use resources for non-code artifacts. Staging copies files so the package runs under Node without --preserve-symlinks. package_json, when supplied, is staged verbatim at the package root as package.json, replacing a package.json the compile emits there. Without it or prebuilt, the package gets a synthesized package.json with name (the package_name), version (default "0.0.0"), type ("commonjs", the default, or "module"), main and bin. It never has types, since TypeScript finds the declaration tsc emits beside main, nor exports, so every file in the package stays importable by path. main is a package-relative file, and bin maps command names to package-relative files. A validation checks the package's package.json, whichever way it came: its name must be the package_name or the out; its main, its bin files and its exports targets other than * patterns must be files in the package, as must its types or typings (or that path with .d.ts or /index.d.ts appended); each bin file must start with a shebang (#!); every conditions object in exports must list types first; main, bin, type and version, when set, must match it; and with module, its type must match the module's own package.json nearest src_root, when the module has one; tsc takes the module format of each source from it unless a nested package.json is closer. package_name (default: target name): a valid npm package name of at most 214 characters, name or @scope/name, where each segment contains only lowercase letters, digits, -, ., _, ~ and does not start with . or _. The unscoped names node_modules and favicon.ico are reserved and rejected, as is @scope/node_modules; either may be used as the scope. node_modules lists third-party trees (nodejs_node_modules targets, e.g. over a yarn install output), for packages with no nodejs_library target. A library's trees are those it lists plus those of its transitive deps; listing a tree a dep already brings is allowed. They are forwarded to libraries, binaries and tests that depend on this one, whatever its content (a nodejs_binary or nodejs_test that sets its own node_modules runs with those instead). The tsc compile of srcs composes them with the packages of the transitive deps into its staged node_modules, package by package. A package name two of those sources provide fails the build and names both; nodejs_node_modules describes the other packages that fail it and how exclude drops them. module, when set, compiles a whole project directory (a target whose single output holds a tsconfig.json and its sources) instead of compiling srcs: tsc -p runs on the module's own tsconfig.json with --outDir, --rootDir (src_root inside the module root, overriding any tsconfig rootDir), --declaration, --declarationDir (the --outDir), --noEmit false and --emitDeclarationOnly false, and the emitted tree is staged as the package's package_subdir, mirroring source paths (with the defaults, src/main.ts emits src/main.js). It cannot be combined with srcs, deps or tsconfig; the module tsconfig must not require writes into the tree. Only the emitted tree is staged, not the module's own package.json (whose paths are relative to the module root, not the package) or node_modules. The package's package.json is synthesized or package_json as for any library, so a module whose package.json declares "type": "module" needs type = "module" (the validation above fails otherwise). A module compile does not stage the listed trees. out, when set, stages the package under that directory name inside node_modules instead of package_name (a relative path with / separators, no : and no ., .. or node_modules segments), for packages whose imports address a canonical directory. The default output is the package's own directory (package_dir). The [node_modules] sub-target is the merged node_modules tree for this package and its transitive deps, laid out by package_name (or out), without third-party trees. A duplicate package_name in the transitive closure with a different package output fails the build, as does one package directory nested inside another. The [runtime] sub-target is the package directory without its .d.ts, .d.mts and .d.cts files and their maps, with symlinks copied as their targets; nodejs_binary and nodejs_test stage it in their composed tree. The [sources] sub-target is a directory holding the library's original sources at their package-relative paths: its srcs, its package_json (at package.json) and its tsconfig, for consumers that work on sources rather than the staged package, such as source typecheckers. For a module library it is the module directory, and for a prebuilt library the prebuilt directory; an aggregate library's is an empty directory. A library with deps or node_modules and none of srcs, resources, module, prebuilt, package_json or tsconfig stages no package: its default output, like its [node_modules], is the merged node_modules tree of its transitive deps. It cannot be a library of a nodejs_binary or nodejs_test, and package_name, out, main, bin, type, version, package_subdir and src_root fail on it.

Function Signature

def nodejs_library(
    *,
    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",
    bin: dict[str, str] = {},
    contacts: list[str] = [],
    deps: list[str] = [],
    labels: list[str] = [],
    main: None | str = None,
    module: None | str = None,
    node_modules: list[str] = [],
    out: None | str = None,
    package_json: None | str = None,
    package_name: None | str = None,
    package_subdir: None | str = None,
    prebuilt: None | str = None,
    resources: list[str] | dict[str, str] = [],
    src_root: str = "",
    srcs: list[str] = [],
    tsconfig: None | str = None,
    type: None | str = None,
    version: 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().