initial commit

.gitignore

@@ -0,0 +1,2 @@
+bazel-*
+frontend/node_modules

README.md

@@ -0,0 +1,192 @@
+# From Bazel
+
+This repo demonstrates how to bootstrap a development environment for Frontend
+Web programming assuming you have Bazel installed on your machine.
+
+You don't need to install any frontend tooling like Node.js, npm, yarn, etc.
+
+This illustrates a typical workflow for a backend engineer who already uses
+Bazel to build code such as a Java or C++ backend, and wants to add some
+frontend code to their build. Such an engineer might work at a company where the
+corporate IT department manages the image for developer machines and doesn't
+give developers administrator rights on their machine.
+
+## Prerequisites
+
+Bazel 0.17 or greater installed.
+
+## Bootstrapping a frontend build
+
+Most frontend tooling runs on the Node.js runtime. We'll need to use
+`rules_nodejs` to get this toolchain.
+
+This example also assumes you'd like to develop in a typed superset of
+JavaScript, called TypeScript.
+
+Add this to your `WORKSPACE` file (or create an empty one if starting from
+scratch):
+
+```python
+http_archive(
+    name = "build_bazel_rules_typescript",
+    url = "https://github.com/bazelbuild/rules_typescript/archive/0.19.1.zip",
+    strip_prefix = "rules_typescript-0.19.1",
+)
+
+# Fetch our Bazel dependencies that aren't distributed on npm
+load("@build_bazel_rules_typescript//:package.bzl", "rules_typescript_dependencies")
+rules_typescript_dependencies()
+
+# Setup the NodeJS toolchain
+load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories", "yarn_install")
+node_repositories()
+
+# Setup TypeScript toolchain
+load("@build_bazel_rules_typescript//:defs.bzl", "ts_setup_workspace")
+ts_setup_workspace()
+```
+
+Let's assume we are in a repository where the frontend code will live in a
+subdirectory. So create a `frontend` directory and `cd` into there.
+
+Now we can run a package manager to fetch the frontend tooling like the
+TypeScript compiler. Either `npm` or `yarn` are typically used for this purpose.
+We'll use `yarn` in this example.
+
+The package manager expects a file called `package.json` which specifies the
+packages and their versions. To create such a file, we'll just call the `init`
+command of the package manager:
+
+```sh
+$ bazel run -- @nodejs//:bin/yarn init -y
+```
+
+> On Windows, the target is `@nodejs//:bin/yarn.cmd`
+
+Now we need to add a dependency on the TypeScript compiler, and its Bazel
+support package.
+
+```sh
+$ bazel run -- @nodejs//:bin/yarn add typescript @bazel/typescript
+```
+
+> Again, on Windows the target is `@nodejs//:bin/yarn.cmd`
+
+## Teaching Bazel to find the frontend dependencies
+
+The previous step created a `node_modules` directory in your project. That's
+useful so your editor can use the matching version of TypeScript as Bazel will.
+
+However, we'll let Bazel manage its own copy of the dependencies. To do that,
+add to your `WORKSPACE`:
+
+```python
+yarn_install(
+    name = "npm",
+    package_json = "//frontend:package.json",
+    yarn_lock = "//frontend:yarn.lock",
+)
+```
+
+> We named this rule "npm" because the repository of frontend dependencies is
+> named "npm" and is found at http://npmjs.com.
+
+That rule references the `package.json` file we created with `yarn init` and
+also a `yarn.lock` file which pins the versions of our transitive dependencies
+so that everyone gets the same build results.
+
+Since we've referenced those files in the `frontend` package, we'll also need
+a `BUILD.bazel` file in that directory, which could be empty.
+
+## Try running TypeScript
+
+Now we can run the TypeScript compiler manually to verify that it works:
+
+```sh
+$ bazel build @npm//:typescript/tsc
+$ ../bazel-bin/external/npm/typescript/tsc
+... some output
+```
+
+> Note, we don't use `bazel run` here because it sets the current working
+> directory to the Bazel runfiles by default, and in this case we want to work
+> in our current directory.
+
+In order to compile TypeScript code, we need a `tsconfig.json` configuration
+file for the compiler. We can use the same `init` trick as with `yarn` above:
+
+```sh
+$ ../bazel-bin/external/npm/typescript/tsc --init
+```
+
+## First ts_library rule
+
+Bazel will run the TypeScript compiler as needed on library rules whose inputs
+have changed since the last build.
+
+First create a simple TypeScript application, `frontend/app.ts`
+
+```typescript
+const el: HTMLDivElement = document.createElement('div');
+el.innerText = 'Hello, TypeScript';
+el.className = 'ts1';
+document.body.appendChild(el);
+```
+
+> Your editor should give you help if you type this code by hand,
+> since TypeScript supplies the API for the `document` variable.
+
+Now edit your `frontend/BUILD.bazel` file to contain
+
+```python
+load("@build_bazel_rules_typescript//:defs.bzl", "ts_library", "ts_devserver")
+ts_library(name = "app", srcs = [":app.ts"], tsconfig = ":tsconfig.json")
+```
+
+> We could have skipped the `tsconfig` attribute on `ts_library` if our config
+> was found in the default location, which is to have the `tsconfig.json` file
+> in the Workspace root, or else to add an `alias` rule to the root
+> `BUILD.bazel` file like
+>
+> ```
+> alias(name = "tsconfig.json", actual = "//frontend:tsconfig.json")
+> ```
+
+Finally, we can build the code:
+
+```sh
+$ bazel build :app
+Target //frontend:app up-to-date:
+  bazel-bin/frontend/app.d.ts
+```
+
+## Serve the app to a browser
+
+> 😢 This step is currently broken on Windows 😢
+
+For scalability, we use an optimized devserver written in Go. This is compiled
+from source, thanks to Bazel's ability to work in many languages.
+
+First you'll need a few lines added to `WORKSPACE`:
+
+```python
+load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains")
+go_rules_dependencies()
+go_register_toolchains()
+```
+
+Then add this to your `frontend/BUILD.bazel` file:
+
+```python
+ts_devserver(name = "devserver", deps = [":app"])
+```
+
+You can now run the server with
+
+```
+$ bazel run :devserver
+Server listening on http://...
+```
+
+Click the link that's printed there, and you should see "Hello, TypeScript"
+appear in the browser.

WORKSPACE

@@ -0,0 +1,28 @@
+http_archive(
+    name = "build_bazel_rules_typescript",
+    url = "https://github.com/bazelbuild/rules_typescript/archive/0.19.1.zip",
+    strip_prefix = "rules_typescript-0.19.1",
+)
+
+# Fetch our Bazel dependencies that aren't distributed on npm
+load("@build_bazel_rules_typescript//:package.bzl", "rules_typescript_dependencies")
+rules_typescript_dependencies()
+
+# Setup the NodeJS toolchain
+load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories", "yarn_install")
+node_repositories()
+
+# Setup TypeScript toolchain
+load("@build_bazel_rules_typescript//:defs.bzl", "ts_setup_workspace")
+ts_setup_workspace()
+
+yarn_install(
+    name = "npm",
+    package_json = "//frontend:package.json",
+    yarn_lock = "//frontend:yarn.lock",
+)
+
+load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains")
+
+go_rules_dependencies()
+go_register_toolchains()

frontend/BUILD.bazel

@@ -0,0 +1,3 @@
+load("@build_bazel_rules_typescript//:defs.bzl", "ts_library", "ts_devserver")
+ts_library(name = "app", srcs = [":app.ts"], tsconfig = ":tsconfig.json")
+ts_devserver(name = "devserver", deps = [":app"])

frontend/app.ts

@@ -0,0 +1,4 @@
+const el: HTMLDivElement = document.createElement('div');
+el.innerText = 'Hello, TypeScript';
+el.className = 'ts1';
+document.body.appendChild(el);

