From 18186f6c4bb50eec77b96a84f625ce7e4f7d0564 Mon Sep 17 00:00:00 2001
From: Bilawal Hameed <bil@spotify.com>
Date: Wed, 5 Feb 2020 16:55:00 +0100
Subject: [PATCH] Updated docs

---
 README.md       | 10 +++++++
 proto/README.md | 70 +++++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 69 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 5c357471bf..7a8c78ecf4 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,16 @@ Backstage is an open platform for building developer portals.
 
 ## Getting started
 
+### Protobuf Definitions
+
+To generate the Protobuf definitions in Go and TypeScript, run the following command from the root with [Prototool](https://github.com/uber/prototool):
+
+```bash
+$ prototool generate ./proto
+```
+
+See [proto/README.md](proto/README.md) for more information.
+
 ## Plugins
 
 ### Creating a Plugin
diff --git a/proto/README.md b/proto/README.md
index 1787ed13b2..62591bab5e 100644
--- a/proto/README.md
+++ b/proto/README.md
@@ -4,32 +4,55 @@ Collection of all Backstage protobuf definitions.
 
 ## Usage
 
-Managed with prototool, install instructions at https://github.com/uber/prototool/blob/dev/docs/install.md
+Managed with [Prototool](https://github.com/uber/prototool), install instructions at <https://github.com/uber/prototool/blob/dev/docs/install.md>
 
 ## Install Dependencies
 
-You will need to have `protoc-gen-go` available in your path. You can find out more information here: https://github.com/golang/protobuf
+### Prototool
 
+```bash
+$ brew install prototool
+```
 
-```sh
+### protoc-gen-go
+
+This will enable code generation in Go for interacting with gRPC-Web. You will need to have `protoc-gen-go` available in your path. You can find out more information here: https://github.com/golang/protobuf
+
+```bash
 $ go get -u github.com/golang/protobuf/protoc-gen-go
 $ protoc-gen-go # should now be available in your path providing you GOPATH + GOBIN paths are setup correctly.
 ```
 
+### protoc-gen-ts
 
-### Generate code
+This will enable code generation in TypeScript for interacting with gRPC-Web. From the root, you will need to run [Yarn](https://yarnpkg.com) in the `frontend` folder:
 
-Run to generate code to `backend/proto/`:
-
-```
-$ prototool generate
+```bash
+$ yarn --cwd ./frontend install
 ```
 
-Generated code should be check in to the repo.
+After this, you should be all set!
 
-### Import generated go code
+## Generating Code
 
-Example import of inventory:
+To generate the Protobuf definitions in Go and TypeScript, run the following command from the root with [Prototool](https://github.com/uber/prototool):
+
+```bash
+$ prototool generate ./proto
+```
+
+This will generate the respective "generated" files in the following folders:
+
+- `backend/proto`
+- `frontend/packages/proto/src/generated`
+
+All generated code related to Protocol Buffers should be checked in to the repository.
+
+## Code Examples
+
+### Import using Go
+
+This is what you'll need to use for development in any of the `backend` services.
 
 ```go
 package spotify.backstage.identity.v1;
@@ -38,3 +61,28 @@ func main() {
   identityv1.NewInventoryClient(nil)
 }
 ```
+
+### Import using TypeScript
+
+This is what you'll need to use for development in any of the `frontend` services.
+Firstly, ensure this line is in your `package.json` within the `frontend/` folder:
+
+```js
+"dependencies": {
+  "@backstage/protobuf-definitions": "0.0.0",
+  ...
+}
+```
+
+Next, you can use them in your [Yarn Workspaces](https://yarnpkg.com/en/docs/workspaces/) package using the following:
+
+```ts
+import { IdentityClient } from "@backstage/protocol-definitions/generated/identity/v1/identity_pb_service";
+
+const client = new IdentityClient("http://localhost:8080");
+// const req = new GetUserRequest();
+// req.setUsername("johndoe");
+// client.getUser(req, (err, user) => {
+//   /* ... */
+// });
+```