Skip to content

Commit e4eae5a

Browse files
alexeaglealexeagle
committed
Update docs for release
1 parent 4554a9f commit e4eae5a

File tree

2 files changed

+146
-20
lines changed

2 files changed

+146
-20
lines changed

‎docs/node/node.html‎

Lines changed: 124 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -321,9 +321,70 @@ <h3 id="nodejs_binary_args">Attributes</h3>
321321
<tr id="nodejs_binary.node_modules">
322322
<td><code>node_modules</code></td>
323323
<td>
324-
<p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional; Default is @//:node_modules</code></p>
324+
<p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional</code></p>
325325
<p>The npm packages which should be available to <code>require()</code> during
326326
execution.</p>
327+
<pre><code> This attribute is DEPRECATED. As of version 0.13.0 the recommended approach
328+
to npm dependencies is to use fine grained npm dependencies which are setup
329+
with the `yarn_install` or `npm_install` rules. For example, in targets
330+
that used a `//:node_modules` filegroup,
331+
332+
```
333+
nodejs_binary(
334+
name = "my_binary",
335+
...
336+
node_modules = "//:node_modules",
337+
)
338+
```
339+
340+
which specifies all files within the `//:node_modules` filegroup
341+
to be inputs to the `my_binary`. Using fine grained npm dependencies,
342+
`my_binary` is defined with only the npm dependencies that are
343+
needed:
344+
345+
```
346+
nodejs_binary(
347+
name = "my_binary",
348+
...
349+
data = [
350+
"@npm//:foo",
351+
"@npm//:bar",
352+
...
353+
],
354+
)
355+
```
356+
357+
In this case, only the `foo` and `bar` npm packages and their
358+
transitive deps are includes as inputs to the `my_binary` target
359+
which reduces the time required to setup the runfiles for this
360+
target (see https://github.com/bazelbuild/bazel/issues/5153).
361+
362+
The @npm external repository and the fine grained npm package
363+
targets are setup using the `yarn_install` or `npm_install` rule
364+
in your WORKSPACE file:
365+
366+
yarn_install(
367+
name = "npm",
368+
package_json = "//:package.json",
369+
yarn_lock = "//:yarn.lock",
370+
)
371+
372+
For other rules such as `jasmine_node_test`, fine grained
373+
npm dependencies are specified in the `deps` attribute:
374+
375+
```
376+
jasmine_node_test(
377+
name = "my_test",
378+
...
379+
deps = [
380+
"@npm//:jasmine",
381+
"@npm//:foo",
382+
"@npm//:bar",
383+
...
384+
],
385+
)
386+
```
387+
</code></pre>
327388
</td>
328389
</tr>
329390
<tr id="nodejs_binary.templated_args">
@@ -427,9 +488,70 @@ <h3 id="nodejs_test_args">Attributes</h3>
427488
<tr id="nodejs_test.node_modules">
428489
<td><code>node_modules</code></td>
429490
<td>
430-
<p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional; Default is @//:node_modules</code></p>
491+
<p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional</code></p>
431492
<p>The npm packages which should be available to <code>require()</code> during
432493
execution.</p>
494+
<pre><code> This attribute is DEPRECATED. As of version 0.13.0 the recommended approach
495+
to npm dependencies is to use fine grained npm dependencies which are setup
496+
with the `yarn_install` or `npm_install` rules. For example, in targets
497+
that used a `//:node_modules` filegroup,
498+
499+
```
500+
nodejs_binary(
501+
name = "my_binary",
502+
...
503+
node_modules = "//:node_modules",
504+
)
505+
```
506+
507+
which specifies all files within the `//:node_modules` filegroup
508+
to be inputs to the `my_binary`. Using fine grained npm dependencies,
509+
`my_binary` is defined with only the npm dependencies that are
510+
needed:
511+
512+
```
513+
nodejs_binary(
514+
name = "my_binary",
515+
...
516+
data = [
517+
"@npm//:foo",
518+
"@npm//:bar",
519+
...
520+
],
521+
)
522+
```
523+
524+
In this case, only the `foo` and `bar` npm packages and their
525+
transitive deps are includes as inputs to the `my_binary` target
526+
which reduces the time required to setup the runfiles for this
527+
target (see https://github.com/bazelbuild/bazel/issues/5153).
528+
529+
The @npm external repository and the fine grained npm package
530+
targets are setup using the `yarn_install` or `npm_install` rule
531+
in your WORKSPACE file:
532+
533+
yarn_install(
534+
name = "npm",
535+
package_json = "//:package.json",
536+
yarn_lock = "//:yarn.lock",
537+
)
538+
539+
For other rules such as `jasmine_node_test`, fine grained
540+
npm dependencies are specified in the `deps` attribute:
541+
542+
```
543+
jasmine_node_test(
544+
name = "my_test",
545+
...
546+
deps = [
547+
"@npm//:jasmine",
548+
"@npm//:foo",
549+
"@npm//:bar",
550+
...
551+
],
552+
)
553+
```
554+
</code></pre>
433555
</td>
434556
</tr>
435557
<tr id="nodejs_test.templated_args">

‎docs/npm_install/npm_install.html‎

Lines changed: 22 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ <h2 id="overview">Overview</h2>
132132

133133
<h2 id="npm_install">npm_install</h2>
134134

135-
<pre>npm_install(<a href="#npm_install.name">name</a>, <a href="#npm_install.data">data</a>, <a href="#npm_install.node_modules_filegroup">node_modules_filegroup</a>, <a href="#npm_install.package_json">package_json</a>, <a href="#npm_install.package_lock_json">package_lock_json</a>, <a href="#npm_install.prod_only">prod_only</a>)</pre>
135+
<pre>npm_install(<a href="#npm_install.name">name</a>, <a href="#npm_install.data">data</a>, <a href="#npm_install.manual_build_file_contents">manual_build_file_contents</a>, <a href="#npm_install.package_json">package_json</a>, <a href="#npm_install.package_lock_json">package_lock_json</a>, <a href="#npm_install.prod_only">prod_only</a>)</pre>
136136

137137
<p>Runs npm install during workspace setup.</p>
138138

@@ -159,16 +159,18 @@ <h3 id="npm_install_args">Attributes</h3>
159159

160160
</td>
161161
</tr>
162-
<tr id="npm_install.node_modules_filegroup">
163-
<td><code>node_modules_filegroup</code></td>
162+
<tr id="npm_install.manual_build_file_contents">
163+
<td><code>manual_build_file_contents</code></td>
164164
<td>
165165
<p><code>String; Optional; Default is ''</code></p>
166-
<p>Experimental attribute that can be used to work-around
167-
a bazel performance issue if the default node_modules filegroup
168-
has too many files in it. Use it to define the node_modules
169-
filegroup used by this rule such as
170-
"filegroup(name = "node_modules", srcs = glob([...]))". See
171-
<a href="https://github.com/bazelbuild/bazel/issues/5153">https://github.com/bazelbuild/bazel/issues/5153</a>.</p>
166+
<p>Experimental attribute that can be used to override
167+
the generated BUILD.bazel file and set its contents manually.
168+
Can be used to work-around a bazel performance issue if the
169+
default node_modules filegroup has too many files in it. See
170+
<a href="https://github.com/bazelbuild/bazel/issues/5153">https://github.com/bazelbuild/bazel/issues/5153</a>. If
171+
you are running into performance issues due to a large
172+
node_modules filegroup it is recommended to switch to using
173+
fine grained npm dependencies.</p>
172174
</td>
173175
</tr>
174176
<tr id="npm_install.package_json">
@@ -198,7 +200,7 @@ <h3 id="npm_install_args">Attributes</h3>
198200

199201
<h2 id="yarn_install">yarn_install</h2>
200202

201-
<pre>yarn_install(<a href="#yarn_install.name">name</a>, <a href="#yarn_install.data">data</a>, <a href="#yarn_install.node_modules_filegroup">node_modules_filegroup</a>, <a href="#yarn_install.package_json">package_json</a>, <a href="#yarn_install.prod_only">prod_only</a>, <a href="#yarn_install.yarn_lock">yarn_lock</a>)</pre>
203+
<pre>yarn_install(<a href="#yarn_install.name">name</a>, <a href="#yarn_install.data">data</a>, <a href="#yarn_install.manual_build_file_contents">manual_build_file_contents</a>, <a href="#yarn_install.package_json">package_json</a>, <a href="#yarn_install.prod_only">prod_only</a>, <a href="#yarn_install.yarn_lock">yarn_lock</a>)</pre>
202204

203205
<p>Runs yarn install during workspace setup.</p>
204206

@@ -225,16 +227,18 @@ <h3 id="yarn_install_args">Attributes</h3>
225227

226228
</td>
227229
</tr>
228-
<tr id="yarn_install.node_modules_filegroup">
229-
<td><code>node_modules_filegroup</code></td>
230+
<tr id="yarn_install.manual_build_file_contents">
231+
<td><code>manual_build_file_contents</code></td>
230232
<td>
231233
<p><code>String; Optional; Default is ''</code></p>
232-
<p>Experimental attribute that can be used to work-around
233-
a bazel performance issue if the default node_modules filegroup
234-
has too many files in it. Use it to define the node_modules
235-
filegroup used by this rule such as
236-
"filegroup(name = "node_modules", srcs = glob([...]))". See
237-
<a href="https://github.com/bazelbuild/bazel/issues/5153">https://github.com/bazelbuild/bazel/issues/5153</a>.</p>
234+
<p>Experimental attribute that can be used to override
235+
the generated BUILD.bazel file and set its contents manually.
236+
Can be used to work-around a bazel performance issue if the
237+
default node_modules filegroup has too many files in it. See
238+
<a href="https://github.com/bazelbuild/bazel/issues/5153">https://github.com/bazelbuild/bazel/issues/5153</a>. If
239+
you are running into performance issues due to a large
240+
node_modules filegroup it is recommended to switch to using
241+
fine grained npm dependencies.</p>
238242
</td>
239243
</tr>
240244
<tr id="yarn_install.package_json">

0 commit comments

Comments
 (0)