rules_closure for Bazel

The closure_js_test macro runs JavaScript unit tests inside a headless web browser (PhantomJS). It composes closure_js_library, closure_js_binary, and phantomjs_test.

Test Definition Requirements:

• A test is any function in the global namespace starting with test, setUp, or tearDown.
• If using goog.module or goog.scope, you must register test functions with goog.testing.testSuite.
• Test files should require goog.testing.jsunit and goog.testing.asserts.
• It is recommended to include goog.setTestOnly() in test-related files.

Environment Constraints:

• Tests run in a hermetically sealed environment with no network access. You cannot send HTTP requests to external servers; use Closure Library mocks for XHR instead.
• A local HTTP server is provided to request runfiles via the /filez/WORKSPACE_NAME/ path.

Arguments:

• srcs: List of _test.js source files.
• compilation_level: Setting this to "WHITESPACE_ONLY" makes tests run significantly faster by skipping type checking.

load("@rules_closure//closure:defs.bzl", "closure_js_test")

closure_js_test(
    name = "my_test",
    srcs = ["//path/to:test_js"],
    deps = ["//path/to:lib"],
    compilation_level = "WHITESPACE_ONLY",
)

The closure_js_binary rule turns JavaScript libraries into a minified, optimized blob of code. It must be used in conjunction with closure_js_library rules.

Implicit Outputs:

• {name}.js: A minified JavaScript file containing all transitive sources.
• {name}.js.map: A sourcemap file for debugging compiled sources in browsers like Chrome or Firefox.

Key Configuration Options:

• compilation_level: Controls minification intensity.
  • ADVANCED (Default): Maximal minification and type checking. Strongly recommended for production. Note: Properties accessed via dot notation will be renamed; use quoted notation (e.g., foo['bar']) to prevent this.
  • SIMPLE: Functions like a traditional minifier. Type checking is disabled. Local variables are minified, but object properties and globals are not.
  • WHITESPACE_ONLY: Strips whitespace and comments only. No renaming or inlining.
• debug: (Boolean, default False) Enables debug mode. Renames properties/variables with $ to help spot bugs in ADVANCED mode, preserves assert statements, and keeps dependency directives.
• entry_points: (List of Strings) A list of unreferenced namespaces that should not be pruned. Use this for functions you intend to call directly from a <script> tag in HTML.
• output_wrapper: (String) Wraps the output. To avoid polluting the global namespace, it is recommended to use "(function(){%output%}).call(this);".

load("@rules_closure//closure:defs.bzl", "closure_js_binary")

closure_js_binary(
    name = "foo_bin",
    deps = ["//path/to:lib"],
    compilation_level = "ADVANCED",
    debug = False,
    entry_points = ["my.namespace.entry"],
    output_wrapper = "(function(){%output%}).call(this);"
)

Use closure_css_library to define a set of CSS or GSS stylesheets. This rule does not perform compilation itself; it is a provider used by closure_css_binary to produce minified CSS.

Integration with JavaScript: If your closure_js_library sources contain calls to goog.getCssName('foo') where 'foo' is a class name defined in this library, you must add this closure_css_library target to the deps of that JavaScript library.

Ordering and Dependencies:

• The order of stylesheets in srcs is undefined.
• If one CSS file overrides another, they must be placed in separate closure_css_library targets. Bazel will then use depth-first preordering of dependencies to ensure correct CSS cascading.
• It is strongly recommended to use @provide and @require statements in your stylesheets to allow the compiler to verify ordering accuracy.

load("@rules_closure//closure:defs.bzl", "closure_css_library")

closure_css_library(
    name = "my_css_lib",
    srcs = ["""style.gss"""],
    data = ["""logo.png"""],
    deps = ["//path/to/other_css_lib"],
    orientation = "LTR",
)

Use closure_css_binary to turn stylesheets defined by closure_css_library rules into a single minified CSS file. This rule evaluates Closure-specific syntax (variables, functions, conditionals, mixins) into standard CSS.

Key Features:

• Class Name Minification: By default, it minifies class names (e.g., .foo-bar becomes .a-b). To support this, you must use goog.getCssName("foo-bar") in your JavaScript and point the css attribute of your closure_js_binary to this target.
• Implicit Outputs:
  • name.css: The minified CSS file.
  • name.css.map: A CSS sourcemap for browser debugging.
  • name.css.js: A JavaScript file containing goog.setCssNameMapping(). This is used by the build system to sync minified names between CSS and JS. If rendering Soy templates from Java, you may need to parse this file manually.

Orientation Conversion: If the orientation argument differs from the orientation of the input libraries, the rule will automatically flip 'left' and 'right' values in direction-sensitive style rules.

load("@rules_closure//closure:defs.bzl", "closure_css_binary")

closure_css_binary(
    name = "my_css_bin",
    deps = ["//path/to:my_css_lib"],
    renaming = True,
    debug = False,
    orientation = "LTR",
)

The closure_css_binary rule accepts the following arguments:

closure_css_binary(
    name = "my_css_bin",
    deps = ["//path/to:my_css_lib"],
    renaming = True,
    orientation = "RTL",
    vendor = "WEBKIT",
)

The closure_js_library rule accepts the following arguments: