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 | shin 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 installand 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:
License
frckl-base is published under the MIT License