request for documentation

[geekyme]

Hi, I think this boilerplate seems very comprehensive and advanced for production usage. However I am having trouble understanding the code.

Would you be able to place some inline comments to help readers understand your code design?

Thanks :)

[jenbennings]

+1

[sokra]

added some comments

[FoxxMD]

+1 Could still use a better explanation of everything! This kit looks incredibly powerful but I'm not sure how to utilize everything you've done.

[geekyme]

I agree that it is really powerful but I am finding it difficult to understand and customize it to my needs. Would probably do best with a wiki or MD file that explains the design choices of the entire setup if anyone is going to adopt this boilerplate seriously.

[FoxxMD]

The Features section in the readme is fairly comprehensive. I'd use that as a starting point and just expand under each point. @sokra if you'd like help I'd be happy to start filling in the more obvious sections.

[sokra]

Started something here:

https://github.com/webpack/react-starter/wiki/How-does-it-work

[FoxxMD]

Awesome thank you! :+1:

Is there anything we can help with?

[barrystaes]

This readme page example might be of interest: https://github.com/webpack/react-starter/pull/45 It might be of use to document it in markdown.

[barrystaes]

As OP says, it is not immediately obvious where to start looking, what the design is, finding the root execution point so to say. I would like to add /README.md is of great quality as-is, it got me up and running in notime.

But for grasping the overall design i just wrote HowStuffWorks.md with some nudges in the right direction. No details by intention.

Feedback is very welcome! I'm still sorting out how the stores work.

[FoxxMD]

Thanks @barrystaes! Great work on the guide. It's short and to the point, exactly what I think we need.

I'd like to see some detail on how pre-rendering works in general terms. I am not using that feature yet but it seems extremely powerful and being able to implement my own system (using marty.js rather than item-store) in the future is an option I would love to have.

I have tried to follow the code for pre-rendering but having a section in "HowStuffWorks" for it would be super useful :)

Also a short guide on entry points and how they are useful would be killer!

[barrystaes]

OK i added a prerender paragraph to production mode. Perhaps it should link to respective websites with more documentation? I rather avoid deeplinks, these just tend to get out of date.

What do you mean with entry points?

I'm still a learner myself, thanks for mentioning marty.js. Should i avoid using the stores as from react-router? I'd like to have a conversation on this, somewhere. I cant afford to investigate every option regarding stores (and Flux).

[FoxxMD]

Yeah external documentation would be more useful if prerendering using webpack/this method is common.

By entry point I mean the entry point in webpack and using pre-rendering with it. Maybe a use case so we can see why it's useful?

Using item-store is fine, what I meant is that there are many areas related to pre-rendering that are not documented (comments) or explained anywhere. Some of the code is specific to how item-store works, other parts are applicable to any isomorphic application. If I was just beginning to use react and webpack (and I am) I would be seriously lost trying to make a distinction between what areas I can re-implement using my own flux flavor and what areas need to stay static (or implemented a specific way).

I'm not asking you to write a how-to for creating an isomorphic app but comments in code with a more thorough explanation of what's going on or a "general" overview of the process taking place would be extremely helpful.