Add more documentation

[markerikson]

We now have a published docs site at https://redux-starter-kit.js.org , and I've moved the API reference content from the README over to there.

However, the API doc pages are pretty short with only some simple examples, and they don't go into very much depth.

It would be great if we can expand those pages with more descriptive content.

I'd also like to see some example projects set up showing how to use this in action. One idea would be to base it off of a recent project shown on Reddit that I refactored to make use of RSK.

[denisw]

During the TypeScript rewrite, I started extending and refining the current API docs a bit within the doc comments. I am currently drafting extended docs pages for the various functions based on these efforts. I'll make sure to create small PR's as I go.

[markerikson]

Just added a "Usage Guide" page in #105 :

https://redux-starter-kit.js.org/usage/usage-guide

Definitely still need some tutorial-like examples, though.

[matthewsecrist]

Is there anything specific you're looking for in a tutorial? I'm interested in helping, but not sure what kind of tutorials/apps you're looking for.

[markerikson]

@matthewsecrist : Thanks! Yeah, I'd specifically like to see two tutorial pages that walk through actually using RSK:

• Creating a new Redux project from scratch
• Updating an existing Redux project to use RSK

As part of that, it would be good to show how thunks and other side effects fit in (since we've had some people recently asking if it's possible to "add thunks to slices" - see #76 ).

For the "existing app" project, I was considering using a slightly slimmed-down version of this app's codebase: jangbl/youtube-react#1 .

The "new" app probably doesn't have to be overly complex either, but it should have enough complexity to show off things like "mutative" immutable updates using createReducer/createSlice.

[matthewsecrist]

Gotcha, I'll play around with it and see what I can come up with. :) I don't have an overly large app at the moment, so doing a new app would probably work better for me.

[markerikson]

Great! Yeah, just lemme know here if/when you get started on something and we can coordinate.

[matthewsecrist]

Not sure if you're looking for something more complex than this, but I made https://github.com/matthewsecrist/ChooseAWinner which is just a simple app that will let the user add a list of things and then it chooses items from the list and puts them into a different list. It makes use of createSlice and shows off both the "mutative" and traditional ways of updating the state.

[markerikson]

@matthewsecrist : it's a potential starting point, yeah. would be nice to expand it a bit, maybe add another slice or two, and have some actions that get handled by both slices.

[matthewsecrist]

Yeah, I didn't know if you wanted something real basic to show off setup and such or something a bit more complex. What about something more like https://github.com/matthewsecrist/github_viewer ? Still needs some cleanup and refactoring right now, but is that more of what you're looking for?

[markerikson]

The tutorial aspects are now mostly covered. I've got a "Basic" and "Intermediate" tutorial added, and will be doing an "Advanced" one shortly.

Another suggestion: add a "Migration" page comparing what RSK offers vs core Redux.

[markerikson]

Finished the "Advanced" tutorial: https://redux-starter-kit.js.org/tutorials/advanced-tutorial .

I think this is actually mostly good for now. Really, the "Examples and Tutorials" link ought to be cleaned up or removed.

[misha-erm]

Hi all, it would be really cool if some examples are added about how to fix circular imports. Because currently docs have a nice example demonstrating the issue but no words about how to deal with them in scope of RSK.

Personally for me circular imports are the biggest issue I've faced right now using the RSK so would like to see some 'best practices' on how people used to fix them.
Thanks

[markerikson]

@MikeYermolayev : hmm. Interesting point.

In general, breaking circular dependencies usually involves moving certain values out into a separate file, and having both the main files import that one. Michel Weststrate gave some suggestions in his post How to fix nasty circular dependency issues in JS.

Specifically, you could:

• Add a separate commonActions file, define your action creators with createAction() in there, and have both slice files import those and reference them in the extraReducers section
• Write the reducers section as normal in both slices, but hand-write the expected action constants from the other file in the extraReducers section rather than relying on the value of someActionCreator.type

But yeah, having this as part of the "Usage Guide" or something might be nice.

[misha-erm]

Your first suggestion sounds like the same thing if I use createReducer instead of createSlice and describe actions with createAction in separate file. So this is what I ended up with
Instead of having one todos.slice.js I switched to having todos.reducer.js and todos.actions.js
Thanks for the tip 🙏

[markerikson]

We've got a "Usage with TS" page thanks to @phryneas .

At this point I think we're fairly good on docs page for now. Totally open to suggestions and improvements, though.

Anything else obvious that needs to be added, as far as new pages or topics?

[LoiKos]

Hello @markerikson,

I was looking for good practices on nested Slices/Reducers.

I'll explain my case : I have a complex form handle by a slice. Managing every part of the form inside one only slice create a lots of actions, selectors on the same file.

I suppose that the recommending way is to build for each part a slice and then combine them with combineReducers but I think it could be great to add a section that explain how to cut a large functionality into little slice for easier management.

Seems linked to : #259