<commit_before>The purpose of this document is to help guide you through working with a potential project using the JavaScript library, [React](https://reactjs.org/). Outside of The official React documentation, you should find here personalized recommendations for using the library based on the types of projects we typically  see at 10up. We have broken these recommendations out into common elements we tend to interact with often in client work. If something you’re looking for isn’t represented you can either submit a pull request to this repository or refer to the [official React documentation](https://reactjs.org/).

## Figuring Out If React Is Right For Your Project

Using the right tool for the job is critical in navigating a successful project. Will React always be the answer? Of course not. But there are some instances where you may want to use this library over something like (for example) a collection of plugins, custom JavaScript, or another framework.

When deciding whether React is the right tool for your project, it might help to ask the following questions:

* Will this project involve building a user interface that requires statefulness? In other words, will your user interface need to...react...in real time to user actions or changeable data coming from an API?
* Does your project need enough reusable components to make it worth using React? React is a fairly heavy library compared with the similar Vue.
* Will your project need to render large amounts of data in real time while remaining performant for the browser?
* Are you building a native mobile app for iOS and/or Android? The React team also maintains React Native, a subset of React which makes it possible to write applications in JavaScript using React components that compile to native Swift and Java.

React is easily integrated into specific parts of the front-end or admin of an existing site, but it can also be used to render entire sites, effectively replacing traditional WordPress templates—although doing so requires a lot more planning and scaffolding of features (such as routing) that would normally be handled by the CMS out of the box.

## Implementing React on a Project

There are a number of ways to get up and running with React in a project. The deciding factor is based on the context of your project and how you plan to implement React. The following subsections will outline instructions that are specific to installing React on a per project basis:

### Script Element

Including React via a script element in your HTML is a pretty quick and standard way of including the library. To do this you can either [download the library directly](https://react-cn.github.io/react/downloads.html), use the [CDN](https://reactjs.org/docs/cdn-links.html), or install through [NPM](https://www.npmjs.com/package/react) and direct-link into your `node_modules` directory.

Something to note about this method is that React and ReactDOM are both required. There is also no inherent support for ES6 or JSX without Webpack or Babel in this context. You would need to separately configure a transpiler or write in Vanilla JavaScript.

### Including with NPM

If you already have a Node / NPM / Yarn project that you wish to include React as a dependency of, then you can use the installation instructions found on the [Official React Documentation](https://reactjs.org/docs/add-react-to-an-existing-app.html). Include React and ReactDOM in your package file just like you would any other dependency. Also be sure your transpiler is working to correctly process the ES6 and JSX from React into something the browser can understand.

### Installation with a CLI

[The React CLI](https://reactjs.org/blog/2016/07/22/create-apps-with-no-configuration.html) (create-react-app) provides us a quick way to setup and scaffold a React project. It makes use of the modern frontend workflows and out of the box, React CLI provides hot reloading, minification, asset management, module bundling, linting and a development server to test your application under realistic circumstances. It works with zero configuration from your part as everything is already set up.

Using the CLI tool is ideal if you are creating a full React App with an API backend.

## Components
When building out components, its beneficial to understand how to construct them in the most appropriate way possible. Certain "types" of components can be written differently which can have big performance benefits on larger scale applications.

### Class Components
Class Components are written in the ES6 Class syntax. When building a component using a JS Class, you are generally inferring that the component either manages its own `state` or it's `state` is managed by a state management library like Redux. LifeCycle methods are only available in class components. 

Class components are also capabale of handling `props`. Use these components when you need to build "intelligent" React components that are aware of their own `state` as well as the `state` of their children. Examples would include: Accordions, Dropdowns, Modals or Responsive Navigation.

### Stateless Functions
A Stateless function can take the form of a plain function in JavaScript, or a fat arrow function stored in a variable. The biggest difference between a Class Component and a Stateless Function is that Stateless Functions are not aware of `state`. `state` can not be passed to them from a parent (unless it's through `props`) thus the component cannot update `state`. Stateless Function's can handle props as a destructured object as a parameter. 

If your component is not required to update `state` or the `state` of child components use a Stateless Function. They have a low re-render cost and provide for cleaner code. Examples would include: Grids, Sections, Dividers, Icons, Scaffolding.

### PureComponents
PureComponents allow for greater performance benefits with in the React Lifecycle. When using a Pure Component, the logic of `shouldComponentUpdate` is altered to check whether a re-render is necessary when changes to `props` or `state` are compared. This is known as a _shallow-comparison_. In Class Components - `shouldComponentUpdate` will always fire, thus so will `render`. 

Use PureComponents to increase performance benefits of stateful components where you can easily ensure updates to `state` and `props` have not caused any mutations or side effects. Pure Components are highly subjective to how your component is tied up with in the context of `state` - many factors could have an influence on this decision such as design patterns, state management libraries and function.


## Routing

In most cases, you will only need routing if your React application needs to navigate between multiple layout components, render different data based on the current app location, and provide browser history. Make sure your app needs routing functionality before you consider adding a routing library.

The most popular routing library for React is [React Router](https://github.com/ReactTraining/react-router). React Router provides a core library plus APIs for both DOM (web) and React Native (native iOS and Android) platforms. To use the library, install the package for one or the other API according to your application’s platform needs—the core library is included in both.

*Best practice recommendation:* Build the app components without routing first, then add routing once the navigation structure is clear, so that you’re not locked into a routing configuration at the outset which might not match your application’s final structure.
To read more about the concept of dynamic routing, with plenty of code examples to follow along with, refer to the [React Router documentation](https://reacttraining.com/react-router/web/guides/philosophy).

## State Management

State in React is the lifeblood of the component. State determines how, and with what data, a component will be rendered on the page. State gives components reactivity and dynamic rendering abilities.

### Managing State within React
<commit_msg>Updated Pure Component docs and added ReactJSorg links<commit_after>The purpose of this document is to help guide you through working with a potential project using the JavaScript library, [React](https://reactjs.org/). Outside of The official React documentation, you should find here personalized recommendations for using the library based on the types of projects we typically  see at 10up. We have broken these recommendations out into common elements we tend to interact with often in client work. If something you’re looking for isn’t represented you can either submit a pull request to this repository or refer to the [official React documentation](https://reactjs.org/).

## Figuring Out If React Is Right For Your Project

Using the right tool for the job is critical in navigating a successful project. Will React always be the answer? Of course not. But there are some instances where you may want to use this library over something like (for example) a collection of plugins, custom JavaScript, or another framework.

When deciding whether React is the right tool for your project, it might help to ask the following questions:

* Will this project involve building a user interface that requires statefulness? In other words, will your user interface need to...react...in real time to user actions or changeable data coming from an API?
* Does your project need enough reusable components to make it worth using React? React is a fairly heavy library compared with the similar Vue.
* Will your project need to render large amounts of data in real time while remaining performant for the browser?
* Are you building a native mobile app for iOS and/or Android? The React team also maintains React Native, a subset of React which makes it possible to write applications in JavaScript using React components that compile to native Swift and Java.

React is easily integrated into specific parts of the front-end or admin of an existing site, but it can also be used to render entire sites, effectively replacing traditional WordPress templates—although doing so requires a lot more planning and scaffolding of features (such as routing) that would normally be handled by the CMS out of the box.

## Implementing React on a Project

There are a number of ways to get up and running with React in a project. The deciding factor is based on the context of your project and how you plan to implement React. The following subsections will outline instructions that are specific to installing React on a per project basis:

### Script Element

Including React via a script element in your HTML is a pretty quick and standard way of including the library. To do this you can either [download the library directly](https://react-cn.github.io/react/downloads.html), use the [CDN](https://reactjs.org/docs/cdn-links.html), or install through [NPM](https://www.npmjs.com/package/react) and direct-link into your `node_modules` directory.

Something to note about this method is that React and ReactDOM are both required. There is also no inherent support for ES6 or JSX without Webpack or Babel in this context. You would need to separately configure a transpiler or write in Vanilla JavaScript.

### Including with NPM

If you already have a Node / NPM / Yarn project that you wish to include React as a dependency of, then you can use the installation instructions found on the [Official React Documentation](https://reactjs.org/docs/add-react-to-an-existing-app.html). Include React and ReactDOM in your package file just like you would any other dependency. Also be sure your transpiler is working to correctly process the ES6 and JSX from React into something the browser can understand.

### Installation with a CLI

[The React CLI](https://reactjs.org/blog/2016/07/22/create-apps-with-no-configuration.html) (create-react-app) provides us a quick way to setup and scaffold a React project. It makes use of the modern frontend workflows and out of the box, React CLI provides hot reloading, minification, asset management, module bundling, linting and a development server to test your application under realistic circumstances. It works with zero configuration from your part as everything is already set up.

Using the CLI tool is ideal if you are creating a full React App with an API backend.

## Components
When building out components, it's beneficial to understand how to construct them in the most appropriate way possible. Certain "types" of components can be written differently which can have big performance benefits on larger scale applications.

### Class Components
Class Components are written in the ES6 Class syntax. When building a component using a [JS Class](https://reactjs.org/docs/react-api.html#reactcomponent), you are generally inferring that the component either manages it's own `state` or it's `state` is managed by a state management library like Redux. LifeCycle methods are only available in class components. 

Class components are also capabale of handling `props`. Use these components when you need to build "intelligent" React components that are aware of their own `state` as well as the `state` of their children. Examples would include: Accordions, Dropdowns, Modals or Responsive Navigation.

### Stateless Functions
A Stateless function can take the form of a [plain function](https://reactjs.org/docs/components-and-props.html#function-and-class-components) in JavaScript, or a fat arrow function stored in a variable. The biggest difference between a Class Component and a Stateless Function is that Stateless Functions are not aware of `state`. `state` can not be passed to them from a parent (unless it's through `props`) thus the component cannot update `state`. Stateless Function's can handle props as a destructured object as a parameter. 

If your component is not required to update `state` or the `state` of child components use a Stateless Function. They have a low re-render cost and provide for cleaner code. Examples would include: Grids, Sections, Dividers, Icons, Scaffolding.

### PureComponents
PureComponents allow for greater performance benefits with in the React Lifecycle. When using a [Pure Component](https://reactjs.org/docs/react-api.html#reactpurecomponent), the logic of the `shouldComponentUpdate` lifecycle method is altered to perform a shallow comparison of what changed in `props` and `state` since the last render, update the values that did change and unmount.

Considering PureComponents perform shallow comparisons of previous `state` and new `state`, a component should become "pure" when theres no need to re-render the entire component everytime data changes. Examples would include: TodoLists, Star Ratings, Event Calendars, Forms, Comments


## Routing

In most cases, you will only need routing if your React application needs to navigate between multiple layout components, render different data based on the current app location, and provide browser history. Make sure your app needs routing functionality before you consider adding a routing library.

The most popular routing library for React is [React Router](https://github.com/ReactTraining/react-router). React Router provides a core library plus APIs for both DOM (web) and React Native (native iOS and Android) platforms. To use the library, install the package for one or the other API according to your application’s platform needs—the core library is included in both.

*Best practice recommendation:* Build the app components without routing first, then add routing once the navigation structure is clear, so that you’re not locked into a routing configuration at the outset which might not match your application’s final structure.
To read more about the concept of dynamic routing, with plenty of code examples to follow along with, refer to the [React Router documentation](https://reacttraining.com/react-router/web/guides/philosophy).

## State Management

State in React is the lifeblood of the component. State determines how, and with what data, a component will be rendered on the page. State gives components reactivity and dynamic rendering abilities.

### Managing State within React

{'fraction_non_alphanumeric': 0.044460865816860644, 'fraction_numerical': 0.001601083810579469, 'mean_word_length': 4.79172610556348, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 21, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '488239', 'n_tokens_mistral': 3680, 'n_tokens_neox': 3546, 'n_words': 2401}