ReactAF does for React what Babel does for JavaScript
Let’s say for a moment that you are a component developer and you maintain, or are writing an OSS React package. As you don’t control the application itself, a best practice if for you to specify react as a peerDependency in your package.json, something file like this.
"peerDependencies": {"react": ">=15.0.0"}
What this specifies is that your package relies on react versions 15.0.0 and above, but you expect that the dependency be provided for you (meaning the application must include react in its list of dependencies). Using peerDependencies prevents the unnecessary bloat and confusion of shipping React within your library build.
But think about this for a second—
Your component has no idea what version of React that the consuming application has specified and that your code will be running against. All you can do, from a package perspective, is give a range of acceptable versions. Your code must be able to handle whatever version of React that it is given.
So… If your package wishes to use a React feature that was introduced in React 16.2.0, for example, you’re out of luck if the application is using React 15.4.0.
For instance, what if you wanted to use the new context API introduced in React 16.3.0? Sorry (well, only if you wanted to force your users to use 16.3.0). What about the new static getDerivedStateFromProps? Same thing.
As a developer, this presents a bit of a quandary. Either you fill your code with all kinds of feature detection or you code to the lowest common denominator.
Wouldn’t it be nice if you could rely on newer React features being there, no matter what version of React is running?
Babel does this with the JavaScript Network language. When you transpile with Babel, you can code as though the browser supports ES2018 (for example), even though your code may be running on IE10, which was released in 2012.
This is what ReactAF does.
How does it work?
ReactAF does for React what Babel does for JavaScript. It allows you to code using React features that aren’t available in older versions of React.
But how does it work? ReactAF imports React internally. If the version of React already has the features that it emulates, the “real” React is returned. If not, it polyfills the missing features and exposes a monkey patched version of React.
How does it work? It’s like magic.
API
ReactAF provides/emulates the following React APIs on lower version of React.
static getDerivedStateFromProps
This is a static method on class components that was introduced in React 16.3.0-alpha. It is intended to replace the lifecycle event componentWillReceiveProps, which will be deprecated in v17.0.
If you are running v16.3.0 or greater, you will be using the native implementation. Otherwise, this method is polyfilled.
More about getDerivedStateFromProps in this article by Bartosz Szczeciński.
React.Fragment
Fragment is a new component that is exposed on the React object in v16.2.0 and greater. It is intended as a way to return multiple elements from render without the need for a wrapping dummy div element.
More information on Fragments can be found on the official React blog.
React.createContext
createContext is the new context API that has so many people excited. It too was released in React 16.3.0-alpha.
You can read more about the new Context API in this article by Kent C. Dodds.
And more…
Actually, no… that’s all.
But as React releases new features, ReactAF will be updated to support them via a polyfill, where possible (PRs welcome 😉). This way you can always code using the latest React APIs in your package, no matter the version that the consuming app is using.
Changing your code
And here’s the best thing of all. To start using ReactAF, all you need to do is add 3 little characters: -af.
Instead of this.
import React from 'react';
You would do this.
import React from 'react**-af**';
Where do you get it?
ReactAF is available on npm (of course). You can see the source code and/or contribute on GitHub. I’d love your help making ReactAF even better!
And if you’re feeling generous, a ⭐️ would be appreciated. 🙏
donavon/react-af_react-af - Allows you to code using certain React.next features today! Perfect for component library maintainers._github.com
Conclusion
While ReactAF may not be for everyone, it can really benefit OSS package developers, giving them the freedom to code using modern React APIs. I’d say that make this package React As F&#%!
And please… Forgive any informercial-esque qualities of this post. ¯\_(ツ)_/¯
I also write for the American Express Engineering Blog. Check out my other works and the works of my talented co-workers at AmericanExpress.io. You can also follow me on Twitter.