Javascript

Build Typescript Project with Bazel Chapter 2: File Structure

Published Mar 30, 2020

Updated Feb 14, 2023

6 min read

Build Typescript Project with Bazel - 1 Part Series

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

Build Typescript Project with Bazel Chapter 2: File Structure

In the last chapter, we introduced the basic concept of Bazel. In this blog, I would like to talk about the file structure of Bazel.

Concept and Terminology

Before we introduce the file structure, we need to understand several key concepts and terminology in Bazel.

Workspace
Package
Target
Rule

These concepts, and terminology, are composed to Build File, which Bazel will analyze, and execute.

The basic relationship among these concepts looks like this graph , we will discuss the details one by one.

Workspace

A "workspace" refers to the directories, which contain

The source files of the project.
Symbolic links contain the build output.

And the Bazel definition is in a file named WORKSPACE, or WORKSPACE.bazel at the root of the project directory. NOTE, one project can only have one WORKSPACE definition file.

Here is an example of the WORKSPACE file.

workspace(
    name = "com_thisdot_bazel_demo",
)

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

# Fetch rules_nodejs so we can install our npm dependencies
http_archive(
    name = "build_bazel_rules_nodejs",
    sha256 = "ad4be2c6f40f5af70c7edf294955f9d9a0222c8e2756109731b25f79ea2ccea0",
    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/0.38.3/rules_nodejs-0.38.3.tar.gz"],
)

load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories", "yarn_install")

node_repositories()

yarn_install(
    name = "npm",
    package_json = "//:package.json",
    yarn_lock = "//:yarn.lock",
)

# Install all Bazel dependencies of the @npm npm packages
load("@npm//:install_bazel_dependencies.bzl", "install_bazel_dependencies")

install_bazel_dependencies()

# Setup the rules_typescript toolchain
load("@npm_bazel_typescript//:index.bzl", "ts_setup_workspace")

ts_setup_workspace()

In a WORKSPACE file, we should

Define the name of the workspace. The name should be unique globally, or at least unique in your organization. You could use the reverse dns name, such as com_thisdot_bazel_demo, or the name of the project on GitHub.
Install environment related packages, such as yarn/npm/bazel.
Setup toolchains needed to build/test the project, such as typescript/karma.

Once WORKSPACE is ready, application developers don't really need to touch this file.

Package

The primary unit of code organization (something like module) in a repository
Collection of related files and a specification of the dependencies among them
Directory containing a file named BUILD or BUILD.bazel, residing beneath the top-level directory in the workspace
A package includes all files in its directory, plus all subdirectories beneath it, except those which, themselves, contain a BUILD file

It is important to know how to split a project into package. It should be easy for the users to develop/test/share the unit of a package. If the unit is too big, the package has to be rebuilt on every package file change. If the unit is too small, it will be very hard to maintain and share. So, this is not an issue of Bazel. It is a general problem of project management.

In Bazel, every package will have a BUILD.bazel file, containing all of the build/test/bundle target definitions.

For example, here is a screenshot of the Angular structure. Every directory under packages directory is a package of code organization, and also the build organization of Bazel.

Let's take a look at the file structure of gulpjs in Angular, so we can have a better understanding about the difference between Bazel and gulpjs.

gulp.task('build-animations', () => {});;
gulp.task('build-core', () => {});
gulp.task('build-core-schematics', () => {});

In most cases,

a gulpjs file doesn't have 1:1 relationship to the package directory.
a gulpjs file can reference any files inside the project.

But for Bazel,

Each package should have their own BUILD.bazel file.
The BUILD.bazel can only reference the file inside the current package, and if the current package depends on other packages, we need to reference the Bazel build target from the other packages instead of the files directly.

Here is a Bazel Package directory structure in Angular repo. Angular

Build File

Before we talk about target, let's take a look at the content of a BUILD.bazel file.

package(default_visibility = ["//visibility:private"])

load("@npm_bazel_typescript//:index.bzl", "ts_library")

ts_library(
    name = "lib",
    srcs = [":lib.ts"],
    visibility = ["//visibility:public"],
)

The language of the BUILD.bazel file is Starlark.

Starlark is a subset of Python.
It is a very feature-limited language. A ton of Python features, such as class, import, while, yield, lambda, is, raise, are not supported.
Recursion is not allowed.
Most of Python's builtin methods are not supported.

So Starlark is a very very simple language, and only supports very limited Python syntax.

Target

The BUILD.bazel file contains build targets. Those targets are the definitions of the build, test, and bundle work we want to achieve.

The build target can represent:

Files
Rules

The target can also depend on other targets

