The intention of this skeleton is to give a base platform for you to build your project on top of. All build tools are supplied through Node and use Gulp as a task runner. It is a collection of build tools, configuration files, folder structures and more. Below are some of the features provided:
- Compile and prefix style sheets from SASS.
- Bundle and uglify JavaScript source files into payloads.
- Lint source files to ensure standards and conformance.
- Perform testing via a test runner and test suite.
- Watch source files and trigger compilation as required.
- Optimize image assets of various formats.
- Convenience methods for building front-end style sheets and scripts.
There are many options available in how you use this repository to best suit your project.
You can use this repo as the basis of your own by re-pointing the origin to your own repo URL (as long as it's freshly-made and blank). Use the code below, replacing the path and branch name as necessary:
git remote rm origin;
git remote add origin [email protected];
git push origin master
You can also copy the files and folders of this repository into your own,
excluding the .git
folder so it doesn't overwrite your own. Be aware that this
will not preserve any git history of this repo.
The entire toolchain is node based so ensure you are using a stable version of
node such as 4.x.x
or 5.x.x
. Also ensure your version of NPM is at least
2.6.x
. Once you have met these requirements, you're ready to start the overall
tooling installation via the Makefile
method below:
make setup;
This will ensure the tooling dependencies are installed and that the build files are compiled and ready for usage within the browser.
There are a multitude of settings files included in the root of the repository.
.editorconfig
is a configuration file for
EditorConfig; a plugin / package that can be
installed in most popular editors. It enforces all team members to use the same
formatting settings such as spaces over tabs, line endings and so on.
.gitignore
offers a collection of common files and folders that should be
removed from source control, as well as some custom files generated by the
tooling of this skeleton.
.jshintignore
and .jshintrc
are used in conjunction with the linting tool
and can be used to customise the standards and rules which the JavaScript source
code must adhere to.
.jscsrc
is used with the style checking tool JSCS to
ensure that JS source files adhere to agreed coding conventions and are styled
in a consistent manner.
karma.conf.js
houses configuration for
Karma. It can also contain settings for Mocha,
Chai and Sinon.
run/config.js
is a global file included into each of the build tool tasks and
acts as a central place for task configuration.
Both style sheets and scripts follow the same structure. Library files are
placed in libs
. These library files do not have to be minifed and in best
practice probably shouldn't be. This is because during development, errors
within them are easier to debug, and also that the build process will be
minifying them anyway.
All source files are placed within src
and are split into modular files to aid
in decoupling and organisation. Build files that are the end result of
compilation are placed wherever the destPath
of global settings points to,
then nested inside css
or js
folders respectively.
JavaScript test files are places within js/tests
and should have the suffix
.spec.js
so they're picked up by the test runner.
Images are placed within an img
folder and should be maintained by grouping
related imagery (features, sections etc..) into sub-folders. They are copied
over to destPath
during the build
task.
Fonts reside within fonts
and should be grouped into individual folders per
font (which house all of that fonts different file formats). They are copied
over to destPath
during the build
task.
Build tool methods are stored within run
to encapsulate them away from project
source files and are split into separate folders per task. Each folder houses an
index.js
which contains the gulp task, but some will also have additional
configuration files.
Remember that everything here is configurable and easily changed; your project will have specific requirements and you should be adapting this structure to suit your needs!
As previously stated, test specifications should be placed into js/tests/
with
a suffix of .spec.js
. This ensures they will be automatically picked up by
Karma whenever it is run. The test specs themselves are piped through Webpack so
be sure to write the spec file syntactically as you would any other JavaScript
module in your project.
The testing stack is Mocha, Chai and Sinon, with Karma as the test runner. This
gives you a full toolset of test frameworks, assertion libraries, spies and
more. Each component of the testing stack is already loaded into the scope of
the test spec so you can just their global/top-level functions automagically
(i.e. assert
, expect
).
An example test spec is shown below, which loads in a contrived model and runs some tests.
'use strict';
// Loading dependencies.
import FeatureModel from '../src/models/FeatureModel';
describe('The Feature model', function() {
beforeEach(function() {
this.testModel = new FeatureModel();
});
afterEach(function() {
this.testModel = null;
});
it('should have defaults', function() {
expect(this.testModel.to.have.ownProperty('defaults');
});
});
Because projects frequently have multiple bundled payloads of styles and scripts
(often for different sections of a web application), the skeleton tasks for
scripts
and styles
have been designed to cycle through an array of bundles
and build each bundle independently.
If you want to compile CSS or JS you will need to define the relevant bundles.
You can do so within global.js
where there is a taskConfiguration
object
with sub-objects for styles
and scripts
. Further instructions can be found
there also.
Each of the tasks have documentation at the top of their source files and list any potential command-line arguments they can take. Below is a short description of each available task.
Convenience method that will ensure style sheets and javascript are compiled.
After this, all assets (style sheets, images, html, fonts and scripts) are
copied over to the destPath
.
An alias for build
.
A watch method that will look for changes to source files, then re-trigger compilation.
Takes site image assets and optimizes them.
Analyzes JavaScript source files to ensure their coding style adheres to a particular set of conventions.
Examines JavaScript source files for errors and code that doesn't conform to the specified standards.
Hosts the dist
folder via a node webserver.
Compiles source files into minified, uglified payloads.
Compiles SASS into CSS and autoprefixes where applicable.
Runs the test runner and any tests within the front-end tests folder. Also outputs JUnit XML for Jenkins.