Rules_nodejs: documentation for install_bazel_dependencies?

[jmhodges]

I see references to the install_bazel_dependencies in some places of the documentation (like in the typescript stuff) and some referencies in e2e tests, but no actual documentation on the doc website for it. The docs don't mention what it does, nor what load statement is used to get it.

[alexeagle]

Yes, we are missing documentation for the repository rules. I think stardoc knows how to generate this now.

[alexeagle]

Oh, thinking about this a bit more - the install_bazel_dependencies rule exists in the @npm workspace which is generated. So I don't think we can generate any docs for it, we'll just have to add some explanation in prose somewhere.

[AustinSchuh]

I struggled mightily as well to find enough docs to get a working example. I eventually pieced together the following:

http_archive(
    name = "build_bazel_rules_nodejs",
    sha256 = "0d9660cf0894f1fe1e9840818553e0080fbce0851169812d77a70bdb9981c946",
    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/0.37.0/rules_nodejs-0.37.0.tar.gz"],
)

# Setup the NodeJS toolchain
load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories", "yarn_install")

node_repositories()

# Setup Bazel managed npm dependencies with the `yarn_install` rule.
#
# To run yarn by hand, use:
#  bazel run @nodejs_linux_amd64//:bin/yarn -- list
# I'm sure there is a better path, but that works...
yarn_install(
    name = "npm",
    package_json = "//:package.json",
    symlink_node_modules = False,
    yarn_lock = "//:yarn.lock",
)

# Install all Bazel dependencies needed for npm packages that supply Bazel rules
load("@npm//:install_bazel_dependencies.bzl", "install_bazel_dependencies")

install_bazel_dependencies()

load("@npm_bazel_typescript//:index.bzl", "ts_setup_workspace")

ts_setup_workspace()

[alexeagle]

@AustinSchuh and @jmhodges Can you help me understand the path you took to get here? I'd expect you to start with @bazel/create which sets up a basic WORKSPACE like this without you having to figure anything out, unless you're trying to do something advanced.

[jmhodges]

I was adding this to an already existing bazel repository that I've had for a long time now.

[AustinSchuh]

This is a bit wordy, but it feels like you are looking for my thought process to help steer future people correctly, so I went for it.

At the risk of hijacking this thread, I've got a large repo with hundreds of targets already in it. I've been looking for the couple of lines of code I need to get ts_library to work. Based on experience with other bazel tools, I was looking for something like the above lines. An http_archive to add, something to import, and likely something to call. I've been trained (for better or worse) through experience to be careful running tools. I'm also very cautious about installing tools onto my laptop to manage the build. I'd much rather figure out how to do the same thing with Bazel, so I don't have to install the tools on everyone's laptops and the tool is versioned. (Which results in me being cautious about installing yarn and looking for another way)

So I worked backwards. I found a commit in the commit log for rules_typescript which pointed me to doing everything with yarn_install. I had found the yarn_install command from a previous attempt. https://bazelbuild.github.io/rules_nodejs/install.html has some of that. After a bunch of searching, and some reading of the code, I pieced together that info from above.

From my point of view, if the front page of the docs for rules_nodejs saying to use @bazel/create had said that it will add the entries to the WORKSPACE file, and also had a good link to a sandboxed version of yarn for future use, I likely wouldn't have gone down this route. Same goes for the rules_typescript. The documentation very much felt like how to automagically configure an existing nodejs/typescript project to work with bazel.

[alexeagle]

possible dupe of #1131