Circular dependencies are not allowed
Two targets, generating the same output, will cause a problem
Target dependency must be declared explicitly.

Let's see the previous sample,

package(default_visibility = ["//visibility:private"])

load("@npm_bazel_typescript//:index.bzl", "ts_library")

ts_library(
    name = "lib",
    srcs = [":lib.ts"],
    visibility = ["//visibility:public"],
)

Here, ts_library is a rule imported from @npm_bazel_typescript workspace, and ts_library(name = "lib") is a target. The name is lib, and this target defines the metadata for compiling the lib.ts with ts_library rule.

Label

Every target has a unique name called label. For example, if the BUILD.bazel file above is under /lib directory, then the label of the target is

@com_thisdot_bazel_demo//lib:lib

The label is composed of several parts.

the name of the workspace: @com_thisdot_bazel_demo.
the name of the package: lib.
the name of the target: lib.

So, the composition is <workspace name>//<package name>:<target name>.

Most of the times, the name of the workspace can be omitted, so the label above can also be expressed as //lib:lib.

Additionally, if the name of the target is the same as the package's name, the name of the target can also be omitted. Therefore, the label above can also be expressed as //lib.

NOTE: The label for the target needs to be unique in the workspace.

Visibility

We can also define the visibility to define whether the rule inside this package can be used by other packages.

package(default_visibility = ["//visibility:private"])

The visibility can be:

private: the rules can be only used inside the current package.
public: the rules can be used everywhere.
//some_package:package_scope: the rules can only be used in the specified scope under //some_package. The package_scope can be: __pkg__/__subpackages__/package group.

And if the rules in one package can be accessed from the other package, we can use load to import them. For example:

load("@npm_bazel_typescript//:index.bzl", "ts_library")

Here, we import the ts_library rule from the Bazel typescript package.

Target

Target can be Files or Rule.
Target has input and output. The input and output are known at build time.
Target will only be rebuilt when input changes.

Let's take a look at Rule first.

Rule

The rule is just like a function or macro. It can accept named parameters as options. Just like in the previous post, calling a rule will not execute an action. It is just metadata. Bazel will decide what to do.

ts_library(
    name = "lib",
    srcs = [":lib.ts"],
    visibility = ["//visibility:public"],
)

So here, we use the ts_library rule to define a target, and the name is lib. The srcs is lib.ts in the same directory. The visibility is public, so this target can be accessed from the other packages.

Rule Naming

It is very important to follow the naming convention when you want to create your own rule.

*_binary: executable programs in a given language (nodejs_binary)
*_test: special _binary rule for testing
*_library: compiled module for a given language (ts_library)

Rule common attributes

Several common attributes exist in almost all rules. For example:

ts_library(
    name = "lib",
    srcs = [":index.ts"],
    tags = ["build-target"],
    visibility = ["//visibility:public"],
    deps = [
        ":date",
        ":user",
    ],
)

name: unique name within this package
srcs: inputs of the target, typically files
deps: compile-time dependencies
data: runtime dependencies
testonly: target which should be executed only when running Bazel test
visibility: specifies who can make a dependency on the given target

Let's see another example:

http_server(
   name = "prodserver",
   data = [
       "index.html",
       ":bundle",
       "styles.css",
   ],
)

Here, we use the data attribute. The data will only be used at runtime. It will not be analyzed by Bazel at build time.

So, in this blog, we introduced the basic Bazel structure concepts. In the next blog, we will introduce how to query Bazel targets.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Jia Li
Jia Li is a frontend developer with passion, he is an Angular Collaborator and the code owner of angular/zone.js. He loves Angular and now develops Angular enterprise application.
@JiaLiPassion @JiaLiPassion

Build Typescript Project with Bazel Chapter 1: Bazel introduction

