/Starter-Kit

A Front End development Gulp.js based workflow. 🚀

Primary LanguageJavaScript

Nicholas Adamou's Starter Kit Build Status

Project Preview

license Say Thanks

Starter Kit is an opinionated build automation for front-end web development based on Gulp, Node, NPM, Bower, Babel, SASS, and Pug.

Note: Starter Kit is simply a guideline and it doesn't solve everything. It is up to you to modify whatever necessary to achieve your project goals.

  1. About
  2. Technologies
  3. Requirements
  4. Install
  5. Set Up/Workflow
  6. How to Use
  7. Build
    1. Environments
      1. Development
      2. Production
  8. Browsersync
    1. Local URLs
    2. Options
  9. Assets
    1. Data
    2. Docs
    3. Fonts
    4. Images
    5. Media
    6. Miscellaneous
    7. Vendors
  10. JS
  11. SASS
    1. BEM Structure
  12. Pug
    1. Pug Structure
    2. Environment Variables
  13. Configuration
  14. Inspiration
  15. License

About

Starter Kit is a simple, responsive boilerplate to kickstart any responsive project. It is built on Scotch\box, to provide a simplistic start to any web development project. This kit is built to be used in conjunction with Gulp and Vagrant to automate different tasks as a web developer.

Technologies

  • Vagrant - Development Environments Made Easy
  • Scotch\box - The Perfect / Easiest Local Dev Environment
  • NodeJS - JavaScript runtime built on Chrome's V8 JavaScript engine.
  • Gulp - Automate and enhance your workflow.
  • Yarn - Fast, Reliable, and secure dependency management.
  • Surge - Simple, single-command web publishing. Publish HTML, CSS, and JS for free, without leaving the command line.
  • GitHub Pages - Websites for you and your projects. Hosted directly from your GitHub repository. Just edit, push, and your changes are live.
  • PostCSS - A tool for transforming CSS with JavaScript.
  • Pug - Simple language for writing HTML templates.
  • SASS - CSS with superpowers.
  • Rucksack - A little bag of CSS superpowers.
  • Skeleton - A simple, responsive boilerplate to kickstart any responsive project.
  • Babel - Babel is a JavaScript compiler; use next generation JavaScript, today.

Requirements

npm install -g yarn bower gulp localtunnel

To install Virtualbox and Vagrant:

  1. if on Windows, use Chocolatey: 
    cinst -y virtualbox virtualbox.extensionpack vagrant vagrant-manager
  2. if on MacOS, use homebrew: 
    brew cask install virtualbox virtualbox-extension-pack vagrant vagrant-manager

