Instant Production-Ready Scaffolding With Create-Static-Site

Create React App is a utility provided by the Facebook team in support of the React JavaScript framework. The goal of Create React App is to allow developers to quickly bootstrap a React project without having to spend time sorting out the build pipeline. With over 47,000 stars on Github (over half as many as the actual React library,) Create React App’s popularity speaks for itself.

The success and utility of Create React App has inspired the Forestry.io community to create a similar project for scaffolding static sites. Create Static Site is a tool that can set up a new Hugo or Jekyll site with a modern, production-ready build pipeline in seconds.

Why You’ll Like Create Static Site

Building a website to keep up with modern demands requires a modern asset pipeline. You need to provide optimum cross-browser and legacy browser support to ensure your code works on as many devices as possible. You will want to use a bundler like Webpack so you can write modular, well-organized JavaScript. You also want to serve optimized assets to your users so that your page loads as quickly as possible. All of this, of course, should be as fast as possible and completely automatic, so you’re not wasting time manually recompiling and re-optimizing your scripts.

Neither Jekyll nor Hugo’s new command will provide this out of the box. Jekyll provides CSS preprocessing with Sass (and can handle CoffeeScript with an additional plugin,) but that’s all. Hugo is even more barebones: it just copies any assets added to your site’s static folder, intending for the developer to install whatever asset processing they want.

This is where Create Static Site comes in. Create Static Site builds off the scaffolding provided by the new command to include a production-ready asset pipeline with your new site, while keeping the interface simple by using a single command and no configuration.

Getting Started

The easiest way to get started with Create Static Site is with npx. In order to use npx, you need to have npm version 5.2 or higher installed, and you need node 6 or higher to run the create-static-site scripts.

If using this tool to create a Jekyll site, you will also need to have ruby and bundler available on your system.

Using npx we can invoke the create-static-site command without having to install it anywhere:

npx create-static-site my-new-site --template hugo

After running the above command, a new Hugo site will be created in the my-new-site directory. You can create a new Jekyll site by passing --template jekyll instead:

npx create-static-site my-new-site --template jekyll

After the install finishes, navigate to the directory of your new site:

cd my-new-site

If you’re using Jekyll, you will need to install the gems before continuing:

bundle install

To start your development server, run the following command:

npm start

This will start up the dev server, watch your files for changes, and set up BrowserSync for automatic reloading.

To build your production site, run the following command:

npm run build

This is the command you will want to run in your CI environment to build your static site before deploying. It will build production assets and also run the static site generator.

Directory Structure

If you’re accustomed to bootstrapping a new site with hugo new or jekyll new, things will look a bit different here. You will find the standard Hugo or Jekyll files in the site/ subdirectory. Your assets (CSS, JS, and images) are located in the src/ subdirectory, and the generated site (after running npm run build) will be generated in the dist/ subdirectory.

Features

.gitignore Included

This may sound like a minor quibble, but having a .gitignore preconfigured to exclude the generated HTML as well as your node_modules directory saves you an extra step during setup.

Live Reloading via BrowserSync

It should be noted here that Hugo offers a nice development workflow out of the box with its hugo serve command, which uses BrowserSync to automatically reload the browser window when changes are detected. Create Static Site offers the same functionality in its asset pipeline. If you’re a Jekyll user, you will love having live reloading without needing any additional config.

Styles

Create Static Site uses PostCSS to handle CSS transformations. You get precss to provide Sass-like features such as variables and selector nesting. You can use cutting-edge CSS features while maintaining cross-browser and legacy browser support with cssnext and laggard. postcss-reporter and postcss-browser-reporter are included to make it easy to spot CSS errors in development, and cssnano shrinks your CSS down to the smallest file size possible.

Scripts

Webpack handles your JavaScript, so you can organize your code into modules. Babel is included, with the popular env preset configuration so you can use modern syntax while supporting older browsers. In addition to the env preset, Create Static Site includes plugins to support the rest/spread operator for objects. Finally, Create Static Site uses Uglify JS to minify your JavaScript.

Images

Imagemin is used to optimize images stored in src/img/.

Create Static Site will also take SVG files added to img/svg and compile them into a single spritesheet. Create Static Site includes a template to easily insert these images into your site. The SVGs can be referenced by their ID in the spritesheet, which is svg-- followed by the filename. The following examples demonstrate including the default SVG image found at img/svg/bitbucket.svg:

Hugo

{{ partial "svg" (dict "id" "svg--bitbucket") }}

Jekyll

{% include svg.html id="svg--bitbucket" %}

You can also pass the class, width, and height parameters to this partial to add the corresponding html attributes.

Ejecting

Just like Create React App, Create Static Site gives you the option to eject your configuration if you need to customize it. Note that after ejecting, you will have to maintain the build configuration yourself!

The Future of Create Static Site

We are actively looking for help and input on how to make Create Static Site better. One thing we want to do is support more static site generators beyond Jekyll and Hugo.

If you’d like to contribute, check out the contribution guidelines and take a look at the issues that are actively seeking contributions.

Have something to add?

Discuss on Hacker News