├── .babelrc
├── .gitignore
├── .jshintrc
├── LICENSE
├── README.md
├── package-lock.json
├── package.json
├── rollup.config.js
├── scripts
└── build.js
├── src
└── index.js
├── test
├── index.spec.js
└── mocha.opts
└── yarn.lock
/.babelrc:
--------------------------------------------------------------------------------
1 | {
2 | "presets": [
3 | "@babel/preset-react",
4 | [
5 | "@babel/preset-env",
6 | {
7 | "targets": {
8 | "node": "current"
9 | },
10 | "loose": true
11 | }
12 | ]
13 | ],
14 | "plugins": [
15 | "@babel/plugin-proposal-class-properties",
16 | "add-module-exports"
17 | ]
18 | }
19 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | coverage
3 | lib
4 |
5 |
--------------------------------------------------------------------------------
/.jshintrc:
--------------------------------------------------------------------------------
1 | {
2 | "node": true,
3 | "browser": true,
4 | "esnext": true,
5 | "newcap": false
6 | }
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | The MIT License (MIT)
2 |
3 | Copyright (c) 2015 Dan Abramov
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
23 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # React Side Effect [](https://npmjs.com/react-side-effect) [](https://www.npmjs.com/package/react-side-effect)
2 |
3 | Create components whose prop changes map to a global side effect.
4 |
5 | ## Installation
6 |
7 | ```
8 | npm install --save react-side-effect
9 | ```
10 |
11 | ### As a script tag
12 |
13 | #### Development
14 |
15 | ```html
16 |
17 |
18 | ```
19 |
20 | #### Production
21 |
22 | ```html
23 |
24 |
25 | ```
26 |
27 | ## Use Cases
28 |
29 | * Setting `document.body.style.margin` or background color depending on current screen;
30 | * Firing Flux actions using declarative API depending on current screen;
31 | * Some crazy stuff I haven't thought about.
32 |
33 | ## How's That Different from `componentDidUpdate`?
34 |
35 | It gathers current props across *the whole tree* before passing them to side effect. For example, this allows you to create `` component like this:
36 |
37 | ```jsx
38 | // RootComponent.js
39 | return (
40 |
41 | {this.state.something ?
43 | );
44 |
45 | // SomeComponent.js
46 | return (
47 |
48 | Choose color:
49 |
50 | );
51 | ```
52 |
53 | and let the effect handler merge `style` from different level of nesting with innermost winning:
54 |
55 | ```js
56 | import { Component, Children } from 'react';
57 | import PropTypes from 'prop-types';
58 | import withSideEffect from 'react-side-effect';
59 |
60 | class BodyStyle extends Component {
61 | render() {
62 | return Children.only(this.props.children);
63 | }
64 | }
65 |
66 | BodyStyle.propTypes = {
67 | style: PropTypes.object.isRequired
68 | };
69 |
70 | function reducePropsToState(propsList) {
71 | var style = {};
72 | propsList.forEach(function (props) {
73 | Object.assign(style, props.style);
74 | });
75 | return style;
76 | }
77 |
78 | function handleStateChangeOnClient(style) {
79 | Object.assign(document.body.style, style);
80 | }
81 |
82 | export default withSideEffect(
83 | reducePropsToState,
84 | handleStateChangeOnClient
85 | )(BodyStyle);
86 | ```
87 |
88 | On the server, you’ll be able to call `BodyStyle.peek()` to get the current state, and `BodyStyle.rewind()` to reset for each next request. The `handleStateChangeOnClient` will only be called on the client.
89 |
90 | ## API
91 |
92 | #### `withSideEffect: (reducePropsToState, handleStateChangeOnClient, [mapStateOnServer]) -> ReactComponent -> ReactComponent`
93 |
94 | A [higher-order component](https://medium.com/@dan_abramov/mixins-are-dead-long-live-higher-order-components-94a0d2f9e750) that, when mounting, unmounting or receiving new props, calls `reducePropsToState` with `props` of **each mounted instance**. It is up to you to return some state aggregated from these props.
95 |
96 | On the client, every time the returned component is (un)mounted or its props change, `reducePropsToState` will be called, and the recalculated state will be passed to `handleStateChangeOnClient` where you may use it to trigger a side effect.
97 |
98 | On the server, `handleStateChangeOnClient` will not be called. You will still be able to call the static `rewind()` method on the returned component class to retrieve the current state after a `renderToString()` call. If you forget to call `rewind()` right after `renderToString()`, the internal instance stack will keep growing, resulting in a memory leak and incorrect information. You must call `rewind()` after every `renderToString()` call on the server.
99 |
100 | For testing, you may use a static `peek()` method available on the returned component. It lets you get the current state without resetting the mounted instance stack. Don’t use it for anything other than testing.
101 |
102 | ## Usage
103 |
104 | Here's how to implement [React Document Title](https://github.com/gaearon/react-document-title) (both client and server side) using React Side Effect:
105 |
106 | ```js
107 | import React, { Children, Component } from 'react';
108 | import PropTypes from 'prop-types';
109 | import withSideEffect from 'react-side-effect';
110 |
111 | class DocumentTitle extends Component {
112 | render() {
113 | if (this.props.children) {
114 | return Children.only(this.props.children);
115 | } else {
116 | return null;
117 | }
118 | }
119 | }
120 |
121 | DocumentTitle.propTypes = {
122 | title: PropTypes.string.isRequired
123 | };
124 |
125 | function reducePropsToState(propsList) {
126 | var innermostProps = propsList[propsList.length - 1];
127 | if (innermostProps) {
128 | return innermostProps.title;
129 | }
130 | }
131 |
132 | function handleStateChangeOnClient(title) {
133 | document.title = title || '';
134 | }
135 |
136 | export default withSideEffect(
137 | reducePropsToState,
138 | handleStateChangeOnClient
139 | )(DocumentTitle);
140 | ```
141 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "react-side-effect",
3 | "version": "2.1.2",
4 | "description": "Create components whose prop changes map to a global side effect",
5 | "main": "lib/index.js",
6 | "scripts": {
7 | "build": "node scripts/build.js",
8 | "clean": "rimraf lib",
9 | "prepare": "npm test && npm run clean && npm run build",
10 | "test": "mocha",
11 | "test:watch": "mocha --watch",
12 | "test:cov": "babel-node ./node_modules/.bin/isparta cover ./node_modules/.bin/_mocha"
13 | },
14 | "repository": {
15 | "type": "git",
16 | "url": "https://github.com/gaearon/react-side-effect.git"
17 | },
18 | "keywords": [
19 | "react",
20 | "component",
21 | "side",
22 | "effect"
23 | ],
24 | "author": "Dan Abramov (http://github.com/gaearon)",
25 | "license": "MIT",
26 | "bugs": {
27 | "url": "https://github.com/gaearon/react-side-effect/issues"
28 | },
29 | "homepage": "https://github.com/gaearon/react-side-effect",
30 | "contributors": [
31 | "Louis DeScioli (https://descioli.design)"
32 | ],
33 | "peerDependencies": {
34 | "react": "^16.3.0 || ^17.0.0 || ^18.0.0"
35 | },
36 | "dependencies": {},
37 | "devDependencies": {
38 | "@babel/cli": "^7.5.5",
39 | "@babel/core": "^7.5.5",
40 | "@babel/node": "^7.5.5",
41 | "@babel/plugin-proposal-class-properties": "^7.5.5",
42 | "@babel/preset-env": "^7.5.5",
43 | "@babel/preset-react": "^7.0.0",
44 | "@babel/register": "^7.5.5",
45 | "babel-plugin-add-module-exports": "^1.0.2",
46 | "chai": "^3.2.0",
47 | "create-react-class": "^15.6.3",
48 | "enzyme": "^3.10.0",
49 | "enzyme-adapter-react-16": "^1.14.0",
50 | "gzip-size": "^4.1.0",
51 | "isparta": "^4.0.0",
52 | "jsdom": "^9.9.1",
53 | "mocha": "^3.2.0",
54 | "pretty-bytes": "^4.0.2",
55 | "react": "^16.9.0",
56 | "react-dom": "^16.9.0",
57 | "rimraf": "^2.4.3",
58 | "rollup": "^1.20.3",
59 | "rollup-plugin-babel": "^4.0.0",
60 | "rollup-plugin-uglify": "^3.0.0"
61 | },
62 | "files": [
63 | "LICENSE",
64 | "README.md",
65 | "lib/"
66 | ]
67 | }
68 |
--------------------------------------------------------------------------------
/rollup.config.js:
--------------------------------------------------------------------------------
1 | import babel from 'rollup-plugin-babel'
2 | import uglify from 'rollup-plugin-uglify'
3 |
4 | const { BUILD_ENV } = process.env
5 |
6 | const config = {
7 | input: 'src/index.js',
8 | output: {
9 | name: 'withSideEffect',
10 | globals: {
11 | react: 'React',
12 | },
13 | },
14 | plugins: [
15 | babel({
16 | babelrc: false,
17 | presets: [
18 | '@babel/preset-react',
19 | ['@babel/preset-env', { loose: true, modules: false }],
20 | ],
21 | plugins: [
22 | '@babel/plugin-proposal-class-properties',
23 | ],
24 | exclude: 'node_modules/**',
25 | }),
26 | ],
27 | external: ['react'],
28 | }
29 |
30 | if (BUILD_ENV === 'production') {
31 | config.plugins.push(uglify())
32 | }
33 |
34 | export default config
35 |
--------------------------------------------------------------------------------
/scripts/build.js:
--------------------------------------------------------------------------------
1 | const fs = require('fs')
2 | const path = require('path')
3 | const { execSync } = require('child_process')
4 | const pkg = require('../package.json')
5 | const prettyBytes = require('pretty-bytes')
6 | const gzipSize = require('gzip-size')
7 |
8 | const { name, dir } = path.parse(pkg.main)
9 |
10 | const filebase = `${dir}/${name}`
11 |
12 | process.chdir(path.resolve(__dirname, '..'))
13 |
14 | const exec = (command, extraEnv) =>
15 | execSync(command, {
16 | stdio: 'inherit',
17 | env: Object.assign({}, process.env, extraEnv),
18 | })
19 |
20 | const formats = [
21 | { format: 'cjs', file: `${filebase}.js`, description: 'CJS module' },
22 | { format: 'es', file: `${filebase}.es.js`, description: 'ES module' },
23 | { format: 'umd', file: `${filebase}.umd.js`, description: 'UMD module' },
24 | {
25 | format: 'umd',
26 | file: `${filebase}.umd.min.js`,
27 | description: 'minified UMD module',
28 | env: {
29 | BUILD_ENV: 'production',
30 | },
31 | },
32 | ]
33 |
34 | for (const { format, file, description, env } of formats) {
35 | console.log(`Building ${description}...`)
36 | exec(`rollup -c -f ${format} -o ${file}`, env)
37 | }
38 |
39 | for (const { file, description } of formats) {
40 | const minifiedFile = fs.readFileSync(file)
41 | const minifiedSize = prettyBytes(minifiedFile.byteLength)
42 | const gzippedSize = prettyBytes(gzipSize.sync(minifiedFile))
43 | console.log(`The ${description} is ${minifiedSize}, (${gzippedSize} gzipped)`)
44 | }
45 |
--------------------------------------------------------------------------------
/src/index.js:
--------------------------------------------------------------------------------
1 | import React, { PureComponent } from 'react';
2 |
3 | const canUseDOM = !!(
4 | typeof window !== 'undefined' &&
5 | window.document &&
6 | window.document.createElement
7 | );
8 |
9 | export default function withSideEffect(
10 | reducePropsToState,
11 | handleStateChangeOnClient,
12 | mapStateOnServer
13 | ) {
14 | if (typeof reducePropsToState !== 'function') {
15 | throw new Error('Expected reducePropsToState to be a function.');
16 | }
17 | if (typeof handleStateChangeOnClient !== 'function') {
18 | throw new Error('Expected handleStateChangeOnClient to be a function.');
19 | }
20 | if (typeof mapStateOnServer !== 'undefined' && typeof mapStateOnServer !== 'function') {
21 | throw new Error('Expected mapStateOnServer to either be undefined or a function.');
22 | }
23 |
24 | function getDisplayName(WrappedComponent) {
25 | return WrappedComponent.displayName || WrappedComponent.name || 'Component';
26 | }
27 |
28 | return function wrap(WrappedComponent) {
29 | if (typeof WrappedComponent !== 'function') {
30 | throw new Error('Expected WrappedComponent to be a React component.');
31 | }
32 |
33 | let mountedInstances = [];
34 | let state;
35 |
36 | function emitChange() {
37 | state = reducePropsToState(mountedInstances.map(function (instance) {
38 | return instance.props;
39 | }));
40 |
41 | if (SideEffect.canUseDOM) {
42 | handleStateChangeOnClient(state);
43 | } else if (mapStateOnServer) {
44 | state = mapStateOnServer(state);
45 | }
46 | }
47 |
48 | class SideEffect extends PureComponent {
49 | // Try to use displayName of wrapped component
50 | static displayName = `SideEffect(${getDisplayName(WrappedComponent)})`;
51 |
52 | // Expose canUseDOM so tests can monkeypatch it
53 | static canUseDOM = canUseDOM;
54 |
55 | static peek() {
56 | return state;
57 | }
58 |
59 | static rewind() {
60 | if (SideEffect.canUseDOM) {
61 | throw new Error('You may only call rewind() on the server. Call peek() to read the current state.');
62 | }
63 |
64 | let recordedState = state;
65 | state = undefined;
66 | mountedInstances = [];
67 | return recordedState;
68 | }
69 |
70 | UNSAFE_componentWillMount() {
71 | mountedInstances.push(this);
72 | emitChange();
73 | }
74 |
75 | componentDidUpdate() {
76 | emitChange();
77 | }
78 |
79 | componentWillUnmount() {
80 | const index = mountedInstances.indexOf(this);
81 | mountedInstances.splice(index, 1);
82 | emitChange();
83 | }
84 |
85 | render() {
86 | return hello {this.props.foo}
76 | }
77 | };
78 |
79 | const withIdentitySideEffect = withSideEffect(identity, noop);
80 | let SideEffect;
81 |
82 | beforeEach(() => {
83 | SideEffect = withIdentitySideEffect(DummyComponent);
84 | });
85 |
86 | it('should expose the canUseDOM flag', () => {
87 | expect(SideEffect).to.have.property('canUseDOM');
88 | });
89 |
90 | describe('rewind', () => {
91 | it('should throw if used in the browser', () => {
92 | SideEffect.canUseDOM = true;
93 | expect(SideEffect.rewind).to.throw('You may only call rewind() on the server. Call peek() to read the current state.');
94 | });
95 |
96 | it('should return the current state', () => {
97 | enzyme.shallow(hello bar
');
181 | });
182 |
183 | describe('with DOM', () => {
184 | const originalWindow = global.window;
185 | const originalDocument = global.document;
186 |
187 | before(done => {
188 | jsdom.env('', (error, window) => {
189 | if (!error) {
190 | global.window = window;
191 | global.document = window.document;
192 | }
193 |
194 | done(error);
195 | });
196 | });
197 |
198 | after(() => {
199 | global.window = originalWindow;
200 | global.document = originalDocument;
201 | });
202 |
203 | it('should be findable by react TestUtils', () => {
204 | class AnyComponent extends React.Component {
205 | render() {
206 | return