Repository files navigation

The code here is only meant for the older Preact 8.x release line. If you're still on Preact 8.x we highly recommend upgrading to the 10.x release line as it includes significant improvements and a much more stable React compatibility layer.

🚨Note: This module is for Preact 8.x and prior - Preact X includes compat by default.For Preact X, please uninstallpreact-compat and replace your aliases withpreact/compat.

This module is a compatibility layer that makes React-based modules work withPreact, without any code changes.

It provides the same exports asreact andreact-dom, meaning you can use your build tool of choice to drop it in where React is being depended on.

Interested? Here's an example project that usespreact-compat to work with an existing React library unmodified,achieving more than 95% reduction in size:

preact-compat-example

... or really, "whypreact"?

React is a great library and a great concept, and has a large community of module authors creating high-quality components.However, these components are tightly coupled to React through the use of generic package imports(example).

Preact is a tiny(3kb) implementation of the core value of React, and maintains a nearly identical API.With a shim like this in place, it is possible to use other React-like libraries like Preact, without forking modules just to change their imports.

There are better long-term ways to solve the coupling issue, like using factory functions that acceptnamed generic methods(not just React DI),assuggested by Eric Elliot. However, since the React community has already authored so many modules in a more explicitly coupled manner, it's worthhaving a simple short-term solution for those who would like to liberate themselves from library lock-in.

You need to installpreact-compat first through npm:

npm i --save preact-compat

NOTE: You need to havepreact already installed, if you don't, install it like so:

npm i --save preact

Usingpreact-compat with Webpack is easy.

All you have to do is add an alias forreact andreact-dom:

{// ...resolve:{alias:{'react':'preact-compat','react-dom':'preact-compat',// Not necessary unless you consume a module using `createClass`'create-react-class':'preact-compat/lib/create-react-class',// Not necessary unless you consume a module requiring `react-dom-factories`'react-dom-factories':'preact-compat/lib/react-dom-factories'}}// ...}

Usingpreact-compat with Browserify is as simple as installing and configuringaliasify.

First, install it:npm install --save-dev aliasify

... then in yourpackage.json, configure aliasify to aliasreact andreact-dom:

{// ..."aliasify":{"aliases":{"react":"preact-compat","react-dom":"preact-compat",// Not necessary unless you consume a module using `createClass`"create-react-class":"preact-compat/lib/create-react-class",// Not necessary unless you consume a module requiring `react-dom-factories`"react-dom-factories":"preact-compat/lib/react-dom-factories"}}// ...}

If you want to use a package that has a peer dependency of React and want it to point to preact-compat you’ll need to set Aliasify to be a global transform.This is not achievable by editing package.json, you’ll need to use the Browserify api and include the global option there:

b.transform(aliasify, {  global: true,  aliases: {    'react': 'preact-compat',    'react-dom': 'preact-compat'  }});

Usingpreact-compat with Babel is easy.

Install the babel plugin for aliasing:npm install --save-dev babel-plugin-module-resolver

All you have to do is tell babel to process jsx with 'h' and add an alias forreact andreact-dom in your .babelrc:

{// ..."plugins":[["module-resolver",{"root":["."],"alias":{"react":"preact-compat","react-dom":"preact-compat",// Not necessary unless you consume a module using `createClass`"create-react-class":"preact-compat/lib/create-react-class",// Not necessary unless you consume a module requiring `react-dom-factories`"react-dom-factories":"preact-compat/lib/react-dom-factories"}}]],"presets":["react"]// ...}

Usingpreact-compat with Brunch requires no extra plugins.

In yourbrunch-config.js you can export annpm object to configure aliases:

// ...exports.npm={enabled:true,aliases:{'react':'preact-compat','react-dom':'preact-compat'}}// ...

With the above Webpack or Browserify aliases in place, existing React modules should work nicely:

importReact,{Component}from'react';import{render}from'react-dom';classFooextendsComponent{propTypes={a:React.PropTypes.string.isRequired};render(){let{ a, b, children}=this.props;return<div{...{a,b}}>{children}</div>;}}render((<Fooa="a">test</Foo>),document.body);

preact-compat and its single dependencyprop-types are both published as UMD modules as ofpreact-compat version0.6. This means you can use them via a<script> tag without issue:

<scriptsrc="//unpkg.com/preact"></script><scriptsrc="//unpkg.com/prop-types/prop-types.min.js"></script><scriptsrc="//unpkg.com/preact-compat"></script><script>varReact=preactCompat,ReactDOM=preactCompat;ReactDOM.render(<h1>Hello!</h1>,document.body);</script>

You can see the above in action with thisJSFiddle Example.

preact-compat adds support for validating PropTypes out of the box. This can be disabled the same way it is when using React, by defining a globalprocess.env.NODE_ENV='production'. PropType errors should work the same as in React - theprop-types module used here is published by the React team to replace PropTypes in React.

MIT