update docs for CRAL with netlify dev

Author: sw-yx

README.md

@@ -1,10 +1,16 @@
-> ⚠️You may not need `netlify-lambda`. [Netlify Dev](https://github.com/netlify/netlify-dev-plugin) works with `create-react-app` out of the box, give it a try! Only use `netlify-lambda` if you need a build step for your functions. [See its README for details](https://github.com/netlify/netlify-lambda/blob/master/README.md#netlify-lambda).
+## Create-React-App-Lambda
 
-This project is based on latest versions of [Create React App v3](https://github.com/facebookincubator/create-react-app) and [netlify-lambda v1](https://github.com/netlify/netlify-lambda).
+This project is a reference demo showing you how to use [Create React App v3](https://github.com/facebookincubator/create-react-app) and [netlify-lambda v1](https://github.com/netlify/netlify-lambda) together in a [Netlify Dev](https://github.com/netlify/netlify-dev-plugin) workflow.
 
-The main addition to base Create-React-App is a new folder: `src/lambda`. Each JavaScript file in there will be built for Lambda function deployment in `/built-lambda`, specified in [`netlify.toml`](https://www.netlify.com/docs/netlify-toml-reference/).
+⚠️NOTE: You may not need `netlify-lambda`. [Netlify Dev](https://github.com/netlify/netlify-dev-plugin) already works with `create-react-app` out of the box, give it a try! **Only use `netlify-lambda` if you need a build step for your functions.** [See its README for details](https://github.com/netlify/netlify-lambda/blob/master/README.md#netlify-lambda).
 
-As an example, we've included a small `src/lambda/hello.js` function, which will be deployed to `/.netlify/functions/hello`. We've also included an async lambda example using async/await syntax in `async-chuck-norris.js`.
+## Project Setup
+
+Source: The main addition to base Create-React-App is a new folder: `src/lambda`. This folder is specified and can be changed in the `package.json` script: `"build:lambda": "netlify-lambda build src/lambda"`.
+
+Dist: Each JavaScript file in there will be built for Lambda function deployment in `/built-lambda`, specified in [`netlify.toml`](https://www.netlify.com/docs/netlify-toml-reference/).
+
+As an example, we've included a small `src/lambda/hello.js` function, which will be deployed to `/.netlify/functions/hello`. We've also included an async lambda example using async/await syntax in `async-dadjoke.js`.
 
 [![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/netlify/create-react-app-lambda)
 
@@ -18,50 +24,43 @@ All functions are compiled with webpack using the Babel Loader, so you can use m
 
 ## Local Development
 
-Before developing, clone the repository and run `yarn` from the root of the repo to install all dependencies.
-
-### Start each server individually
+```bash
+## prep steps for first time users
+npm i -g netlify-cli # Make sure you have the [Netlify CLI](https://github.com/netlify/cli) installed
+git clone https://github.com/netlify/create-react-app-lambda ## clone this repo
+cd create-react-app-lambda ## change into this repo
+yarn # install all dependencies
 
-**Run the functions dev server**
-
-From inside the project folder, run:
-
-```
-yarn start:lambda
+## done every time you start up this project
+ntl dev ## nice shortcut for `neltify dev`
 ```
 
-This will open a local server running at `http://localhost:9000` serving your Lambda functions, updating as you make changes in the `src/lambda` folder.
+This fires up [Netlify Dev](https://github.com/netlify/netlify-dev-plugin/), which:
 
-You can then access your functions directly at `http://localhost:9000/{function_name}`, but to access them with the app, you'll need to start the app dev server. Under the hood, this uses `react-scripts`' [advanced proxy feature](https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/README.md#configuring-the-proxy-manually) with the `setupProxy.js` file.
+- Detects that you are running a `create-react-app` project and runs the npm script that contains `react-scripts start`, which in this project is the `start` script
+- Detects that you use `netlify-lambda` as a [function builder](https://github.com/netlify/netlify-dev-plugin/#function-builders-function-builder-detection-and-relationship-with-netlify-lambda), and runs the npm script that contains `netlify-lambda build`, which in this project is the `build:lambda` script
 
-**Run the app dev server**
+## Deployment
 
-While the functions server is still running, open a new terminal tab and run:
+During deployment, this project is configured, inside `netlify.toml` to run the build `command`: `yarn build`.
 
-```
-yarn start
-```
-
-This will start the normal create-react-app dev server and open your app at `http://localhost:3000`.
-
-Local in-app requests to the relative path `/.netlify/functions/*` will automatically be proxied to the local functions dev server.
-
-> Note: You can also use [npm-run-all](https://github.com/mysticatea/npm-run-all#readme) to run the functions dev server and app dev server concurrently. Note that you don't need this if you use [`netlify dev`](https://github.com/netlify/netlify-dev-plugin/) as [function builder detection](https://www.netlify.com/blog/2019/04/24/zero-config-yet-technology-agnostic-how-netlify-dev-detectors-work/) does that for you.
+`yarn build` corresponds to the npm script `build`, which uses `npm-run-all` (aka `run-p`) to concurrently run `"build:app"` (aka `react-scripts build`) and `build:lambda` (aka `netlify-lambda build src/lambda`).
 
 ## Typescript
 
 <details>
   <summary>
     <b id="typescript">Click for instructions</b>
   </summary>
-You can use Typescript in both your React code (with `react-scripts` v2.1+) and your lambda functions )with `netlify-lambda` v1.1+). Follow these instructions:
+
+You can use Typescript in both your frontend React code (with `react-scripts` v2.1+) and your serverless functions (with `netlify-lambda` v1.1+). Follow these instructions:
 
 1. `yarn add -D typescript @types/node @types/react @types/react-dom @babel/preset-typescript @types/aws-lambda`
 2. convert `src/lambda/hello.js` to `src/lambda/hello.ts`
 3. use types in your event handler:
 
 ```ts
-import { Handler, Context, Callback, APIGatewayEvent } from "aws-lambda"
+import { Handler, Context, Callback, APIGatewayEvent } from 'aws-lambda'
 
 interface HelloResponse {
   statusCode: number
@@ -74,8 +73,8 @@ const handler: Handler = (event: APIGatewayEvent, context: Context, callback: Ca
     statusCode: 200,
     body: JSON.stringify({
       msg: `Hello world ${Math.floor(Math.random() * 10)}`,
-      params
-    })
+      params,
+    }),
   }
 
   callback(undefined, response)
@@ -98,4 +97,4 @@ For a full demo of routing and authentication, check this branch: https://github
 
 ## Service Worker
 
-The service worker does not work with lambda functions out of the box. It prevents calling the function and returns the app itself instead ([Read more](https://github.com/facebook/create-react-app/issues/2237#issuecomment-302693219)). To solve this you have to eject and enhance the service worker configuration in the webpack config. Whitelist the path of your lambda function and you are good to go.
+`create-react-app`'s default service worker (in `src/index.js`) does not work with lambda functions out of the box. It prevents calling the function and returns the app itself instead ([Read more](https://github.com/facebook/create-react-app/issues/2237#issuecomment-302693219)). To solve this you have to eject and enhance the service worker configuration in the webpack config. Whitelist the path of your lambda function and you are good to go.

netlify.toml

@@ -1,4 +1,4 @@
 [build]
-  command = "yarn build"
-  functions = "built-lambda"
-  publish = "build"
+  command = "yarn build" # the command you run to build this file
+  functions = "built-lambda" # netlify-lambda builds to this folder AND Netlify reads functions from here
+  publish = "build" # create-react-app builds to this folder, Netlify should serve all these files statically

package.json

@@ -1,16 +1,15 @@
 {
-  "name": "react-lambda",
-  "version": "0.4.0",
+  "name": "create-react-app-lambda",
+  "version": "0.5.0",
   "private": true,
   "dependencies": {
     "axios": "^0.19.0",
     "react": "^16.8.6",
     "react-dom": "^16.8.6",
-    "react-scripts": "^3.0.0"
+    "react-scripts": "^3.0.1"
   },
   "scripts": {
     "start": "react-scripts start",
-    "start:lambda": "netlify-lambda serve src/lambda",
     "build": "run-p build:**",
     "build:app": "react-scripts build",
     "build:lambda": "netlify-lambda build src/lambda",
@@ -27,9 +26,6 @@
     "not op_mini all"
   ],
   "devDependencies": {
-    "@babel/plugin-transform-object-assign": "^7.0.0",
-    "babel-loader": "8.0.5",
-    "http-proxy-middleware": "^0.19.0",
     "netlify-lambda": "^1.4.5",
     "npm-run-all": "^4.1.5"
   }

src/lambda/hello.js

@@ -1,7 +1,8 @@
+// this uses the callback syntax, however, we encourage you to try the async/await syntax shown in async-dadjoke.js
 export function handler(event, context, callback) {
-  console.log("queryStringParameters", event.queryStringParameters)
+  console.log('queryStringParameters', event.queryStringParameters)
   callback(null, {
     statusCode: 200,
-    body: JSON.stringify({ msg: "Hello, World!" })
+    body: JSON.stringify({ msg: 'Hello, World!' }),
   })
 }