1.0 doc newcomer feedback

[phtrivier]

Hi

I've been checking the docs for redux 1.0, hoping to start using it.

Here is some feedback from total n00b :

• The Introduction and Basic part is great (expacially the "Motivation" and links to other Flux lib)
• The "Advanced" part is incredibly frustrating (maybe it's just me, but it's the third flux-like lib I've seen this last few weeks that does not explain how to do async / ajax, which is kind of a pretty common requirement)
  I'm pretty sure're you're working on it, and from what I gathered the article seems to boil down to "use redux-thunk", but meanwhile a new user will have to guess and dive into examples without much direction
• The "Installation" part is really confusing to someone who does not know how to go from npm install redux to use redux in a browser. Maybe it's just a matter of knowing how to use webpack / browserify, and maybe I'm the last person who does not find it obvious ;)

I hope it does not sound too much like a rant.

Thanks

[ForbesLindesay]

For async the story is use redux-thunk or (even better in my opinion) use some form of redux promise middleware. We should definitely add docs for both those options and start adding some more basic async examples.

For getting it working in the browser, we should probably also distribute a pre-built version and include some basic instructions for browserify/webpack.

[phtrivier]

Thanks for the reply.

I got around the "install" part (the surprising bit was that a pretty default setup of webpack does the trick - I was expecting to have something more to do.)

Are there already promise middleware examples that you would recommend ?

Looking forward to reading the updated docs.

Thanks.

[ForbesLindesay]

The code I use is:

function promiseMiddleware(store) {
  return function (next) {
    return function (action) {
      action && typeof action.then === 'function'
        ? action.then(next, onError)
        : next(action);
    }
  }
};

function onError(err) {
  // use setTimeout to prevent error being silenced
  setTimeout(function () {
    throw err;
  }, 0);
}

You can then do async like:

dispatch(
  getJSON('/example.json').then(
    data => (
      {type: 'DATA_FETCH_COMPLETE', data: data}
    ),
    err => (
      {type: 'DATA_FETCH_FAILED', err: err}
    )
));

[gaearon]

The "Advanced" part is incredibly frustrating (maybe it's just me, but it's the third flux-like lib I've seen this last few weeks that does not explain how to do async / ajax, which is kind of a pretty common requirement)

How is it frustrating if it isn't written yet? I'm working on it. :-)

[gaearon]

In the meantime this might help you get started:

https://gist.github.com/gaearon/074b0905337a6a835d82

Also:

#99
http://gaearon.github.io/redux/docs/recipes/ReducingBoilerplate.html#async-action-creators
http://gaearon.github.io/redux/docs/api/applyMiddleware.html

[phtrivier]

How is it frustrating if it isn't written yet? I'm working on it. :-)

Good to hear that !

It's frustrating because I fell like "telling people to use a flux-ish lib", without an example of "doing an ajax call the right way" in the doc, seems to be the norm those days. I've litteraly seen it with : redux, flummox, plain-old-flux and elm since I started looking into flux implementations. (EDIT : as pointed out, I dreamt the part about flummox. Poor little framework.)

I tend to blame "todomvc" for that ; you don't need ajax to implement the "canonical" version, but it could be argued that such a backend-less single page app is going to be completely useless to a vast majority of developpers (who will have to call an API sooner than later.)

Anyway, thanks for the help and good luck with the writing !

[gaearon]

To be fair Flummox docs were focused on AJAX stuff from the start, from what I remember.

[phtrivier]

@gaearon that's right, sorry. "Rant mode" makes you imagine things ;)

[swordsreversed]

@phtrivier +1

[gaearon]

We just added two new examples focused on async interaction:

• Add a simple async example #474 (simple: loading state, re-fetching, invalidation)
• Add “real world” example #460 (real world: pagination, caching, state normalization, routing, custom middleware)

Feel free to check them out!

[phtrivier]

Great !

#474 looks great (I had arrived at about this point, thanks to the other examples mentionned in this thread, but I did some weird things, and the organisation is clearer )

It's good that you introduce that "explicit" handling of sending a request / waiting for the response / getting the response and storing it / invalidating the cache. Although, is there a middleware / pattern that can remove some boilerplate for that ?

Also, I'm not sure why you introduce "isomorphic-fetch" in the example (Is it just because you use it everywhere and want to prepare the ground for later examples ?)

Will you be using those examples in the guide ?

Thanks !

[gaearon]

It's good that you introduce that "explicit" handling of sending a request / waiting for the response / getting the response and storing it / invalidating the cache. Although, is there a middleware / pattern that can remove some boilerplate for that ?

See "real-world" example. :-)

Also, I'm not sure why you introduce "isomorphic-fetch" in the example (Is it just because you use it everywhere and want to prepare the ground for later examples ?)

Yes.

[phtrivier]

See "real-world" example. :-)

Can't wait to 😉 (will do as soon as I can !)

Will you also touch on how you would test async actions (or is it out of scope ?) I would love to have your opinion on injecting / mocking / patching things like fetch...

[gaearon]

New doc is up: Async Actions.

[lesterzone]

Thanks!

[tchon]

@gaearon I'm trying to run redux/examples/real-world and my cloned repository is at the current head of branch "breaking-changes-1.0" (which is fd7f884), but I am receiving this error when requesting http://localhost:3000/ (while running npm start):

ERROR in /Users/tim/.local/src/js/react/redux/src/utils/combineReducers.js Module not found: Error: Cannot resolve module 'warning' in /Users/tim/.local/src/js/react/redux/src/utils @ /Users/tim/.local/src/js/react/redux/src/utils/combineReducers.js 26:15-33

Any ideas? Thank you!

[tchon]

I am really enjoying redux and react-redux, by the way. Great work!

[gaearon]

@tchon Did you run npm install in the root folder? From examples:

To run any of them, you need to clone the repo and run npm install:

git clone https://github.com/gaearon/redux.git
cd redux
npm install

[tchon]

@gaearon Ok, running npm install at the top level fixed it. Thanks again!

[gaearon]

The "Advanced" part is incredibly frustrating (maybe it's just me, but it's the third flux-like lib I've seen this last few weeks that does not explain how to do async / ajax, which is kind of a pretty common requirement)

Should be solved by Async Actions.

The "Installation" part is really confusing to someone who does not know how to go from npm install redux to use redux in a browser. Maybe it's just a matter of knowing how to use webpack / browserify, and maybe I'm the last person who does not find it obvious ;)

We assume user is familiar with NPM ecosystem. We can't teach the user to use NPM and JavaScript bundlers—they'll have to get this knowledge elsewhere. We will provide a standalone build (#212) soon, but every Redux-related package is on NPM anyway so there's no point in resisting it.

Will you also touch on how you would test async actions (or is it out of scope ?) I would love to have your opinion on injecting / mocking / patching things like fetch...

Please raise a separate issue to discuss this.