Proposal: Package reshuffle for user friendliness

[gigabo]

Right now react-server isn't easy to get started with.

It's missing big pieces that are provided by react-server-cli.

Proposal:

• Move react-server to react-server-core.
• Pull the bulk of react-server-cli into react-server
  • react-server exports startServer.js (as .start() or .run())
  • react-server-cli just becomes CLI for calling require('react-server').start().

[doug-wade]

I'm struggling to understand the scope of react-server. As far as I can tell, we seem to believe that we are going to manage all of the complexity of the build for every client of react-server, which I think is unrealistic, as it requires new clients that want to do something we haven't considered. Consider a client that wants to set up a react-server instance with browserify, clojurescript, and support a dev, test, staging, perf testing, and multiple prod environments (say, for instance, they would like to have different build for China vs the US). As I understand the proposal, that client would need to open a pr to what is you are proposing would be named react-server to add browserify support, clojurescript support, jshint for linting, and to change the existing way of handling environments to allow them to use react-server. As I understand it, you'd either fork react-server and use that (which would be frustrating when you want to get new features, since you'd have to rebase onto/merge redfin/react-server), or you'd use react-server-core and lose any other configuration that is exported by the proposed react-server solution.

There's also a question of support -- in our use of react-server, we've had to spend a lot of time debugging webpack errors. If we hide all the complexity of webpack in the react-server-cli, when there is an error (which although I would love to guarantee would never happen, I think realistically will), then rather than using the existing webpack documentation, clients would have to rely solely on the code from react-server-cli to figure out the source of their failure, fork the cli, build and deploy with the fork, and then submit the fork upstream.

Also, since we Babelify the code for clients, how would clients opt in or out of language features? Do they simply have to accept the variant of es6 exported by react-server? Or what if they want a different set of webpack plugins? Or a different set of eslint settings? Do we plan on consuming the config files of every possible bundler, transpiler, linter, etc as part of our api?

[aickin]

@doug-wade thanks for the thoughtful post, and sorry for my delay in jumping in. Life intervenes sometimes. First a small point:

Also, since we Babelify the code for clients, how would clients opt in or out of language features?

This is currently supported by the .babelrc in the project, so it's under the control of the project, not react-server-cli, but your larger point absolutely still holds.

I hear what you are saying here, and I asked a lot of questions trying to get at the same issues in my react-server-cli pull request. I agree that react-server-cli right now doesn't have a flexible API, and in an ideal world it would. My problem is that I can't figure out how to expose extension points in a way that doesn't multiply complexity and chances of breakage tremendously.

My motivation for react-server-cli was originally just to get react-server working and provide some path for other devs who wanted to do the same. Last summer, @gigabo and @roblg gave me access to the triton codebase because I volunteered to write some example projects for documentation. It took me something like a solid week of work to get a simple "Hello, World" that had client-side React working because setup had so many pitfalls. It took me another week or so to get bundle-per-route and hot reload working. If that's what it took me, as someone who had been working with the code base for 2-3 months, I figured no one in the open source world would be able to unravel it, so I packaged together what I had learned in react-server-cli.

I think you are asking the right questions: what API will we support, how will we deal with new requirements, and what's the guarantee of what will work and what won't? And I think you are arguing that the current react-server API is near the right level of abstraction, when combined with a one-time project generator. Is that a fair characterization? (And to be clear, because tone on the internet is so, so hard, I'm genuinely curious about your position here, and I'm only characterizing your argument to see if I understand it correctly, not to put words in your mouth.)

[doug-wade]

I've been thinking about this one, and I think we can do better. I'd like to keep react-server-core in react-server, and I'd like for our packages to be more granular, if possible. What about if we split out three modules

react-server-config
react-server-compiler
react-server-runner

react-server-runner would start/run React Server instances, and would mostly just be startServer.js. I imagine that eventually this would contain our clustering module.

react-server-config would handle .reactserverrc, and provide a way to merge its options with the default options (which it provides) and override options (like from the cli), and would contain findOptionsInFiles, defaultOptions, and mergeOptions

react-server-compiler would do babelification and run the module tagger, and might (?) include a watch mode. It would contain compileClient and the middleware templates.

Thoughts?

[gigabo]

@doug-wade - That sounds like a good breakdown. Not sure how easy it will be to disentangle those from each other. The runner needs to be able to host the webpack hot loader, for instance... but that's probably just a matter of finding choke points for the API between the modules.

Seems worth a shot.

@aickin - Any thoughts? You still have the deepest knowledge of the internals of react-server-cli, I think.

[aickin]

react-server-config
react-server-compiler
react-server-runner

At high level, this seems like a good breakdown to me, although I'm not 100% sure how it will work without seeing and thinking about the APIs for each of the modules.

What's the goal of making separate modules? Is there a case where you'd use one but not the others? Or is it more about understandability?