README.md

Documentation

Table of Contents

• Documentation
  • Table of Contents
  • Quickstart
  • Development
  • Building and Deploying
  • Structure
  • CSS
  • HTML
  • JavaScript
  • PNG Sprites
  • SVG Symbol Sprites
  • DATA
  • Command Line Commands
    • Initialization
    • Development
    • Cleaning
    • Building
    • Deploying
    • Zip
    • Generator
  • License

Quickstart

1. Install the node.js

2. Clone the project or download the file

   git clone [email protected]:zoxon/gulp-front.git --depth 1 my-project

3. Go to project folder and run

   npm run setup

4. Start dev server

   npm start

5. In browser open page with address http://localhost:3000/

Development

1. Run npm run cleanup. This command delete demo app.
2. Run npm start to see your app at http://localhost:3000/

Building and Deploying

1. Run npm run build, which will compile all the necessary files to the dest folder.
2. Upload the contents of the dest folder to your web server's root folder.

Structure

The source directory contains your entire application code, including CSS, JavaScript, HTML.

The rest of the folders and files only exist to make your life easier, and should not need to be touched.

Below you can find full details about significant files and folders.

gulp-front/                         # Project root
├── dest                            # Compiled files
├── docs                            # Documentation
├── gulp                            # Gulpfile tasks and config
├── source
│   ├── icons                       # SVG icons sprite files
│   ├── layouts                     # Pug layouts
│   ├── modules                     # Modules folder
│   ├── pages                       # Pages
│   ├── public                      # Static files copy to project root
│   ├── scripts
│   │   ├── core                    # JS Modules core
│   │   ├── helpers                 # JS various helpers
│   │   └── main.js                 # Main JavaScript file
│   ├── sprite                      # PNG Sprite files
│   └── styles
│       ├── core
│       │   ├── helpers             # System level helper classes
│       │   ├── mixins              # System mixins
│       │   ├── typography          # Typography styles
│       │   └── variables           # System variables
│       ├── _common.styl            # Different styles
│       ├── _variables.styl         # Variables
│       ├── main.styl               # Main styles
│       └── reset.styl              # Styles reset + typography
├── tmp                             # Temp folder
├── tools                           # Gulp-front tools
└── zip                             # Folder with buld zip archives

CSS

• Normalize.css
• Stylus
  • rupture - Simple media queries mixins for stylus - npm css files import with stylus include feature
• PostCSS
  • autoprefixer - Parse CSS and add vendor prefixes to rules by Can I Use
  • perfectionist - Beautify CSS files
  • postcss-sorting - Keep rules and at-rules content in order
  • postcss-reporter - Log PostCSS messages in the console

HTML

• Pug (ex Jade) - Robust, elegant, feature rich template engine
• PostHTML - Tool to transform HTML/XML with JS plugins
• gulp-prettify - js-beautify gulp wrapper

JavaScript

• Tools
  • Node.js - JavaScript runtime
  • Webpack 4 - module bundler
  • npm - package manager
  • Yarn - package manager
  • ECMAScript 6 and Babel
  • Service Worker Precache - service worker that precaches resources
• Libraries
  • FastClick - remove 300ms delay on mobile browsers
  • js-cookie - JavaScript API for handling cookies
  • Micromodal - accessible modal dialogs
  • Nano ID - unique string ID generator
  • scroll - animates an element’s scrollTop or scrollLeft position
  • lodash - utility library delivering modularity, performance & extras
  • Tooltip.js - dead simple tooltips, powered by popper.js
  • attrs - Object as DOM attributes.
  • Classnames - A simple javascript utility for conditionally joining classNames together
  • omit - Remove values from an object (or an array of objects) based on key, value or an evaluator function
  • ScrollReveal - Animate elements as they scroll into view
  • skrollr - Stand-alone parallax scrolling JavaScript library for mobile and desktop
  • slide-anim - Light weight, stand alone, jQuery like slideDown / slideUp
• Polyfills
  • svg4everybody - adds SVG External Content support to all browsers.
  • promise
  • raf - equestAnimationFrame polyfill
  • babel-polyfill
  • whatwg-fetch - Fetch API polyfill
  • element-closest - Element.closest and Element.matches polyfills

PNG Sprites

For converting a set of images into a spritesheet add your image to source/sprite folder. Spritesheet generates with the help of gulp.spritesmith Retina spritesheets/templates are supported too.

SVG Symbol Sprites

To convert a bunch of svg files to a single svg sprite add svg file to source/icons folder. Then you can use icon mixin call in your template.

Example:

1. You copy file icon-name.svg to source/icons folder.
2. In any pug template, import icon mixin include ../icon/icon
3. Use +icon(name="icon-name" title="Icon title") to render icon

Spritesheet generates with plugin gulp-svg-symbols

DATA

All data in modules stores in data/*.yaml files

YAML Ain't Markup Language

Command Line Commands

Initialization

npm install

Development

Starts the development server running on http://localhost:3000

npm start

Cleaning

Remove demo app.

npm run cleanup

Building

Build project.

npm run build

Deploying

Create build branch in your git repository and push compilled files.

npm run deploy

Zip

Build a project and pack content of dest folder in zip file

npm run zip

Generator

Create empty module by name in source/modules folder

By default generate only *.pug and *.styl files.

You can call npm run new (Add Module) with additional params like js and yml

npm run amo <module-name> [js || yml]

License

The MIT License (MIT)