Please note: While you're welcome to use this starter kit for your own projects, it comes as-is and we don't specifically offer support for it because it's an internal tool for our use. If you have any questions, please feel free to ask, we'll do our best to help but we can't guarantee a speedy response or solution :)
Your local dev environment probably already has this stuff installed anyway but it might be worth checking if everything is there.
- Ruby
- Sass
- Node.js
- Grunt
- Imagemagick
We're currently using Grunt for our task management and there are some basic tasks set up in the Gruntfile.js config but you're welcome to add to them on a per project basis if you need other jobs doing beyond what's there.
Install the Grunt tasks we use so in command line/terminal cd to the project directory, and run npm install
It might also be prudent once everything is installed, to run grunt devupdates if you've not used this starter kit for a while. This will check for any updates to devDepenedencies and dependencies and advise which versions are current.
Dev updates is currently set to just report what updates are available and not automatically update so if you do wish to update, edit the version numbers in the package.json file in the project root.
If you need to add new JS files to the project, simply drop them into /js/app/ and Grunt will minify and concatenate everything.
You don't need to reference them in the HTML, Grunt will run the task and compile them all into production.js which is referenced at the bottom of your HTML template above the </body> tag.
For the time being, files in /js/libs/ need referencing in HTML and are not processed in Grunt.
Any images located in /assets/images/ (jpg, png, gif) are automatically optimised and re-saved with the same name/paths when Grunt is run
Image optimisation will normally be handled by Umbraco / imagegen on the server but it's handy to run this command on any site assets that might not be uploaded and processed via the CMS.
All files in /assets/sass/ are automatically compiled and minified and then output to /assets/css/screen.css which is referenced in the HTML
Do not under any circumstances edit /assets/css/screen.css, any changes you make will be lost next time Sass is compiled.
If you need to add a new scss file for some reason, you can do so by creating a _yourfilename.scss file (the underscore is needed) and you can then reference that in /assets/sass/screen.scss and it'll compile next time Grunt runs.
Any file created in /assets/sass/ (including sub folders) is watched and compiled as long as you reference it in the screen.scss file.
You don't need to include browser specific prefixing for properties, they're automatically added when Grunt compiles the Sass so just add un-prefixed properties and if they're needed it's taken care of.
You can edit Gruntfile.js to specify how many browser versions you want to support and provide autoprefixes for. It's just set for last 2 browser versions by default.
There's a couple of simple tasks to save you running everything each time. They are:
grunt- Just compiles, autoprefixes and watches your Sass while doing local devgrunt build- Compiles your Sass, concatenates all your JS into a production file and builds Modernizrgrunt assets- Optimises image and script assets ready for releasegrunt devupdates- Only need to run at the start of a new project to check if dependencies need updating
The starter kit does not include any additional scripts but here are a few tools that have been useful in past projects:
When adding a new js script, just save it into the /assets/js/libs folder and it will be automatically minified and built into the production js file. It is best to include the uncompressed version in the libs folder so it's easy modify and debug if necessary.
Any 3rd party css files should be saved as .scss files and added to the /assets/sass/externals folder and referenced in /assets/sass/screen.scss. Be aware that you might need to tweak file paths or variables in some downloaded files.