babel-plugin-react-transform weekly downloads statistics

## This Project Is Deprecated

React Hot Loader 3 is on the horizon, and you can try it today (boilerplate branch, upgrade example). It fixes some long-standing issues with both React Hot Loader and React Transform, and is intended as a replacement for both. The docs are not there yet, but they will be added before the final release. For now, this commit is a good reference.

babel-plugin-react-transform

:rocket: Now with Babel 6 support (thank you @thejameskyle!)

This plugin wraps React components with arbitrary transforms. In other words, it allows you to instrument React components in any way—limited only by your imagination.

🚧🚧🚧🚧🚧

This is highly experimental tech. If you’re enthusiastic about hot reloading, by all means, give it a try, but don’t bet your project on it. Either of the technologies it relies upon may change drastically or get deprecated any day. You’ve been warned 😉 .

This technology exists to prototype next-generation React developer experience. Please don’t use it blindly if you don’t know the underlying technologies well. Otherwise you are likely to get disillusioned with JavaScript tooling.

No effort went into making this user-friendly yet. The goal is to eventually kill this technology in favor of less hacky technologies baked into React. These projects are not long term.

Table of Contents

• Ecosystem • Demo Project • Installation • Writing Transforms

Ecosystem

For a reference implementation, see react-transform-boilerplate. For a starter kit to help write your own transforms, see react-transform-noop.

Transforms

• react-transform-hmr - enables hot reloading using HMR API • react-transform-catch-errors - catches errors inside render() • react-transform-debug-inspector - renders an inline prop inspector • react-transform-render-visualizer - highlight components when updated • react-transform-style - support style and className styling for all components • react-transform-log-render - log component renders with passed props and state • react-transform-count-renders - counts how many times your components render

Feeling inspired? Learn how to write transforms and send a PR!

Demo Project

Check out react-transform-boilerplate for a demo showing a combination of transforms.

Installation

This plugin is designed to be used with the Babel 6 ecosystem. These instructions assume you have a working project set up. If you do not have Babel set up in your project, learn how to integrate it with your toolkit before installing this plugin.

Using NPM

Install plugin and save in devDependencies:

Install some transforms:

Configuration

Add react-transform to the list of plugins in your babel configuration (usually .babelrc):

As you can see, each transform, apart from the transform field where you write it name, also has imports and locals fields. You should consult the docs of each individual transform to learn which imports and locals it might need, and how it uses them. You probably already guessed that this is just a way to inject local variables (like module) or dependencies (like react) into the transforms that need them.

Note that when using React.createClass() and allowing babel to extract the displayName property you must ensure that babel-plugin-react-display-name is included before react-transform. See this github issue for more details.

You may optionally specify an array of strings called factoryMethods if you want the plugin to look for components created with a factory method other than React.createClass. Note that you don’t have to do anything special to look for ES6 components—factoryMethods is only relevant if you use factory methods akin to React.createClass.

Writing Transforms

It’s not hard to write a custom transform! First, make sure you call your NPM package react-transform-* so we have uniform naming across the transforms. The only thing you should export from your transform module is a function.

This function should *return another function*:

As you can see, you’ll receive ReactClass as a parameter. It’s up to you to do something with it: monkeypatch its methods, create another component with the same prototype and a few different methods, wrap it into a higher-order component, etc. Be creative!

Oh, how do I get displayName? Actually, we give your transformation function a single argument called options. Yes, options:

It contains some useful data. For example, your options could look like this:

Of course, you might not want to use *all* options, but isn’t it nice to know that you have access to them in the top scope—which means before the component definitions actually run? (Hint: a hot reloading plugin might use this to decide whether a module is worthy of reloading, even if it contains an error and no React components have yet been wrapped because of it.)

So, to retrieve the displayName (or isInFunction, when available), use the options parameter *and* the second uniqueId parameter given to the inner function after ReactClass:

This is it!

Sure, it’s a slightly contrived example, as you can grab ReactClass.displayName just fine, but it illustrates a point: you have information about all of the components inside a file before that file executes, which is *very* handy for some transformations.

Here is the complete code for this example transformation function:

Now go ahead and write your own! Don’t forget to tag it with react-transform keyword on npm.

Patrons

The work on React Transform, React Hot Loader, Redux, and related projects was funded by the community. Meet some of the outstanding companies that made it possible:

• Webflow • Ximedes

See the full list of React Transform patrons.

License

MIT

Description from the npm listing.