An alternative side effect model for Redux apps
JavaScript TypeScript
Latest commit cef0770 Jan 16, 2017 @Andarist Andarist 0.14.3
Permalink
Failed to load latest commit information.
dist Fixed CHANNEL_END public export Jan 16, 2017
docs Merge pull request #733 from thezanke/master Jan 16, 2017
examples Added declarative effect creators for helpers Dec 12, 2016
src Fixed CHANNEL_END public export Jan 16, 2017
test Reworked middleware custom emitter test Jan 8, 2017
.babelrc Fixed deprecated (and broken) dependency (fixes #489) Aug 17, 2016
.bookignore Added ignore list for gitbook cli Feb 3, 2016
.eslintrc.json Rename .eslintrc (deprecated) to .eslintrc.json Apr 29, 2016
.gitignore fix es build to properly use jsnext:main field Jun 20, 2016
.npmignore npmingore gitbook specific files Feb 4, 2016
LICENSE Initial commit Nov 29, 2015
README.md Merge pull request #749 from clbn/patch-1 Jan 9, 2017
README_ja.md Migrate all links to the new organization URL (fixes #719) Dec 26, 2016
README_ko.md docs(translate): Add Korean translation Jan 8, 2017
README_zh-cn.md Migrate all links to the new organization URL (fixes #719) Dec 26, 2016
README_zh-hant.md Migrate all links to the new organization URL (fixes #719) Dec 26, 2016
book.json Migrate all links to the new organization URL (fixes #719) Dec 26, 2016
effects.d.ts Updated TS definition to include saga helpers in redux-saga/effects Dec 28, 2016
effects.js export effects Feb 15, 2016
index.d.ts Merge remote-tracking branch 'pbadenski/master' Jan 8, 2017
package.json 0.14.3 Jan 16, 2017
types.d.ts Add TypeScript definitions May 17, 2016
utils.d.ts Updated helper name to hasOwn and fixed the typescript definition of … Dec 31, 2016
utils.js added top level utils export Feb 15, 2016
webpack.config.base.js Added support to umd builds Jan 9, 2016
webpack.config.dev.js Added support to umd builds Jan 9, 2016
webpack.config.prod.js Added support to umd builds Jan 9, 2016

README.md

redux-saga

Join the chat at https://gitter.im/yelouafi/redux-saga npm version CDNJS OpenCollective OpenCollective

redux-saga is a library that aims to make side effects (i.e. asynchronous things like data fetching and impure things like accessing the browser cache) in React/Redux applications easier and better.

The mental model is that a saga is like a separate thread in your application that's solely responsible for side effects. redux-saga is a redux middleware, which means this thread can be started, paused and cancelled from the main application with normal redux actions, it has access to the full redux application state and it can dispatch redux actions as well.

It uses an ES6 feature called Generators to make those asynchronous flows easy to read, write and test. (if you're not familiar with them here are some introductory links) By doing so, these asynchronous flows look like your standard synchronous JavaScript code. (kind of like async/await, but generators have a few more awesome features we need)

You might've used redux-thunk before to handle your data fetching. Contrary to redux thunk, you don't end up in callback hell, you can test your asynchronous flows easily and your actions stay pure.

Getting started

Install

$ npm install --save redux-saga

or

$ yarn add redux-saga

Alternatively, you may use the provided UMD builds directly in the <script> tag of an HTML page. See this section.

Usage Example

Suppose we have an UI to fetch some user data from a remote server when a button is clicked. (For brevity, we'll just show the action triggering code.)

class UserComponent extends React.Component {
  ...
  onSomeButtonClicked() {
    const { userId, dispatch } = this.props
    dispatch({type: 'USER_FETCH_REQUESTED', payload: {userId}})
  }
  ...
}

The Component dispatches a plain Object action to the Store. We'll create a Saga that watches for all USER_FETCH_REQUESTED actions and triggers an API call to fetch the user data.

sagas.js

import { call, put, takeEvery, takeLatest } from 'redux-saga/effects'
import Api from '...'

// worker Saga: will be fired on USER_FETCH_REQUESTED actions
function* fetchUser(action) {
   try {
      const user = yield call(Api.fetchUser, action.payload.userId);
      yield put({type: "USER_FETCH_SUCCEEDED", user: user});
   } catch (e) {
      yield put({type: "USER_FETCH_FAILED", message: e.message});
   }
}

/*
  Starts fetchUser on each dispatched `USER_FETCH_REQUESTED` action.
  Allows concurrent fetches of user.
*/
function* mySaga() {
  yield takeEvery("USER_FETCH_REQUESTED", fetchUser);
}

/*
  Alternatively you may use takeLatest.

  Does not allow concurrent fetches of user. If "USER_FETCH_REQUESTED" gets
  dispatched while a fetch is already pending, that pending fetch is cancelled
  and only the latest one will be run.
*/
function* mySaga() {
  yield takeLatest("USER_FETCH_REQUESTED", fetchUser);
}

export default mySaga;

To run our Saga, we'll have to connect it to the Redux Store using the redux-saga middleware.

main.js

import { createStore, applyMiddleware } from 'redux'
import createSagaMiddleware from 'redux-saga'

import reducer from './reducers'
import mySaga from './sagas'

// create the saga middleware
const sagaMiddleware = createSagaMiddleware()
// mount it on the Store
const store = createStore(
  reducer,
  applyMiddleware(sagaMiddleware)
)

// then run the saga
sagaMiddleware.run(mySaga)

// render the application

Documentation

Translation

Using umd build in the browser

There is also a umd build of redux-saga available in the dist/ folder. When using the umd build redux-saga is available as ReduxSaga in the window object.

The umd version is useful if you don't use Webpack or Browserify. You can access it directly from unpkg.

The following builds are available:

Important! If the browser you are targeting doesn't support ES2015 generators, you must provide a valid polyfill, such as the one provided by babel. The polyfill must be imported before redux-saga:

import 'babel-polyfill'
// then
import sagaMiddleware from 'redux-saga'

Building examples from sources

$ git clone https://github.com/yelouafi/redux-saga.git
$ cd redux-saga
$ npm install
$ npm test

Below are the examples ported (so far) from the Redux repos.

Counter examples

There are three counter examples.

counter-vanilla

Demo using vanilla JavaScript and UMD builds. All source is inlined in index.html.

To launch the example, just open index.html in your browser.

Important: your browser must support Generators. Latest versions of Chrome/Firefox/Edge are suitable.

counter

Demo using webpack and high-level API takeEvery.

$ npm run counter

# test sample for the generator
$ npm run test-counter

cancellable-counter

Demo using low-level API to demonstrate task cancellation.

$ npm run cancellable-counter

Shopping Cart example

$ npm run shop

# test sample for the generator
$ npm run test-shop

async example

$ npm run async

# test sample for the generators
$ npm run test-async

real-world example (with webpack hot reloading)

$ npm run real-world

# sorry, no tests yet

Backers

Support us with a monthly donation and help us continue our activities. [Become a backer]

Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [Become a sponsor]