From a8d8b0f618ee1977d35c6da27bd9a01cde9b7fd0 Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Wed, 24 Mar 2021 13:29:32 -0700 Subject: [PATCH] fix(typescript): update documentation now that ts_project is recommended (#2548) We don't deprecated ts_library yet --- packages/typescript/BUILD.bazel | 4 +- packages/typescript/_README.md | 135 +++++++++ packages/typescript/install.md | 306 -------------------- packages/typescript/internal/build_defs.bzl | 81 +++++- 4 files changed, 213 insertions(+), 313 deletions(-) create mode 100644 packages/typescript/_README.md delete mode 100644 packages/typescript/install.md diff --git a/packages/typescript/BUILD.bazel b/packages/typescript/BUILD.bazel index 64c07e41c7..33f3cf9d4e 100644 --- a/packages/typescript/BUILD.bazel +++ b/packages/typescript/BUILD.bazel @@ -63,10 +63,10 @@ genrule( name = "generate_README", srcs = [ "index.md", - "install.md", + "_README.md", ], outs = ["README.md"], - cmd = """cat $(execpath install.md) $(execpath index.md) | sed 's/^##/\\\n##/' > $@""", + cmd = """cat $(execpath _README.md) $(execpath index.md) | sed 's/^##/\\\n##/' > $@""", tags = ["fix-windows"], visibility = ["//docs:__pkg__"], ) diff --git a/packages/typescript/_README.md b/packages/typescript/_README.md new file mode 100644 index 0000000000..4dc39f7252 --- /dev/null +++ b/packages/typescript/_README.md @@ -0,0 +1,135 @@ +# TypeScript rules for Bazel + +The TypeScript rules integrate the TypeScript compiler with Bazel. + +## Alternatives + +This package provides Bazel wrappers around the TypeScript compiler. + +At a high level, there are three alternatives provided: `tsc`, `ts_project`, `ts_library`. +This section describes the trade-offs between these rules. + +### tsc + +`tsc` is the TypeScript compiler published by the team at Microsoft. +You can call it without any custom Bazel rules. + +To use this option, you **do not need to install the `@bazel/typescript` package**. + +The only reason to use raw `tsc` is if you want to compile a directory of `.ts` files and cannot enumerate them ahead-of-time in your BUILD file so that Bazel can predict all the output files. +(For example if the `.ts` files are generated by some tool). +This will produce an opaque directory of `.js` file outputs, which you won't be able to individually reference. + +Any other use case for `tsc` is better served by using `ts_project`, see below. + +Like we do for any npm package that exposes a binary, rules_nodejs will see your dependency on +`typescript` and will generate an `index.bzl` file allowing you to run `tsc`. +To use it, add the load statement `load("@npm//typescript:index.bzl", "tsc")` to your BUILD file. +(Possibly replacing `@npm` with the name of the repository where you installed dependencies) + +Then call it, using the [`npm_package_bin`](Built-ins#npm_package_bin) documentation. + +Here is an example: +https://github.com/bazelbuild/rules_nodejs/blob/3.2.2/internal/node/test/BUILD.bazel#L491-L507 + +### ts_project + +`ts_project` simply runs `tsc --project`, with Bazel knowing which outputs to expect based on the TypeScript compiler options, +and with interoperability with other TypeScript rules via the [DeclarationInfo] Provider that transmits the type information. + +It is intended as an easy on-boarding for existing TypeScript code and should be familiar if your background is in frontend ecosystem idioms. + +Any behavior of `ts_project` should be reproducible outside of Bazel, with a couple of caveats noted in the rule documentation below. + +`ts_project` is recommended for all new code. + +Exhaustive examples of calling `ts_project` are in the test suite: +https://github.com/bazelbuild/rules_nodejs/tree/stable/packages/typescript/test/ts_project + +And there are also many uses of it in our + +[DeclarationInfo]: Built-ins#declarationinfo + +### ts_library + +`ts_library` should not be used for new code, and may be deprecated in the future. + +`ts_library` is an open-sourced version of the rule used to compile TS code at Google. +However there is no support from the team that maintains that internal version. +It is very complex, involving code generation of the `tsconfig.json` file, a custom compiler binary, and a lot of extra features. + +It is also opinionated, and may not work with existing TypeScript code. For example: + +- Your TS code must compile under the `--declaration` flag so that downstream libraries depend only on types, not implementation. This makes Bazel faster by avoiding cascading rebuilds in cases where the types aren't changed. +- We control the output format and module syntax so that downstream rules can rely on them. +- Some other options are incompatible. For example you cannot use the `--noEmit` compiler option in `tsconfig.json`. + +The only reason to use `ts_library` for new code is if you are bought-in to using a [concatjs] bundler, which requires the named AMD module format. This may be faster than other tooling, and this format can be consumed by the Closure Compiler (via integration with [tsickle](https://github.com/angular/tsickle)). +However it is very challenging to configure and there is little available support for problems you'll run into. + +[concatjs]: https://www.npmjs.com/package/@bazel/concatjs + +## Installation + +Add a `devDependency` on `@bazel/typescript` + +```sh +$ yarn add -D @bazel/typescript +# or +$ npm install --save-dev @bazel/typescript +``` + +Watch for any `peerDependency` warnings - we assume you have already installed the `typescript` package from npm. + +## Typical Usage + +The `ts_project` rule invokes the TypeScript compiler on one compilation unit, +or "library" (generally one directory of source files). In TypeScript terms, this is one "Project" +which can use "Project References" to break up a large application. + +Create a `BUILD` file next to your sources: + +```starlark +load("//packages/typescript:index.bzl", "ts_project") + +ts_project( + name = "my_code", + # glob is a quick way to select all the code, + # but has performance penalty in that Bazel must evaluate it. + srcs = glob(["*.ts"]), + deps = ["//path/to/other:library"], +) +``` + +Here, `//path/to/other:library` is another target in your repo that produces TypeScript typings (for example, another `ts_project` rule). +Be sure to set the `rootDirs` in your tsconfig.json as noted below, so that TypeScript can find the `.d.ts` files produced by that other target. + +To use third-party libraries from npm, first install them (likely using `npm_install` or `yarn_install` rules) then add those to the `deps` as well: + +```starlark +ts_project( + name = "my_code", + srcs = glob(["*.ts"]), + deps = [ + "@npm//@types/node", + "@npm//@types/foo", + "@npm//somelib", + "//path/to/other:library", + ], +) +``` + +You can also use the `@npm//@types` grouping target which will include all +packages in the `@types` scope as dependencies. + +To build a `ts_library` target run: + +`bazel build //path/to/package:target` + +Note that the `tsconfig.json` file used for compilation should be the same one +your editor references, or `extends` from it, to keep consistent settings for the TypeScript compiler. + +Anything you do with TypeScript is possible with `ts_project`, including json imports, type-checking only, +transpile only, outdir, rootdir, and so on. +See many examples in our test cases: +https://github.com/bazelbuild/rules_nodejs/tree/stable/packages/typescript/test/ts_project diff --git a/packages/typescript/install.md b/packages/typescript/install.md deleted file mode 100644 index eb10061cb5..0000000000 --- a/packages/typescript/install.md +++ /dev/null @@ -1,306 +0,0 @@ -# TypeScript rules for Bazel - -The TypeScript rules integrate the TypeScript compiler with Bazel. - -## Alternatives - -This package provides Bazel wrappers around the TypeScript compiler. - -At a high level, there are three alternatives provided: `tsc`, `ts_project`, `ts_library`. -This section describes the trade-offs between these rules. - -`tsc` is the raw TypeScript compiler published by the team at Microsoft. -Like any npm package that exposes a binary, rules_nodejs will generate an `index.bzl` file allowing -you to run `tsc`. - -To use it, add the load statement `load("@npm//typescript:index.bzl", "tsc")` to your BUILD file. -Then call it, using the [`npm_package_bin`](Built-ins#npm_package_bin) documentation. - -The only reason to use raw `tsc` is if you want to compile an opaque directory of `.ts` files and cannot enumerate them to Bazel. -(For example if the `.ts` files are generated by some tool). -This will produce an opaque directory of `.js` file outputs, which you won't be able to individually reference. -Any other use case for `tsc` is better served by using `ts_project`. - -`ts_project` simply runs `tsc --project`, with Bazel knowing which outputs to expect based on the TypeScript compiler options, and with interoperability with other TypeScript rules via a Bazel Provider (DeclarationInfo) that transmits the type information. -It is intended as an easy on-boarding for existing TypeScript code and should be familiar if your background is in frontend ecosystem idioms. -Any behavior of `ts_project` should be reproducible outside of Bazel, with a couple of caveats noted in the rule documentation below. - -`ts_library` is an open-sourced version of the rule used to compile TS code at Google. -It should be familiar if your background is in Bazel idioms. -It is very complex, involving code generation of the `tsconfig.json` file, a custom compiler binary, and a lot of extra features. -It is also opinionated, and may not work with existing TypeScript code. For example: - -- Your TS code must compile under the `--declaration` flag so that downstream libraries depend only on types, not implementation. This makes Bazel faster by avoiding cascading rebuilds in cases where the types aren't changed. -- We control the output format and module syntax so that downstream rules can rely on them. - -On the other hand, `ts_library` is also fast and optimized. -We keep a running TypeScript compile running as a daemon, using Bazel workers. -This process avoids re-parse and re-JIT of the >1MB `typescript.js` and keeps cached bound ASTs for input files which saves time. -We also produce JS code which can be loaded faster (using named AMD module format) and which can be consumed by the Closure Compiler (via integration with [tsickle](https://github.com/angular/tsickle)). - -## Installation - -Add a `devDependency` on `@bazel/typescript` - -```sh -$ yarn add -D @bazel/typescript -# or -$ npm install --save-dev @bazel/typescript -``` - -Watch for any `peerDependency` warnings - we assume you have already installed the `typescript` package from npm. - -Create a `BUILD.bazel` file in your workspace root. If your `tsconfig.json` file is in the root, use - -```python -exports_files(["tsconfig.json"], visibility = ["//visibility:public"]) -``` - -otherwise create an alias: - -```python -alias( - name = "tsconfig.json", - actual = "//path/to/my:tsconfig.json", -) -``` - -Make sure to remove the `--noEmit` compiler option from your `tsconfig.json`. This is not compatible with the `ts_library` rule. - -## User-managed npm dependencies - -We recommend you use Bazel managed dependencies, but if you would like -Bazel to also install a `node_modules` in your workspace you can also -point the `node_repositories` repository rule in your `WORKSPACE` file to -your `package.json`. - -```python -node_repositories(package_json = ["//:package.json"]) -``` - -You can then run `yarn` in your workspace with: - -```sh -$ bazel run @nodejs//:yarn_node_repositories -``` - -To use your workspace `node_modules` folder as a dependency in `ts_library` and -other rules, add the following to your root `BUILD.bazel` file: - -```python -js_library( - name = "node_modules", - srcs = glob( - include = [ - "node_modules/**/*.js", - "node_modules/**/*.d.ts", - "node_modules/**/*.json", - "node_modules/.bin/*", - ], - exclude = [ - # Files under test & docs may contain file names that - # are not legal Bazel labels (e.g., - # node_modules/ecstatic/test/public/中文/檔案.html) - "node_modules/**/test/**", - "node_modules/**/docs/**", - # Files with spaces in the name are not legal Bazel labels - "node_modules/**/* */**", - "node_modules/**/* *", - ], - ), - # Provide ExternalNpmPackageInfo which is used by downstream rules - # that use these npm dependencies - external_npm_package = True, -) - -# Create a tsc_wrapped compiler rule to use in the ts_library -# compiler attribute when using user-managed dependencies -nodejs_binary( - name = "@bazel/typescript/tsc_wrapped", - entry_point = "@npm//:node_modules/@bazel/typescript/internal/tsc_wrapped/tsc_wrapped.js", - # Point bazel to your node_modules to find the entry point - data = ["//:node_modules"], -) -``` - -See the [dependencies docs](dependencies.html) for more information on managing npm dependencies with Bazel. - -## Customizing the TypeScript compiler binary - -An example use case is needing to increase the NodeJS heap size used for compilations. - -Similar to above, you declare your own binary for running `tsc_wrapped`, e.g.: - -```python -nodejs_binary( - name = "tsc_wrapped_bin", - entry_point = "@npm//:node_modules/@bazel/typescript/internal/tsc_wrapped/tsc_wrapped.js", - templated_args = [ - "--node_options=--max-old-space-size=2048", - ], - data = [ - "@npm//protobufjs", - "@npm//source-map-support", - "@npm//tsutils", - "@npm//typescript", - "@npm//@bazel/typescript", - ], -) -``` - -then refer to that target in the `compiler` attribute of your `ts_library` rule. - -Note that `nodejs_binary` targets generated by `npm_install`/`yarn_install` can include data dependencies -on packages which aren't declared as dependencies. For example, if you use [tsickle](https://github.com/angular/tsickle) to generate Closure Compiler-compatible JS, then it needs to be a data dependency of `tsc_wrapped` so that it can be loaded at runtime. - -## Usage - -### Compiling TypeScript: `ts_library` - -The `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: - -```python -package(default_visibility=["//visibility:public"]) -load("//packages/typescript:index.bzl", "ts_library") - -ts_library( - name = "my_code", - srcs = glob(["*.ts"]), - deps = ["//path/to/other:library"], -) -``` - -If your ts_library target has npm dependencies you can specify these -with fine grained npm dependency targets created by the `yarn_install` or -`npm_install` rules: - -```python -ts_library( - name = "my_code", - srcs = glob(["*.ts"]), - deps = [ - "@npm//@types/node", - "@npm//@types/foo", - "@npm//foo", - "//path/to/other:library", - ], -) -``` - -You can also use the `@npm//@types` target which will include all -packages in the `@types` scope as dependencies. - -If you are using user-managed npm dependencies, you can pass your `//:node_modules` -target defined in your root `BUILD.bazel` file to the deps of `ts_library`. -You'll also need to override the `compiler` attribute if you do this -as the Bazel-managed deps and user-managed cannot be used together -in the same rule. - -```python -ts_library( - name = "my_code", - srcs = glob(["*.ts"]), - deps = [ - "//path/to/other:library", - "//:node_modules", - ], - compiler = "//:@bazel/typescript/tsc_wrapped", -) -``` - -To build a `ts_library` target run: - -`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](https://www.typescriptlang.org/docs/handbook/compiler-options.html) -> compiler option will be silently overwritten if present. - -[ts_library API docs]: http://tsetse.info/api/build_defs.html#ts_library - -## Accessing JavaScript outputs - -The default output of the `ts_library` rule is the `.d.ts` files. -This is for a couple reasons: - -- help ensure that downstream rules which access default outputs will not require - a cascading re-build when only the implementation changes but not the types -- make you think about whether you want the `devmode` (named `UMD`) or `prodmode` outputs - -You can access the JS output by adding a `filegroup` rule after the `ts_library`, -for example - -```python -ts_library( - name = "compile", - srcs = ["thing.ts"], -) - -filegroup( - name = "thing.js", - srcs = ["compile"], - # Change to es6_sources to get the 'prodmode' JS - output_group = "es5_sources", -) - -my_rule( - name = "uses_js", - deps = ["thing.js"], -) -``` - -## Serving TypeScript for development - -This is now documented in the `@bazel/concatjs` package. - -## Writing TypeScript code for Bazel - -Bazel's TypeScript compiler has your workspace path mapped, so you can import -from an absolute path starting from your workspace. - -`/WORKSPACE`: -```python -workspace(name = "myworkspace") -``` - -`/some/long/path/to/deeply/nested/subdirectory.ts`: -```javascript -import {thing} from 'myworkspace/place'; -``` - -will import from `/place.ts`. - - -Since this is an extension to the vanilla 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 -```json -"paths": { - "myworkspace/*": ["*"] -} -``` -to `tsconfig.json` will fix the imports for the common case of using absolute paths. -See [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. - -### Notes - -If you'd like a "watch mode", try [ibazel]. - -At some point, we plan to release a tool similar to [gazelle] to generate the -`BUILD` files from your source code. - -[gazelle]: https://github.com/bazelbuild/bazel-gazelle -[ibazel]: https://github.com/bazelbuild/bazel-watcher -[path mapping]: https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping diff --git a/packages/typescript/internal/build_defs.bzl b/packages/typescript/internal/build_defs.bzl index 34311cc509..d94e5c8459 100644 --- a/packages/typescript/internal/build_defs.bzl +++ b/packages/typescript/internal/build_defs.bzl @@ -22,6 +22,51 @@ load("@build_bazel_rules_typescript//internal:common/compilation.bzl", "COMMON_A load("@build_bazel_rules_typescript//internal:common/tsconfig.bzl", "create_tsconfig") load("//packages/typescript/internal:ts_config.bzl", "TsConfigInfo") +_DOC = """type-check and compile a set of TypeScript sources to JavaScript. + +It produces declarations files (`.d.ts`) which are used for compiling downstream +TypeScript targets and JavaScript for the browser and Closure compiler. + +By default, `ts_library` uses the `tsconfig.json` file in the workspace root +directory. See the notes about the `tsconfig` attribute below. + +## Serving TypeScript for development + +`ts_library` is typically served by the concatjs_devserver rule, documented in the `@bazel/concatjs` package. + +## Accessing JavaScript outputs + +The default output of the `ts_library` rule is the `.d.ts` files. +This is for a couple reasons: + +- help ensure that downstream rules which access default outputs will not require + a cascading re-build when only the implementation changes but not the types +- make you think about whether you want the `devmode` (named `UMD`) or `prodmode` outputs + +You can access the JS output by adding a `filegroup` rule after the `ts_library`, +for example + +```python +ts_library( + name = "compile", + srcs = ["thing.ts"], +) + +filegroup( + name = "thing.js", + srcs = ["compile"], + # Change to es6_sources to get the 'prodmode' JS + output_group = "es5_sources", +) + +my_rule( + name = "uses_js", + deps = ["thing.js"], +) +``` + +""" + # NB: substituted with "//@bazel/typescript/bin:tsc_wrapped" in the pkg_npm rule _DEFAULT_COMPILER = "@build_bazel_rules_typescript//internal:tsc_wrapped_bin" @@ -329,6 +374,34 @@ and Angular compilations can replace this with `ngc`. The default ts_library compiler depends on the `//@bazel/typescript` target which is setup for projects that use bazel managed npm deps and install the @bazel/typescript npm package. + +You can also use a custom compiler to increase the NodeJS heap size used for compilations. + +To do this, declare your own binary for running `tsc_wrapped`, e.g.: + +```python +nodejs_binary( + name = "tsc_wrapped_bin", + entry_point = "@npm//:node_modules/@bazel/typescript/internal/tsc_wrapped/tsc_wrapped.js", + templated_args = [ + "--node_options=--max-old-space-size=2048", + ], + data = [ + "@npm//protobufjs", + "@npm//source-map-support", + "@npm//tsutils", + "@npm//typescript", + "@npm//@bazel/typescript", + ], +) +``` + +then refer to that target in the `compiler` attribute. + +Note that `nodejs_binary` targets generated by `npm_install`/`yarn_install` can include data dependencies +on packages which aren't declared as dependencies. +For example, if you use [tsickle](https://github.com/angular/tsickle) to generate Closure Compiler-compatible JS, +then it needs to be a data dependency of `tsc_wrapped` so that it can be loaded at runtime. """, default = Label(_DEFAULT_COMPILER), allow_files = True, @@ -400,6 +473,8 @@ either: - Have your `tsconfig.json` file in the workspace root directory - Use an alias in the root BUILD.bazel file to point to the location of tsconfig: `alias(name="tsconfig.json", actual="//path/to:tsconfig-something.json")` + and also make the tsconfig.json file visible to other Bazel packages: + `exports_files(["tsconfig.json"], visibility = ["//visibility:public"])` - Give an explicit `tsconfig` attribute to all `ts_library` targets """, allow_single_file = True, @@ -418,11 +493,7 @@ either: outputs = { "tsconfig": "%{name}_tsconfig.json", }, - doc = """`ts_library` type-checks and compiles a set of TypeScript sources to JavaScript. - -It produces declarations files (`.d.ts`) which are used for compiling downstream -TypeScript targets and JavaScript for the browser and Closure compiler. -""", + doc = _DOC, ) def ts_library_macro(tsconfig = None, **kwargs):