• This repository has been archived on 16/Dec/2021
  • Stars
    star
    949
  • Rank 48,145 (Top 1.0 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created almost 9 years ago
  • Updated almost 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

ATTENTION: The React compatibility layer for Preact has moved to the main preact repo.

ATTENTION: preact-compat has moved to the main repo.

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.

NPM travis-ci CDNJS

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

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

It provides the same exports as react and react-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 uses preact-compat to work with an existing React library unmodified, achieving more than 95% reduction in size:

preact-compat-example


Why?

... or really, "why preact"?

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 accept named generic methods (not just React DI), as suggested by Eric Elliot. However, since the React community has already authored so many modules in a more explicitly coupled manner, it's worth having a simple short-term solution for those who would like to liberate themselves from library lock-in.


Installation

You need to install preact-compat first through npm:

npm i --save preact-compat

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

npm i --save preact

Usage with Webpack

Using preact-compat with Webpack is easy.

All you have to do is add an alias for react and react-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'
        }
    }
    // ...
}

Usage with Browserify

Using preact-compat with Browserify is as simple as installing and configuring aliasify.

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

... then in your package.json, configure aliasify to alias react and react-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'
  }
});

Usage with Babel

Using preact-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 for react and react-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"
    ]
    // ...
}

Usage with Brunch

Using preact-compat with Brunch requires no extra plugins.

In your brunch-config.js you can export an npm object to configure aliases:

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

Once Aliased

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

import React, { Component } from 'react';
import { render } from 'react-dom';

class Foo extends Component {
    propTypes = {
        a: React.PropTypes.string.isRequired
    };
    render() {
        let { a, b, children } = this.props;
        return <div {...{a,b}}>{ children }</div>;
    }
}

render((
    <Foo a="a">test</Foo>
), document.body);

Use Without Webpack/Browserify

preact-compat and its single dependency prop-types are both published as UMD modules as of preact-compat version 0.6. This means you can use them via a <script> tag without issue:

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

You can see the above in action with this JSFiddle Example.


PropTypes

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 global process.env.NODE_ENV='production'. PropType errors should work the same as in React - the prop-types module used here is published by the React team to replace PropTypes in React.

PropType validation example output

License

MIT

More Repositories

1

preact

⚛️ Fast 3kB React alternative with the same modern API. Components & Virtual DOM.
JavaScript
36,650
star
2

wmr

👩‍🚀 The tiny all-in-one development tool for modern web apps.
JavaScript
4,928
star
3

preact-cli

😺 Your next Preact PWA starts in 30 seconds.
JavaScript
4,685
star
4

signals

Manage state with style in every framework
TypeScript
2,105
star
5

preact-router

🌎 URL router for Preact.
JavaScript
972
star
6

awesome-preact

A curated list of amazingly awesome things regarding Preact ecosystem 🌟
885
star
7

preact-render-to-string

📄 Universal rendering for Preact: render JSX and Preact components to HTML.
JavaScript
574
star
8

compressed-size-action

GitHub Action that adds compressed size changes to your PRs.
JavaScript
541
star
9

next-plugin-preact

Next.js plugin for preact X
JavaScript
391
star
10

preact-www

📖 Preact documentation website.
JavaScript
358
star
11

preact-custom-element

Wrap your component up as a custom element
JavaScript
356
star
12

prefresh

Hot Module Reloading for Preact
JavaScript
351
star
13

preact-devtools

Browser extension for inspection Preact applications
TypeScript
295
star
14

preset-vite

Preset for using Preact with the vite bundler
TypeScript
256
star
15

eslint-config-preact

Unopinionated baseline ESLint config for Preact and Preact CLI codebases.
JavaScript
85
star
16

enzyme-adapter-preact-pure

Preact adapter for the Enzyme UI testing library
TypeScript
67
star
17

preact-iso

Isomorphic utilities for Preact
JavaScript
55
star
18

preact-ssr-prepass

Drop-in replacement for react-ssr-prepass
JavaScript
47
star
19

create-preact

Create a Vite-powered Preact app in seconds
JavaScript
35
star
20

preact-integrations

A collection of sample apps demonstrating Preact's compatibility with various 3rd party libraries
JavaScript
35
star
21

rfcs

RFCs for changes and ideas in relation to Preact
30
star
22

babel-plugin-transform-replace-expressions

A Babel plugin for replacing expressions with other expressions
JavaScript
23
star
23

jest-preset-preact

Jest preset for testing Preact apps
JavaScript
19
star
24

babel-plugin-transform-rename-properties

A Babel plugin for renaming JavaScript properties
JavaScript
19
star
25

legacy-compat

React 15 compatibility layer for Preact
JavaScript
16
star
26

preact-netlify

Preact's netlify CMS template
JavaScript
15
star
27

playwright-ct

Preact adapter for Playwright Component testing
TypeScript
15
star
28

compat-alias-package

JavaScript
10
star
29

babel-plugin-transform-hook-names

Add custom hook names for devtools
TypeScript
7
star
30

migrate-preact-x

JavaScript
6
star
31

preact-cli-experiment

TypeScript
4
star
32

codesandbox-template

JavaScript
4
star
33

.github

Default community files for the PreactJS organization
3
star