react-reconciler

What is react-reconciler?

The react-reconciler package is a framework for building custom React renderers. It provides the core algorithms that React uses for reconciliation, allowing developers to create their own renderers for different target environments beyond what React supports out of the box (e.g., the web or native mobile). This package is an under-the-hood tool primarily intended for advanced use cases where you need to create a custom rendering environment.

What are react-reconciler's main functionalities?

Creating a Custom Renderer

This code sample demonstrates how to start creating a custom renderer using react-reconciler. You define methods like `createInstance` for creating instances of components and `createTextInstance` for handling text. The host config object passed to `ReactReconciler` includes a variety of methods for managing instances, updates, and more.

const MyRenderer = ReactReconciler({
  now: Date.now,
  createInstance: (type, props) => {
    // Create instance of a component
  },
  createTextInstance: (text) => {
    // Create text instance
  },
  // Other host config methods...
});

Scheduling Updates

This example shows how to schedule updates to the container using your custom renderer. The `updateContainer` method is used to apply updates to the container, which in this case is a custom object you manage. This method is part of what allows React's declarative API to work with your custom rendering logic.

const container = {}; // Your container object
MyRenderer.updateContainer(<App />, container, null, () => {
  console.log('Rendered with MyRenderer');
});

Other packages similar to react-reconciler

preact

Preact is a fast 3kB alternative to React with the same modern API. While not a direct alternative to react-reconciler, it offers a different approach to building user interfaces with a smaller footprint. Preact can be used to build custom renderers, but its primary use case is as a React alternative for building web applications.

inferno

Inferno is another high-performance alternative to React that focuses on speed and performance. Similar to Preact, Inferno is not a direct alternative to react-reconciler but offers a different approach to building UIs with an emphasis on performance. Inferno includes its own mechanisms for creating custom renderers, making it a potential alternative for performance-critical applications.

README

react-reconciler

This is an experimental package for creating custom React renderers.

Its API is not as stable as that of React, React Native, or React DOM, and does not follow the common versioning scheme.

Use it at your own risk.

API

var Reconciler = require('react-reconciler');

var HostConfig = {
  // You'll need to implement some methods here.
  // See below for more information and examples.
};

var MyRenderer = Reconciler(HostConfig);

var RendererPublicAPI = {
  render(element, container, callback) {
    // Call MyRenderer.updateContainer() to schedule changes on the roots.
    // See ReactDOM, React Native, or React ART for practical examples.
  }
};

module.exports = RendererPublicAPI;

Practical Examples

A "host config" is an object that you need to provide, and that describes how to make something happen in the "host" environment (e.g. DOM, canvas, console, or whatever your rendering target is). It looks like this:

var HostConfig = {
  createInstance(type, props) {
    // e.g. DOM renderer returns a DOM node
  },
  // ...
  supportsMutation: true, // it works by mutating nodes
  appendChild(parent, child) {
    // e.g. DOM renderer would call .appendChild() here
  },
  // ...
};

The full list of supported methods can be found here. For their signatures, we recommend looking at specific examples below.

The React repository includes several renderers. Each of them has its own host config.

The examples in the React repository are declared a bit differently than a third-party renderer would be. In particular, the HostConfig object mentioned above is never explicitly declared, and instead is a module in our code. However, its exports correspond directly to properties on a HostConfig object you'd need to declare in your code:

• React ART and its host config
• React DOM and its host config
• React Native and its host config

If these links break please file an issue and we’ll fix them. They intentionally link to the latest versions since the API is still evolving. If you have more questions please file an issue and we’ll try to help!

Changelog

0.12.0 (October 28, 2014)

React Core

Breaking Changes

• key and ref moved off props object, now accessible on the element directly
• React is now BSD licensed with accompanying Patents grant
• Default prop resolution has moved to Element creation time instead of mount time, making them effectively static
• React.__internals is removed - it was exposed for DevTools which no longer needs access
• Composite Component functions can no longer be called directly - they must be wrapped with React.createFactory first. This is handled for you when using JSX.

New Features

• Spread operator ({...}) introduced to deprecate this.transferPropsTo
• Added support for more HTML attributes: acceptCharset, classID, manifest

Deprecations

• React.renderComponent --> React.render
• React.renderComponentToString --> React.renderToString
• React.renderComponentToStaticMarkup --> React.renderToStaticMarkup
• React.isValidComponent --> React.isValidElement
• React.PropTypes.component --> React.PropTypes.element
• React.PropTypes.renderable --> React.PropTypes.node
• DEPRECATED React.isValidClass
• DEPRECATED instance.transferPropsTo
• DEPRECATED Returning false from event handlers to preventDefault
• DEPRECATED Convenience Constructor usage as function, instead wrap with React.createFactory
• DEPRECATED use of key={null} to assign implicit keys

Bug Fixes

• Better handling of events and updates in nested results, fixing value restoration in "layered" controlled components
• Correctly treat event.getModifierState as case sensitive
• Improved normalization of event.charCode
• Better error stacks when involving autobound methods
• Removed DevTools message when the DevTools are installed
• Correctly detect required language features across browsers
• Fixed support for some HTML attributes:
  • list updates correctly now
  • scrollLeft, scrollTop removed, these should not be specified as props
• Improved error messages

React With Addons

New Features

• React.addons.batchedUpdates added to API for hooking into update cycle

Breaking Changes

• React.addons.update uses assign instead of copyProperties which does hasOwnProperty checks. Properties on prototypes will no longer be updated correctly.

Bug Fixes

• Fixed some issues with CSS Transitions

JSX

Breaking Changes

• Enforced convention: lower case tag names are always treated as HTML tags, upper case tag names are always treated as composite components
• JSX no longer transforms to simple function calls

New Features

• @jsx React.DOM no longer required
• spread ({...}) operator introduced to allow easier use of props

Bug Fixes

• JSXTransformer: Make sourcemaps an option when using APIs directly (eg, for react-rails)