Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update docs for CRAL with netlify dev #30

Merged
merged 4 commits into from
Aug 1, 2019
Merged

update docs for CRAL with netlify dev #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7977ddc
update docs for CRAL with netlify dev
Aug 1, 2019
8c7aab3
resolve merge
Aug 1, 2019
bd29162
resolve yarn lockfiles
Aug 1, 2019
3948599
readme
Aug 1, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 34 additions & 39 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,18 @@
> ⚠️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 this project at all. [Netlify Dev](https://github.com/netlify/netlify-dev-plugin) already works with `create-react-app` out of the box! **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), eg if you want to use Babel or TypeScript.

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`.

Your functions will be available locally at

[![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)

Expand All @@ -18,60 +26,47 @@ 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 both servers concurrently

From inside the project folder, run:

```
yarn start
```

This will run both `yarn start:lambda` and `yarn start:app` at the same time (more information about the commands can be found below).

> Note: 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.

### Start each server individually

**Run the functions dev server**

From inside the project folder, run:
```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

```
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**
You can view the project locally via Netlify Dev, via `localhost:8888`.

While the functions server is still running, open a new terminal tab and run:
Each function will be available at the same port as well: `http://localhost:8888/.netlify/functions/hello` and `http://localhost:8888/.netlify/functions/async-dadjoke`.

```
yarn start
```
## Deployment

This will start the normal create-react-app dev server and open your app at `http://localhost:3000`.
During deployment, this project is configured, inside `netlify.toml` to run the build `command`: `yarn build`.

Local in-app requests to the relative path `/.netlify/functions/*` will automatically be proxied to the local functions dev server.
`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
Expand All @@ -84,8 +79,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)
Expand All @@ -108,4 +103,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.
6 changes: 3 additions & 3 deletions netlify.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Loading