Skip to content

Commit 2136edd

Browse files
rafaelspintorafaelspinto
committed
Updated README
1 parent a555af7 commit 2136edd

File tree

1 file changed

+149
-29
lines changed

1 file changed

+149
-29
lines changed

‎README.md

Lines changed: 149 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,37 @@
11
# Serverless React App Workshop
22

3-
This workshop is designed to help you start building [Serverless](https://martinfowler.com/articles/serverless.html) [ReactJS](https://reactjs.org/) Apps. For simplification purposes we will be creating a basic **Contact Us** application. The application will be implemented using a [3 Tier Architecture](https://en.wikipedia.org/wiki/Multitier_architecture#Three-tier_architecture):
4-
- **Presentation** (aka Frontend)
3+
This workshop is designed to help you start building [Serverless](https://martinfowler.com/articles/serverless.html) [React](https://reactjs.org/) Apps using the ```AWS``` services. The main goal is for you to have the full infrastructure running on your local setup to easily develop and test.
4+
5+
For simplification purposes we will be creating a basic **Contact Us** application. The application will be implemented using a [3 Tier Architecture](https://en.wikipedia.org/wiki/Multitier_architecture#Three-tier_architecture):
6+
- **Presentation** using [ReactJS](https://reactjs.org/)
7+
This tier is also known as Front-end.
58
- A page with a contact form with a name, email and message.
69
- A page with a list of received contacts.
7-
- **Logic** (aka Backend)
10+
- **Logic** using [AWS Lambda](https://aws.amazon.com/lambda/)
11+
This tier is also known as Back-end.
812
- Two endpoints for submitting the form and reading all contacts.
9-
- **Data** (aka Persistency)
13+
- **Data** using [AWS DynamoDB](https://aws.amazon.com/dynamodb/) and [AWS DynamoDB-local](https://hub.docker.com/r/amazon/dynamodb-local/)
14+
This tier is also known as Persistency.
1015
- A database to store all contacts.
1116

17+
### What will not be covered (for now)
18+
- Authentication
19+
- Authorization
20+
- Deployment to AWS
21+
22+
## Table of Contents
23+
24+
- [Pre-requisites](#pre-requisites)
25+
- [Running locally](#running-locally)
26+
- [Essentials](#essentials)
27+
1228
## Pre-requisites
1329

1430
You should be familiar with the Composition Pattern because React recommends it. Please have a look at the [Composition vs Inheritance](https://reactjs.org/docs/composition-vs-inheritance.html) page from the React docs.
1531

16-
Although we will not cover deployment into AWS in this workshop, you still need to create an [AWS Free Tier](https://aws.amazon.com/free/) account in order to use the local stack. After creating your account and installing the software from the [Logic](#Logic) section, please run the following command to configure your local default settings:
32+
Although we will not cover deployment into AWS in this workshop, **you still need to create** an [AWS Free Tier](https://aws.amazon.com/free/) account in order to use the local stack.
33+
34+
After creating your account and installing the software from the [Logic](#logic) section, please run the following command to configure your local default settings:
1735

1836
```
1937
aws configure
@@ -30,6 +48,7 @@ Via npm (already in package.json):
3048
- [ReactJS](https://reactjs.org/) - A JavaScript library for building user interfaces.
3149
- [React Router](https://github.com/ReactTraining/react-router) - Declarative routing for React.
3250
- [React Router Dom](https://github.com/ReactTraining/react-router/tree/master/packages/react-router-dom) - DOM bindings for React Router.
51+
- [cross-env](https://github.com/kentcdodds/cross-env) - Set and use environment variables across platforms.
3352

3453
### Logic
3554

@@ -54,38 +73,139 @@ For the data tier we will be using:
5473

5574
Via npm (already in package.json):
5675
- [AWS SDK](https://github.com/aws/aws-sdk-js) - AWS SDK for JavaScript.
76+
- [cross-env](https://github.com/kentcdodds/cross-env) - Set and use environment variables across platforms.
5777

5878
## Running Locally
5979

60-
To run this project locally in development mode you need to clone the repository and either use the [start.sh](start.sh) script or start the 3 tiers independently (using the following commands):
61-
62-
```
63-
git clone https://github.com/rafaelspinto/workshop-serverless-react-app
80+
To run this project in development mode you need to:
81+
1. clone the repository
82+
```bash
83+
git clone https://github.com/rafaelspinto/workshop-serverless-react-app
84+
```
85+
2. if you are using Linux or MacOS you can run the start.sh script at the root of the project:
86+
87+
```bash
88+
./start.sh
89+
```
90+
or
91+
92+
2. start the 3 tiers independently (using the following commands):
93+
94+
- Starting the Presentation tier
95+
```bash
96+
cd presentation
97+
npm install # only required in the first time
98+
npm start
99+
```
100+
101+
- Starting the Logic tier
102+
```bash
103+
cd logic
104+
cd handlers; npm install; cd .. # only required in the first time
105+
sam local start-api --docker-network lambda-local
106+
```
107+
108+
- Starting the Data tier
109+
```bash
110+
docker run -d --rm --name dynamodb-local --network lambda-local -p 8000:8000 amazon/dynamodb-local
111+
cd data
112+
npm install # only required in the first time
113+
npm run create-db
114+
```
115+
116+
3. Stopping the Data tier
117+
118+
```
119+
docker stop dynamodb-local
120+
```
121+
122+
## Essentials
123+
124+
### Code changes
125+
126+
The tools used here support hot reloading, which means that everytime you change the code it will automatically be reflected on the local application.
127+
128+
**Note:** changes to the SAM template.yaml file will only be reflected when you restart the ```sam local start-api...``` command.
129+
130+
131+
### AWS
132+
133+
- You need at least an [AWS Free Tier](https://aws.amazon.com/free/) account in order to use the local or cloud stack.
134+
- To configure locally your AWS account run the command ```aws configure```:
135+
- Credentials will be stored in ```~/.aws/credentials```and are a set of ```access_key_id``` + ```secret_access_key```.
136+
- Configuration will be stored in ```~/.aws/config```and requires at least the region.
137+
138+
### Docker
139+
140+
- A local docker network called ```lambda-local``` needs to be created to easily support communication between ```lambda``` and ```dynamodb```.
141+
142+
### JavaScript
143+
144+
- [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) are a mechanism used to support asynchronous operations, that gives you ```resolve``` and ```reject``` functions to handle the result after it was processed. A good example of this is the [axios](https://github.com/axios/axios) http client:
145+
146+
147+
```javascript
148+
axios.post('/user', {
149+
firstName: 'Fred',
150+
lastName: 'Flintstone'
151+
})
152+
.then(function (response) {
153+
console.log(response);
154+
})
155+
.catch(function (error) {
156+
console.log(error);
157+
});
158+
```
159+
160+
### ReactJS
161+
162+
[ReactJS](https://reactjs.org/)
163+
164+
- Composition over Inheritance, see [Composition vs Inheritance](https://reactjs.org/docs/composition-vs-inheritance.html).
165+
- Updates and renders the right components on data change.
166+
- JSX syntax (xml-like):
167+
```jsx
168+
class HelloMessage extends React.Component {
169+
render() {
170+
return (
171+
<div>
172+
Hello {this.props.name}
173+
</div>
174+
);
175+
}
176+
}
64177
```
178+
- ***props*** holds the Component attributes.
179+
- ***state*** holds the Component state.
180+
- **MUST** know methods:
181+
- ```render()``` - defines how a Component shall be rendered.
182+
- ```componentWillMount()``` - perform actions before component is mounted (e.g.: fetch data)
183+
- ```componentWillUnmount()``` - perform actions before component unmounted (e.g.: clear timers)
184+
- It is configured to run locally at **Port 3001**
65185
66-
#### Starting the Presentation tier
67-
```
68-
cd presentation; npm start
69-
```
186+
### AWS Lambda
70187
71-
#### Starting the Logic tier
72-
```
73-
cd logic; sam local start-api --docker-network lambda-local
74-
```
188+
[AWS Lambda](https://aws.amazon.com/lambda/)
75189
76-
#### Starting the Data tier
77-
```
78-
docker run -d --rm --name dynamodb-local --network lambda-local -p 8000:8000 amazon/dynamodb-local
79-
cd data && npm run create-db
80-
```
81-
#### Stopping the Data tier
190+
- Local usage is possible with the docker image [lambci/lambda:nodejs8.10](https://github.com/lambci/docker-lambda).
191+
- It is configured to run locally at **Port 3000**
82192
83-
```
84-
docker stop dynamodb-local
85-
```
193+
### AWS Serverless Application Model (SAM)
194+
195+
[AWS SAM](https://aws.amazon.com/serverless/sam/#Install_SAM_CLI)
196+
197+
- Relies on a file called ```template.yaml``` that specifies the Resources (Functions, Database, APIs, etc). This is an extension to [CloudFormation](https://aws.amazon.com/cloudformation/).
198+
- Has a command line tool ```sam``` that uses the ```aws-cli``` as a base.
199+
200+
### AWS DynamoDB
201+
202+
[DynamoDB](https://aws.amazon.com/dynamodb/)
203+
204+
- Local usage is possible with the docker image [amazon/dynamodb-local](https://hub.docker.com/r/amazon/dynamodb-local/).
205+
- It is configured to run locally at **Port 8000**
86206
87-
## Changing the code
207+
### Cross-Origin Resource Sharing (CORS)
88208
89-
Due to hot reloading, everytime you change the code it will automatically be reflected on the application.
209+
[Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
90210
91-
**Note:** changes to the SAM template.yaml file will only be reflected when you restart the ```sam local start-api...``` command.
211+
For security reasons, browsers restrict HTTP requests initiated from within scripts.

0 commit comments

Comments
 (0)
close