React Bootstrap Site Generator

Jan 6 2018

React Bootstrap Site Generator is an npm package that builds on top of the fantastic Create React App tool. The configuration and template have been adapted to work as a crazy simple, opinionated static site generator designed to make creating sites like this one super fast.

I built it with these goals in mind:

  • Make it as quick as possible to get something meaningful in the browser
  • Make adding new content as quick as possible, while still allowing content to be arbitrarily complex
  • Separate form from content - writing a new entry should only require touching one file for the usual case
  • Automate the boring stuff - nested nav generation, site and page metadata for search engine crawlers, static HTML generation, browser tab titles
  • Automatic social media stuff per-post
  • Straightforward deployment: run npm build and scp the build directory to my hosting service's public_html directory
  • A modern stack with all the trimmings, including a precommit hook for automatic style-enforcement and sass support with file watching

So why god why not just write stuff on Wordpress or Medium and be done with it?

O'Reilly: Rolling your own CMS for no good reason

Well because c'mon, who wouldn't rather have their own domain where they can have control over every pixel on the screen, rather than dealing with some WYSIWYG editor in the browser and playing by the rules of the MAN?!

More reasons:

Now that we all agree making your own site is still a desirable thing to do in 20-whatever, let's talk about how!

My journey building a content hub

Squarespace

Originally I subscribed to Squarespace account where I posted simple blog-style content.

Squarespace + manual hosting

I started this site to add other content like Processing sketches that Squarespace isn't well-suited to host. I built it using raw HTML, CSS and JS for simplicity and control, but also because I wanted it to be served statically from the Namecheap hosting I bought. I love React, but it kind of felt like overkill and it serves pages dynamically, meaning direct links won't resolve since the directory won't be actually serving up an index.hml file and thus won't load unless you visit the site index and follow a Route link. (More on this in a bit!)

Honestly though, I mostly just thought it was refreshing and fun to write things barebones after working so much with more complex stacks at my day job.

Manual hosting only

It started to feel silly to have two places for content, so I moved the Squarespace posts over here and stole the CSS styles I liked.

After adding more content, I was getting fed up with the amount of duplication involved. I was avoiding a lot of it using simple tactics like this for each page:

<script type="text/javascript">
  $(document).ready(function() {
    $('#main_nav').load('../../../main_nav.html');
    $('.main-content').load('main_content.html');
  });
</script>
and putting the raw content of each post into its own main_content.html.

But there were still a lot of shortcomings:

  • I still had a ton of duplication in the form of html head tags and other random junk.
  • Making structural changes to each post still required changing html everywhere, and there was no easy way around this.
  • Managing js dependencies and versions and running a local server manually was a pain and felt really outdated.
  • I was really missing inheritance and composition, and other object-oriented properties.
Basically, I didn't have the setup I wanted, where I could focus on content alone. When adding new things, I usually had to edit multiple files. I could not easily make more complex changes like adding a post summary list page.

Rewriting in React

I decided to do a rewrite. I didn't want to to incur the learning overhead and unnecessary complexity of another site generator like Jekyll. I wanted to work with common tools that I'm already comfortable with, using and developing skills that are transferable to other projects in my career. I've also developed a healthy fear of running into arbitrary limitations with strict frameworks.

I love React, but it has this whole dynamic routing issue I mentioned above. However! I found this amazing tool, react-snapshot, that performs static prerendering on React apps by crawling the site and generating html for each page! Problem solved.

I used Create React App and React Bootstrap to spin up a new site, and copied the content over. Now that I had nice object-oriented tools at my disposal, I was able to solve my larger goal of building a system that allows me to focus on content independently of form and architecture.

Using the tool

I've shared the framework as a react-script to be used directly with create-react-app. It's inteded more as a starting point than a framework. In the simplest cases, if your needs are similar to mine, you can get away with only modifying a couple files (entries.js and config.js), but more likely you'll want to modify the site-generation code in src/app to suit your own needs.

Setting up a new site

$ npm install -g create-react-app
$ create-react-app my-app --scripts-version react-scripts-bootstrap-site-generator
$ cd my-app
$ npm install
$ npm start

That's it! Your browser should load a new tab to localhost:3000 and you'll be greeted with the example app:Demo gif of site generator

See the project README for all the details and documentation, including how to modify and add new content and posts to the generated site, and how to build and deploy.

I hope this saves someone time setting up their next site! If you have any questions, comments or bugs, comment below or contact me directly!

Share