refactor: rename ts_devserver to concatjs_devserver and move to @baze…

…l/concatjs BREAKING CHANGE: users need to change their load statements for ts_devserver Fixes bazel-contrib#1082
alexeagle · Oct 18, 2020 · 855b35a · 855b35a
1 parent 8bbc27b
commit 855b35a
Show file tree

Hide file tree

Showing 70 changed files with 1,001 additions and 434 deletions.
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
@@ -73,6 +73,7 @@ rules_nodejs_docs(
     layouts = glob(["_layouts/*"]),
     readmes = {
         "Built-ins": ":builtins.doc",
+        "Concatjs": "//packages/concatjs:README.md",
         "Cypress": "//packages/cypress:README.md",
         "Jasmine": "//packages/jasmine:README.md",
         "Karma": "//packages/karma:README.md",

diff --git a/docs/Built-ins.html b/docs/Built-ins.html
diff --git a/docs/Built-ins.md b/docs/Built-ins.md
@@ -1500,7 +1500,7 @@ js_library(
 )
 ```
 
-> To help work with "named AMD" modules as required by `ts_devserver` and other Google-style "concatjs" rules,
+> To help work with "named AMD" modules as required by `concatjs_devserver` and other Google-style "concatjs" rules,
 > `js_library` has some undocumented advanced features you can find in the source code or in our examples.
 > These should not be considered a public API and aren't subject to our usual support and semver guarantees.
 

diff --git a/docs/Concatjs.html b/docs/Concatjs.html
diff --git a/docs/Concatjs.md b/docs/Concatjs.md
@@ -0,0 +1,187 @@
+---
+title: Concatjs
+layout: default
+toc: true
+nav: rule
+---
+<!-- *********************
+  DO NOT EDIT THIS FILE
+  It is a generated build output from Stardoc.
+  Instead you must edit the .bzl file where the rules are declared,
+  or possibly a markdown file next to the .bzl file
+ ********************* -->
+# @bazel/concatjs
+
+Concatjs is a JavaScript bundler, in a trivial sense: the UNIX `cat` command is a basic implementation:
+
+```bash
+$ cat one.js two.js > bundle.js
+```
+
+Clearly self-evident is that this bundler is super-fast and simple.
+A performant implementation adds some in-memory caching, and for developer ergonomics you add a simple IIFE wrapper
+around each file so that the Chrome DevTools shows the files in the tree as if they had been independently loaded.
+
+However at its core, concatjs requires a big tradeoff of a migration cost to buy-in, to get this incredible performance.
+The path of the JavaScript files is lost in the bundling process, so they must contain their module ID internally.
+
+Named AMD/UMD (non-anonymous require.js modules) and `goog.module` are the two JS module formats that are compatible with concatjs.
+Most packages do not ship with this format, so in order to use concatjs tooling, you have to shim your code and dependencies.
+
+This is at the core of how Google does JavaScript development.
+So Bazel rules that originated in Google's codebase, such as `ts_library` depend in some ways on producing concatjs output.
+
+
+## Serving JS in development mode under Bazel
+
+There are two choices for development mode:
+
+1. Use the `concatjs_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.
+1. Teach your real frontend server to serve files from Bazel's output directory.
+   This is not yet documented. Choose this option if you have an existing server
+   used in development mode, or if your requirements exceed what the
+   `concatjs_devserver` supports. Be careful that your development round-trip stays
+   fast (should be under two seconds).
+
+To use `concatjs_devserver`, you simply `load` the rule, and call it with `deps` that
+point to your `ts_library` target(s):
+
+```python
+load("@npm//@bazel/typescript:index.bzl", "concatjs_devserver", "ts_library")
+
+ts_library(
+    name = "app",
+    srcs = ["app.ts"],
+)
+
+concatjs_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
+`concatjs_devserver`.
+
+See `examples/app` in this repository for a working example. To run the
+devserver, we recommend you use [ibazel]:
+
+```sh
+$ 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.
+
+[ibazel]: https://github.com/bazelbuild/bazel-watcher
+
+
+## concatjs_devserver
+
+**USAGE**
+
+<pre>
+concatjs_devserver(<a href="#concatjs_devserver-name">name</a>, <a href="#concatjs_devserver-additional_root_paths">additional_root_paths</a>, <a href="#concatjs_devserver-bootstrap">bootstrap</a>, <a href="#concatjs_devserver-deps">deps</a>, <a href="#concatjs_devserver-devserver">devserver</a>, <a href="#concatjs_devserver-devserver_host">devserver_host</a>,
+                   <a href="#concatjs_devserver-entry_module">entry_module</a>, <a href="#concatjs_devserver-port">port</a>, <a href="#concatjs_devserver-scripts">scripts</a>, <a href="#concatjs_devserver-serving_path">serving_path</a>, <a href="#concatjs_devserver-static_files">static_files</a>)
+</pre>
+
+concatjs_devserver is a simple development server intended for a quick "getting started" experience.
+
+Additional documentation at https://github.com/alexeagle/angular-bazel-example/wiki/Running-a-devserver-under-Bazel
+
+
+**ATTRIBUTES**
+
+
+<h4 id="concatjs_devserver-name">name</h4>
+
+(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this target.
+
+
+<h4 id="concatjs_devserver-additional_root_paths">additional_root_paths</h4>
+
+(*List of strings*): Additional root paths to serve `static_files` from.
+            Paths should include the workspace name such as `["__main__/resources"]`
+
+Defaults to `[]`
+
+<h4 id="concatjs_devserver-bootstrap">bootstrap</h4>
+
+(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Scripts to include in the JS bundle before the module loader (require.js)
+
+Defaults to `[]`
+
+<h4 id="concatjs_devserver-deps">deps</h4>
+
+(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Targets that produce JavaScript, such as `ts_library`
+
+Defaults to `[]`
+
+<h4 id="concatjs_devserver-devserver">devserver</h4>
+
+(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): Go based devserver executable.
+
+            With cross-platform RBE for OSX & Windows ctx.executable.devserver will be linux as --cpu and
+            --host_cpu must be overridden to k8. However, we still want to be able to run the devserver on the host
+            machine so we need to include the host devserver binary, which is ctx.executable.devserver_host, in the
+            runfiles. For non-RBE and for RBE with a linux host, ctx.executable.devserver & ctx.executable.devserver_host
+            will be the same binary.
+
+            Defaults to precompiled go binary setup by @bazel/typescript npm package
+
+Defaults to `@npm//@bazel/devserver:devserver`
+
+<h4 id="concatjs_devserver-devserver_host">devserver_host</h4>
+
+(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): Go based devserver executable for the host platform.
+            Defaults to precompiled go binary setup by @bazel/typescript npm package
+
+Defaults to `@npm//@bazel/devserver:devserver_darwin_amd64`
+
+<h4 id="concatjs_devserver-entry_module">entry_module</h4>
+
+(*String*): The `entry_module` should be the AMD module name of the entry module such as `"__main__/src/index".`
+            `concatjs_devserver` concats the following snippet after the bundle to load the application:
+            `require(["entry_module"]);`
+
+Defaults to `""`
+
+<h4 id="concatjs_devserver-port">port</h4>
+
+(*Integer*): The port that the devserver will listen on.
+
+Defaults to `5432`
+
+<h4 id="concatjs_devserver-scripts">scripts</h4>
+
+(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): User scripts to include in the JS bundle before the application sources
+
+Defaults to `[]`
+
+<h4 id="concatjs_devserver-serving_path">serving_path</h4>
+
+(*String*): The path you can request from the client HTML which serves the JavaScript bundle.
+            If you don't specify one, the JavaScript can be loaded at /_/ts_scripts.js
+
+Defaults to `"/_/ts_scripts.js"`
+
+<h4 id="concatjs_devserver-static_files">static_files</h4>
+
+(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Arbitrary files which to be served, such as index.html.
+            They are served relative to the package where this rule is declared.
+
+Defaults to `[]`
+
+
diff --git a/docs/Cypress.html b/docs/Cypress.html
diff --git a/docs/Jasmine.html b/docs/Jasmine.html
diff --git a/docs/Karma.html b/docs/Karma.html
diff --git a/docs/Labs.html b/docs/Labs.html
diff --git a/docs/Labs.md b/docs/Labs.md
@@ -65,10 +65,10 @@ result will be `car.d.ts`. This means our TypeScript code can just
 name the rule differently from the output file.
 
 The JavaScript produced by protobuf.js has a runtime dependency on a support library.
-Under devmode (e.g. `ts_devserver`, `karma_web_test_suite`) you'll need to include these scripts
+Under devmode (e.g. `concatjs_devserver`, `karma_web_test_suite`) you'll need to include these scripts
 in the `bootstrap` phase (before Require.js loads). You can use the label
 `@npm//@bazel/labs/protobufjs:bootstrap_scripts` to reference these scripts
-in the `bootstrap` attribute of `karma_web_test_suite` or `ts_devserver`.
+in the `bootstrap` attribute of `karma_web_test_suite` or `concatjs_devserver`.
 
 To complete the example above, you could write a `karma_web_test_suite`:
 

diff --git a/docs/Protractor.html b/docs/Protractor.html
diff --git a/docs/Rollup.html b/docs/Rollup.html
diff --git a/docs/Terser.html b/docs/Terser.html