ember-simple-redux

react-redux-compatible way to use Redux in Ember applications.

Installation

ember install ember-simple-redux

Usage

ember-simple-redux provides a very similar interface with the ones provided by react-redux.

Whatever you have learned for react-redux can be applied here. This is especially useful if you are migrating Ember to React since your connect() codes is now framework-agnostic!

Check the API section!

Basic Usage

import { connect } from 'ember-simple-redux';
import TodoList from 'my-app/components/todo-list';

const mapStateToProps = state => ({
  todos: state.todos,
});

export default connect(mapStateToProps)(TodoList);

Default Props

In React, defining default props is as straightforward as adding defaultProps to the React component. In Ember, default props are defined directly to the components. This remains working after connect().

// React
const SayHi = props => `Hi, ${props.name}!`;

SayHi.defaultProps = {
  name: 'Guest',
};

// Ember
const SayHi = Ember.Component.extend({
  name: 'Guest',
});

However, remember that connect() creates a higher-order component, so this does not apply to the connected component. To supply default props, we support defining defaultProps directly on the connected component.

const mapStateToProps = (state, ownProps) => ({
  name: state.users[ownProps.id].name,
});

const Connected = connect()(SayHi);

Connected.defaultProps = {
  id: 2,
};

export default Connected;

For more info, check out this issue.

API

Since the goal of ember-simple-redux is to provide an interface as close as possible to react-redux, this documentation is heavily inspired by the documentation of react-redux. In fact, most examples are exactly the same (except the import).

provider(store, application)

react-redux: Documentation

Similar to Provider in react-redux, provider() function makes the Redux store available to the connect() calls in Ember application.

Notice that this function starts with lower case because it is not a React component.

The best place to use this function is in an application initializer, which should already be generated by ember-simple-redux.

Arguments

• [store] (Redux Store): The single Redux store in your application
• application: The instantiated Ember application

Examples

// app/initializers/redux.js

import { provider } from 'ember-simple-redux';
import { createStore } from 'redux';

export function initialize(application) {
  const store = createStore(() => {});
  provider(store, application);
}

export default {
  initialize,
};

connect([mapStateToProps], [mapDispatchToProps], [mergeProps], [options])

react-redux: Documentation

This function is almost completely identical with the one provided by react-redux, please check the documentation of react-redux for its usage.

The differences with its react-redux counterpart:

• Default storeKey is changed to simpleReduxStore to avoid possible conflict with Ember-Data Store
• This function returns a "higher-order Ember component"

connectAdvanced(selectorFactory, [connectOptions])

react-redux: Documentation

This is the major difference with react-redux since it interacts with Ember directly. However, its interface still remains as close as possible.

The differences with its react-redux counterpart:

• Default storeKey is changed to simpleReduxStore to avoid possible conflict with Ember-Data Store
• withRef and getWrappedInstance() do not work since they are React-specific
• There is no WrappedComponent static properties
• This function returns a "higher-order Ember component"

createProvider([storeKey])

react-redux: Documentation

This can be used when you are in the inadvisable position of having multiple stores.

It can also be used if the default storeKey conflicts with your existing injection. This is a very rare case since the default storeKey has been changed to simpleReduxStore, instead of store that is commonly used by legacy Ember applications to reference Ember-Data Store.

Arguments

• [storeKey] (String): The key of the component on which to set the store. Default value: 'simpleReduxStore'

Examples

As reminded in react-redux, before creating multiple stores, please go through this FAQ: Can or should I create multiple stores?

import { connect, createProvider } from 'ember-simple-redux';

const STORE_KEY = 'componentStore';

// `provider` in `ember-simple-redux` is not a React component
export const provider = createProvider(STORE_KEY);

function connectExtended(
  mapStateToProps,
  mapDispatchToProps,
  mergeProps,
  options = {}
) {
  options.storeKey = STORE_KEY;
  return connect(
    mapStateToProps,
    mapDispatchToProps,
    mergeProps,
    options
  );
}

export { connectExtended as connect };

Now the new provider and connect should be used instead.

Prior Arts

• ember-redux
• ember-cli-redux

Contributing

Installation

• git clone <repository-url>
• cd ember-simple-redux
• yarn install

Linting

• yarn lint:js
• yarn lint:js --fix

Running tests

• ember test – Runs the test suite on the current Ember version
• ember test --server – Runs the test suite in "watch mode"
• ember try:each – Runs the test suite against multiple Ember versions

Running the dummy application

• ember serve
• Visit the dummy application at http://localhost:4200.

For more information on using ember-cli, visit https://ember-cli.com/.

License

This project is licensed under the MIT License.

Credits

Great thanks to the contributors of react-redux, this addon has borrowed a huge part of heavy lifting components from it.