Skip to content

Commit

Permalink
docs(chore): 📚️ 🔧 review & update
Browse files Browse the repository at this point in the history
  • Loading branch information
Can-Sahin committed Nov 6, 2020
1 parent c55054a commit 45c604c
Show file tree
Hide file tree
Showing 23 changed files with 202 additions and 253 deletions.
9 changes: 9 additions & 0 deletions .all-contributorsrc
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,15 @@
"ideas",
"design"
]
},
{
"login": "mogsdad",
"name": "David Bingham",
"avatar_url": "https://avatars3.githubusercontent.com/u/1707731",
"profile": "https://github.com/mogsdad",
"contributions": [
"doc"
]
}
],
"contributorsPerLine": 8,
Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,12 +124,13 @@ But wait... there's more!
<!-- markdownlint-disable -->
<table>
<tr>
<td align="center"><a href="https://github.com/Can-Sahin"><img src="https://avatars2.githubusercontent.com/u/33245689" width="80px;" alt=""/><br /><sub><b>Can Sahin</b></sub></a><br /><a href="https://github.com/react-boilerplate/react-boilerplate-cra-template/commits?author=Can-Sahin" title="Code">💻</a> <a href="https://github.com/react-boilerplate/react-boilerplate-cra-template/commits?author=Can-Sahin" title="Documentation">📖</a> <a href="#ideas-Can-Sahin" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/react-boilerplate/react-boilerplate-cra-template/pulls?q=is%3Apr+reviewed-by%3ACan-Sahin" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/react-boilerplate/react-boilerplate-cra-template/commits?author=Can-Sahin" title="Tests">⚠️</a></td>
<td align="center"><a href="https://github.com/receptiryaki"><img src="https://avatars0.githubusercontent.com/u/3495307" width="80px;" alt=""/><br /><sub><b>Recep Tiryaki</b></sub></a><br /><a href="https://github.com/react-boilerplate/react-boilerplate-cra-template/commits?author=receptiryaki" title="Code">💻</a> <a href="#ideas-receptiryaki" title="Ideas, Planning, & Feedback">🤔</a> <a href="#design-receptiryaki" title="Design">🎨</a></td>
<td align="center"><a href="https://github.com/Can-Sahin"><img src="https://avatars2.githubusercontent.com/u/33245689?s=80" width="80px;" alt=""/><br /><sub><b>Can Sahin</b></sub></a><br /><a href="https://github.com/react-boilerplate/react-boilerplate-cra-template/commits?author=Can-Sahin" title="Code">💻</a> <a href="https://github.com/react-boilerplate/react-boilerplate-cra-template/commits?author=Can-Sahin" title="Documentation">📖</a> <a href="#ideas-Can-Sahin" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/react-boilerplate/react-boilerplate-cra-template/pulls?q=is%3Apr+reviewed-by%3ACan-Sahin" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/react-boilerplate/react-boilerplate-cra-template/commits?author=Can-Sahin" title="Tests">⚠️</a></td>
<td align="center"><a href="https://github.com/receptiryaki"><img src="https://avatars0.githubusercontent.com/u/3495307?s=80" width="80px;" alt=""/><br /><sub><b>Recep Tiryaki</b></sub></a><br /><a href="https://github.com/react-boilerplate/react-boilerplate-cra-template/commits?author=receptiryaki" title="Code">💻</a> <a href="#ideas-receptiryaki" title="Ideas, Planning, & Feedback">🤔</a> <a href="#design-receptiryaki" title="Design">🎨</a></td>
<td align="center"><a href="https://github.com/mogsdad"><img src="https://avatars3.githubusercontent.com/u/1707731?s=80" width="80px;" alt=""/><br /><sub><b>David Bingham</b></sub></a><br /><a href="https://github.com/react-boilerplate/react-boilerplate-cra-template/commits?author=mogsdad" title="Documentation">📖</a></td>
</tr>
</table>

