frckl-base — a frontend starter kit

Introduction

You have heard of all the fancy new frontend-tools and want to use them, but don't have the time or nerve to set everything up? That's what this is for: everything you need to get started with 'modern' frontend development with ES2015, rollup, sass and linters to keep your code sane and consistent. This is a highly opinionated, but easily extensible collection of tools for a nice workflow to create modern websites.

Requirements

Make sure that you have a current version of node and npm installed on your system. Node is required for the whole build process and gulp.

• Install node — preferably with nvm or download an installer package
• Install npm — if npm is not installed via node (which it should be), run curl -L https://npmjs.org/install.sh | sh in your terminal or have a look here

After having installed node and npm, open a fresh terminal and check if everything is installed correctly by typing: node -v && npm -v, this should result in sth. like:

v6.4.0
3.10.6

This package is tested with current node LTS (4.x) and the latest stable (6.x) and should work without any issues.

Installation

Clone this repository (or download the .zip-File and extract everything), open up a terminal and type: npm install.

This will take a while, npm will install gulp (our build system of choice) globally and all dependencies for this starter kit. If something fails, try removing the node_modules-folder and run npm install again. On some systems you have to this with sudo, so try sudo npm install if it still fails.

For the lazy people:

git clone https://github.com/webgefrickel/frckl-base.git ./myproject
cd myproject
npm i

IMPORTANT NOTE

Create a new virtual host pointing to the public-folder of this project, and start up your LAMP or nginx-Stack. I often use this starter kit with CMSs or PHP-Frameworks of various kinds, so creating a virtual host is the correct way to use this starter-package.

This project is intended to be used for new websites/projects. I do not recommend updating old frckl-base instances to a current version.

Configuration

After installing frckl-base, you should edit the file config.js and configure it to your liking, normally you just have to change two to three options:

• proxy: this should match your vhost on your local machine, and the vhost should point to the public-folder of this project
• scheme: if you want to use https instead of http, change this value
• root: this is the folder where you should point your webserver to
• dest: this is where you want all compiled and minified CSS and JS-Files to go (defaults to ./public/assets, e.g. if you plan on using this with WordPress, the dest-variable could look like ./public/wp-content/themes/yourtheme/)

There are a lot of other options in config.js, just have look at them and read the comments and change everything to your liking. You can change all paths, browser-support for autoprefixer, deactivate linters etc. pp.

Usage

You now should be all set up, to use this thing, just type gulp or npm run in your terminal and start coding. The default task starts the watch-task on all your files and you can code away. It also initalizes the Browsersync proxy for fast and easy live-previews and remote debugging.

You should do all your work and save all files in the ./src/-folder and the subfolders contained therein — you will find some examples and helpers for Sass and JavaScript in the folders scss and js.

Your websites root-folder is the folder ./public/ — throw in any CMS, PHP or plain HTML here. There are some presets in there, feel free to delete them or use them as a starting point, especially have a look at ./public/index.php for how to use and include all generated CSS and JS files in your page and some SVG-usage examples.

All done? If you want to build a minified and production-ready version of your project, type gulp build or npm run build. This task checks for errors and creates minified versions of your CSS and JS, copies images etc.

For more documentation on tasks, conventions, building and other issues, please refer to the separate documention in the doc-folder, you will find a lot of information for the different aspects of this project:

Conventions | Workflow | Gulp & Tasks Overview | Sass | JavaScript | Images & Sprites | Linting

Troubleshooting

• Make sure you have up-to-date and working installations node and npm on your machine.
• Remove the node_modules-folder, run npm cache clean && npm install and try again...
• Try to install gulp globally as sudo: sudo npm install -g gulp

This is not thoroughly tested on Windows and any linuxes except for ubuntu/debian.

Browser Support

IE<=10 is explicitly not supported, and the default styles and JavaScript don't add any support or fallbacks for this browser. Regarding everything else: it's up to you. The default assumption is: support the last 2 versions of the most used browsers, and the current version of browsers with a smaller marketshare. Have a look at config.js for autoprefixer-browser-support.

Known Bugs

When adding new files (JavaScript, Sass or images/fonts) you maybe have to restart the default gulp-task gulp (type Ctrl+C ↑ ↲ in the terminal running gulp), so that the watcher recognizes the new files. This will hopefully be fixed with gulp4.

Collaboration

Feel free to open issues and send me pull requests.

Maintainers

Steffen Rademacker @webgefrickel

Future ideas

• Choose a testing framework for JavaScript (tape, ava)
• Choose a method for sass mixins/functions Sass-testing
• Choose a regression testing framework sth. in the likes of phantomcss/dalekjs (when it's done)

Thanks to

There are way to many people, that influenced me and everything in this repository. If you have the feeling that I should mention you - say so. I took heavy inspiration from those projects and the people behing it:

• HTML5 Boilerplate
• Init
• inuitcss
• Sass Guidelines

License

frckl-base is published under the MIT License