Configuration Directives

You can configure Aspect CLI using directives, which are specially-formatted comments in BUILD files that govern behavior of the tool when visiting files within the Bazel package rooted at that file.

There are generic gazelle directives that apply to any language, Aspect directives supported by Aspect authored languages, and directives specific to individual languages.

Aspect CLI

Directives supported by Aspect languages.

Directive	Default value
# gazelle:generation_mode none\|update\|create	create

| Traditionally gazelle generates new BUILD files in each and every directory.
This directive allows you to control whether gazelle should only update existing BUILD files or create new BUILD files, or neither.

Go

Go directives for generating BUILD files are from the standard gazelle go directives.

JavaScript

JavaScript directives for generating BUILD files follow the same format as gazelle. You can use generic directives from the gazelle directives, as well as JS/TS specific directives to configure the generation of BUILD files including which targets are generated.

Source files are collected into the srcs of ts_project targets. By default targets are generated for tests and library targets. Source globs can be configured using js_[test_]files glob directives.

Additional custom targets can be generated using the js_[test_]files target_name glob directives.

If a package.json file exists declaring npm dependencies, a npm_link_all_packages target is generated for declaring depending on individual NPM packages.

If the package.json is a pnpm workspace project a npm_package or js_library target will be generated for the package, the target type may be configured using the js_package_rule_kind directive.

Finally, the import statements in the source files are parsed, and dependencies are added to the deps attribute of the appropriate ts_project target which the source file belongs to.

Dependencies may also be found other ways such as from the CommonJS require function.

Directive	Default value
# gazelle:js enabled\|disabled	enabled
Enable the JavaScript directives.
# gazelle:js_tsconfig enabled\|disabled	enabled
Enable generation of ts_config rules. This value is inherited by sub-directories and applied relative to each BUILD. The ts_project(tsconfig) attribute is NOT set and must be done manually if necessary
# gazelle:js_npm_package enabled\|disabled\|referenced	referenced
Enable generation of npm_package targets. When set to referenced (DEPRECATED) npm_package targets will only be generated for packages that are referenced by other projects.
# gazelle:js_npm_package enabled\|disabled\|referenced	referenced
Enable generation of npm_package targets. DEPRECATED: referenced will only generate npm_package targets for packages that are referenced by other projects.
# gazelle:js_package_rule_kind js_library\|npm_package	npm_package
The target type to use for the npm package rule.
# gazelle:js_pnpm_lockfile _lockfile_	pnpm-lock.yaml
Path to the pnpm-lock.yaml file containing available npm packages. This value is inherited by sub-directories and applied relative to each BUILD.
# gazelle:js_ignore_imports _glob_
Imports matching the glob will be ignored when generating BUILD files in the specifying directory and descendants.
# gazelle:js_resolve _glob_ _target_
Imports matching the glob will be resolved to the specified target within the specifying directory and descendants. This directive is an extension of the standard resolve directive with added glob support and only applying to JavaScript rules.
# gazelle:js_validate_import_statements error\|warn\|off	error
Ensure all import statements map to a known dependency.
# gazelle:js_project_naming_convention _name_	{dirname}
The format used to generate the name of the main ts_project rule.
# gazelle:js_tests_naming_convention _name_	{dirname}_tests
The format used to generate the name of the test ts_project rule.
# gazelle:js_files [custom_target_name] _glob_	**/*.{ts,tsx,mts,cts}
A glob pattern for files to be included in the main ts_project target, or a custom target. Multiple patterns can be specified by using the js_files directive multiple times. When specified the inherited configuration is replaced, not extended.
# gazelle:js_test_files [custom_target_name] _glob_	**/*.{spec,test}.{ts,tsx,mts,cts}
Equivalent to js_files but for the test ts_project target, or a custom test target.
# gazelle:js_npm_package_target_name _name_	{dirname}
The format used to generate the name of the npm_package target.
# gazelle:js_generation_mode update\|create	create
DEPRECATED: see generation_mode directive.
# gazelle:js_custom_files _name_ _glob_
DEPRECATED: use # gazelle:js_files name glob
# gazelle:js_custom_test_files _name_ _glob_
DEPRECATED: use # gazelle:js_test_files name glob