Note: (Windows Users) In order for localtunnel to work properly, please configure Windows Firewall to allow port 3000, 3001 to allow in-bound and out-bound connections (port 3000, 3001 is Browsersync's default port allocation). For Security reasons, only allow in-bound and out-bound connections on port 3000, 3001 on your home network.

Gulp is the process that will run all the task of compilation, watchers, and others. Bower will get the dependencies for the client-side like jQuery. Yarn is an alternative to npm for dependency managment. It is much more reliable when compared to npm, so we will use yarn for dependency management instead of npm. Virtualbox and Vagrant are used for the spin-up development environment. Those are the only requirements to run this project.

Install

In order to start using this project, you need to clone/download it to your machine.

Set Up/Workflow

Now after you have cloned/downloaded the kit to a desirable location, you will need to navigate to the Starter Kit folder using terminal and execute the following commands to gather all the dependencies, bring up the vagrant box and open Gulp Help.

vagrant up
vagrant ssh
cd /var/www
gem install travis
yarn install-dependencies
gulp help

Note: (Windows Users) If after running vagrant ssh you are presented with the below error, please follow How to use vagrant on windows guide for connecting to the VM via SSH.

The `ssh` executable found in the PATH is a PuTTY Link SSH client.
Vagrant is only compatible with OpenSSH SSH clients. Please install
an OpenSSH SSH client or manually SSH in using your existing client
using the information below.

Host: 127.0.0.1
Port: 2222
Username: vagrant
Private key: C:/dev/Starter-Kit/.vagrant/machines/default/virtualbox/private_key

After the processes finish, you can now proceed into the How to Use section to understand each option the kit presents to you.

How to Use

To start using the kit, open the project on the code editor of your choice and start coding.

To compile and live-preview all of your changes, you have some commands that will help you. Here is a list of commands you should know.

Every command has to be executed on the root directory of the project using the gulp command like gulp clean or gulp build.

  • start: Compile and watch for changes (For dev.)
  • clean: Removes all the compiled files in public/
  • ftp: Deploy to an FTP/SFTP server
  • surge: Deploy to a Surge.sh domain
  • ghpages: Deploy to Github-Pages
  • js: Compile the JavaScript files
  • pug: Compile the Pug templates
  • sass: Compile the SASS styles
  • assets: copy static files from src/assets to public/assets
  • images: copy and optomize image files from src/assets/images to public/assets/images
  • data: copy data files from src/assets/data to public/assets/data
  • docs: copy (.pdf) files from src/assets/docs to public/assets/docs
  • fonts: copy font files from src/assets/fonts to public/assets/fonts
  • media: copy media files from src/assets/media to public/assets/media
  • misc: copy misc files from src/assets/misc to ./public
  • build: build the project
  • pagespeed: Run Google PageSpeed Insights
  • help: Print a list of available Gulp tasks
  • browserSync: Start the browser-sync server

If you are in the development process, the gulp start command is the best option for you. Go to the project folder in the console and execute gulp start, it will compile the project and start server that will refresh every time you change something in the code. The command will be waiting for changes and will tell you how to access the project from local and public url. Every browser that points to that url will be auto refreshed. As an extra feature for testing purpose any interaction on one browser will be reflected on any others. Try it on a phone, tablet, and pc at the same time.

Build

Generate a fresh build of your project. Task will run several individual tasks on files within ./src and then output them to ./public.

Run: gulp build

Environments

You can specify which environment you want to build in config.js. By default, config.environment is set to development.

Development

environment: development

Production

environment: production

Browsersync

Start a local dev server. Additionally, gulp will watch for any changes to files and reload browser while server is running.

Run: gulp browsersync

Local URLs

Options

You can modify port, proxy, tunnel, and many other settings in config.js. For more information about BrowserSync go to http://www.browsersync.io/.

Assets

Run several individual tasks to copy static files from src/assets to public/assets.

Run: gulp assets

Data

Copy data files to public/assets/data.

Run: gulp data

Docs

Copy (.pdf) files to public/assets/docs.

Run: gulp data

Fonts

Copy font files to public/assets/fonts.

Run: gulp fonts

Images

Copy images to public/assets/images. As a personal preference Starter Kit uses imagemin and imagemin-pngquant to automate image optimization. However, it is strongly recommended to use services like TinyPNG and TinyJPG to optimize images manually.

Run: gulp images

Media

Copy media files to public/assets/media.

Run: gulp media

Miscellaneous

Copy miscellaneous files, such as .htaccess or robots.txt, to the root of ./public.

Vendors

Bundle vendor files to public/vendors. You can install new client-side vendors using Bower or yarn, then reference appropriate files in ./src/vendors/bundle.js and in src/sass/settings/_vendors.scss. Follow the guidelines for gulp-include to properly add the plugins to your project.

Starter Kit comes with the following tools by default.

  1. jQuery
  2. animate-css
  3. brand-colors
  4. colors
  5. normalize-css
  6. skeleton

Run: gulp vendors

js

Run a series of sub-tasks to generate final JavaScript files. See gulp/tasks/build/js.js for reference.

Note: Each file on the root of src/js will be compiled to its own file in public/assets/js. Each file can have own includes, just like Sass with @import functionality. See src/js/index.js as an example.

Run: gulp js

SASS

Run a series of sub-tasks to generate final CSS files. See gulp/tasks/build/sass.js for reference.

Note: Each file on the root of src/sass will be compiled to its own file in public/assets/css.

Run: gulp sass

BEM Structure

Starter Kit follows a strict naming convention using BEM methodology.

Directory structure and selector names are divided into namespaces based on More Transparent UI Code with Namespaces article by Harry Roberts.

Pug

Run a series of sub-tasks to generate final HTML files. See gulp/tasks/build/pug.js for reference.

Run: gulp pug

Pug Structure

Starter Kit follows an opinionated directory structure. To learn more about Pug go to https://pugjs.org/api/getting-started.html/.

Environment Variables

Every Pug file has access to global env variable. You can use it to conditionally load unminified/minified assets. See src/views/includes/partials/head.pug as an example.

Configuration

This project has some nice configuration options to meet all your needs. To configure, you will need to edit the gulp/config.js file and change any value you need. Every aspect of this configuration is described in the file so that you can understand their functions.

Inspiration

License

© 2018 Nicholas Adamou.

It is free software, and may be redistributed under the terms specified in the LICENSE file.