Skip to content

Commit

Permalink
chore: docs updates for 2.0 (#1887)
Browse files Browse the repository at this point in the history
* chore: docs updates for 2.0

- Add a migration guide, adapted from #1671
- Add eslint in a few spots so it's more likely users discover it
- Promote Aspect Workflows for CI/CD

* Update migrate_2.md
  • Loading branch information
alexeagle authored Aug 13, 2024
1 parent acb0f7e commit c996609
Show file tree
Hide file tree
Showing 3 changed files with 136 additions and 18 deletions.
25 changes: 12 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
# Bazel rules for JavaScript

This ruleset is a high-performance and npm-compatible Bazel integration for JavaScript.
This ruleset is a high-performance Bazel integration for JavaScript, based on the [pnpm package manager](https://pnpm.io).

- Lazy: only fetches/installs npm packages needed for the requested build/test targets.
- Correct: works seamlessly with node.js module resolution. For example there are no pathMapping issues with TypeScript `rootDirs`.
- Fast: Bazel's sandbox only sees npm packages as directories, not individual files.
<https://blog.aspect.build/rulesjs-npm-benchmarks> shows benchmarks for fetching, installing, and linking packages under rules_js as well as typical alternatives like npm and yarn.
- Supports npm "workspaces": nested npm packages in a monorepo.

Many companies are successfully building with rules_js. If you're getting value from the project, please let us know! Just comment on our [Adoption Discussion](https://github.com/aspect-build/rules_js/discussions/1000).

<https://blog.aspect.build/rulesjs-npm-benchmarks> shows benchmarks for fetching, installing, and linking packages under rules_js as well as typical alternatives like npm and yarn.

Google does not fund development of rules_js. If your company benefits, please consider donating to continue development and maintenance work: <https://opencollective.com/aspect-build/projects/rules_js>

rules_js is just a part of what Aspect provides:
rules_js is just a part Aspect's monorepo developer platform:

- [Aspect Workflows](https://docs.aspect.build/workflows) delivers on Bazel's promises of speed and cost-savings.
It provides Continuous Integration and Delivery, including Remote Cache and Remote Build Execution (RBE).
Best of all, it includes all the expertise that you expect from the team at Aspect!
- _Need help?_
- Community support is available on the #javascript channel on [Bazel Slack](https://slack.bazel.build/)
- This ruleset has commercial support provided by https://aspect.build/services.
- Best-effort community support is available on the #javascript channel on [Bazel Slack](https://slack.bazel.build/)
- Commercial support as a Slack Connect channel is offered by https://aspect.build/services.
- See our other Bazel rules, especially those built for rules_js:
- [rules_ts](https://github.com/aspect-build/rules_ts) - Bazel rules for [TypeScript](http://typescriptlang.org)
- [rules_swc](https://github.com/aspect-build/rules_swc) - Bazel rules for [swc](https://swc.rs)
Expand All @@ -28,14 +28,14 @@ rules_js is just a part of what Aspect provides:
- [rules_jasmine](https://github.com/aspect-build/rules_jasmine) - Bazel rules to run tests using [Jasmine](https://jasmine.github.io/)
- [rules_terser](https://github.com/aspect-build/rules_terser) - Bazel rules for [Terser](https://terser.org) - a JavaScript minifier
- [rules_cypress](https://github.com/aspect-build/rules_cypress) - Bazel rules to run tests using [Cypress](https://cypress.io)
- [rules_lint](https://github.com/aspect-build/rules_lint) includes [eslint support](https://github.com/aspect-build/rules_lint/blob/main/docs/eslint.md).

## Bazel compatibility

The ruleset is known to work with:

- Bazel 7 using WORKSPACE and Bzlmod _(tested on CI)_
- Bazel 6 using WORKSPACE and Bzlmod _(tested on CI)_
- Bazel 5 using WORKSPACE _(no longer tested on CI)_

> [!NOTE]
> Remote Execution (RBE) requires at least Bazel [6.0](https://blog.bazel.build/2022/12/19/bazel-6.0.html).
Expand All @@ -46,13 +46,12 @@ The ruleset is known to work with:

## Installation

From the release you wish to use:
<https://github.com/aspect-build/rules_js/releases>
copy the WORKSPACE snippet into your `WORKSPACE` file.
Follow instructions from the release you wish to use:
<https://github.com/aspect-build/rules_js/releases>.

To use a commit rather than a release, you can point at any SHA of the repo.

For example to use commit `abc123`:
For example, to use commit `abc123` with `WORKSPACE`:

1. Replace `url = "https://github.com/aspect-build/rules_js/releases/download/v0.1.0/rules_js-v0.1.0.tar.gz"`
with a GitHub-provided source archive like
Expand Down
16 changes: 11 additions & 5 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,12 @@ Stuck?
- See the [Frequently asked questions](./faq.md)
- Ask in `#javascript` on <http://slack.bazel.build>
- Check for [known issues](https://github.com/aspect-build/rules_js/issues)
- Pay for support, provided by <https://aspect.build/services>.
- Sign up for commercial support, provided as a Slack Connect channel by <https://aspect.build/services>.

## Installation

From the release you wish to use:
<https://github.com/aspect-build/rules_js/releases>
copy the WORKSPACE snippet into your `WORKSPACE` file.
Follow instructions in the release you wish to use:
<https://github.com/aspect-build/rules_js/releases>.

## Usage

Expand All @@ -38,7 +37,7 @@ Other recommendations:

### Node.js

rules_js depends on rules_nodejs version 5.0 or greater.
rules_js depends on rules_nodejs version 6.1.0 or greater.

Installation is included in the `WORKSPACE` snippet you pasted from the Installation instructions above.

Expand Down Expand Up @@ -305,6 +304,7 @@ Aspect has written a number of these based on rules_js, such as:
- [rules_terser](https://github.com/aspect-build/rules_terser) - Bazel rules for <https://terser.org/> - a JavaScript minifier
- [rules_rollup](https://github.com/aspect-build/rules_rollup) - Bazel rules for <https://rollupjs.org/> - a JavaScript bundler
- [rules_deno](https://github.com/aspect-build/rules_deno) - Bazel rules for Deno http://deno.land
- [rules_lint](https://github.com/aspect-build/rules_lint) includes [eslint support](https://github.com/aspect-build/rules_lint/blob/main/docs/eslint.md).

You can also write your own custom rule, though this is an advanced topic and not covered in this documentation.

Expand Down Expand Up @@ -364,6 +364,12 @@ Or, you can use it locally within a monorepo using [pnpm workspaces].
[gazelle]: https://github.com/bazelbuild/bazel-gazelle
[stardoc]: https://github.com/bazelbuild/stardoc

### CI/CD setup

We recommend using [Aspect Workflows](https://docs.aspect.build/workflows) which provides a pool of warm Bazel CI runners
for your existing CI system. This provides the promised Bazel speed and cost savings, with very little work required from your
developer infrastructure team!

### Debugging

Add [Debug options](https://docs.aspect.build/guides/bazelrc#debug-options) and [Options for JavaScript](https://docs.aspect.build/guides/bazelrc#options-for-javascript) to your project’s .bazelrc file to add the `--config=debug` settings for debugging Node.js programs.
Expand Down
113 changes: 113 additions & 0 deletions docs/migrate_2.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

0 comments on commit c996609

Please sign in to comment.