<!-- markdownlint-enable -->
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->
Expand Down
10 changes: 5 additions & 5 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,17 @@

{% endhint %}

This is a custom [create-react-app] template of [react-boilerplate]. React Boilerplate has been developing the ultimate react starter kit for many years now. On the other hand **`CRA`**(create-react-app) is currently the people's favourite choice. This template has been created to join their strengths together. **`CRA`** provides the necessary bootstrapping to start your projects but does not provide a guide on how to build it. That is where **react-boilerplate** provides battle-tested techniques and tools to guide development of state-of-the-art web applications.
This is a custom [`create-react-app`] template of [`react-boilerplate`]. React Boilerplate has been developing the ultimate React starter kit for many years now. On the other hand **`CRA`** (`create-react-app`) is currently the people's favorite choice. This template has been created to join their strengths together. **`CRA`** provides the necessary bootstrapping to start your projects but does not provide a guide on how to build it. That is where **`react-boilerplate`** comes in and prepares the bases with the battle-tested techniques and tools to guide you into creating state-of-the-art web applications.

{% hint style="warning" %}

This documentation assumes that you are familiar with the [create-react-app]. The template is built on top of it ;)
This documentation assumes that you are familiar with the [`create-react-app`]. The template is built on top of it. ;)

{% endhint %}

## Let's get started with the documentation

In the following sections we will introduce this boilerplate to you shortly and then start diving into details with the [Building Blocks](building-blocks) section
In the following sections, we will briefly introduce this boilerplate to you and then start diving into details with the [Building Blocks](building-blocks/overview) section.

{% hint style="info" %}

