A simple contact application built using the Front-end skeleton, backbone and express js. The app offers the ability to add, delete, edit, filter and view contacts.
To run the application simply run the following from the terminal in the project root directory.
node server/index.js
The application will then be served on the localhost:3000 server.
You can also use the utility nodemon to automatically restart the server if any changes in the source code have been made. Simply run the following in the terminal, if not installed already.
npm install -g nodemon
Then run nodemon server/index.js from the terminal.
The application uses Gulp as it's task runner. If any changes have been made to the source code run either:
gulp buildgulp watch- constantly watch for any changes, then automatically builds the app.
Contacteeeer consists of unit testing created in the js/test folder. To run the tests, type gulp test into the terminal.
The live version of Contacteeeer be found on Heroku here.
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 fe-setup;
This will ensure the tooling dependencies are installed and that the build files are compiled and ready for usage within the browser.
If you have docker installed you can build the skeleton's toolchain without installing node or any of the skeleton's dependencies on your local machine. This can be done simply with the following make command:
make docker cmd=build
The cmd variable can be any command in the makefile, for example watch or lint. The default command is build so running make docker is equivalent to above command.
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.