docs: updates the node formula example to use the node installed by Homebrew

[ctaintor]

The existing example uses a symlink which means that whatever node is first in the PATH will be used. This can mean that a Homebrew-installed nodejs executable may not work reliably (since it may execute with a different version of node)

This PR changes it so that using the Homebrew-installed node will be used. It also includes common other options (like shell completion) as well as the old symlink solution.

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew style with your changes locally?
• Have you successfully run brew typecheck with your changes locally?
• Have you successfully run brew tests with your changes locally?

---

[MikeMcQuaid]

How many formulae does this?

[ctaintor]

I'm not sure but personally when I was writing a formula I didn't know that this was an option (adding completions) and I also did not know that the generate_completions_from_executable function exists. I kept these comments here to help people know that adding completions is easy.

(In my case, my CLI already supported completions – so it was as simple as knowing that it's possible and easy to have Homebrew set it up)

[Rylan12]

Looks like 387 formulae use generate_completions_from_executable in total.

However, out of the 173 formulae that have require "language/node", only 10 use generate_completions_from_executable.

Of those 10, only cdktf uses the generate_completions_from_executable(libexec/"bin/foo") scheme described here, the other 9 use generate_completions_from_executable(bin/"foo").

[ctaintor]

Of those 10, only cdktf uses the generate_completions_from_executable(libexec/"bin/foo") scheme described here, the other 9 use generate_completions_from_executable(bin/"foo")

Note that when you use write_env_script then you must use libexec here (using bin will result in a runtime error)

[MikeMcQuaid]

Given this is used by <10% of Node formulae: I'm not sure it's worth documenting specifically here.

[MikeMcQuaid]

Which/how many formulae do this each of these ways? CC @homebrew/core for thoughts.

[ctaintor]

I personally don't know when you'd ever want it this way – it's just how it was documented previously. At the very least, if the formula has a depends_on to node then I'd expect it to always use the write_env_script to force the usage of the Homebrew-installed node.

yarn will use the first node on the path but I'd imagine this is an outlier (and it is also not calling bin.install_symlink – but it is not trying to always use homebrew's node)

[Rylan12]

Looking at the 173 formulae with require "language/node":

5 use write_env_script, although only 3 use it in the exact way suggested here:

• protoc-gen-grpc-web
  • This doesn't actually use system "npm", "install", *Language::Node.std_npm_install_args(libexec) so maybe it shouldn't count
• mongosh
• code-server
• bcoin
• emscripten
  • This is another case where the formula is much more complex than the sample here os it probably shouldn't be included

On the other hand, there are 155 formulae that use bin.install_symlink and 145 of those use bin.install_symlink Dir[libexec/"foo"]. So, the original way this is written seems to be by far the most prevalent.

[MikeMcQuaid]

Thanks @Rylan12!

On the other hand, there are 155 formulae that use bin.install_symlink and 145 of those use bin.install_symlink Dir[libexec/"foo"]. So, the original way this is written seems to be by far the most prevalent.

Given the prevalence here: I think this may be worth opening a Homebrew/core issue to discuss if we want to migrate the approach here. I don't think it makes sense to have the documentation recommend the opposite of what most formulae are doing.