> For the complete documentation index, see [llms.txt](https://bryan-guner.gitbook.io/my-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bryan-guner.gitbook.io/my-docs/redux/repos/examples/real-world.md).

# real-world

## Redux Real World Example

Huge thanks to [**@thejmazz**](https://github.com/thejmazz) for taking the time to write these notes about how the codebase works! 🍻

## React-Redux App Architecture

### Entrypoint

File: `index.js`

Imports: `agent.js`, `store.js`, `./components/*`

Renders routes pointing to their associated components:

```html
<Provider store="{store}">
  <Router history="{hashHistory}">
    <Route path="/" component="{App}">
      <IndexRoute component="{Home}" />
      <Route path="login" component="{Login}" />
      <Route path="register" component="{Register}" />
      <Route path="editor" component="{Editor}" />
      <Route path="editor/:slug" component="{Editor}" />
      <Route path="article/:id" component="{Article}" />
      <Route path="settings" component="{Settings}" />
      <Route path="@:username" component="{Profile}" />
      <Route path="@:username/favorites" component="{ProfileFavorites}" />
    </Route>
  </Router>
</Provider>
```

### Agent

File: `agent.js`

Exports an object where each key is a "service" and a service has methods that internally run a request:

* `get`
* `put`
* `post`
* `delete`

For example, `Auth`:

```javascript
const Auth = {
  current: () => requests.get('/user'),
  login: (email, password) =>
    requests.post('/users/login', { user: { email, password } }),
  register: (username, email, password) =>
    requests.post('/users', { user: { username, email, password } }),
  save: (user) => requests.put('/user', { user }),
}
```

Thus, these services essentially take some options, map to a request, and return the promise of that request. The general type could be:

```javascript
type Service = {
  [key: string]: (opts: any) => Promise<T>,
}
```

As well, `agent.js` locally stores a token which can be set via the exported `setToken`. As some config there is `API_ROOT`.

### Redux

#### Store

File: `store.js`

Imports: `reducer.js`, `middleware.js`

Fairly simple store setup, applies `promiseMiddleware` before `localStorageMiddleware`, logger only on development.

#### Middleware

File: `middleware.js`

Imports: `agent.js`

**promiseMiddleware**

Intercepts all actions where `action.payload` is a Promise. In which case it:

1. `store.dispatch({ type: 'ASYNC_START', subtype: action.type })`
2. `action.payload.then`
   * success: `store.dispatch({ type: 'ASYNC_END', promise: res })`
   * error: sets `action.error = true`, `store.dispatch({ type: 'ASYNC_END', promise: action.payload })`
3. Then, for success and error, using the modified `action` object: `store.dispatch(action)`

**localStorageMiddleware**

Runs after `promiseMiddleware`. Intercepts `REGISTER | LOGIN` and either

* a. sets token into localstorage and `agent.setToken(token)`
* b. sets token in localstorage to `''` and does `agent.setToken(null)`

#### Reducers

File: `reducer.js`

Imports: `./reducers/*.js`

Uses `combineReducers` to export a reducer where each key is the reducer of the file with the same key.

**General Reducer Patterns**

* map payload into piece of state
* toggle loading states by casing on `ASYNC_START` and `action.subtype`

```javascript
case 'ASYNC_START':
  if (action.subtype === 'LOGIN' || action.subtype === 'REGISTER') {
    return { ...state, inProgress: true };
  }
```

* toggle errors by taking `action.errors` if it is there (see middleware)

```javascript
case 'REGISTER':
  return {
    ...state,
    inProgress: false,
    errors: action.error ? action.payload.errors : null
  };
```

* set state keys to null if they did not come in payload (Flow type issues?)

```javascript
case 'REGISTER':
  return {
    ...state,
    inProgress: false,
    errors: action.error ? action.payload.errors : null
  };
```

* handle redirections (will be triggered by `componentWillReceiveProps` somewhere)

```javascript
case 'REDIRECT':
  return { ...state, redirectTo: null };
case 'LOGOUT':
  return { ...state, redirectTo: '/', token: null, currentUser: null };
case 'ARTICLE_SUBMITTED':
  const redirectUrl = `article/${action.payload.article.slug}`;
  return { ...state, redirectTo: redirectUrl };
```

### Components

Most `mapStateToProps` won't be mentionned, as there are fairly simple. Take some objects, use them in render.

`mapDispatchToProps` will be referred to as "handlers". Some will emerge as common ones. Dispatching some specific handlers on some specific lifecylce methods will also emerge as a pattern.

Handlers:

* `onLoad`
* `onUnload`
* `onSubmit`
* `onClick`
* `onX`

`onLoad` seems to be the most common one, used for any components that need ajax in data into store into props into their render method (which is basically everything on an SPA lol).

Patterns

* `onLoad` handlers pass a Promise or multiple promises via `Promise.all`
* sending multiple leads to magic `payload[0]` and `payload[1]` in reducer (see `reducers/article.js`)
* pass a handler, e.g. `onClickTag` as a prop to a child component. child component then calls it with agent: `props.onClickTag(tag, agent.Articles.byTag(tag))`. (does this only ever happen with a connected `index.jsx` inside a folder?)
* to render or not to render:

```javascript
if (!this.props.data) {
  component = <Loading /> // or perhaps null like in Header.js, ListErrors, EditProfileSettings in Profile
} else {
  component = <Thing data={this.props.data} />
}
```

* similary, if you cannot call handlers yet since props are not ready:

```javascript
componentWillMount() {
  if (this.props.params.slug) {
    return this.props.onLoad(agent.Articles.get(this.props.params.slug));
  }
  this.props.onLoad(null);
}
```

* use `componentWillReceiveProps` to call handlers if necessary, e.g. in `Editor.js`:

```javascript
componentWillReceiveProps(nextProps) {
  if (this.props.params.slug !== nextProps.params.slug) {
    if (nextProps.params.slug) {
      this.props.onUnload();
      return this.props.onLoad(agent.Articles.get(this.props.params.slug));
    }
    this.props.onLoad(null);
  }
}
```

#### Root Component - "/"

Imported components: `Header`

Handlers

* `onLoad: (payload, token) => dispatch({ type: 'APP_LOAD', payload, token, skipTracking: true })`
* `onRedirect: () => dispatch({ type: 'REDIRECT' })`

Lifecycle

```javascript
componentWillMount() {
  const token = window.localStorage.getItem('jwt');
  if (token) {
    agent.setToken(token);
  }

  this.props.onLoad(token ? agent.Auth.current() : null, token);
}

componentWillReceiveProps(nextProps) {
  if (nextProps.redirectTo) {
    this.context.router.replace(nextProps.redirectTo);
    this.props.onRedirect();
  }
}
```

#### Home Component - "/"

(`<IndexRoute>` on "/")

Handlers

```javascript
onClickTag: (tag, payload) => dispatch({ type: 'APPLY_TAG_FILTER', tag, payload }),
onLoad: (tab, payload) => dispatch({ type: 'HOME_PAGE_LOADED', tab, payload }),
onUnload: () => dispatch({  type: 'HOME_PAGE_UNLOADED' })
```

Lifecycle

```javascript
componentWillMount() {
  const tab = this.props.token ? 'feed' : 'all';
  const articlesPromise = this.props.token ?
    agent.Articles.feed() :
    agent.Articles.all();

  this.props.onLoad(tab, Promise.all([agent.Tags.getAll(), articlesPromise]));
}

componentWillUnmount() {
  this.props.onUnload();
}
```

#### Other Components

Should be self explanatory, follow patterns described above, it was just the home and index components are somewhat unique due to handling of routing.

This project template was built with [Create React App](https://github.com/facebookincubator/create-react-app), which provides a simple way to start React projects with no build configuration needed.

Projects built with Create-React-App include support for ES6 syntax, as well as several unofficial / not-yet-final forms of Javascript syntax such as Class Properties and JSX. See the list of [language features and polyfills supported by Create-React-App](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#supported-language-features-and-polyfills) for more information.

### Available Scripts

In the project directory, you can run:

#### `npm start`

Runs the app in the development mode.\
Open <http://localhost:3000> to view it in the browser.

The page will reload if you make edits.\
You will also see any lint errors in the console.

#### `npm run build`

Builds the app for production to the `build` folder.\
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.\
Your app is ready to be deployed!

#### `npm run eject`

**Note: this is a one-way operation. Once you `eject`, you can’t go back!**

If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.

You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bryan-guner.gitbook.io/my-docs/redux/repos/examples/real-world.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.