| commit | b2232bca9c0fb6c6f725064bab47ca3b69518d14 | [log] [tgz] |
|---|---|---|
| author | Alex Eagle <eagle@post.harvard.edu> | Wed Aug 22 17:34:02 2018 -0700 |
| committer | Copybara-Service <copybara-piper@google.com> | Wed Aug 22 17:34:16 2018 -0700 |
| tree | 5ea0b9b39b8ac85f5103b0d81c9336f486b81073 | |
| parent | e9aa7fad26a04141260e47e29f9d44e6f253dd50 [diff] |
Remove dependency on tsickle There is still a compile-time dependency, so to avoid users having to install tsickle, this depends on shipping a JS distro of @bazel/typescript on npm Closes #260 PiperOrigin-RevId: 209859448
| Circle CI | Bazel CI |
|---|---|
 |  |
WARNING: this is beta-quality software. Breaking changes are likely. Not recommended for production use without expert support.
The TypeScript rules integrate the TypeScript compiler with Bazel.
Generated documentation for using each rule is at: http://tsetse.info/api/
First, install a current Bazel distribution.
Create a BUILD.bazel file in your project root:
package(default_visibility = ["//visibility:public"]) exports_files(["tsconfig.json"]) # NOTE: this will move to node_modules/BUILD in a later release filegroup(name = "node_modules", srcs = glob([ "node_modules/**/*.js", "node_modules/**/*.d.ts", "node_modules/**/*.json", ]))
Next create a WORKSPACE file in your project root (or edit the existing one) containing:
# Include @bazel/typescript in package.json#devDependencies local_repository( name = "build_bazel_rules_typescript", path = "node_modules/@bazel/typescript", ) # Fetch our Bazel dependencies that aren't distributed on npm load("@build_bazel_rules_typescript//:package.bzl", "rules_typescript_dependencies") rules_typescript_dependencies() # Setup TypeScript toolchain load("@build_bazel_rules_typescript//:defs.bzl", "ts_setup_workspace") ts_setup_workspace() # Point to the package.json file so Bazel can run the package manager for you. load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories") node_repositories(package_json = ["//:package.json"]) # Setup Go toolchain load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains") go_rules_dependencies() go_register_toolchains() # Setup web testing, choose browsers we can test on load("@io_bazel_rules_webtesting//web:repositories.bzl", "browser_repositories", "web_test_repositories") web_test_repositories() browser_repositories( chromium = True, )
We recommend using the Yarn package manager, because it has a built-in command to verify the integrity of your node_modules directory. You can run the version Bazel has already installed:
$ bazel run @nodejs//:yarn
ts_libraryThe ts_library rule invokes the TypeScript compiler on one compilation unit, or “library” (generally one directory of source files).
Create a BUILD file next to your sources:
package(default_visibility=["//visibility:public"]) load("@build_bazel_rules_typescript//:defs.bzl", "ts_library") ts_library( name = "my_code", srcs = glob(["*.ts"]), deps = ["//path/to/other:library"], )
Then build it:
bazel build //path/to/package:target
The resulting .d.ts file paths will be printed. Additionally, the .js outputs from TypeScript will be written to disk, next to the .d.ts files 1.
Note that the tsconfig.json file used for compilation should be the same one your editor references, to keep consistent settings for the TypeScript compiler. By default, ts_library uses the tsconfig.json file in the workspace root directory. See the notes about the tsconfig attribute in the ts_library API docs.
1 The declarationDir compiler option will be silently overwritten if present.
There are two choices for development mode:
ts_devserver rule to bring up our simple, fast development server. This is intentionally very simple, to help you get started quickly. However, since there are many development servers available, we do not want to mirror their features in yet another server we maintain.ts_devserver supports. Be careful that your development round-trip stays fast (should be under two seconds).To use ts_devserver, you simply load the rule, and call it with deps that point to your ts_library target(s):
load("@build_bazel_rules_typescript//:defs.bzl", "ts_devserver", "ts_library") ts_library( name = "app", srcs = ["app.ts"], ) ts_devserver( name = "devserver", # We'll collect all the devmode JS sources from these TypeScript libraries deps = [":app"], # This is the path we'll request from the browser, see index.html serving_path = "/bundle.js", # The devserver can serve our static files too static_files = ["index.html"], )
The index.html should be the same one you use for production, and it should load the JavaScript bundle from the path indicated in serving_path.
If you don't have an index.html file, a simple one will be generated by the ts_devserver.
See examples/app in this repository for a working example. To run the devserver, we recommend you use ibazel:
$ ibazel run examples/app:devserver
ibazel will keep the devserver program running, and provides a LiveReload server so the browser refreshes the application automatically when each build finishes.
Bazel's TypeScript compiler has your workspace path mapped, so you can import from an absolute path starting from your workspace.
/WORKSPACE:
workspace(name = "myworkspace")
/some/long/path/to/deeply/nested/subdirectory.ts:
import {thing} from 'myworkspace/place';
will import from /place.ts.
Since this is an extension to the vanillia TypeScript compiler, editors which use the TypeScript language services to provide code completion and inline type checking will not be able to resolve the modules. In the above example, adding
"paths": { "myworkspace/*": ["*"] }
to tsconfig.json will fix the imports for the common case of using absolute paths. See https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping for more details on the paths syntax.
Similarly, you can use path mapping to teach the editor how to resolve imports from ts_library rules which set the module_name attribute.
If you‘d like a “watch mode”, try https://github.com/bazelbuild/bazel-watcher (note, it’s also quite new).
At some point, we plan to release a tool similar to gazelle to generate the BUILD files from your source code.
In the meantime, we suggest associating the .bazel extension with Python in your editor, so that you get useful syntax highlighting.
Start from a clean checkout at master/HEAD. Check if there are any breaking changes since the last tag - if so, this will be a minor, if not, it's a patch. (This may not sound like semver - but since our major version is a zero, the rule is that minors are breaking changes and patches are new features).
yarn skydocbazel run :gazellegit commit -a -m 'Update docs for release'npm config set tag-version-prefix ''npm version minor -m 'rel: %s' (replace minor with patch if no breaking changes)git push && git push --tagsnpm publish