From 855b35a584ad1042233df9aac3788aab2d83f102 Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Sun, 18 Oct 2020 08:13:14 -0700 Subject: [PATCH] refactor: rename ts_devserver to concatjs_devserver and move to @bazel/concatjs BREAKING CHANGE: users need to change their load statements for ts_devserver Fixes #1082 --- docs/BUILD.bazel | 1 + docs/Built-ins.html | 6 +- docs/Built-ins.md | 2 +- docs/Concatjs.html | 445 ++++++++++++++++++ docs/Concatjs.md | 187 ++++++++ docs/Cypress.html | 4 + docs/Jasmine.html | 4 + docs/Karma.html | 4 + docs/Labs.html | 8 +- docs/Labs.md | 4 +- docs/Protractor.html | 4 + docs/Rollup.html | 4 + docs/Terser.html | 4 + docs/TypeScript.html | 150 +----- docs/TypeScript.md | 151 +----- docs/changing-rules.html | 4 + docs/debugging.html | 4 + docs/dependencies.html | 4 + docs/examples.html | 4 + docs/index.html | 4 + docs/install.html | 8 +- docs/repositories.html | 6 +- docs/repositories.md | 2 +- docs/stamping.html | 4 + e2e/BUILD.bazel | 3 +- .../.bazelignore | 0 .../.bazelrc | 0 .../BUILD.bazel | 7 +- .../WORKSPACE | 2 +- .../app.ts | 0 .../app_e2e-spec.ts | 0 .../dummy_test.sh | 0 .../genrule/BUILD.bazel | 7 +- .../genrule/app.ts | 0 .../genrule/app_e2e-spec.ts | 0 .../genrule/index.html | 0 .../package.json | 0 .../protractor.on-prepare.js | 0 .../red-body-style.css | 0 .../subpackage/BUILD.bazel | 5 +- .../subpackage/index.tmpl.html | 0 .../subpackage/subpackage_e2e-spec.ts | 2 +- .../tsconfig.json | 0 .../yarn.lock | 0 examples/angular/src/BUILD.bazel | 7 +- examples/angular_view_engine/src/BUILD.bazel | 7 +- examples/app/BUILD.bazel | 5 +- examples/parcel/README.md | 1 - examples/protocol_buffers/BUILD.bazel | 5 +- internal/js_library/js_library.bzl | 4 +- packages/concatjs/BUILD.bazel | 83 ++++ packages/concatjs/README | 75 +++ .../devserver/BUILD.bazel | 21 +- .../devserver/concatjs_devserver.bzl} | 24 +- .../devserver/launcher_template.sh | 6 +- .../BUILD.bazel => concatjs/index.bzl} | 26 +- packages/concatjs/index.docs.bzl | 25 + packages/{typescript => concatjs}/package.bzl | 2 +- packages/concatjs/package.json | 25 + .../third_party/npm/requirejs/BUILD | 2 +- .../third_party/npm/requirejs/LICENSE | 0 .../third_party/npm/requirejs/require.js | 0 packages/labs/grpc_web/README.md | 2 +- packages/labs/protobufjs/ts_proto_library.bzl | 4 +- .../protractor/test/protractor-2/BUILD.bazel | 5 +- packages/typescript/BUILD.bazel | 4 - packages/typescript/index.bzl | 2 - packages/typescript/index.docs.bzl | 2 - packages/typescript/install.md | 53 +-- packages/typescript/internal/BUILD.bazel | 1 - 70 files changed, 1001 insertions(+), 434 deletions(-) create mode 100755 docs/Concatjs.html create mode 100755 docs/Concatjs.md rename e2e/{ts_devserver => concatjs_devserver}/.bazelignore (100%) rename e2e/{ts_devserver => concatjs_devserver}/.bazelrc (100%) rename e2e/{ts_devserver => concatjs_devserver}/BUILD.bazel (92%) rename e2e/{ts_devserver => concatjs_devserver}/WORKSPACE (97%) rename e2e/{ts_devserver => concatjs_devserver}/app.ts (100%) rename e2e/{ts_devserver => concatjs_devserver}/app_e2e-spec.ts (100%) rename e2e/{ts_devserver => concatjs_devserver}/dummy_test.sh (100%) rename e2e/{ts_devserver => concatjs_devserver}/genrule/BUILD.bazel (92%) rename e2e/{ts_devserver => concatjs_devserver}/genrule/app.ts (100%) rename e2e/{ts_devserver => concatjs_devserver}/genrule/app_e2e-spec.ts (100%) rename e2e/{ts_devserver => concatjs_devserver}/genrule/index.html (100%) rename e2e/{ts_devserver => concatjs_devserver}/package.json (100%) rename e2e/{ts_devserver => concatjs_devserver}/protractor.on-prepare.js (100%) rename e2e/{ts_devserver => concatjs_devserver}/red-body-style.css (100%) rename e2e/{ts_devserver => concatjs_devserver}/subpackage/BUILD.bazel (91%) rename e2e/{ts_devserver => concatjs_devserver}/subpackage/index.tmpl.html (100%) rename e2e/{ts_devserver => concatjs_devserver}/subpackage/subpackage_e2e-spec.ts (86%) rename e2e/{ts_devserver => concatjs_devserver}/tsconfig.json (100%) rename e2e/{ts_devserver => concatjs_devserver}/yarn.lock (100%) create mode 100644 packages/concatjs/BUILD.bazel create mode 100644 packages/concatjs/README rename packages/{typescript => concatjs}/devserver/BUILD.bazel (85%) rename packages/{typescript/internal/devserver/ts_devserver.bzl => concatjs/devserver/concatjs_devserver.bzl} (92%) rename packages/{typescript/internal => concatjs}/devserver/launcher_template.sh (94%) rename packages/{typescript/internal/devserver/BUILD.bazel => concatjs/index.bzl} (52%) create mode 100644 packages/concatjs/index.docs.bzl rename packages/{typescript => concatjs}/package.bzl (98%) create mode 100644 packages/concatjs/package.json rename packages/{typescript => concatjs}/third_party/npm/requirejs/BUILD (65%) rename packages/{typescript => concatjs}/third_party/npm/requirejs/LICENSE (100%) rename packages/{typescript => concatjs}/third_party/npm/requirejs/require.js (100%) diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index e25b8eaf58..bbc1d01f8c 100644 --- 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 index f7158a4524..53624b2b71 100755 --- a/docs/Built-ins.html +++ b/docs/Built-ins.html @@ -97,6 +97,10 @@

Rules

