We at Me & Company are using this boilerplate project to set up our web projects. It unifies the structure of each project and simplifies the start of development.
Essentially, it provides the folder structure and some basic files for SASS and JavaScript. It has a builder included with various tasks, which add value to each project and improve the quality without any major effort. We implemented some features, at this stage especially for the work with SASS. It is adaptable for other frameworks, but can also be used as an independent HTML framework.
- Download or clone into your project folder
- Run
npm install - As macOS user you need some extra steps for the images build process to work: Install Homebrew, then install libpng library with
brew install libpng - Run
gulp devand you are ready to go
There is a basic index.html file, where you can import template snippets via Gulp File Include e.g.:
<html>
@@include('./src/html/snippets/header.html');
...
</html>
With gulp include the html files get build and gulp html minifies them into the dist folder.
We have variables for most attributes in CSS, which are individual for each project and design related.
- define basic variables, like maximum page size, values for spacing rhythm
- define breakpoints
- define color variables, font-size variables, grid options, spacing variables
- see settings
There are several mixins and functions to simplify and unify common used declarations like font-sizes, colors, breakpoints and spacing.
- responsive font-size:
@include font-size(base) - fixed font-size:
@include font-size(base, sm, false) - use defined colors:
color: color(base) - device-based breakpoints:
@include breakpoint(md) - content-based breakpoints:
@include breakpoint(920px) - use defined spacings:
padding-top: spacing(m), for text-spacing:padding-bottom: text-spacing(l)
We implemented a sass generated grid. You are able to choose your preferred grid type (flex, float, inlineblock, CSS Grids coming soon), the amount of columns and the spacing between columns. The generated grid classes are mostly named like bootstrap, e.g.:
col-6,col-lg-6,col-md-6,col-sm-6,col-xs-6col-offset-6,col-lg-offset-6,col-md-offset-6,col-sm-offset-6,col-xs-offset-6
We are using a customized approach of Atomic Design. We decided to call molecules 'elements' and organisms 'modules'. Semantically they are pretty much the same.
Have a look at our template file for a suggested structure of attribute declarations and examples of usage.
Instead of creating a variation of an element or atom class for unique styling cases we are using helper classes.
- spacing:
.mt-1,.mb-1,.n-mt-1,.mt-md-1,.pt-1,... - font styling:
.font-lg-base,.font-bold,.text-uppercase,... - see helpers for more
To improve code quality and consistency we follow the Airbnb Javascript Style Guide. We use ESLint with the Airbnb config to comply with the style guide (ESLint config). To enable linting, check the preferences of your editor.
Our basic approach is to get as close as possible to Object Oriented Programming with JavaScript. For each module, create a class which implements the needed functionality. The Class Template defines a basic structure. The class constructor expects a Node Object as element. Optionally, further parameters can be provided.
This is the main script from where all functions should be called and all classes should be created. Use the factory functions to create instances of your classes. See main.js how to use them.
- The graceProduce function produces many instance of the class. For each Node with the given selector, an instance of the class is created. So each Node has its own class instance.
- The graceCreate function creates one instance of the class. The element is an Array of each Node with the given selector.
- You should add global event listeners inside the events.js file. Global events are not related to a module, like sending a Google Analytics event triggered by every button on the page.
- If you are writing global functions, the folder functions is the right place.
- If you need to include 3rd party libraries, add them to the libraries folder, and Gulp bundles them into a libs.js file.
- singles are processed as they are and are stored to the dist/js folder
- libs get build into a libs.js, with the scripts inside the first folder being added at first
- all other scripts get build into the main.js
- support of EcmaScript6 via Babel Polyfill
- additional browser support with the main.legacy.js
We are using inline SVG-Icons. The build process gulp images optimizes the SVGs using SVGO, builds them into a PHP file and as .svg-files to the image folder. From there you can either import them by using the PHP variables or using the built-in Gulp File Include module.
-
inline import into HTML template via
@@include(dist/img/icons/icon-atom.svg) -
inline import for PHP e.g.:
<?php require 'icons.php'; ?> <span class="icon"><?php echo $icon_atom; ?></span>
gulp dev - used in development environment
gulp build - used for production environment
- images optimized by mozjpeg, pngquant
- BrowserSync
- minified JS, CSS and HTML
- last 4 versions, not ie <= 10, not Edge <= 13, Safari >= 8
- see browserl.ist fore more information
- implement JS Features
- add JS and SASS Linting
- integrate automated test setup
We'd like to hear your opinion, any comments or suggestions to make it even better.
Built with <3 by Me & Company