# Create Web App

A complete fullstack boilerplate for React/Graphql/AppSync web applications which extends the amazing [Create-React-App](https://github.com/facebook/create-react-app) with Apollo2, Reach Router, code splitting, aws s3 deploy and much more.

## Table of Contents

- [Create an App](#create-an-app)
- [Folder Structure](#folder-structure)
- [Available Scripts](#avialable-scripts)
- [Importing Modules](#importing-modules)
- [Styling](#styling)
  - [Responsive Design](#responsive-design)
  - [Global styles](#global-styles)
- [Testing](#testing)
  - [Unit Testing](#unit-testing)
  - [Integration Testing](#integration-testing)
- [Code Splitting](#code-splitting)
- [Internationalization](#internationalization)
- [Environment Variables](#environment-variables)
- [Error Tracking](#error-tracking)
- [Analytics](#analytics)
- [Continous Integration](#continous-integration)

## Create an App

There are two ways to create a new app.

### npm (global package)

```sh
sudo npm install -g @cuttlas8/create-web-app
create-web-app my-web-app
```

### npx

```sh
npx @cuttlas8/create-web-app my-web-app
```

_([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) comes with npm 5.2+ and higher)_

## Folder Structure

## Available Scripts

## Importing Modules

## Styling

To style the application the [styled-components](https://github.com/styled-components/styled-components) library is used. Every component that needs styling must have a `styles.js` file next to components' `index.js` file where all its styled components are defined and exported. The styled components are then imported in the `index.js` file using the desconstructing syntax.

```javascript
//styles.js

import styled from "styled-components";

export const Wrapper = styled.div`
  padding-top: 50px;
  background-color: blue;
`;
```

```javascript
//index.js

import { Wrapper } from "./styles";

const myComponent = () => {
  return <Wrapper>Hello World!</Wrapper>;
};
```

### Responsive Design

The application follows a mobile-first approach.

### Global Styles

Global syles (ex. styles for the body tag, CSS resets..) are defined at the `index.css` file found in the project root.

## Testing

### Unit Testing

Jest & react-testing-library

### Integration Testing

Cypress

## Code Splitting

The application supports code splitting through ES6 dynamic imports and [React.lazy](https://reactjs.org/blog/2018/10/23/react-v-16-6.html#reactlazy-code-splitting-with-suspense). It's encouraged to dynamically load all route components plus any other hidden expensive component (ex. a map inside a tab). To dynamically load a component, use the lazy function from React:

```javascript
import React, { lazy, Suspense } from "react";

const MyComponent = lazy(() => import("main/MyComponent"));

//use MyComponent as a normal component.
```

The component (and the sub-components it requires) won't be included in the initial bundle and only will be loaded when the component is rendered.

## Internationalization

## Environment Variables

Environment variables are defined in the following files in the project root:

- `.env`: Default.
- `.env.development`, `.env.test`, `.env.production`: Environment-specific settings.
- `.env.development.local`, `.env.test.local`, `.env.production.local`: Local overrides of environment-specific settings.

Files on the left have more priority than files on the right:

- `npm start`: `.env.development.local`, `.env.development`, `.env`
- `npm run build`: `.env.production.local`, `.env.production`, `.env`
- `npm test`: `.env.test.local`, `.env.test`, `.env`

Note that the `.local` files shouldn't be commited to the version control repository and are already in the `.gitignore` file.

> IMPORTANT: For [security reasons](https://github.com/facebook/create-react-app/issues/865#issuecomment-252199527), all custom variables must be prefixed with `REACT_APP_`

In `.js` files, environment variables are accessible through the `process.env` variable:

```javascript
const apiUrl = process.env.REACT_APP_API_URL;
```

In the `public/index.html` file, environment variables are accessible as follows:

```html
<title>%REACT_APP_WEBSITE_NAME%</title>
```

There is also a special built-in environment variable called NODE_ENV. You can read it from process.env.NODE_ENV. When you run npm start, it is always equal to 'development', when you run npm test it is always equal to 'test', and when you run npm run build to make a production bundle, it is always equal to 'production'. You cannot override NODE_ENV manually. This prevents developers from accidentally deploying a slow development build to production.

## Error Tracking

Sentry & LogRocket

## Analytics

AWS Pinpoint

## Continous Integration

CycleCI