If you want tocontribute to React we hope that this guide will help you feel more comfortable making changes.

We don’t necessarily recommend any of these conventions in React apps. Many of them exist for historical reasons and might change with time.

Top-Level Folders

After cloning theReact repository, you will see a few top-level folders in it:

• packages contains metadata (such aspackage.json) and the source code (src subdirectory) for all packages in the React repository.If your change is related to the code, thesrc subdirectory of each package is where you’ll spend most of your time.
• fixtures contains a few small React test applications for contributors.
• build is the build output of React. It is not in the repository but it will appear in your React clone after youbuild it for the first time.

The documentation is hostedin a separate repository from React.

There are a few other top-level folders but they are mostly used for the tooling and you likely won’t ever encounter them when contributing.

Colocated Tests

We don’t have a top-level directory for unit tests. Instead, we put them into a directory called__tests__ relative to the files that they test.

For example, a test forsetInnerHTML.js is located in__tests__/setInnerHTML-test.js right next to it.

Warnings and Invariants

The React codebase usesconsole.error to display warnings:

if(__DEV__){  console.error('Something is wrong.');}

Warnings are only enabled in development. In production, they are completely stripped out. If you need to forbid some code path from executing, useinvariant module instead:

var invariant=require('invariant');invariant(2+2===4,'You shall not pass!');

The invariant is thrown when theinvariant condition isfalse.

“Invariant” is just a way of saying “this condition always holds true”. You can think about it as making an assertion.

It is important to keep development and production behavior similar, soinvariant throws both in development and in production. The error messages are automatically replaced with error codes in production to avoid negatively affecting the byte size.

Development and Production

You can use__DEV__ pseudo-global variable in the codebase to guard development-only blocks of code.

It is inlined during the compile step, and turns intoprocess.env.NODE_ENV !== 'production' checks in the CommonJS builds.

For standalone builds, it becomestrue in the unminified build, and gets completely stripped out with theif blocks it guards in the minified build.

if(__DEV__){// This code will only run in development.}

Flow

We recently started introducingFlow checks to the codebase. Files marked with the@flow annotation in the license header comment are being typechecked.

We accept pull requestsadding Flow annotations to existing code. Flow annotations look like this:

ReactRef.detachRefs=function(instance: ReactInstance,element: ReactElement| string| number|null|false,):void{// ...}

When possible, new code should use Flow annotations.You can runyarn flow locally to check your code with Flow.

Multiple Packages

React is amonorepo. Its repository contains multiple separate packages so that their changes can be coordinated together, and issues live in one place.

React Core

The “core” of React includes all thetop-levelReact APIs, for example:

• React.createElement()
• React.Component
• React.Children

React core only includes the APIs necessary to define components. It does not include thereconciliation algorithm or any platform-specific code. It is used both by React DOM and React Native components.

The code for React core is located inpackages/react in the source tree. It is available on npm as thereact package. The corresponding standalone browser build is calledreact.js, and it exports a global calledReact.

Renderers

React was originally created for the DOM but it was later adapted to also support native platforms withReact Native. This introduced the concept of “renderers” to React internals.

Renderers manage how a React tree turns into the underlying platform calls.

Renderers are also located inpackages/:

• React DOM Renderer renders React components to the DOM. It implementstop-levelReactDOM APIs and is available asreact-dom npm package. It can also be used as standalone browser bundle calledreact-dom.js that exports aReactDOM global.
• React Native Renderer renders React components to native views. It is used internally by React Native.
• React Test Renderer renders React components to JSON trees. It is used by theSnapshot Testing feature ofJest and is available asreact-test-renderer npm package.

The only other officially supported renderer isreact-art. It used to be in a separateGitHub repository but we moved it into the main source tree for now.

Note:

Technically thereact-native-renderer is a very thin layer that teaches React to interact with React Native implementation. The real platform-specific code managing the native views lives in theReact Native repository together with its components.

Reconcilers

Even vastly different renderers like React DOM and React Native need to share a lot of logic. In particular, thereconciliation algorithm should be as similar as possible so that declarative rendering, custom components, state, lifecycle methods, and refs work consistently across platforms.

To solve this, different renderers share some code between them. We call this part of React a “reconciler”. When an update such assetState() is scheduled, the reconciler callsrender() on components in the tree and mounts, updates, or unmounts them.

Reconcilers are not packaged separately because they currently have no public API. Instead, they are exclusively used by renderers such as React DOM and React Native.

Stack Reconciler

The “stack” reconciler is the implementation powering React 15 and earlier. We have since stopped using it, but it is documented in detail in thenext section.

Fiber Reconciler

The “fiber” reconciler is a new effort aiming to resolve the problems inherent in the stack reconciler and fix a few long-standing issues. It has been the default reconciler since React 16.

Its main goals are:

• Ability to split interruptible work in chunks.
• Ability to prioritize, rebase and reuse work in progress.
• Ability to yield back and forth between parents and children to support layout in React.
• Ability to return multiple elements fromrender().
• Better support for error boundaries.

You can read more about React Fiber Architecturehere andhere. While it has shipped with React 16, the async features are not enabled by default yet.

Its source code is located inpackages/react-reconciler.

Event System

React implements a layer over native events to smooth out cross-browser differences. Its source code is located inpackages/react-dom/src/events.

What Next?

Read thenext section to learn about the pre-React 16 implementation of reconciler in more detail. We haven’t documented the internals of the new reconciler yet.