fix(typescript): update documentation now that ts_project is recommended

We don't deprecated ts_library yet

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__"],
 )

packages/typescript/_README.md

@@ -0,0 +1,129 @@
+# 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/stable/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 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_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 <examples>
+
+### 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). 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_library(
+    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