frontend/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "frontend",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "dependencies": {
+    "@bazel/typescript": "^0.19.1",
+    "typescript": "^3.1.1"
+  }
+}

frontend/tsconfig.json

@@ -0,0 +1,59 @@
+{
+  "compilerOptions": {
+    /* Basic Options */
+    "target": "es5",                          /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017','ES2018' or 'ESNEXT'. */
+    "module": "commonjs",                     /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */
+    // "lib": [],                             /* Specify library files to be included in the compilation. */
+    // "allowJs": true,                       /* Allow javascript files to be compiled. */
+    // "checkJs": true,                       /* Report errors in .js files. */
+    // "jsx": "preserve",                     /* Specify JSX code generation: 'preserve', 'react-native', or 'react'. */
+    // "declaration": true,                   /* Generates corresponding '.d.ts' file. */
+    // "declarationMap": true,                /* Generates a sourcemap for each corresponding '.d.ts' file. */
+    // "sourceMap": true,                     /* Generates corresponding '.map' file. */
+    // "outFile": "./",                       /* Concatenate and emit output to single file. */
+    // "outDir": "./",                        /* Redirect output structure to the directory. */
+    // "rootDir": "./",                       /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
+    // "composite": true,                     /* Enable project compilation */
+    // "removeComments": true,                /* Do not emit comments to output. */
+    // "noEmit": true,                        /* Do not emit outputs. */
+    // "importHelpers": true,                 /* Import emit helpers from 'tslib'. */
+    // "downlevelIteration": true,            /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */
+    // "isolatedModules": true,               /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */
+
+    /* Strict Type-Checking Options */
+    "strict": true,                           /* Enable all strict type-checking options. */
+    // "noImplicitAny": true,                 /* Raise error on expressions and declarations with an implied 'any' type. */
+    // "strictNullChecks": true,              /* Enable strict null checks. */
+    // "strictFunctionTypes": true,           /* Enable strict checking of function types. */
+    // "strictPropertyInitialization": true,  /* Enable strict checking of property initialization in classes. */
+    // "noImplicitThis": true,                /* Raise error on 'this' expressions with an implied 'any' type. */
+    // "alwaysStrict": true,                  /* Parse in strict mode and emit "use strict" for each source file. */
+
+    /* Additional Checks */
+    // "noUnusedLocals": true,                /* Report errors on unused locals. */
+    // "noUnusedParameters": true,            /* Report errors on unused parameters. */
+    // "noImplicitReturns": true,             /* Report error when not all code paths in function return a value. */
+    // "noFallthroughCasesInSwitch": true,    /* Report errors for fallthrough cases in switch statement. */
+
+    /* Module Resolution Options */
+    // "moduleResolution": "node",            /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
+    // "baseUrl": "./",                       /* Base directory to resolve non-absolute module names. */
+    // "paths": {},                           /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
+    // "rootDirs": [],                        /* List of root folders whose combined content represents the structure of the project at runtime. */
+    // "typeRoots": [],                       /* List of folders to include type definitions from. */
+    // "types": [],                           /* Type declaration files to be included in compilation. */
+    // "allowSyntheticDefaultImports": true,  /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
+    "esModuleInterop": true                   /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
+    // "preserveSymlinks": true,              /* Do not resolve the real path of symlinks. */
+
+    /* Source Map Options */
+    // "sourceRoot": "",                      /* Specify the location where debugger should locate TypeScript files instead of source locations. */
+    // "mapRoot": "",                         /* Specify the location where debugger should locate map files instead of generated locations. */
+    // "inlineSourceMap": true,               /* Emit a single file with source maps instead of having a separate file. */
+    // "inlineSources": true,                 /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */
+
+    /* Experimental Options */
+    // "experimentalDecorators": true,        /* Enables experimental support for ES7 decorators. */
+    // "emitDecoratorMetadata": true,         /* Enables experimental support for emitting type metadata for decorators. */
+  }
+}