+
  • Concatjs
    • + + +
  • Cypress
    • @@ -1560,7 +1564,7 @@

    Example

    -

    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/Built-ins.md b/docs/Built-ins.md index 34ae8304e3..beec2815e3 100755 --- 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 new file mode 100755 index 0000000000..81d0f8a13c --- /dev/null +++ b/docs/Concatjs.html @@ -0,0 +1,445 @@ + + + + + + + + + + rules_nodejs - Concatjs + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    +
    + + + +
    + + +
    +
    + +

    @bazel/concatjs

    + +

    Concatjs is a JavaScript bundler, in a trivial sense: the UNIX cat command is a basic implementation:

    + +
    $ 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.
      2. +
    2. 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).
      3. +
    + +

    To use concatjs_devserver, you simply load the rule, and call it with deps that +point to your ts_library target(s):

    + +
    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:

    + +
    $ 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.

    + +

    concatjs_devserver

    + +

    USAGE

    + +
    +concatjs_devserver(name, additional_root_paths, bootstrap, deps, devserver, devserver_host,
+                   entry_module, port, scripts, serving_path, static_files)
+
    + +

    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

    + +

    name

    + +

    (Name, mandatory): A unique name for this target.

    + +

    additional_root_paths

    + +

    (List of strings): Additional root paths to serve static_files from. + Paths should include the workspace name such as ["__main__/resources"]

    + +

    Defaults to []

    + +

    bootstrap

    + +

    (List of labels): Scripts to include in the JS bundle before the module loader (require.js)

    + +

    Defaults to []

    + +

    deps

    + +

    (List of labels): Targets that produce JavaScript, such as ts_library

    + +

    Defaults to []

    + +

    devserver

    + +

    (Label): 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

    + +

    devserver_host

    + +

    (Label): 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

    + +

    entry_module

    + +

    (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 ""

    + +

    port

    + +

    (Integer): The port that the devserver will listen on.

    + +

    Defaults to 5432

    + +

    scripts

    + +

    (List of labels): User scripts to include in the JS bundle before the application sources

    + +

    Defaults to []

    + +

    serving_path

    + +

    (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"

    + +

    static_files

    + +

    (List of labels): 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/Concatjs.md b/docs/Concatjs.md new file mode 100755 index 0000000000..00668f13f1 --- /dev/null +++ b/docs/Concatjs.md @@ -0,0 +1,187 @@ +--- +title: Concatjs +layout: default +toc: true +nav: rule +--- + +# @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** + +
    +concatjs_devserver(name, additional_root_paths, bootstrap, deps, devserver, devserver_host,
+                   entry_module, port, scripts, serving_path, static_files)
+
    + +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** + + +

    name

    + +(*Name, mandatory*): A unique name for this target. + + +

    additional_root_paths

    + +(*List of strings*): Additional root paths to serve `static_files` from. + Paths should include the workspace name such as `["__main__/resources"]` + +Defaults to `[]` + +

    bootstrap

    + +(*List of labels*): Scripts to include in the JS bundle before the module loader (require.js) + +Defaults to `[]` + +

    deps

    + +(*List of labels*): Targets that produce JavaScript, such as `ts_library` + +Defaults to `[]` + +

    devserver

    + +(*Label*): 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` + +

    devserver_host

    + +(*Label*): 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` + +

    entry_module

    + +(*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 `""` + +

    port

    + +(*Integer*): The port that the devserver will listen on. + +Defaults to `5432` + +

    scripts

    + +(*List of labels*): User scripts to include in the JS bundle before the application sources + +Defaults to `[]` + +

    serving_path

    + +(*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"` + +

    static_files

    + +(*List of labels*): 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 index 96a5d2b621..adec7cb22e 100755 --- a/docs/Cypress.html +++ b/docs/Cypress.html @@ -97,6 +97,10 @@

    Rules

    +
  • Concatjs
    • + + +
  • Cypress
    • diff --git a/docs/Jasmine.html b/docs/Jasmine.html index 1951e58e1e..740e505d08 100755 --- a/docs/Jasmine.html +++ b/docs/Jasmine.html @@ -97,6 +97,10 @@

    Rules

    +
  • Concatjs
    • + + +
  • Cypress
    • diff --git a/docs/Karma.html b/docs/Karma.html index d1922ac2cc..1849756d44 100755 --- a/docs/Karma.html +++ b/docs/Karma.html @@ -97,6 +97,10 @@

    Rules

    +
  • Concatjs
    • + + +
  • Cypress
    • diff --git a/docs/Labs.html b/docs/Labs.html index 4d472fd22f..561a3ea9ba 100755 --- a/docs/Labs.html +++ b/docs/Labs.html @@ -97,6 +97,10 @@

    Rules

    +
  • Concatjs
    • + + +
  • Cypress
    • @@ -223,10 +227,10 @@

    protobufjs_ts_library

    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/Labs.md b/docs/Labs.md index 8eaca3c2bd..ec1e9f06b9 100755 --- 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 index 774171e828..87d66a4180 100755 --- a/docs/Protractor.html +++ b/docs/Protractor.html @@ -97,6 +97,10 @@

    Rules

    +
  • Concatjs
    • + + +
  • Cypress
    • diff --git a/docs/Rollup.html b/docs/Rollup.html index f458dfba61..1017f96584 100755 --- a/docs/Rollup.html +++ b/docs/Rollup.html @@ -97,6 +97,10 @@

    Rules

    +
  • Concatjs
    • + + +
  • Cypress
    • diff --git a/docs/Terser.html b/docs/Terser.html index 62c1ea7006..b81af9f460 100755 --- a/docs/Terser.html +++ b/docs/Terser.html @@ -97,6 +97,10 @@

    Rules

    +
  • Concatjs
    • + + +
  • Cypress
    • diff --git a/docs/TypeScript.html b/docs/TypeScript.html index 907dae08be..8d3dde454b 100755 --- a/docs/TypeScript.html +++ b/docs/TypeScript.html @@ -97,6 +97,10 @@

    Rules

    +
  • Concatjs
    • + + +
  • Cypress
    • @@ -418,56 +422,7 @@

    Accessing JavaScript outputs

    Serving TypeScript for development

    -

    There are two choices for development mode:

    - -
      -
    1. Use the 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.
      2. -
    2. 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 -ts_devserver supports. Be careful that your development round-trip stays -fast (should be under two seconds).
      3. -
    - -

    To use ts_devserver, you simply load the rule, and call it with deps that -point to your ts_library target(s):

    - -
    load("@npm//@bazel/typescript:index.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.

    +

    This is now documented in the @bazel/concatjs package.

    Writing TypeScript code for Bazel

    @@ -533,100 +488,6 @@

    src

    (Label, mandatory): The tsconfig.json file passed to the TypeScript compiler

    -

    ts_devserver

    - -

    USAGE

    - -
    -ts_devserver(name, additional_root_paths, bootstrap, deps, devserver, devserver_host, entry_module,
-             port, scripts, serving_path, static_files)
-
    - -

    ts_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

    - -

    name

    - -

    (Name, mandatory): A unique name for this target.

    - -

    additional_root_paths

    - -

    (List of strings): Additional root paths to serve static_files from. - Paths should include the workspace name such as ["__main__/resources"]

    - -

    Defaults to []

    - -

    bootstrap

    - -

    (List of labels): Scripts to include in the JS bundle before the module loader (require.js)

    - -

    Defaults to []

    - -

    deps

    - -

    (List of labels): Targets that produce JavaScript, such as ts_library

    - -

    Defaults to []

    - -

    devserver

    - -

    (Label): 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

    - -

    devserver_host

    - -

    (Label): 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

    - -

    entry_module

    - -

    (String): The entry_module should be the AMD module name of the entry module such as "__main__/src/index". - ts_devserver concats the following snippet after the bundle to load the application: - require(["entry_module"]);

    - -

    Defaults to ""

    - -

    port

    - -

    (Integer): The port that the devserver will listen on.

    - -

    Defaults to 5432

    - -

    scripts

    - -

    (List of labels): User scripts to include in the JS bundle before the application sources

    - -

    Defaults to []

    - -

    serving_path

    - -

    (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"

    - -

    static_files

    - -

    (List of labels): Arbitrary files which to be served, such as index.html. - They are served relative to the package where this rule is declared.

    - -

    Defaults to []

    -

    ts_library

    USAGE

    @@ -1194,7 +1055,6 @@

    kwargs

  • ts_config
    • -
  • ts_devserver
  • ts_library
  • ts_project diff --git a/docs/repositories.md b/docs/repositories.md index fd10284db5..bf04e786d5 100644 --- a/docs/repositories.md +++ b/docs/repositories.md @@ -52,7 +52,7 @@ Commonly used ones are: - Every file that was installed from npm: `@npm//:node_modules`. This target can have a very large number of files and slow down your build, however it's a simple way to skip having to declare more fine-grained inputs to your BUILD targets. - If you had a dependency on the `foo` package, you can reference `@npm//foo` to get all the files. We mirror the npm dependency graph, so if `foo` declares a dependency on another package `dep`, Bazel will include that dependency when `foo` is used. - If the `foo` package has an executable program `bar`, then `@npm//foo/bin:bar` is a `nodejs_binary` that you can call with `bazel run` or can pass as the `executable` to your own rules. -- Sometimes you need a UMD bundle, but a package doesn't ship one. For example, the `ts_devserver` rule depends on third-party libraries having a named UMD entry point. The `@npm//foo:foo__umd` target will automatically run Browserify to convert the package's `main` entry into UMD. +- Sometimes you need a UMD bundle, but a package doesn't ship one. For example, the `concatjs_devserver` rule depends on third-party libraries having a named UMD entry point. The `@npm//foo:foo__umd` target will automatically run Browserify to convert the package's `main` entry into UMD. - DEPRECATED: A helper to install npm packages into their own Bazel repository: `@npm//:install_bazel_dependencies.bzl` provides a `install_bazel_dependencies` function. Some npm packages ship custom bazel rules, for example, the `@angular/bazel` package provides rules which you should load from `@npm_angular_bazel//:index.bzl`. However this causes the build to always fetch npm packages even when not needed, so we plan to remove this in a future release. > One convenient (maybe also confusing) way to understand what BUILD files are generated is to look at our integration test at https://github.com/bazelbuild/rules_nodejs/tree/stable/internal/npm_install/test/golden - this directory looks similar to the content of an `@npm` repository. diff --git a/docs/stamping.html b/docs/stamping.html index f0b74810a4..6aabb603ce 100755 --- a/docs/stamping.html +++ b/docs/stamping.html @@ -97,6 +97,10 @@

    Rules

    +
  • Concatjs
    • + + +
  • Cypress
    • diff --git a/e2e/BUILD.bazel b/e2e/BUILD.bazel index fedfbcefcf..48af4886c7 100644 --- a/e2e/BUILD.bazel +++ b/e2e/BUILD.bazel @@ -110,8 +110,9 @@ e2e_integration_test( ) e2e_integration_test( - name = "e2e_ts_devserver", + name = "e2e_concatjs_devserver", npm_packages = { + "//packages/concatjs:npm_package": "@bazel/concatjs", "//packages/protractor:npm_package": "@bazel/protractor", "//packages/typescript:npm_package": "@bazel/typescript", }, diff --git a/e2e/ts_devserver/.bazelignore b/e2e/concatjs_devserver/.bazelignore similarity index 100% rename from e2e/ts_devserver/.bazelignore rename to e2e/concatjs_devserver/.bazelignore diff --git a/e2e/ts_devserver/.bazelrc b/e2e/concatjs_devserver/.bazelrc similarity index 100% rename from e2e/ts_devserver/.bazelrc rename to e2e/concatjs_devserver/.bazelrc diff --git a/e2e/ts_devserver/BUILD.bazel b/e2e/concatjs_devserver/BUILD.bazel similarity index 92% rename from e2e/ts_devserver/BUILD.bazel rename to e2e/concatjs_devserver/BUILD.bazel index f2c010fac7..b8b0bc0daf 100644 --- a/e2e/ts_devserver/BUILD.bazel +++ b/e2e/concatjs_devserver/BUILD.bazel @@ -13,8 +13,9 @@ # limitations under the License. load("@build_bazel_rules_nodejs//internal/npm_install:npm_umd_bundle.bzl", "npm_umd_bundle") +load("@npm//@bazel/concatjs:index.bzl", "concatjs_devserver") load("@npm//@bazel/protractor:index.bzl", "protractor_web_test_suite") -load("@npm//@bazel/typescript:index.bzl", "ts_devserver", "ts_library") +load("@npm//@bazel/typescript:index.bzl", "ts_library") exports_files([ "red-body-style.css", @@ -42,9 +43,9 @@ npm_umd_bundle( package = "@npm//typeorm", ) -ts_devserver( +concatjs_devserver( name = "devserver", - entry_module = "e2e_ts_devserver/app", + entry_module = "e2e_concatjs_devserver/app", scripts = [ "@npm//date-fns:date-fns.umd.js", "@npm//rxjs:rxjs.umd.js", diff --git a/e2e/ts_devserver/WORKSPACE b/e2e/concatjs_devserver/WORKSPACE similarity index 97% rename from e2e/ts_devserver/WORKSPACE rename to e2e/concatjs_devserver/WORKSPACE index 3a3ea9700f..d2eb65b2f5 100644 --- a/e2e/ts_devserver/WORKSPACE +++ b/e2e/concatjs_devserver/WORKSPACE @@ -13,7 +13,7 @@ # limitations under the License. workspace( - name = "e2e_ts_devserver", + name = "e2e_concatjs_devserver", managed_directories = {"@npm": ["node_modules"]}, ) diff --git a/e2e/ts_devserver/app.ts b/e2e/concatjs_devserver/app.ts similarity index 100% rename from e2e/ts_devserver/app.ts rename to e2e/concatjs_devserver/app.ts diff --git a/e2e/ts_devserver/app_e2e-spec.ts b/e2e/concatjs_devserver/app_e2e-spec.ts similarity index 100% rename from e2e/ts_devserver/app_e2e-spec.ts rename to e2e/concatjs_devserver/app_e2e-spec.ts diff --git a/e2e/ts_devserver/dummy_test.sh b/e2e/concatjs_devserver/dummy_test.sh similarity index 100% rename from e2e/ts_devserver/dummy_test.sh rename to e2e/concatjs_devserver/dummy_test.sh diff --git a/e2e/ts_devserver/genrule/BUILD.bazel b/e2e/concatjs_devserver/genrule/BUILD.bazel similarity index 92% rename from e2e/ts_devserver/genrule/BUILD.bazel rename to e2e/concatjs_devserver/genrule/BUILD.bazel index 016ca2650b..a3bf350375 100644 --- a/e2e/ts_devserver/genrule/BUILD.bazel +++ b/e2e/concatjs_devserver/genrule/BUILD.bazel @@ -12,8 +12,9 @@ # See the License for the specific language governing permissions and # limitations under the License. +load("@npm//@bazel/concatjs:index.bzl", "concatjs_devserver") load("@npm//@bazel/protractor:index.bzl", "protractor_web_test_suite") -load("@npm//@bazel/typescript:index.bzl", "ts_devserver", "ts_library") +load("@npm//@bazel/typescript:index.bzl", "ts_library") ts_library( name = "app", @@ -34,11 +35,11 @@ ts_library( ], ) -ts_devserver( +concatjs_devserver( name = "devserver", additional_root_paths = [ "npm/node_modules/tslib", - "e2e_ts_devserver/genrule/devserver/", + "e2e_concatjs_devserver/genrule/devserver/", ], serving_path = "/bundle.js", static_files = [ diff --git a/e2e/ts_devserver/genrule/app.ts b/e2e/concatjs_devserver/genrule/app.ts similarity index 100% rename from e2e/ts_devserver/genrule/app.ts rename to e2e/concatjs_devserver/genrule/app.ts diff --git a/e2e/ts_devserver/genrule/app_e2e-spec.ts b/e2e/concatjs_devserver/genrule/app_e2e-spec.ts similarity index 100% rename from e2e/ts_devserver/genrule/app_e2e-spec.ts rename to e2e/concatjs_devserver/genrule/app_e2e-spec.ts diff --git a/e2e/ts_devserver/genrule/index.html b/e2e/concatjs_devserver/genrule/index.html similarity index 100% rename from e2e/ts_devserver/genrule/index.html rename to e2e/concatjs_devserver/genrule/index.html diff --git a/e2e/ts_devserver/package.json b/e2e/concatjs_devserver/package.json similarity index 100% rename from e2e/ts_devserver/package.json rename to e2e/concatjs_devserver/package.json diff --git a/e2e/ts_devserver/protractor.on-prepare.js b/e2e/concatjs_devserver/protractor.on-prepare.js similarity index 100% rename from e2e/ts_devserver/protractor.on-prepare.js rename to e2e/concatjs_devserver/protractor.on-prepare.js diff --git a/e2e/ts_devserver/red-body-style.css b/e2e/concatjs_devserver/red-body-style.css similarity index 100% rename from e2e/ts_devserver/red-body-style.css rename to e2e/concatjs_devserver/red-body-style.css diff --git a/e2e/ts_devserver/subpackage/BUILD.bazel b/e2e/concatjs_devserver/subpackage/BUILD.bazel similarity index 91% rename from e2e/ts_devserver/subpackage/BUILD.bazel rename to e2e/concatjs_devserver/subpackage/BUILD.bazel index 3ae8a4b3d9..6b48120a73 100644 --- a/e2e/ts_devserver/subpackage/BUILD.bazel +++ b/e2e/concatjs_devserver/subpackage/BUILD.bazel @@ -12,8 +12,9 @@ # See the License for the specific language governing permissions and # limitations under the License. +load("@npm//@bazel/concatjs:index.bzl", "concatjs_devserver") load("@npm//@bazel/protractor:index.bzl", "protractor_web_test_suite") -load("@npm//@bazel/typescript:index.bzl", "ts_devserver", "ts_library") +load("@npm//@bazel/typescript:index.bzl", "ts_library") load("@npm//html-insert-assets:index.bzl", "html_insert_assets") html_insert_assets( @@ -32,7 +33,7 @@ html_insert_assets( ], ) -ts_devserver( +concatjs_devserver( name = "devserver", static_files = [ "inject", diff --git a/e2e/ts_devserver/subpackage/index.tmpl.html b/e2e/concatjs_devserver/subpackage/index.tmpl.html similarity index 100% rename from e2e/ts_devserver/subpackage/index.tmpl.html rename to e2e/concatjs_devserver/subpackage/index.tmpl.html diff --git a/e2e/ts_devserver/subpackage/subpackage_e2e-spec.ts b/e2e/concatjs_devserver/subpackage/subpackage_e2e-spec.ts similarity index 86% rename from e2e/ts_devserver/subpackage/subpackage_e2e-spec.ts rename to e2e/concatjs_devserver/subpackage/subpackage_e2e-spec.ts index f9eab9834d..65ee3b8b62 100644 --- a/e2e/ts_devserver/subpackage/subpackage_e2e-spec.ts +++ b/e2e/concatjs_devserver/subpackage/subpackage_e2e-spec.ts @@ -6,7 +6,7 @@ describe('subpackage', () => { await browser.get(''); }); - // Ensures that the "ts_devserver" properly injects and loads static files which + // Ensures that the "concatjs_devserver" properly injects and loads static files which // are in the current workspace, but not part of the current Bazel package. See // related issue: https://github.com/bazelbuild/rules_typescript/issues/409 it('should be able to properly load the injected CSS file', async () => { diff --git a/e2e/ts_devserver/tsconfig.json b/e2e/concatjs_devserver/tsconfig.json similarity index 100% rename from e2e/ts_devserver/tsconfig.json rename to e2e/concatjs_devserver/tsconfig.json diff --git a/e2e/ts_devserver/yarn.lock b/e2e/concatjs_devserver/yarn.lock similarity index 100% rename from e2e/ts_devserver/yarn.lock rename to e2e/concatjs_devserver/yarn.lock diff --git a/examples/angular/src/BUILD.bazel b/examples/angular/src/BUILD.bazel index 9952508ead..7d84acd84f 100644 --- a/examples/angular/src/BUILD.bazel +++ b/examples/angular/src/BUILD.bazel @@ -3,9 +3,10 @@ load("@io_bazel_rules_docker//container:container.bzl", "container_image") load("@io_bazel_rules_docker//nodejs:image.bzl", "nodejs_image") load("@io_bazel_rules_sass//:defs.bzl", "sass_binary") load("@npm//@babel/cli:index.bzl", "babel") +load("@npm//@bazel/concatjs:index.bzl", "concatjs_devserver") load("@npm//@bazel/rollup:index.bzl", "rollup_bundle") load("@npm//@bazel/terser:index.bzl", "terser_minified") -load("@npm//@bazel/typescript:index.bzl", "ts_config", "ts_devserver", "ts_library") +load("@npm//@bazel/typescript:index.bzl", "ts_config", "ts_library") load("@npm//history-server:index.bzl", "history_server") load("@npm//html-insert-assets:index.bzl", "html_insert_assets") load("//tools:angular_prerender.bzl", "ng_prerender", "ng_prerender_test") @@ -97,7 +98,7 @@ html_insert_assets( "--roots=. $(RULEDIR)", "--assets", ] + ["$(execpath %s)" % s for s in _ASSETS] + [ - # This file doesn't exist during the build, but will be served by ts_devserver + # This file doesn't exist during the build, but will be served by concatjs_devserver "./_/ts_scripts.js", ], data = ["//src:example/index.html"] + _ASSETS, @@ -107,7 +108,7 @@ html_insert_assets( # It doesn't run any bundler or code splitter. Instead, it concatenates # named UMD and named AMD JavaScript code on-the-fly in-memory. # This scales really well for massive codebases. -ts_devserver( +concatjs_devserver( name = "devserver", # Serve src/example/index.html at /index.html additional_root_paths = ["src/example"], diff --git a/examples/angular_view_engine/src/BUILD.bazel b/examples/angular_view_engine/src/BUILD.bazel index 4ce8c3c85f..c590fa2f2a 100644 --- a/examples/angular_view_engine/src/BUILD.bazel +++ b/examples/angular_view_engine/src/BUILD.bazel @@ -1,9 +1,10 @@ load("@build_bazel_rules_nodejs//:index.bzl", "pkg_web") load("@io_bazel_rules_sass//:defs.bzl", "sass_binary") load("@npm//@babel/cli:index.bzl", "babel") +load("@npm//@bazel/concatjs:index.bzl", "concatjs_devserver") load("@npm//@bazel/rollup:index.bzl", "rollup_bundle") load("@npm//@bazel/terser:index.bzl", "terser_minified") -load("@npm//@bazel/typescript:index.bzl", "ts_config", "ts_devserver", "ts_library") +load("@npm//@bazel/typescript:index.bzl", "ts_config", "ts_library") load("@npm//history-server:index.bzl", "history_server") load("@npm//html-insert-assets:index.bzl", "html_insert_assets") load("@npm_angular_bazel//:index.bzl", "ng_module") @@ -99,7 +100,7 @@ html_insert_assets( "--roots=. $(RULEDIR)", "--assets", ] + ["$(execpath %s)" % s for s in _ASSETS] + [ - # This file doesn't exist during the build, but will be served by ts_devserver + # This file doesn't exist during the build, but will be served by concatjs_devserver "./_/ts_scripts.js", ], data = ["//src:example/index.html"] + _ASSETS, @@ -109,7 +110,7 @@ html_insert_assets( # It doesn't run any bundler or code splitter. Instead, it concatenates # named UMD and named AMD JavaScript code on-the-fly in-memory. # This scales really well for massive codebases. -ts_devserver( +concatjs_devserver( name = "devserver", # Serve src/example/index.html at /index.html additional_root_paths = ["src/example"], diff --git a/examples/app/BUILD.bazel b/examples/app/BUILD.bazel index 77bf6dc0e3..db73be5dd3 100644 --- a/examples/app/BUILD.bazel +++ b/examples/app/BUILD.bazel @@ -1,8 +1,9 @@ load("@build_bazel_rules_nodejs//:index.bzl", "pkg_web") +load("@npm//@bazel/concatjs:index.bzl", "concatjs_devserver") load("@npm//@bazel/protractor:index.bzl", "protractor_web_test_suite") load("@npm//@bazel/rollup:index.bzl", "rollup_bundle") load("@npm//@bazel/terser:index.bzl", "terser_minified") -load("@npm//@bazel/typescript:index.bzl", "ts_devserver", "ts_library", "ts_project") +load("@npm//@bazel/typescript:index.bzl", "ts_library", "ts_project") load("@npm//html-insert-assets:index.bzl", "html_insert_assets") load("@npm//http-server:index.bzl", "http_server") @@ -13,7 +14,7 @@ ts_library( srcs = ["app.ts"], ) -ts_devserver( +concatjs_devserver( name = "devserver", # We'll collect all the devmode JS sources from these TypeScript libraries deps = [":app"], diff --git a/examples/parcel/README.md b/examples/parcel/README.md index fd930b62bf..79db88f3fa 100644 --- a/examples/parcel/README.md +++ b/examples/parcel/README.md @@ -11,7 +11,6 @@ Parcel can do many jobs which overlap with Bazel, such as development serving an Parcel can do file-system watching, but this overlaps with [ibazel](https://github.com/bazelbuild/bazel-watcher) so this mode is probably undesirable under Bazel. Also, Parcel has a development server. -This could be an alternative to the `ts_devserver` we recommend under Bazel. It would need to be hosted properly to see generated Bazel outputs from other build steps. See https://github.com/angular/angular-bazel-example/wiki/Running-a-devserver-under-Bazel diff --git a/examples/protocol_buffers/BUILD.bazel b/examples/protocol_buffers/BUILD.bazel index 3753ca574e..6f7181dcc8 100644 --- a/examples/protocol_buffers/BUILD.bazel +++ b/examples/protocol_buffers/BUILD.bazel @@ -1,9 +1,10 @@ +load("@npm//@bazel/concatjs:index.bzl", "concatjs_devserver") load("@npm//@bazel/karma:index.bzl", "karma_web_test_suite") load("@npm//@bazel/labs:index.bzl", "ts_proto_library") load("@npm//@bazel/protractor:index.bzl", "protractor_web_test_suite") load("@npm//@bazel/rollup:index.bzl", "rollup_bundle") load("@npm//@bazel/terser:index.bzl", "terser_minified") -load("@npm//@bazel/typescript:index.bzl", "ts_config", "ts_devserver", "ts_library") +load("@npm//@bazel/typescript:index.bzl", "ts_config", "ts_library") load("@npm//http-server:index.bzl", "http_server") load("@rules_proto//proto:defs.bzl", "proto_library") @@ -72,7 +73,7 @@ ts_library( deps = [":car"], ) -ts_devserver( +concatjs_devserver( name = "devserver", entry_module = "examples_protocol_buffers/app", scripts = ["@npm//@bazel/labs/grpc_web:bootstrap_scripts"], diff --git a/internal/js_library/js_library.bzl b/internal/js_library/js_library.bzl index 8525bd6b43..f39b99d938 100644 --- a/internal/js_library/js_library.bzl +++ b/internal/js_library/js_library.bzl @@ -50,7 +50,7 @@ _ATTRS = { "named_module_srcs": attr.label_list( doc = """Non-public legacy API, not recommended to make new usages. A subset of srcs that are javascript named-UMD or - named-AMD for use in rules such as ts_devserver. + named-AMD for use in rules such as concatjs_devserver. They will be copied into the package bin folder if needed.""", allow_files = True, ), @@ -272,7 +272,7 @@ def 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/packages/concatjs/BUILD.bazel b/packages/concatjs/BUILD.bazel new file mode 100644 index 0000000000..d7d0e39135 --- /dev/null +++ b/packages/concatjs/BUILD.bazel @@ -0,0 +1,83 @@ +# Copyright 2017 The Bazel Authors. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") +load("@build_bazel_rules_nodejs//:tools/defaults.bzl", "pkg_npm") +load("@build_bazel_rules_nodejs//tools/stardoc:index.bzl", "stardoc") +load("//third_party/github.com/bazelbuild/bazel-skylib:rules/copy_file.bzl", "copy_file") + +bzl_library( + name = "bzl", + srcs = glob(["*.bzl"]) + [ + # Work-around since we don't have and don't wnat a bzl_library in the generated + # @nodejs//:BUILD.bazel file + "@nodejs//:index.bzl", + ], + deps = [ + "//packages/concatjs/devserver:bzl", + "@build_bazel_rules_nodejs//:bzl", + "@build_bazel_rules_nodejs//internal/common:bzl", + "@build_bazel_rules_nodejs//internal/node:bzl", + ], +) + +stardoc( + name = "docs", + out = "index.md", + input = "index.docs.bzl", + tags = ["fix-windows"], + deps = [":bzl"], +) + +# Ugly genrule depending on local linux environment to build the README out of skylark doc generation. +# Only referenced when we do a release. +# TODO: This ought to be possible with stardoc alone. Need to coordinate with Chris Parsons. +genrule( + name = "generate_README", + srcs = [ + "index.md", + "README", + ], + outs = ["README.md"], + cmd = """cat $(execpath README) $(execpath index.md) | sed 's/^##/\\\n##/' > $@""", + tags = ["fix-windows"], + visibility = ["//docs:__pkg__"], +) + +copy_file( + name = "npm_version_check", + src = "//internal:npm_version_check.js", + out = ":npm_version_check.js", +) + +pkg_npm( + name = "npm_package", + srcs = [ + "index.bzl", + "package.json", + "//packages/concatjs/devserver:package_contents", + "//packages/concatjs/third_party/npm/requirejs:package_contents", + ], + build_file_content = "", + vendor_external = [ + "build_bazel_rules_typescript", + ], + deps = [ + ":npm_version_check", + ] + select({ + # FIXME: fix stardoc on Windows + "@bazel_tools//src/conditions:windows": [], + "//conditions:default": [":generate_README"], + }), +) diff --git a/packages/concatjs/README b/packages/concatjs/README new file mode 100644 index 0000000000..4c2350392f --- /dev/null +++ b/packages/concatjs/README @@ -0,0 +1,75 @@ +# @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("//packages/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 diff --git a/packages/typescript/devserver/BUILD.bazel b/packages/concatjs/devserver/BUILD.bazel similarity index 85% rename from packages/typescript/devserver/BUILD.bazel rename to packages/concatjs/devserver/BUILD.bazel index b180fb7ab1..9e3fc71d68 100644 --- a/packages/typescript/devserver/BUILD.bazel +++ b/packages/concatjs/devserver/BUILD.bazel @@ -12,6 +12,25 @@ # See the License for the specific language governing permissions and # limitations under the License. +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +licenses(["notice"]) # Apache 2.0 + +package(default_visibility = [ + "//packages/concatjs:__subpackages__", +]) + +bzl_library( + name = "bzl", + srcs = glob(["*.bzl"]), + deps = [ + "@build_bazel_rules_nodejs//internal/js_library:bzl", + "@build_bazel_rules_nodejs//internal/pkg_web:bzl", + ], +) + +exports_files(["launcher_template.sh"]) + filegroup( name = "devserver_darwin_amd64", srcs = ["devserver-darwin_x64"], @@ -109,5 +128,5 @@ filegroup( filegroup( name = "package_contents", srcs = glob(["*"]), - visibility = ["//packages/typescript:__pkg__"], + visibility = ["//packages/concatjs:__pkg__"], ) diff --git a/packages/typescript/internal/devserver/ts_devserver.bzl b/packages/concatjs/devserver/concatjs_devserver.bzl similarity index 92% rename from packages/typescript/internal/devserver/ts_devserver.bzl rename to packages/concatjs/devserver/concatjs_devserver.bzl index badd0418db..620621bb5e 100644 --- a/packages/typescript/internal/devserver/ts_devserver.bzl +++ b/packages/concatjs/devserver/concatjs_devserver.bzl @@ -28,7 +28,7 @@ def _to_manifest_path(ctx, file): else: return ctx.workspace_name + "/" + file.short_path -def _ts_devserver(ctx): +def _concatjs_devserver(ctx): files_depsets = [] for dep in ctx.attr.deps: if JSNamedModuleInfo in dep: @@ -124,8 +124,8 @@ def _ts_devserver(ctx): ), )] -ts_devserver = rule( - implementation = _ts_devserver, +concatjs_devserver = rule( + implementation = _concatjs_devserver, attrs = { "additional_root_paths": attr.string_list( doc = """Additional root paths to serve `static_files` from. @@ -164,7 +164,7 @@ ts_devserver = rule( ), "entry_module": attr.string( doc = """The `entry_module` should be the AMD module name of the entry module such as `"__main__/src/index".` - `ts_devserver` concats the following snippet after the bundle to load the application: + `concatjs_devserver` concats the following snippet after the bundle to load the application: `require(["entry_module"]);` """, ), @@ -197,22 +197,22 @@ ts_devserver = rule( "script": "%{name}.sh", "scripts_manifest": "scripts_%{name}.MF", }, - doc = """ts_devserver is a simple development server intended for a quick "getting started" experience. + doc = """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 """, ) -def ts_devserver_macro(name, args = [], visibility = None, tags = [], testonly = 0, **kwargs): - """Macro for creating a `ts_devserver` +def concatjs_devserver_macro(name, args = [], visibility = None, tags = [], testonly = 0, **kwargs): + """Macro for creating a `concatjs_devserver` - This macro re-exposes a `sh_binary` and `ts_devserver` target that can run the + This macro re-exposes a `sh_binary` and `concatjs_devserver` target that can run the actual devserver implementation. - The `ts_devserver` rule is just responsible for generating a launcher script + The `concatjs_devserver` rule is just responsible for generating a launcher script that runs the Go devserver implementation. The `sh_binary` is the primary target that matches the specified "name" and executes the generated bash launcher script. - This is re-exported in `//:index.bzl` as `ts_devserver` so if you load the rule + This is re-exported in `//:index.bzl` as `concatjs_devserver` so if you load the rule from there, you actually get this macro. Args: @@ -221,9 +221,9 @@ def ts_devserver_macro(name, args = [], visibility = None, tags = [], testonly = visibility: Visibility of the devserver targets tags: Standard Bazel tags, this macro adds a couple for ibazel testonly: Whether the devserver should only run in `bazel test` - **kwargs: passed through to `ts_devserver` + **kwargs: passed through to `concatjs_devserver` """ - ts_devserver( + concatjs_devserver( name = "%s_launcher" % name, testonly = testonly, visibility = ["//visibility:private"], diff --git a/packages/typescript/internal/devserver/launcher_template.sh b/packages/concatjs/devserver/launcher_template.sh similarity index 94% rename from packages/typescript/internal/devserver/launcher_template.sh rename to packages/concatjs/devserver/launcher_template.sh index e88e32cbd2..91340edd10 100644 --- a/packages/typescript/internal/devserver/launcher_template.sh +++ b/packages/concatjs/devserver/launcher_template.sh @@ -36,7 +36,7 @@ case "${unameOut}" in *) machine=linux printf "\nUnrecongized uname '${unameOut}'; defaulting to use node for linux.\n" >&2 printf "Please file an issue to https://github.com/bazelbuild/rules_nodejs/issues if \n" >&2 - printf "you would like to add your platform to the supported ts_devserver platforms.\n\n" >&2 + printf "you would like to add your platform to the supported concatjs_devserver platforms.\n\n" >&2 ;; esac @@ -58,10 +58,10 @@ else fi if [ ! -f "${main}" ]; then - printf "\n>>>> FAIL: The ts_devserver binary '${main_platform}' not found in runfiles.\n" >&2 + printf "\n>>>> FAIL: The concatjs_devserver binary '${main_platform}' not found in runfiles.\n" >&2 printf "This node toolchain was chosen based on your uname '${unameOut}'.\n" >&2 printf "Please file an issue to https://github.com/bazelbuild/rules_nodejs/issues if \n" >&2 - printf "you would like to add your platform to the supported ts_devserver platforms. <<<<\n\n" >&2 + printf "you would like to add your platform to the supported concatjs_devserver platforms. <<<<\n\n" >&2 exit 1 fi diff --git a/packages/typescript/internal/devserver/BUILD.bazel b/packages/concatjs/index.bzl similarity index 52% rename from packages/typescript/internal/devserver/BUILD.bazel rename to packages/concatjs/index.bzl index 1643b9a394..cf918ea4e4 100644 --- a/packages/typescript/internal/devserver/BUILD.bazel +++ b/packages/concatjs/index.bzl @@ -12,27 +12,11 @@ # See the License for the specific language governing permissions and # limitations under the License. -load("@bazel_skylib//:bzl_library.bzl", "bzl_library") +"""Public API surface is re-exported here. -licenses(["notice"]) # Apache 2.0 +Users should not load files under "/internal" +""" -package(default_visibility = [ - "//packages/typescript:__subpackages__", - "//third_party/bazel_rules/rules_typescript/internal:__subpackages__", -]) +load("//:concatjs_devserver.bzl", _concatjs_devserver = "concatjs_devserver_macro") -bzl_library( - name = "bzl", - srcs = glob(["*.bzl"]), - deps = [ - "@build_bazel_rules_nodejs//internal/js_library:bzl", - "@build_bazel_rules_nodejs//internal/pkg_web:bzl", - ], -) - -exports_files(["launcher_template.sh"]) - -filegroup( - name = "package_contents", - srcs = glob(["*"]), -) +concatjs_devserver = _concatjs_devserver diff --git a/packages/concatjs/index.docs.bzl b/packages/concatjs/index.docs.bzl new file mode 100644 index 0000000000..4d716a3d27 --- /dev/null +++ b/packages/concatjs/index.docs.bzl @@ -0,0 +1,25 @@ +# Copyright 2019 The Bazel Authors. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""This contains references to the symbols we want documented. + +We can't point stardoc to the top-level index.bzl since then it will see macros rather than the rules they wrap. +So this is a copy of index.bzl with macro indirection removed. +""" + +load("//packages/concatjs/devserver:concatjs_devserver.bzl", _concatjs_devserver = "concatjs_devserver") + +concatjs_devserver = _concatjs_devserver +# DO NOT ADD MORE rules here unless they appear in the generated docsite. +# Run yarn stardoc to re-generate the docsite. diff --git a/packages/typescript/package.bzl b/packages/concatjs/package.bzl similarity index 98% rename from packages/typescript/package.bzl rename to packages/concatjs/package.bzl index da69f9bc37..9b14f432d7 100644 --- a/packages/typescript/package.bzl +++ b/packages/concatjs/package.bzl @@ -27,7 +27,7 @@ def rules_typescript_dev_dependencies(): Also this allows other repos to reference our sources with local_repository and install the needed deps. """ - # For building ts_devserver binary + # For building concatjs_devserver binary # See https://github.com/bazelbuild/rules_go#setup for the latest version. _maybe( http_archive, diff --git a/packages/concatjs/package.json b/packages/concatjs/package.json new file mode 100644 index 0000000000..ee806c6b8f --- /dev/null +++ b/packages/concatjs/package.json @@ -0,0 +1,25 @@ +{ + "name": "@bazel/concatjs", + "description": "Fast JavaScript bundler for Bazel", + "license": "Apache-2.0", + "version": "0.0.0-PLACEHOLDER", + "repository": { + "type": "git", + "url": "https://github.com/bazelbuild/rules_nodejs.git", + "directory": "packages/concatjs" + }, + "bugs": { + "url": "https://github.com/bazelbuild/rules_nodejs/issues" + }, + "keywords": [ + "bazel" + ], + "dependencies": { + "protobufjs": "6.8.8", + "source-map-support": "0.5.9", + "tsutils": "2.27.2" + }, + "scripts": { + "postinstall": "node npm_version_check.js" + } +} diff --git a/packages/typescript/third_party/npm/requirejs/BUILD b/packages/concatjs/third_party/npm/requirejs/BUILD similarity index 65% rename from packages/typescript/third_party/npm/requirejs/BUILD rename to packages/concatjs/third_party/npm/requirejs/BUILD index fe0ec683d3..11a14f8d4d 100644 --- a/packages/typescript/third_party/npm/requirejs/BUILD +++ b/packages/concatjs/third_party/npm/requirejs/BUILD @@ -3,5 +3,5 @@ exports_files(["require.js"]) filegroup( name = "package_contents", srcs = glob(["*"]), - visibility = ["//packages/typescript:__pkg__"], + visibility = ["//packages/concatjs:__pkg__"], ) diff --git a/packages/typescript/third_party/npm/requirejs/LICENSE b/packages/concatjs/third_party/npm/requirejs/LICENSE similarity index 100% rename from packages/typescript/third_party/npm/requirejs/LICENSE rename to packages/concatjs/third_party/npm/requirejs/LICENSE diff --git a/packages/typescript/third_party/npm/requirejs/require.js b/packages/concatjs/third_party/npm/requirejs/require.js similarity index 100% rename from packages/typescript/third_party/npm/requirejs/require.js rename to packages/concatjs/third_party/npm/requirejs/require.js diff --git a/packages/labs/grpc_web/README.md b/packages/labs/grpc_web/README.md index 314b3cb9f2..0c8f4fd3a7 100644 --- a/packages/labs/grpc_web/README.md +++ b/packages/labs/grpc_web/README.md @@ -48,7 +48,7 @@ You can now use the `test_ts_proto` target as a `dep` in other `ts_library` targ - `google-protobuf` - `grpc-web` -UMD versions of these runtime dependencies are provided by `//packages/labs/grpc_web:bootstrap_scripts` (for use within `ts_devserver` and `karma_web_test_suite`) +UMD versions of these runtime dependencies are provided by `//packages/labs/grpc_web:bootstrap_scripts` (for use within `concatjs_devserver` and `karma_web_test_suite`) See `//examples/protocol_buffers/BUILD.bazel` for an example. diff --git a/packages/labs/protobufjs/ts_proto_library.bzl b/packages/labs/protobufjs/ts_proto_library.bzl index 52e0744b40..d69b6ebce0 100644 --- a/packages/labs/protobufjs/ts_proto_library.bzl +++ b/packages/labs/protobufjs/ts_proto_library.bzl @@ -201,10 +201,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/packages/protractor/test/protractor-2/BUILD.bazel b/packages/protractor/test/protractor-2/BUILD.bazel index 697be5d053..63c7c94646 100644 --- a/packages/protractor/test/protractor-2/BUILD.bazel +++ b/packages/protractor/test/protractor-2/BUILD.bazel @@ -1,8 +1,9 @@ load("@npm//http-server:index.bzl", "http_server") +load("//packages/concatjs:index.bzl", "concatjs_devserver") load("//packages/protractor:index.bzl", "protractor_web_test_suite") load("//packages/rollup:index.bzl", "rollup_bundle") load("//packages/terser:index.bzl", "terser_minified") -load("//packages/typescript:index.bzl", "ts_config", "ts_devserver", "ts_library") +load("//packages/typescript:index.bzl", "ts_config", "ts_library") ts_config( name = "tsconfig-test", @@ -27,7 +28,7 @@ terser_minified( src = ":bundle", ) -ts_devserver( +concatjs_devserver( name = "devserver", devserver = "@build_bazel_rules_typescript//devserver:devserver_bin", devserver_host = "@build_bazel_rules_typescript//devserver:devserver_bin", diff --git a/packages/typescript/BUILD.bazel b/packages/typescript/BUILD.bazel index e2bfc6a136..fb5761dbae 100644 --- a/packages/typescript/BUILD.bazel +++ b/packages/typescript/BUILD.bazel @@ -30,7 +30,6 @@ bzl_library( ], deps = [ "//packages/typescript/internal:bzl", - "//packages/typescript/internal/devserver:bzl", "@build_bazel_rules_nodejs//:bzl", "@build_bazel_rules_nodejs//internal/common:bzl", "@build_bazel_rules_nodejs//internal/node:bzl", @@ -82,11 +81,8 @@ pkg_npm( name = "npm_package", srcs = [ "index.bzl", - "package.bzl", "package.json", - "//packages/typescript/devserver:package_contents", "//packages/typescript/internal:package_contents", - "//packages/typescript/third_party/npm/requirejs:package_contents", ], build_file_content = "", nested_packages = [ diff --git a/packages/typescript/index.bzl b/packages/typescript/index.bzl index de754f0f9a..584c12ca3b 100644 --- a/packages/typescript/index.bzl +++ b/packages/typescript/index.bzl @@ -20,10 +20,8 @@ Users should not load files under "/internal" load("//packages/typescript/internal:build_defs.bzl", _ts_library = "ts_library_macro") load("//packages/typescript/internal:ts_config.bzl", _ts_config = "ts_config") load("//packages/typescript/internal:ts_project.bzl", _ts_project = "ts_project_macro") -load("//packages/typescript/internal/devserver:ts_devserver.bzl", _ts_devserver = "ts_devserver_macro") ts_library = _ts_library ts_config = _ts_config -ts_devserver = _ts_devserver ts_project = _ts_project # If adding rules here also add to index.docs.bzl diff --git a/packages/typescript/index.docs.bzl b/packages/typescript/index.docs.bzl index 75b6d1ed48..256e44905b 100644 --- a/packages/typescript/index.docs.bzl +++ b/packages/typescript/index.docs.bzl @@ -21,11 +21,9 @@ So this is a copy of index.bzl with macro indirection removed. load("//packages/typescript/internal:build_defs.bzl", _ts_library = "ts_library") load("//packages/typescript/internal:ts_config.bzl", _ts_config = "ts_config") load("//packages/typescript/internal:ts_project.bzl", _ts_project = "ts_project_macro") -load("//packages/typescript/internal/devserver:ts_devserver.bzl", _ts_devserver = "ts_devserver") ts_library = _ts_library ts_config = _ts_config ts_project = _ts_project -ts_devserver = _ts_devserver # DO NOT ADD MORE rules here unless they appear in the generated docsite. # Run yarn stardoc to re-generate the docsite. diff --git a/packages/typescript/install.md b/packages/typescript/install.md index f98fa0bff3..fd4b6f777c 100644 --- a/packages/typescript/install.md +++ b/packages/typescript/install.md @@ -253,58 +253,7 @@ my_rule( ## Serving TypeScript for development -There are two choices for development mode: - -1. Use the `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. -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 - `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): - -```python -load("//packages/typescript:index.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]: - -```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 +This is now documented in the `@bazel/concatjs` package. ## Writing TypeScript code for Bazel diff --git a/packages/typescript/internal/BUILD.bazel b/packages/typescript/internal/BUILD.bazel index 0a95c526ff..f21c224aa5 100644 --- a/packages/typescript/internal/BUILD.bazel +++ b/packages/typescript/internal/BUILD.bazel @@ -63,7 +63,6 @@ filegroup( "build_defs.bzl", "ts_config.bzl", "ts_project.bzl", - "//packages/typescript/internal/devserver:package_contents", ], visibility = ["//packages/typescript:__subpackages__"], )