From 2f55c115d434619b63492feb595e297c199a69ae Mon Sep 17 00:00:00 2001 From: Naseem Date: Sun, 9 Aug 2020 11:09:07 -0400 Subject: [PATCH 1/5] docs: add ts example Signed-off-by: Naseem --- docs/README.md | 35 +++++++++++++++--------------- docs/typescript.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+), 17 deletions(-) create mode 100644 docs/typescript.md diff --git a/docs/README.md b/docs/README.md index 786b97c1..6b703058 100644 --- 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 new file mode 100644 index 00000000..a32ae715 --- /dev/null +++ b/docs/typescript.md @@ -0,0 +1,53 @@ +# Typescript + +This guide shows you 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 package(s): + + ```sh + npm install @google-cloud/functions-framework + ``` + + In this example we are using an HTTP signature and require express + types: + + ```sh + npm install @types/express -D + ``` + +3. Add a `start` script to `package.json`, passing in the `--source` flag to + point to the compiled code directory: + + ```js + "scripts": { + "start": "functions-framework --source=build/src/ --target=helloWorld", + ... + } + ``` + +4. Create a `src/index.ts` file with the following contents: + + ```ts + import type { HttpFunction } from '@google-cloud/functions-framework/build/src/functions'; + + export const helloWorld: HttpFunction = (req, res) => { + res.send('Hello, World'); + }; + ``` + +5. Compile and start the built-in local development server: + + ```sh + $ npm run compile && npm start + ... + Serving function... + Function: helloWorld + URL: http://localhost:8080/ + ``` From e068d55acbea366eab25ba042317f25ed1c2569d Mon Sep 17 00:00:00 2001 From: Naseem Date: Mon, 10 Aug 2020 00:09:03 -0400 Subject: [PATCH 2/5] docs: simplify instructions, leverage tsc-watch for development Signed-off-by: Naseem --- docs/typescript.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/typescript.md b/docs/typescript.md index a32ae715..c67485d9 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -1,6 +1,6 @@ # Typescript -This guide shows you an example of how to develop a function in Typescript with +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. @@ -9,25 +9,24 @@ the Functions Framework. npx gts init ``` -2. Install the required package(s): +2. Install the required packages: ```sh npm install @google-cloud/functions-framework - ``` - - In this example we are using an HTTP signature and require express - types: - - ```sh - npm install @types/express -D + # an HTTP signature requires express types + npm install @types/express --save-dev + # https://www.npmjs.com/package/tsc-watch + npm install tsc-watch --save-dev ``` 3. Add a `start` script to `package.json`, passing in the `--source` flag to - point to the compiled code directory: + 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": "tsc-watch --onSuccess 'npm start'", ... } ``` @@ -42,10 +41,11 @@ the Functions Framework. }; ``` -5. Compile and start the built-in local development server: +5. Start the built-in local development server: ```sh - $ npm run compile && npm start + $ npm run watch + [12:34:56 AM] Starting compilation in watch mode... ... Serving function... Function: helloWorld From 63df9a2b4d90bb220c9e661ba49f6bb3aeae9531 Mon Sep 17 00:00:00 2001 From: Naseem Date: Mon, 10 Aug 2020 09:14:20 -0400 Subject: [PATCH 3/5] fix: use Title Casing for title Signed-off-by: Naseem --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 6b703058..2f5735b0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,7 +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) +- [Writing a Function in Typescript](typescript.md) ## TODO Docs From 7d3d4a49ede7c594563393adaceea35b2303116f Mon Sep 17 00:00:00 2001 From: Naseem Date: Mon, 10 Aug 2020 09:16:49 -0400 Subject: [PATCH 4/5] fix: improve readbility and copy pasteability Signed-off-by: Naseem --- docs/typescript.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/typescript.md b/docs/typescript.md index c67485d9..b7447741 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -31,7 +31,7 @@ the Functions Framework. } ``` -4. Create a `src/index.ts` file with the following contents: +4. Replace the contents of `src/index.ts` with: ```ts import type { HttpFunction } from '@google-cloud/functions-framework/build/src/functions'; @@ -41,11 +41,17 @@ the Functions Framework. }; ``` -5. Start the built-in local development server: +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 - $ npm run watch [12:34:56 AM] Starting compilation in watch mode... + [12:34:57 AM] Found 0 errors. Watching for file changes. ... Serving function... Function: helloWorld From 84ca4e2079ec11708f21d49f04c2687fc6f621a9 Mon Sep 17 00:00:00 2001 From: Naseem Date: Tue, 11 Aug 2020 23:36:04 -0400 Subject: [PATCH 5/5] adapt watch script to use nodemon and concurrently Signed-off-by: Naseem --- docs/typescript.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/typescript.md b/docs/typescript.md index b7447741..b6130f89 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -13,10 +13,7 @@ the Functions Framework. ```sh npm install @google-cloud/functions-framework - # an HTTP signature requires express types - npm install @types/express --save-dev - # https://www.npmjs.com/package/tsc-watch - npm install tsc-watch --save-dev + npm install @types/express concurrently nodemon --save-dev ``` 3. Add a `start` script to `package.json`, passing in the `--source` flag to @@ -26,7 +23,7 @@ the Functions Framework. ```js "scripts": { "start": "functions-framework --source=build/src/ --target=helloWorld", - "watch": "tsc-watch --onSuccess 'npm start'", + "watch": "concurrently \"tsc -w\" \"nodemon --watch ./build/ --exec npm run start\"", ... } ```