Expand All @@ -28,5 +28,5 @@ NPM Package: [npm](https://www.npmjs.com/package/cra-template-rb)

{% endhint %}

[create-react-app]: https://github.com/facebook/create-react-app
[react-boilerplate]: https://github.com/react-boilerplate/react-boilerplate
[`create-react-app`]: https://github.com/facebook/create-react-app
[`react-boilerplate`]: https://github.com/react-boilerplate/react-boilerplate
4 changes: 2 additions & 2 deletions docs/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
‌# Summary​

- [Quick Start](quick-start.md)
- [Understading react-boilerplate](understanding-react-boilerplate.md)
- [Understanding `react-boilerplate`](understanding-react-boilerplate.md)

## Tools

Expand All @@ -13,7 +13,7 @@
- [Building Blocks](building-blocks/README.md)
- [Redux & Toolkit](building-blocks/redux-toolkit.md)
- [Reselect](building-blocks/reselect.md)
- [Redux Saga](building-blocks/redux-saga.md)
- [Redux-Saga](building-blocks/redux-saga.md)
- [Redux Injectors](building-blocks/redux-injectors.md)
- [Async Components](building-blocks/async-components.md)
- [Routing](building-blocks/routing.md)
Expand Down
58 changes: 29 additions & 29 deletions docs/building-blocks/README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Building Blocks

In this section we are going to explain the **building blocks** of the boilerplate in details.
In this section, we will explain the **building blocks** of the boilerplate in detail.

First we have to look at what is happening when react starts its life with `index.tsx` file.

### `src/index.tsx`:

It is one of the biggest files of the boilerplate. It contains all the global setup to make sure your app runs smoothly. Let's break its contents down:
It is one of the most important files of the boilerplate. It contains all the global setup to make sure your app runs smoothly. Let's break its contents down:

- `react-app-polyfill` is imported to enable compatibility with many browsers and cool stuff like generator functions, Promises, etc.
- A Redux `store` is instantiated.
Expand All @@ -15,78 +15,78 @@ It is one of the biggest files of the boilerplate. It contains all the global se
- i18next internationalization support setup.
- `<Provider />` connects your app with the Redux `store`.

So, all the bootstrapping and setup of the features we are using are being handled here. Here is the summary of the **building blocks**
Again, `src/index.tsx` handles all the bootstrapping and setup of the features we are using in the boilerplate. Now, let's review a summary of the **building blocks**.

{% hint style="info" %}

**🧙Tips:** Following chapters reveals more details and tutorials on how to use them
**🧙Tips:** Following chapters reveal more details and tutorials on how to use the building blocks.

{% endhint %}

### Redux

Redux is going to play a huge role in your application. If you're new to Redux, we'd strongly suggest you to complete this checklist and then come back:
Redux is likely to play a significant role in your application. If you're new to Redux, we'd strongly suggest that you complete this checklist and then come back:

- Understand the motivation behind Redux
- Understand the three principles of Redux
- Implement Redux in a small React app of yours
- Understand the motivation behind Redux.
- Understand the three principles of Redux.
- Implement Redux in a small React app of yours.

The Redux `store` is the heart of your application. Check out `src/store/configureStore.ts` to see how we have configured the store.

The store is created with the `createStore()` factory, which accepts three parameters.
The `createStore()` factory creates the Redux store and accepts three parameters.

1. **Root reducer:** A master reducer combining all your reducers.
2. **Initial state:** The initial state of your app as determined by your reducers.
3. **Middleware/enhancers:** Middlewares are third party libraries which intercept each redux action dispatched to the redux store and then... do stuff. For example, if you install the [`redux-logger`](https://github.com/evgenyrodionov/redux-logger) middleware, it will listen to all the actions being dispatched to the store and print previous and next state in the browser console. It's helpful to track what happens in your app.
3. **Middleware/enhancers:** Middlewares are third party libraries which intercept each Redux action dispatched to the Redux store and then... do stuff. For example, if you install the [`redux-logger`](https://github.com/evgenyrodionov/redux-logger) middleware, it will listen to all the actions being dispatched to the store and print the previous and next state in the browser console. It's helpful to track what happens in your app.

In our application we are using a single middleware.
In our application, we are using a single middleware.

1. **Redux saga:** Used for managing _side-effects_ such as dispatching actions asynchronously or accessing browser data.
1. **`redux-saga`:** Used for managing _side-effects_ such as dispatching actions asynchronously or accessing browser data.

### Redux-Toolkit

> The official, opinionated, batteries-included toolset for efficient Redux development
> The official, opinionated, batteries-included toolset for efficient Redux development.
This is the latest and best way of using redux. It handles lot of the things you would need to do to get redux working.
This is the latest and best way of using Redux. It handles lots of the things you would need to do to get Redux working.

We will leave you alone with their [documentation](https://redux-toolkit.js.org) at this point. This boilerplate heavily uses it and its crucial for you to understand and digest it.
We will leave you alone with their [documentation](https://redux-toolkit.js.org) at this point. This boilerplate uses Redux heavily, so you must understand it.

### Reselect

Reselect is a library used for slicing your redux state and providing only the relevant sub-tree to a react component. It has three key features:
Reselect is a library used for slicing your Redux state and providing only the relevant sub-tree to a React component. It has three key features:

1. Computational power
2. Memoization
3. Composability
1. Computational power.
2. Memoization.
3. Composability.

Imagine an application that shows a list of users. Its redux state tree stores an array of usernames with signatures:
Imagine an application that shows a list of users. Its Redux state tree stores an array of usernames with signatures:

`{ id: number, username: string, gender: string, age: number }`.

Let's see how the three features of reselect help.

- **Computation:** While performing a search operation, reselect will filter the original array and return only matching usernames. Redux state does not have to store a separate array of filtered usernames.
- **Memoization:** A selector will not compute a new result unless one of its arguments change. That means, if you are repeating the same search once again, reselect will not filter the array over and over. It will just return the previously computed, and subsequently cached, result. Reselect compares the old and the new arguments and then decides whether to compute again or return the cached result.
- **Composability:** You can combine multiple selectors. For example, one selector can filter usernames according to a search key and another selector can filter the already filtered array according to gender. One more selector can further filter according to age. You combine these selectors by using `createSelector()`
- **Memoization:** A selector will not compute a new result unless one of its arguments change. That means, if you are repeating the same search once again, reselect will not filter the array over and over. It will just return the previously computed and, subsequently, cached result. Reselect compares the old and the new arguments and then decides whether to compute again or return the cached result.
- **Composability:** You can combine multiple selectors. For example, one selector can filter usernames according to a search key, and another selector can filter the already filtered array according to gender. One more selector can further filter according to age. You combine these selectors by using `createSelector()`.

### Redux Saga
### Redux-Saga

If your application is going to interact with some back-end application for data, we recommend using redux saga for side effect management. Too much jargon? Let's simplify.
If your application interacts with some back-end API for data, we recommend using `redux-saga` for side-effect management. Too much jargon? Let's simplify.

Imagine that your application is fetching data in json format from a back-end. For every API call, ideally you should define at least three kinds of [action creators](http://redux.js.org/docs/basics/Actions.html):
Imagine that your application is fetching data in JSON format from a back-end. For every API call, ideally, you should define at least three kinds of [action creators](http://redux.js.org/docs/basics/Actions.html):

1. `API_REQUEST`: Upon dispatching this, your application should show a spinner to let the user know that something's happening.
2. `API_SUCCESS`: Upon dispatching this, your application should show the data to the user.
3. `API_FAILURE`: Upon dispatching this, your application should show an error message to the user.

And this is only for **_one_** API call. In a real-world scenario, one page of your application could be making tens of API calls. How do we manage all of them effectively? This essentially boils down to controlling the flow of your application. What if there was a background process that handles multiple actions simultaneously, communicates with the Redux store and react containers at the same time? This is where redux-saga comes into the picture.
And this is only for **_one_** API call. In a real-world scenario, one page of your application could be making tens of API calls. How do we manage all of them effectively? It essentially boils down to controlling the flow of your application. What if there was a background process that handled multiple actions simultaneously and communicated with the Redux store and React containers at the same time? Here is where `redux-saga` enters the picture.

The mental model is that a saga is like a separate thread in your application that's solely responsible for side effects. `redux-saga` is a redux middleware, which means this thread can be started, paused and cancelled from the main application with normal redux actions, it has access to the full redux application state and it can dispatch redux actions as well.
For a mental model, consider a saga like a separate thread in your application that's solely responsible for side-effects. Then `redux-saga` is a Redux middleware, which means this thread can be started, paused, and canceled from the main application with standard Redux actions. It has access to the full Redux application state, and it can dispatch Redux actions as well.

### Linting

This boilerplate includes a complete static code analysis setup. It's composed of [ESLint](http://eslint.org/), [stylelint](https://stylelint.io/), and [Prettier](https://prettier.io/).

We recommend that you install the relevant IDE extensions for each one of these tools. Once you do, every time you'll press save, all your code will be formatted and reviewed for quality automatically.
We recommend that you install the relevant IDE extensions for each one of these tools. Once you do, every time you press [save], all your code will automatically be formatted and reviewed for quality.

We've also set up a git hook to automatically analyze and fix linting errors before your code is committed. If you'd like to disable it or modify its behavior, take a look at the `lint-staged` section in `package.json`.
The boilerplate provides a pre-commit git hook to analyze and fix linting errors automatically before committing your code. If you'd like to disable it or modify its behavior, take a look at the `lint-staged` section in `package.json`.
2 changes: 1 addition & 1 deletion docs/building-blocks/async-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ export const HomePage = lazyLoad(
);
```

In this case, the app won't show anything while loading your component. You can however make it display a custom loader with:
In this case, the app won't show anything while loading your component. You can, however, make it display a custom loader with:

```ts
import * as React from 'react';
Expand Down
Loading

0 comments on commit 45c604c

Please sign in to comment.