Bazel Gazelle rule that generates BUILD file content for javascript/typescript code.
examples/nextjs contains an end-to-end working example of BUILD file generation for an example next.js project. It may be helpful to reference when configuring your project
To use this extension in a project, you'll need to add Gazelle and its dependencies to your WORKSPACE
file.
Follow the instructions at https://github.com/bazelbuild/bazel-gazelle#running-gazelle-with-bazel
Many of the rules generated by this extension also depend on rules_js, instructions for installing rules_js can be found at https://github.com/aspect-build/rules_js
Then add this repository to your WORKSPACE
file:
http_archive(
name = "com_github_benchsci_rules_nodejs_gazelle",
sha256 = "************",
strip_prefix = "rules_nodejs_gazelle-0.4.0",
urls = [
"https://github.com/benchsci/rules_nodejs_gazelle/archive/refs/tags/v0.4.0.tar.gz",
],
)
Once you have set up a gazelle
rule by following the installation instructions in Gazelle
, you can add this extension as a language.
It should look something like this:
load("@bazel_gazelle//:def.bzl", "DEFAULT_LANGUAGES", "gazelle", "gazelle_binary")
gazelle(
name = "gazelle",
gazelle = ":gazelle_js",
)
gazelle_binary(
name = "gazelle_js",
languages = DEFAULT_LANGUAGES + [
"@com_github_benchsci_rules_nodejs_gazelle//gazelle",
],
)
If you are using NPM for your project, you will probably want to add at least these directives (more on directives below) to your root BUILD
file as well:
# gazelle:exclude **/node_modules
# gazelle:exclude tsconfig.json
# gazelle:js_package_file package.json :node_modules
# gazelle:js_web_asset .json,.css,.scss
# gazelle:js_collect_all_assets
# gazelle:js_root
If you have custom implementations of the rules generated by this extension, you may wish to re-map them with the map_kind
directive:
# gazelle:map_kind js_library js_library @build_bazel_rules_nodejs
# gazelle:map_kind ts_project ts_project @my_local_repo
Gazelle can be configured with directives, which are written as top-level comments in build files.
Directive comments have the form # gazelle:key value
.
More information here
Directives apply in the directory where they are set and in subdirectories.
This means, for example, if you set # gazelle:prefix
in the build file
in your project's root directory, it affects your whole project. If you
set it in a subdirectory, it only affects rules in that subtree.
Example of most of these directives can be found in tests
The following directives are recognized by this plugin:
Directive | Default value |
---|---|
# gazelle:js_extension |
enabled |
Controls whether the JS extension is enabled or not. Sub-packages inherit this value. Can be either "enabled" or "disabled". |
|
# gazelle:js_default_npm_label |
//:node_modules |
Defines the label prefix for third npm dependencies. |
|
# gazelle:js_lookup_types true|false |
true |
Causes Gazelle to try and find a matching "@types/pkg" dependency for each "pkg" dependency, including @types/node for Node.js builtins |
|
# gazelle:js_package_file package.json :node_modules |
//:node_modules |
Instructs Gazelle to use a package.json file to lookup imports from dependencies and devDependencies |
|
# gazelle:js_import_alias some_folder other |
none |
Specifies partial string substitutions applied to imports before resolving them. Eg. |
|
# gazelle:js_visibility label |
none |
By default, internal packages are only visible to its siblings. This directive adds a label internal packages should be visible to additionally. This directive can be used several times, adding a list of labels. |
|
# gazelle:js_root |
workspace root |
Specifies the current package (folder) as a JS root. Imports for JS and TS consider this folder the root level for relative and absolute imports. This is used on monorepos with multiple Python projects that don't share the top-level of the workspace as the root. |
|
# gazelle:js_collect_all |
none |
Stops recursion into subdirectories of the folder containing the directive, and collects all sources and tests into a single rule. Use this to reduce rule count for large repositories. See |
|
# gazelle:js_collect_barrels true|false |
false |
Generate 1 js_library, or ts_project rule per package when a |
|
# gazelle:js_collect_web_assets true|false |
false |
Causes Gazelle to generate 1 web_assets rule, rather than 1 per file |
|
# gazelle:js_collect_all_assets true|false |
false |
Generates a |
|
# gazelle:js_web_asset .json,.css,.scss |
none |
Files with a matching suffix will have |
|
# gazelle:js_quiet true|false |
false |
Silence extension warnings about missing imports (overrides gazelle:js_verbose) |
|
# gazelle:js_verbose true|false |
false |
Print more information about missing imports (overrides gazelle:js_quiet) |
|
# gazelle:js_jest_config :my_config |
none |
Provide a default label for the |
|
# gazelle:js_jest_size |
none |
Provide a default value for the |
|
# gazelle:js_jest_test_per_shard |
none |
Provide a ratio of number of counted tests for each increment of the |