Bazel is a fast, scalable, incremental, and universal (for any languages/frameworks) build tool, and is especially useful for big mono repo projects. I would like to write a series of blogs to introduce the concept of how to build a typescript project with Bazel. - Chapter 1: Bazel Introduction - Chapter 2: Bazel file structure and Bazel Query - Chapter 3: Build/Develop/Test a typescript project In chapter 1, I would like introduce basic Bazel concepts, and define some of the benefits we can expect from using Bazel. - What is Bazel? - Bazel: Correctness - Bazel: Fast - Bazel: Universal - Bazel: Industrial grade What is Bazel? As you may know, we already have a lot of build tools. They include: - CI tools: Jenkins/CircleCI - Compile tools: tsc/sass - Bundle tools: webpack/rollup - Coordinate tools: make/grunt/gulp So what is Bazel? Does it simply replace Jenkins or Webpack? @AlexEagle helped us answer this question at ngconf 2019, but here is a great picture that will explain a little as well. So Bazel is a build tool, used to coordinate other tools (compile/bundle tools), and will use all the existing tools (such as tsc/webpack/rollup) to do the underlying work. Another graph, also from @AlexEagle, will show this relationship more clearly. Ok, so Bazel is at the same position as Gulp, why not continue to use Gulp? To answer this question, let's think about what the goal of the build tool is. - Essential: - Correct - don't need to worry about environmental pollution. - Fast - Incremental - Parallelism - Predictable - Same input will guarantee the same output. - Reusable - Build logic can be easily composed and reused. - Nice to have: - Universal - support multiple languages and frameworks. Correctness This is the most important requirement. We all want our build systems to be stable, and we don't want them to generate unexpected results. Therefore, we want every build to be executed in an isolated environment. Otherwise, we will run into problems if, for example, we forget to delete some temp files, forget to reset environment variables, or if the build only works under certain conditions. - Sandboxing: Bazel supports sandboxing to isolate the environment. When we do a Bazel build, it will create an isolated working folder, and Bazel will run the build process under this folder. This is what we would call "sandboxing". Bazel will then restrict the access to the files outside of this folder. Also, Bazel makes sure that elements of the build tool, such as the compiler, only know their own input files, so the output will only depend on input. - The rule can only access an input file. Unlike a Gulp task, a Bazel rule can only access the files declared as input (we will talk about the target/rule in detail later). Here is an example of a Gulp task: ` So inside of a Gulp task, there is just a normal function. There is no concept of Input, and dependencies only tells gulp to run tasks in a specified order, so the task can access any files, and use any environmental variables with no restrictions. Gulp will have no idea which files are used in this task, so if some logic depends on the unintended file access/environment reference, it is impossible for Gulp to guarantee that the task will always generate the same results. Let's see a Bazel target. ` We will talk about the Bazel target/rule in more detail in the next chapter. Here, we will declare a Bazel target with a ts_library rule. Unlike with a Gulp task, here we have a strict input which is srcs = ["a.ts"], so when Bazel decides to execute this target, the typescript compiler can only access the file a.ts inside of the sandbox, and nowhere else. Therefore, there is no way that the Bazel target will produce wrong results because of the unpredictable environment or input. Fast Bazel is incremental because Bazel is declarative and predictable. Bazel is Declarative Let's use Gulp to compile those two files, in order to demonstrate that Gulp is imperative and Bazel is declarative. Let's see an example with Gulp. ` When we run gulp test for the first time, both the compile, and the test tasks will be executed. And then, even if we don't change any files, those two tasks will still be executed if we run gulp test again. Gulp is imperative, so we just have to tell it to do those two commands, and Gulp will do what we asked. Specifically, it checks the dependency, and guarantees the execution order. That's all. Let's see how Bazel works. Here, we have two typescript files: user.ts, and print.ts. print.ts uses user.ts. ` ` To demonstrate that Bazel is declarative, let's use two Bazel build targets. ` So we declare two Bazel targets, user, and print. The print target depends on the user target. All those targets are using the ts_library rule. It contains the metadata to tell Bazel how to compile the typescript files. And again, all this information is just a definition. It's not about commands, so when you use Bazel to build those targets, it is up to Bazel to decide whether to execute those rules or not. Let's see the result first. When we run bazel build //src:print, both the user and print targets will be compiled, which makes sense. When we run bazel build //src:print again, you will find Bazel will not run any targets because nothing changed, and Bazel knows it. As a result, Bazel decides not to run any targets. Let's change something in user.ts, and see what happens. ` After we run bazel build //src:print again, we may expect that both user and print will be compiled once more because user.ts has been changed, and print.ts references user.ts, and the print target depends on the user target. But the result is that only the user target has been compiled, and the print target has not. Why? This is because changes in user.ts don't impact print.ts, and Bazel understands this. Let's check out the following graph, which describes the input/output of the target. So for user target, the input is user.ts, and we have two outputs. One is user.js, and the other is user.d.ts. The latter of the two is the typescript declaration file. So let's see the relationship between the user, and print target. Here, we can see that the print target depends on the user target, and that it uses one of the user target's outputs, user.d.ts, as it's own input. So, because we only updated toString of user.ts, and the user.d.ts was not changed at all, Bazel analyses the dependency graph. As a result, it knows that only user target needs to be built. Further, it also knows that the print target doesn't need to be built because the inputs of the print target, which are user.d.ts and print.ts, have not changed. Because of this, Bazel decides not to build print target. It is very important to remember that Bazel is declarative and not imperative. Bazel analyses the input/output of all build targets to determine which targets need to be executed. (We can generate the dependency graph with bazel query, and we will talk about it in the next chapter.) So Bazel can do incremental builds based on the analysis of the dependency graph, and only build the really impacted targets. Bazel is Predictable (Bazel's Rules are Pure Functions) Also, all Bazel rules are pure functions, so the same input will always result in the same output, hence Bazel is predictable. We can use the input as a key to cache the result of each target, and save the cache locally or remotely. For example, developer 1 builds some targets, and pushes the result to remote cache. The other developer can then directly use this cache without building those targets in their own environment. So these amazing features make Bazel super fast. Universal Bazel is a coordinate tool. It doesn't rely on any specified languages/frameworks, and it can build within almost all languages/frameworks from server to client, and from desktop to mobile. It is difficult and costly to employ a specialist team to handle builds with several build tools/frameworks when working on a full-stack project. In one of my previous projects, we used Maven to build a Java backend, used Webpack to build its frontend, and used XCode and Gradle to build iOS and Android clients. Consequently, we needed a special build team consisting of people that knew all of those build tools, which makes it very difficult to do an incremental build, cache the results, or share the build script with other projects. Bazel is also a perfect tool for mono repo, and full-stack projects that include multiple languages/frameworks. Industrial Grade Bazel is not an experimental project. It is used in almost all projects inside Google. When I started contributing to Angular, I did not use Bazel. Because of this, the time that Angular CI was taking was about 1 hour. Once Bazel was introduced to Angular CI, the time reduced to about 15 minutes, and the build process became much more stable, and less flaky than before, even with double the amount of test cases. It is amazing! I believe that Bazel will be the "must have" tool for many big projects. I really like Bazel, and in the next blog post, I would like to introduce Bazel's file structure with bazel query. Thanks for reading, and any feedback is appreciated....

