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.
require('x')
syntax in your frontend to organize code and
use NPM modules
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.
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.
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.
All your frontend code will be in three files: index.html, bundle.js, and bundle.css – simple.
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.
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.
**/*.less
files and rebuild bundle.css
in local development.
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.
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
-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./node_modules/.bin/browserify -h
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.
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.
npm run minify-js
).
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.
**/*.less
or
./styles/**/*.css
files and runs npm run build-styles-dev
on each change.
npm run build-styles-dev
)Full command:
npm run build-less && npm run postcss && echo 'Styles built!'
npm run build-less
builds bundle.css
npm run build-styles
)Full command:
npm run build-less && npm run postcss && npm run minify-css
npm run build-less
builds bundle.css
npm run minify-css
minifies bundle.css using clean-css.
As much as I like npm scripts and browserify, here are some downsides in the setup.
npm install
autoformats the package.json again.
This problem can be avoided by running projects inside Docker or Vagrant. This StackOverflow discussion helps to understand why to use either of them.