A generator to scaffold out the front end boilerplate using BoilerplateV. BoilerplateV itself is an extensive HTML5 framework for building robust web sites utilising Pug, SCSS/PostCSS with Gulp. The boilerplate is based on Yeogurt Generator. The differences are:
Notes:
- gulp-sass though using node-sass options, can't make a sourcemap without gulp-sourcemaps
- for browsersync, because using node-gyp, see INSTALLATION part on https://github.com/nodejs/node-gyp
P.S On my home machine (Win10), it works fine without installing the requirements- To install latest and save to dev a module => yarn add @latest --dev
This generator utilizes Yeoman and Gulp to scaffold out projects, automate tasks, and manage front-end dependencies respectively. If this is your first time here, it is recommended you read about these tools before proceeding.
There are a few dependencies that this project relies on:
NOTE: For OSX users You may have some issues compiling code during installation of packages. Please install Xcode from App Store first. After Xcode is installed, open Xcode and go to Preferences -> Download -> Command Line Tools -> Install to install command line tools.
NOTE: For Windows users You may have some issues compiling BrowserSync during installation of packages. Please go to http://www.browsersync.io/docs/#windows-users for more information on how to get all the needed dependencies.
Check to see if you already have Node installed. Do this by bringing up a terminal/command prompt and type node -v
. If the response shows a version at or above v8.x
, you are all set and can proceed to installing Yeoman, Gulp, and Bower. If you see an error and/or your version is too low, navigate to the Node.js website and install Node from there.
Once you have Node installed, make sure you have these tools by opening up a terminal/command prompt and entering following commands:
Command | Response |
---|---|
yo --version |
at or above v1.2.1
|
gulp -v |
gulp-cli at or above v0.3.9
|
If you get any errors and/or you're version(s) are too low, you should run npm install -g yo gulp
.
This will install both tools and update them to their latest versions.
Now that you have all the needed dependencies, you can install this generator with the following command: npm install -g generator-boilerplatev
That completes installation! So at this point you should have all the needed tools to start working BoilerplateV.
When starting a new project, you will want to: open up a terminal/command prompt, make a new directory, and navigate into it.
mkdir my-new-project && cd $_
then, run the BoilerplateV generator.
yo boilerplatev
Follow all the prompts and choose what suits you most for the project you would like to create. When you finish with all of the prompts, your project scaffold will be created and all dependencies will be installed.
NOTE: If you choose to
skip installation
option, no dependencies will have been installed and your gulp tasks will NOT work. You will need to runyarn
in your project's root directory in order to get started running automated tasks
Once everything is installed, you will see a project structure like below:
├── gulp/ # Folder for gulp tasks
├── www/ # Folder for production www output
├── tmp/ # Folder for temporary development output
├── src
| ├── _css # Global css, mixins, variables, etc
| | └── main.scss # Main stylesheet (import everything to this file)
| ├── _data # JSON files that add data to templates
| ├── _fonts # Fonts (including icon font)
| ├── _icons # Icons (svg files) that will be generated as the icon font (default: g-icons.woff,svg,...etc)
| ├── _img # Images
| ├── _js # Global js, base classes, etc
| | └── main.js # Main bootstrap file
| ├── _layouts # Layout structure for app
| | └── global.pug
| ├── _mixins # Pug mixins
| ├── _modules # Reusable modules (curretly not implemented)
| | └── link
| | ├── __tests__
| | | └── link.spec.js
| | ├── link.pug
| | ├── link.js
| | └── link.scss
| ├── _partials # Reusable jade partials
| ├── index.pug # Homepage template
| ├── favicon.ico
| └── robots.txt
├── gulpfile.babel.js # Gulp task configuration
└── package.json # Dependencies and site/folder configuration
Congratulations! You should now have successfully created a BoilerplateV project and are ready to start building out your site/app.
Now you can run the following gulp tasks:
gulp
for testing and building a development version of your site.gulp --production
same as gulp
but builds a production version of your site.You can learn more about what tasks are available in the gulp tasks section.
In the package.json
file, within the root of the generated project, you have the ability to configure some project settings:
Setting | Description |
---|---|
host | Host URL of the development server (browserSync) |
port | Port of the development server (browserSync) |
baseUrl | Root directory of your site |
Setting | Description |
---|---|
source | Source folder for all development files) |
destination | Build folder where production version of site is generated |
temporary | Temporary folder where development server files are generated |
Folders relative to the source
configured directory
Setting | Description |
---|---|
data | Data folder where JSON/YAML files are loaded into templates |
scripts | Scripts folder where all .js files are located (main.js must be in root of this folder) |
styles | Styles folder where all stylesheet files are located (main stylesheet must be in root of this folder) |
modules | Modules folder where all reusable code should live) |
layouts | Layouts folder where all layout templates should live) |
images | Images folder where all .png, jpeg, jpg, svg, gif files should live |
Files that should be searched for and created by build tasks.
File strings and Globs can be used to process desired file(s).
Ex: main**.js
will process all files that start with main
and end with .js
Setting | Description |
---|---|
js | Tells webpack what file(s) to bundle and generate at your desired build target |
css | Tells your stylesheet preprocessor (Sass) what file(s) to generate at your desired build target |
It will be generated using Pug (was Jade)
It will be generated using SCSS with the concept of BEM (Block Element Modifier) with ITCSS (Inverted Triangle CSS)
Default: Bootstrap. The most important files for Bootstrap in this boilerplate are _settings.bootstrap.scss and _generic.bootstrap.scss
(ref: https://speakerdeck.com/dafed/managing-css-projects-with-itcss)
Managing CSS at scale is hard; and a lot harder than it should be. ITCSS is a simple, effective, and as-yet unpublished methodology to help manage, maintain, and scale CSS projects of all sizes. In this talk we’ll take a sneak peek at what ITCSS is and how it works to tame and control UI code as it grows.
The structure:
ITCSS benefits:
(ref: http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/)
Important note: Just because something happens to live inside a block it doesn’t always mean is is actually a BEM element
I'm using gulp-iconfont to generate fonts. The SCSS file is generated from the src_icons\icons_template.scss, which results in 03_generic/_generic.icons.scss.
The icons scss follows the Font-Awesome standard, so use it like when you use Font-Awesome, but instead of using .fa, you need to use .g-icon.
Although the template is similar to FontAwesome, don't use it like .fa.fa-[icon-name], instead just use like .g-icon-[icon-name] e.g. .g-icon-facebook (don't need .icon.icon-facebook).
Notes "icon" as a class. Adblock Plus apparently has a CSS rule to hide icon-[social-icons] elements. This happens for other classes like .footer-[social] as well
I'm using postcss-sprites plugin to generate a sprite. All you need to do is to put all the images that you want to generate as a sprite in src/_img/sprite/ folder and it will be generated as sprite.png. If you want to use it, you can use the sprite mixin m-sprite(filename).
Important: Foundation mixins found here.
Notes: It hasn't had any setup the task to generate more than 1 sprite. Please see here for reference.
gulp --production=dev
Builds and copies out files through compilation of preprocessors (Pug, Sass, etc), Javascript, and optimization of images to the destionation folder (set in packages.json
under CUSTOM CONFIGURATION
). Run this to copy assets to Assets folder in DEVELOPMENT environment
gulp --production
Builds and copies out an optimized site through compilation of preprocessors (Pug, Sass, etc), minification of CSS and HTML, uglification of Javascript, and optimization of images. Run this to copy assets to Assets folder in PRODUCTION environment
gulp
Starts up a development server that watches files and automatically reloads them to the browser when a change is detected.
This is fixed by changing the outputStyle of the sass to default.
Sometimes, browsersync doesn't reload, even though there's no error
postcss-import 9.1.0 had an issue with webpack 2.3.3 (https://github.com/webpack/webpack/issues/2411#issuecomment-247313388)
gulp/copy.js has copy_otherWWW which is configured in package.json
This will allow the users to copy the tmp directory to single or multiple other directories (i.e sites directories).
To run this task, type gulp copy_otherWWW
. But before making and copying js/css to multiple directories/sites, make sure you check the other two tips below. This will prevent duplication that gives you a headache and hard to manage codes.
CSS-wise, it's BEST to use ONE main.css for all of the sites and using theme for specific site. For example, siteA has a theme class theme--siteA, while siteB has theme--siteB class in the body so that the users can just those classes
JS-wise, it's BEST to use ONE main.js for all of the sites and using require to import the specific-site script into the main.js asynchronously. For example, if you look on _src/js, there's a folder called partials. Inside it, we can have files / folders depend how you want to structure it, and you can use require as per example to include them asyncly in main.js. If the codes needed all the time, just use import.