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.
If you're unfamiliar with the skeleton and want to get a quick "Hello World!" style project running with HTML, CSS and JS compilation then give our "Getting Started: Your First Application" guide a read.
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 git@path-to-your-own-repo.git;
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.
.babelrc is a configuration file used by gulp when consuming skeleton gulp
tasks. It is loaded automatically and isn't referenced anywhere in our codebase.
.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.
.eslintrc.json is used in conjuntion with the linting tool
ESLint and can be used to customise the rules which the
projets JavaScript source code must adhere to.
.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.
.npmrc can be used to set project specific configuration options for NPM.
karma.conf.js houses configuration for
Karma. It can also contain settings for Mocha,
Chai and Sinon.
web-manifest.json brings "Add to homescreen" functionality by allowing control
over settings such as theme colour, orientation, homescreen name and icon.
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 placed within js/tests and should have the suffix
.spec.js so they're picked up by the test wrapper file and 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!
Test specifications should be placed into js/tests/ with a suffix of
.spec.js. These files are then required into an overall test wrapper file
(run/tasks/test/wrapper.js) from which webpack creates one single test bundle.
This bundle is then used by Karma and any tests within are then processed. The
test specs themselves are piped through Webpack so be sure to write the contents
of the file syntactically as you would any other JavaScript file in the 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, web manifest 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. Hosts the dist folder via Webpack BrowserSync.
Takes site image assets and optimizes them.
Examines JavaScript source files for errors and code that doesn't conform to the specified standards.
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.