Jan 8, 2020

8 mins

Bazel

Angular 11 Released

I'm so excited to see the recent release of Angular v11.0.0! There are lot of improvements especially with regards to tooling. What's new in the release CLI: Inlining of Google Fonts First, contentful paint is always the critical part for performance. [Eliminate render-blocking resources] (https://web.dev/render-blocking-resources/) is an important guide to improve the FCP performance, and Angular is also working on following the guide to inline the blocking resources. In Angular v11, the Google Fonts will be inline by adding the following options to the angular.json. ` And without this option, your Google font importing looks like this. ` After activating this optimization, it looks like this. ` CLI: Hot Module Replacement Support Angular supports HMR for a while, but to make it work requires configuration and code changes, which is not a good developer experience. From v11, it is simple to enable the HMR support by using ` Now, the live reload will also keep the state of your application, so it is much easier to apply some small updates to your application. CLI: Experimental Webpack 5 support Webpack 5 supports many new features such as: - Module federation which is a new way to develop micro-frontend - Disk caching for faster build - Better tree shaking Now, you can opt-in the Webpack 5 by adding the following section in the package.json file. ` CLI: ng build better output Now, running ng build will generate more clear output. CLI: ng serve ask for new port It is a really nice feature! If the 4200 port is in use, ng serve will ask you for a different port without re-run with --port option. ` CLI: Lint Now, Angular uses TSLint as the default linter, and since TSLint is deprecated now, Angular uses angular-eslint to replace TSLint/Codelyzer. Here is the migration guide. Features: Trusted Types support Trusted Types is a new solution to prevent DOM-based cross-site scripting vulnerabilities. Consider the following example: ` With Trusted Types enabled, the browser throws a TypeError and prevent this behavior. To tell the browser this is a trusted safe operation, you need to do it like this: ` Note that the aTrustedHtml is a TrustedHtml object. It looks similar to the DomSanitizer's functionality, so now Angular permits support to allow such an operation to return a Trusted Types. Tooling - Typescript is updated to v4.0 Deprecations - IE 9,10 and IE mobile are no longer supported. - ViewEncapsulation.Native has been removed. - async test helper function is renamed to waitForAsync. For the full deprecation list, please check here. Triaging issues and PRs The Angular team put forward a significant effort to go through all the issues/PRs now opened in the GitHub, and check/triage these issues to make sure that they are at the correct state. It greatly helps the community to get better/faster support and feedback. I am so honored to also take part in this process. How to update to v11 It is very simple. Just use the Angular CLI. ` You can find more information from update.angular.io/ and also from the official blog....

Nov 20, 2020

3 mins

Angular

“We were seen as amplifiers, not collaborators,” Ashley Willis, Sr. Director of Developer Relations at GitHub, on How DevRel has Changed, Open Source, and Holding Space as a Leader

Ashley Willis has seen Developer Relations evolve from being on the sidelines of the tech team to having a seat at the strategy table. In her ten years in the space, she’s done more than give great conference talks or build community—she’s helped shape what the DevRel role looks like for software providers. Now as the Senior Director of Developer Relations at GitHub, Ashley is focused on building spaces where developers feel heard, seen, and supported. > “A decade ago, we were seen as amplifiers, not collaborators,” she says. “Now we’re influencing product roadmaps and shaping developer experience end to end.” DevRel Has Changed For Ashley, the biggest shift hasn’t been the work itself—but how it’s understood. > “The work is still outward-facing, but it’s backed by real strategic weight,” she explains. “We’re showing up in research calls and incident reviews, not just keynotes.” That shift matters, but it’s not the finish line. Ashley is still pushing for change when it comes to burnout, representation, and sustainable metrics that go beyond conference ROI. > “We’re no longer fighting to be taken seriously. That’s a win. But there’s more work to do.” Talking Less as a Leader When we asked what the best advice Ashley ever received, she shared an early lesson she received from a mentor: “Your presence should create safety, not pressure.” > “It reframed how I saw my role,” she says. “Not as the one with answers, but the one who holds the space.” Ashley knows what it’s like to be in rooms where it’s hard to speak up. She leads with that memory in mind, and by listening more than talking, normalizing breaks, and creating environments where others can lead too. > “Leadership is emotional labor. It’s not about being in control. It’s about making it safe for others to lead, too.” Scaling More Than Just Tech Having worked inside high-growth companies, Ashley knows firsthand: scaling tech is one thing. Scaling trust is another. > “Tech will break. Roadmaps will shift. But if there’s trust between product and engineering, between company and community—you can adapt.” And she’s learned not to fall for premature optimization. Scale what you have. Don’t over-design for problems you don’t have yet. Free Open Source Isn’t Free There’s one myth Ashley is eager to debunk: that open source is “free.” > “Open source isn’t free labor. It’s labor that’s freely given,” she says. “And it includes more than just code. There’s documentation, moderation, mentoring, emotional care. None of it is effortless.” Open source runs on human energy. And when we treat contributors like an infinite resource, we risk burning them out, and breaking the ecosystem we all rely on. > “We talk a lot about open source as the foundation of innovation. But we rarely talk about sustaining the people who maintain that foundation.” Burnout is Not Admirable Early in her career, Ashley wore burnout like a badge of honor. She doesn’t anymore. > “Burnout doesn’t prove commitment,” she says. “It just dulls your spark.” Now, she treats rest as productive. And she’s learned that clarity is kindness—especially when giving feedback. > “I thought being liked was the same as being kind. It’s not. Kindness is honesty with empathy.” The Most Underrated GitHub Feature? Ashley’s pick: personal instructions in GitHub Copilot. Most users don’t realize they can shape how Copilot writes, like its tone, assumptions, and context awareness. Her own instructions are specific: empathetic, plainspoken, technical without being condescending. For Ashley, that helps reduce cognitive load and makes the tool feel more human. > “Most people skip over this setting. But it’s one of the best ways to make Copilot more useful—and more humane.” Connect with Ashley Willis She has been building better systems for over a decade. Whether it’s shaping Copilot UX, creating safer teams, or speaking truth about the labor behind open source, she’s doing the quiet work that drives sustainable change. Follow Ashley on BlueSky to learn more about her work, her maker projects, and the small things that keep her grounded in a fast-moving industry. Sticker Illustration by Jacob Ashley....

Apr 18, 2025

3 mins

Engineering LeadershipGitHub

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Build Typescript Project with Bazel Chapter 2: File Structure

Build Typescript Project with Bazel - 1 Part Series

Build Typescript Project with Bazel Chapter 2: File Structure

Concept and Terminology

Workspace

Package

Build File

Target

Label

Visibility

Target

Rule

Rule Naming

Rule common attributes

Jia Li

You might also like

Build Typescript Project with Bazel Chapter 1: Bazel introduction

Angular 11 Released

“We were seen as amplifiers, not collaborators,” Ashley Willis, Sr. Director of Developer Relations at GitHub, on How DevRel has Changed, Open Source, and Holding Space as a Leader

Let's innovate together!

You might also like

Build Typescript Project with Bazel Chapter 1: Bazel introduction

Angular 11 Released

“We were seen as amplifiers, not collaborators,” Ashley Willis, Sr. Director of Developer Relations at GitHub, on How DevRel has Changed, Open Source, and Holding Space as a Leader