Rico's opinionated Metalsmith frontend kit

frontend-starter-kit

Boilerplate for a frontend project powered by Metalsmith

This is a small project that takes a bunch of HTML, CSS, JS files (web/) and turns them into a website (public/). Use it to build your new Reddit webapp, Pokemon tool, Firebase-based webapp, Phoenix app assets, or whatever suits your fancy.

Installation

See instructions for:

**Vanilla** (no framework)

mkdir my-project
cd my-project
curl -sSL https://raw.githubusercontent.com/rstacruz/frontend-starter-kit/master/_extras/INSTALL.sh | bash

See INSTALL.sh to see what it does.

with **Decca**

Decca is a React-like library for rendering functional views.

# Run both:
curl -sSL https://raw.githubusercontent.com/rstacruz/frontend-starter-kit/master/_extras/INSTALL.sh | bash
curl -sSL https://raw.githubusercontent.com/rstacruz/frontend-starter-kit/master/_extras/decca/INSTALL.sh | bash

with **React** + **Redux**

This is a React boilerplate with Redux. It uses riot-route for routing.

# Run both:
curl -sSL https://raw.githubusercontent.com/rstacruz/frontend-starter-kit/master/_extras/INSTALL.sh | bash
curl -sSL https://raw.githubusercontent.com/rstacruz/frontend-starter-kit/master/_extras/react/INSTALL.sh | bash

in a **Phoenix** project

Experimental! Use this with Phoenix to replace Brunch with Metalsmith. Bootstrap your app with mix phoenix.new --no-brunch, then:

curl -sSL https://raw.githubusercontent.com/rstacruz/frontend-starter-kit/master/_extras/phoenix/INSTALL.sh | bash

Usage

Run in development (or production):

npm start

Or build for production (builds /public):

npm run build

What you get

Extensible everything build pipeline (via Metalsmith)
Extensible JavaScript build pipeline (via Browserify)
Modern JavaScript with support for ES2017 (via Babel)
Modern CSS via Sass, PostCSS, Cssnext, and Autoprefixer
Reliable dependency management via Yarn

As well as:

Support for Pug (as well as any templating language) via jstransformer
Production-ready tools (JS and CSS compression)
Super-useful development server (via metalsmith-start)
Ready to deploy to Heroku (just git push)

What you DON'T get

It's opinionated, but only up to a point. All it does is take web/ and turn it into public/ with a production build command (npm run build) and a development auto-watcher command (npm start). The rest is up to you.

These things are not included here:

React (bring your own framework!)
Testing boilerplate (bring your own testing tools!)
CSS framework (bring your own Bootstrap/Foundation/etc!)
...and so on

Paths

web/ is compiled into public/.

web/assets/ — files compiled into /public. Anything not "compilable" is simply copied over.
- app.scss
- app.browserify.js - compiles web/js/app.js
- vendor.browserify.js - separate bundle for big 3rd-party modules
- index.pug
- robots.txt
web/css/ — files @imported by assets/app.scss.
- app.scss
web/js/ — files compiled by Browserify.
- app.js
web/layouts/ – template layouts.
- base.pug
metalsmith.js — metalsmith configuration.

Why Metalsmith?

Metalsmith is a compiler "framework". Its purpose in life is to take a folder (web/) and turn it into another folder (public/).

It's (kinda) functional. Metalsmith brings together plugins that transform files into new files. A Metalsmith plugin is simply a map() for your entire project. Your build pipeline is simply a series of map()s.

It's also great for development. metalsmith-start is a fantastic development server for Metalsmith. It rebuilds your files instantaneously as you change them, supports LiveReloading, and can run on any Metalsmith project.

It simplifies many things. Everything here is in <100 lines of JS and JSON (including package.json). The only significant pieces here are metalsmith.js and the Babel config in package.json.

Why not X?

You can use Webpack (it compiles JS wonderfully!), but webpack won't copy over any non-JS files (.html, .png and so on). It also won't compile into CSS (it'll compile your CSS into JS, yuck).
You can use Brunch (it does the same folder-into-another-folder build style!), but Brunch has its own JS build pipeline, which is very hard to work with. It also doesn't support webpack/browserify.
You can use Gulp (it ties together build tools, too!), but interoperability between Gulp plugins is dismal. Good luck getting real-time file watching working with Browserify. Try to get LiveReload working without losing your hair and you'll see.
You can use Grunt (it's a task runner everyone loves! or at least used to), but I'll let this article explain why you shouldn't.