GENESIS

This starter kit is an internal tool for use by the Offroadcode team and helps set a few base tasks and styles up as well as creating the start of a folder structure we use on our projects.

Getting started

Genesis uses Sass for CSS and Gulp 4 as a task runner, please ensure you have both these installed and running in your local environment before use.

Your local dev environment probably already has this stuff installed anyway but it might be worth checking if everything is there.

• Node.js
• Sass
• Gulp 4

For simpler projects this starter kit should be enough for compiling scss and non-react javascript files. The Gulp setup is based on the one found at The Codercoder Frontend Boilerplate. There is additional documentation there if you require.

Getting errors? It may be you have an older version of Gulp (3) installed on your build. You will need to update to Gulp 4. Read this

Project Setup

SCSS and JS folder structure

All Offroadcode projects have an /assets/ folder in the project root. This contains all Sass (CSS), Javascript and Image assets and if used, fonts too. Our structure is:

• Build
  • assets
    • img
    • js
    • scss
    • production (All files in here are generated and minified by Gulp)
      • css
      • js

Non react Javascript files

If you need to add new JS files to the project, simply drop them into assets/js - It's best to add the full production file so it's easy to work on and read.

Gulp will watch, minify and concatenate everything into the production/js folder and update the all.js file. You do not need to edit anything in the production folder. It's all generated by Gulp.

The /assets/production/js/all.js is what you should reference in your HTML template just above the closing </body> tag.

Sass compilation

All files in /assets/scss/ are watched, compiled and minified automatically then output to /assets/production/css/screen.css which is referenced in the HTML.

If you need to add a new scss file for any reason, you can do so by creating a _yourfilename.scss file (the underscore is needed) and you can then reference that in /assets/scss/screen.scss and it'll compile next time Gulp runs.

Any file created in /assets/scss/ (including sub folders) is watched and compiled as long as you reference it in the screen.scss file.

CSS Prefixing

You don't need to include browser specific prefixing for properties, they're automatically added when Gulp compiles the Sass so just add un-prefixed properties and if they're needed it's taken care of. You can specify the browsers you're targeting in the top of the Gulp file and it will generate the relevant prefixes.

Image Otimisation

For any image assets (jpg, gif, svg, png) that aren't managed by CMS, these go into the /assets/images/ folder and are automatically watched and optimised using gulp-imagemin and a production version is output to assets/production/images/ - It is the production version of the image you need to reference in your code.

Gulp Tasks

For simplicity, there's a single Gulp task.

If you're using a Windows machine you can simply double-click the StartDev.bat file in the root of the site and it'll launch the Gulp task for you. If you're not, just run it as normal in a command line and use:

• gulp - Watch, compile, concatenate for JS and Sass and cache bust

Some more complicated projects may also make use of Webpack for compiling react but this will be documented on a project by project basis.