I’m back to hacking on my own projects again, and it once again seems like the docs are missing. So begins the laborious process of finding and filling the gaps.

On Jekyll

Github wants to make it super easy to host simple websites. For blogs like this one they point you toward Jekyll, and the expectation is that it should be easy. It’s not really though, because someone forgot to connect the dots between “Github will run Jekyll” and “here are the Jekyll docs.” Except I don’t want to learn how to install and configure Jekyll. I was promised a lazier path than that.

Fortunately others have been here before, and one of those folks took pity on me (or at least the idea of me). Jekyll Now comes with all the batteries included, and sensible documentation to boot. So I went that route and successfully avoided learning anything about Github hosting. Maybe later.

By the way, good luck if you want to use any pre-built themes for your Github-flavored Jekyll. There appear to be a dozen or so that Github has chosen to support, but I’m not even quite sure if that worked. The best outcome I’ve achieved so far is to get “Minimal” working, and I think that was actually the default because it looks the same as before. Everything else I tried led to page build warning. For example:

You are attempting to use a Jekyll theme, “jekyll-whiteglass”, which is not supported by GitHub Pages. Please visit https://pages.github.com/themes/ for a list of supported themes.

I’m already wondering if maybe I should just figure out what Github is doing under the hood and stop pretending Jekyll is somehow special.

On bootstrapping a React project

All I want to do is serve up a React frontend with best practices like server-side pre-rendering (aka universal JS aka isomorphic JS). I don’t want this service to do much else, so I figure JS and Node are fine for this part of the stack. Any actual smarts will live in separate services and the JS endpoints will dispatch accordingly.

The last time I did this I was really into Golang, and really not into Node. So I used olebedev/go-starter-kit to get a React frontend served up by a Golang server. That worked well, but Go is kind of a pain this close to the frontend where almost everything is JSON. So I’m back to using Node for the full stack, but back to square one for getting started.

The good and bad news is that there a lot of options out there. I have basically no idea what I’m doing, so I want batteries included. The first breadcrumb I found was Facebook’s own create-react-app. That’s good for the frontend, but doesn’t give me a server. A bit of poking around leads to Razzle, which gives you a server but not much project structure. If you want that then it appears the next step is to either fork a boilerplate or use a framework.

I’ve had mixed experiences with boilerplate, but the frameworks these days seem pretty reasonable. I’m all for an opinionated approach at this point. Razzle points you at two options. Next.js makes me log in to view the docs, so I skipped it. Redfin’s react-server was more accessible, and seems to fit the bill. We have a winner.

On react-server

The docs are not great. One installation path uses Yeoman, which I know nothing about. Another suggests npm install -g, which is probably only a good idea if you want to use this framework a lot. In retrospect I should have figured out Yeoman, but instead I’ll just suffer with the global install. And also the global installs for cookie-parser, express, and express-state; since react-server-cli maybe forgot to mention those.

A bit of following the docs later, and I’ve got a working server. Next up is to add an API endpoint, for which there is no documentation. There are a few well hidden examples. The bike-share description was most promising, and indeed had the goods. Here are the most important parts:

• Create an api/ subdirectory and add an index.js, to register your API endpoints as middleware. I find this usage of “middleware” to be unfamiliar at best.
• Add api/ to the middleware section of the .reactserverrc config.
• Per the comments, add some code to kick off a data request from the Page’s handleRoute method.
• Add some mysterious port redirection logic, as another more different type of middleware, because apparently ReactServerAgent doesn’t know which port it’s running on.

Here’s the diff I ended up with: