docs: add npm_package vs js_library info to troubleshooting.md (#2164)

Author: jbedard

docs/troubleshooting.md

@@ -151,6 +151,14 @@ See [examples/stack_traces](../examples/stack_traces) for a working example.
 
 For general bazel performance tips see the [Aspect bazelrc guide](https://docs.aspect.build/guides/bazelrc/#performance-options).
 
+### Linking first-party packages
+
+When linking first-party packages it is recommended to use `js_library` or another `JsInfo`-providing rule to represent the package instead of the `npm_package` rule (which provides `NpmPackageInfo`).
+
+The use of `NpmPackageInfo` requires building the full package content in order to output a single directory artifact representing the package.
+
+Using `JsInfo` allows rules_js to passthru the provider without collecting the package content until another action requests it. For example `JsInfo.types`, normally outputted by a slow `.d.ts` producing tool such as `tsc`, is most likely unnecessary when only executing or bundling JavaScript files from `JsInfo.sources`. If `JsInfo.types` is produced by different actions then `JsInfo.sources` then those actions may not be required at all.
+
 ### Parallelism (build, test)
 
 A lot of tooling in the JS ecosystem uses parallelism to speed up builds. This is great, but as Bazel also parallels builds this can lead to a lot of contention for resources.

npm/private/npm_package_store.bzl

@@ -24,7 +24,7 @@ https://github.com/npm/rfcs/blob/main/accepted/0042-isolated-mode.md.
 
 _ATTRS = {
     "src": attr.label(
-        doc = """A npm_package target or or any other target that provides a NpmPackageInfo.
+        doc = """A target providing a `NpmPackageInfo` or `JsInfo` containing the package sources.
         """,
         mandatory = True,
     ),
@@ -117,15 +117,15 @@ _ATTRS = {
     "package": attr.string(
         doc = """The package name to link to.
 
-If unset, the package name in the NpmPackageInfo src must be set.
-If set, takes precendance over the package name in the NpmPackageInfo src.
+If unset, the package name in the `NpmPackageInfo` src must be set.
+If set, takes precendance over the package name in the `NpmPackageInfo` src.
 """,
     ),
     "version": attr.string(
         doc = """The package version being linked.
 
-If unset, the package version in the NpmPackageInfo src must be set.
-If set, takes precendance over the package version in the NpmPackageInfo src.
+If unset, the package version in the `NpmPackageInfo` src must be set.
+If set, takes precendance over the package version in the `NpmPackageInfo` src.
 """,
     ),
     "dev": attr.bool(

npm/private/npm_package_store_internal.bzl

@@ -5,7 +5,7 @@ load(":npm_package_store.bzl", _npm_package_store_lib = "npm_package_store_lib")
 
 _INTERNAL_ATTRS_STORE = dicts.add(_npm_package_store_lib.attrs, {
     "src": attr.label(
-        doc = """A npm_package target or or any other target that provides a NpmPackageInfo.
+        doc = """A target providing a `NpmPackageInfo` or `JsInfo` containing the package sources.
 
         Can be left unspecified to allow for npm_link_package "reference" targets. `npm_link_package`
         targets without a `src` are used internally by `npm_import` to create "reference"
@@ -18,13 +18,13 @@ _INTERNAL_ATTRS_STORE = dicts.add(_npm_package_store_lib.attrs, {
     "package": attr.string(
         doc = """The package name to link to.
         
-        Takes precedence over the package name in the NpmPackageInfo src.""",
+        Takes precedence over the package name in the `NpmPackageInfo` src.""",
         mandatory = True,
     ),
     "version": attr.string(
         doc = """The package version to link to.
         
-        Takes precedence over the package version in the NpmPackageInfo src.""",
+        Takes precedence over the package version in the `NpmPackageInfo` src.""",
         mandatory = True,
     ),
 })