Don't Copy Paste This Frontend Template

By git cloning this project template, you get quickly started in frontend development. I use this project template in almost all of my static site projects, which need the basic set of frontend tools.

Before git clone, please go through the short explanation of how and why it works and see package.json devDependencies explained to get a quick introduction to all tools. See also frequently asked questions. After you understand the whole stack and tools, go ahead and just copy paste this setup.

Features

Provides basic but understandable features which can be fine-tuned later

Browserify provides require('x') syntax in your frontend to organize code and use NPM modules

syntax in your frontend to organize code and use NPM modules New ES6 features via Babel

LESS to organize CSS code across files plus other neat features

Autoprefixer so you can stop worrying about CSS browser prefixes

Automatically build bundle.js or bundle.css after changes to code

or after changes to code Minify JS and CSS for production

Build time configuration for JS

Cross-platform support

Customizing and debugging is easy because you fully understand the stack

GitHub Pages friendly

Get started

You need to have Node.js environment installed before anything. Clone this repository, run npm install and you're ready to run the following commands.

npm start To develop locally. Open your browser at http://localhost:8080 and start coding.

To develop locally. Open your browser at http://localhost:8080 and start coding. npm run build To build minified versions of bundle.js and bundle.css for production.

There are other commands too, but they are only used internally by these two main commands. These other commands are explained in package.json scripts reference.

How and why it works

Everything happens via npm scripts. The project "configuration" is in package.json, which in practice means command line tools and their options. These tools all solve a specific problem, and they do it well. You can find all exact shell commands from package.json "scripts" section.

If you spot a new tool, check what it is and why it is used from package.json devDependencies explained section.

Project structure

index.html is the entry point to your frontend.

styles/ contains all styles. All code in this directory will be built to bundle.css . styles/index.less is the entrypoint to LESS code.

. styles/index.less is the entrypoint to LESS code. scripts/ contains all JS code. All code in this directory will be built to bundle.js . scripts/index.js is the entrypoint to JS code.

. scripts/index.js is the entrypoint to JS code. assets/ contains all static assets, such as images.

All your frontend code will be in three files: index.html, bundle.js, and bundle.css – simple.

package.json devDependencies explained

browserify is used to build production build of bundle.js . babelify is a Babel plugin for Browserify and it uses babel-preset-es2015 to support new ES6 features. envify is a plugin for Browserify to allow build time configuration. As an example, you could build a bundle.js which points to production backend with: API_URL=https://my-app-prod.herokuapp.com npm run build In local development, you can set the variable to point to a locally running backend.

. watchify is same as browserify but for local development. Instead of building the bundle.js once, it watches changes in .js files and rebuilds bundle.js on each change. First build is a bit slow, builds after that are very fast.

once, it watches changes in files and rebuilds on each change. First build is a bit slow, builds after that are very fast. less is a LESS compiler written with NodeJS. Used to divide CSS code across files.

concurrently is used to run three separate commands concurrently when you type npm start . It is just for convenience, so that you don't need to run three separate terminals. http-server -c0 . to serve local files. npm run watch-js to watch JS files and rebuild bundle.js on each change. npm run watch-styles to watch LESS files and rebuild bundle.css on each change.

. It is just for convenience, so that you don't need to run three separate terminals. clean-css for minifying CSS.

uglifyjs for minifying JS.

http-server to serve the frontend files at http://localhost:8080.

chokidar-cli to watch changes in **/*.less files and rebuild bundle.css in local development.

files and rebuild bundle.css in local development. postcss-cli to automatically apply certain modifications to CSS. autoprefixer is a plugin for PostCSS to automatically add vendor prefixes to CSS. You can write clean CSS without worrying browser prefixes too much.



package.json scripts reference

Each npm script is a fairly simple one-line command. This chapter contains very detailed explanation of these commands and written with beginners in mind. It is much more important to know and understand the tools instead of memorizing what each of these commands do.

JavaScript local development watch ( npm run watch-js )

Full command:

API_URL=http://localhost:9001 watchify ./scripts/index.js -t [ babelify --presets [ es2015 ] ] -t envify --debug --verbose -o ./bundle.js

Watchify builds JS code to bundle.js , starts waiting for changes in JS code and rebuilds bundle.js when needed.

, starts waiting for changes in JS code and rebuilds when needed. watchify flags -t Use a given browserify transform plugin. By surrounding the plugin with brackets, you can give options to the transform plugin. --debug Enables source maps to ease debugging --verbose Increases watchify verbosity -o Which file the bundle is written to

Watchify supports the same option as browserify. So you can run: ./node_modules/.bin/browserify -h to figure out what each flag does.

to figure out what each flag does. API_URL is given as an environment variable so that envify knows to replace process.env.API_URL variable in code with that given value. This allows us to build bundle.js which connects to e.g. QA backend.

JavaScript production build ( npm run build-js )

Full command:

NODE_ENV=production browserify ./scripts/index.js -t [ babelify --presets [ es2015 ] ] -t envify -o ./bundle.js && npm run minify-js

Note: you need to define API_URL environment variable before running this command. You can set it in e.g. in your deployment script.

NODE_ENV=production is set so that your code or e.g. React can disable certain development features. You could for example disable logging, or possible debugging tools in production mode.

is set so that your code or e.g. React can disable certain development features. You could for example disable logging, or possible debugging tools in production mode. browserify builds bundle.js and exits. Command line options are almost the same as with watchify. Source maps are not created.

and exits. Command line options are almost the same as with watchify. Source maps are not created. After browserify creates bundle.js, the whole file is minified in place with uglifyjs ( npm run minify-js ).

CSS local development watch ( npm run watch-styles )

Full command:

npm run build-styles-dev && chokidar '**/*.less' './styles/**/*.css' -c 'npm run build-styles-dev'

npm run build-styles-dev is run immediately before watching is started in case styles have been modified while chokidar-cli was not running.

is run immediately before watching is started in case styles have been modified while was not running. chokidar-cli listens changes to **/*.less or ./styles/**/*.css files and runs npm run build-styles-dev on each change.

CSS local development build ( npm run build-styles-dev )

Full command:

npm run build-less && npm run postcss && echo 'Styles built!'

npm run build-less builds bundle.css

builds PostCSS applies transformations to bundle.css , e.g. Autoprefixer

, e.g. Autoprefixer After everything, we log something to console for convenience

CSS production build ( npm run build-styles )

Full command:

npm run build-less && npm run postcss && npm run minify-css

npm run build-less builds bundle.css

builds PostCSS applies transformations to bundle.css , e.g. Autoprefixer

, e.g. Autoprefixer npm run minify-css minifies bundle.css using clean-css.

Downsides

As much as I like npm scripts and browserify, here are some downsides in the setup.