docs: add ts example (GoogleCloudPlatform#192)

naseemkullah · web-flow · commit 391ebfa8458c · 2020-08-12T14:42:47.000-05:00
* docs: add ts example

Signed-off-by: Naseem &lt;naseem@transit.app&gt;

* docs: simplify instructions, leverage tsc-watch for development

Signed-off-by: Naseem &lt;naseem@transit.app&gt;

* fix: use Title Casing for title

Signed-off-by: Naseem &lt;naseem@transit.app&gt;

* fix: improve readbility and copy pasteability

Signed-off-by: Naseem &lt;naseem@transit.app&gt;

* adapt watch script to use nodemon and concurrently

Signed-off-by: Naseem &lt;naseem@transit.app&gt;
diff --git a/docs/README.md b/docs/README.md
@@ -5,6 +5,7 @@ This directory contains advanced docs around the Functions Framework.
 - [Testing events and Pub/Sub](events.md)
 - [Debugging Functions](debugging.md)
 - [Running and Deploying Docker Containers](docker.md)
+- [Writing a Function in Typescript](typescript.md)
 
 ## TODO Docs
 
@@ -16,28 +17,28 @@ The Functions Framework works with standard tooling that you might use when writ
 
 1. Write an `index.js` file containing your Node.js function:
 
-```js
-exports.helloWorld = (req, res) => {
-  res.send('Hello, World');
-};
-```
+    ```js
+    exports.helloWorld = (req, res) => {
+      res.send('Hello, World');
+    };
+    ```
 
 2. Install the Functions Framework:
 
-```sh
-npm install @google-cloud/functions-framework
-```
+    ```sh
+    npm install @google-cloud/functions-framework
+    ```
 
 3. Run `node`, enable the inspector and run the Functions Framework:
 
-```sh
-node --inspect node_modules/@google-cloud/functions-framework --target=helloWorld
-...
-Debugger listening on ws://127.0.0.1:9229/5f57f5e9-ea4b-43ce-be1d-6e9b838ade4a
-For help see https://nodejs.org/en/docs/inspector
-Serving function...
-Function: helloWorld
-URL: http://localhost:8080/
-```
+    ```sh
+    node --inspect node_modules/@google-cloud/functions-framework --target=helloWorld
+    ...
+    Debugger listening on ws://127.0.0.1:9229/5f57f5e9-ea4b-43ce-be1d-6e9b838ade4a
+    For help see https://nodejs.org/en/docs/inspector
+    Serving function...
+    Function: helloWorld
+    URL: http://localhost:8080/
+    ```
 
 You can now use an IDE or other tooling to add breakpoints, step through your code and debug your function.
diff --git a/docs/typescript.md b/docs/typescript.md
@@ -0,0 +1,56 @@
+# Typescript
+
+This guide is an example of how to develop a function in Typescript with
+the Functions Framework.
+
+1. Use [gts](https://github.com/google/gts) to configure Typescript.
+
+    ```sh
+    npx gts init
+    ```
+
+2. Install the required packages:
+
+    ```sh
+    npm install @google-cloud/functions-framework
+    npm install @types/express concurrently nodemon --save-dev
+    ```
+
+3. Add a `start` script to `package.json`, passing in the `--source` flag to
+   point to the compiled code directory (configured by `gts` in this example).
+   Also add a `watch` script to use for development:
+
+    ```js
+      "scripts": {
+        "start": "functions-framework --source=build/src/ --target=helloWorld",
+        "watch": "concurrently \"tsc -w\" \"nodemon --watch ./build/ --exec npm run start\"",
+        ...
+      }
+    ```
+
+4. Replace the contents of `src/index.ts` with:
+
+    ```ts
+    import type { HttpFunction } from '@google-cloud/functions-framework/build/src/functions';
+
+    export const helloWorld: HttpFunction = (req, res) => {
+      res.send('Hello, World');
+    };
+    ```
+
+5. Start the built-in local development server in watch mode:
+
+    ```sh
+    npm run watch
+    ```
+
+    This will continuously watch changes to your TypeScript project and recompile when changes are detected:
+
+    ```sh
+    [12:34:56 AM] Starting compilation in watch mode...
+    [12:34:57 AM] Found 0 errors. Watching for file changes.
+    ...
+    Serving function...
+    Function: helloWorld
+    URL: http://localhost:8080/
+    ```
