A simple and well structured boilerplate project based on AngularJS and Zurb's Foundation
- Responsive layout
- Mobile ready
- SASS support
- Grunt watch, build and local server tasks
- Live reload
- Organised folder structure
- Minified CSS, HTML and JS build files
- Font Awesome icons
- Support for Unit & E2E Testing
- Unit Test reporting
- ESLint to detect incorrect coding patterns.
- Jasmine testing framework
- Karma test runner
- Protractor end-to-end test framework
- Install Git and NodeJS
- Clone this project:
git clone https://github.com/cmacdonnacha/angularjs-foundation-boilerplate.git
- Install Grunt and Bower globally:
npm install -g grunt-cli bower
- Install Karma globally:
npm install -g karma
- Install PhantomJS headless browser globally:
npm install -g phantomjs
- Install Protractor globally:
npm install -g protractor
- Install Selenium web driver binaries by running:
webdriver-manager update(installs the Chrome driver by default)
- Install a local Http server:
npm install -g serve(for local web testing)
NOTE: If you have previous versions of any of the above packages, it's recommended that you update them:
npm update -g
Install Project Dependencies
npm install- this installs both the required NodeJS modules and the bower component libraries.
IMPORTANT: If you run into any issues please have a look at the "Troubleshooting" section at the bottom of this page.
grunt watch: Creates a development build folder called 'public' and serves it on:
grunt test: Runs code checks, unit tests and E2E tests
grunt run:unit: Runs unit tests only
grunt run:e2e: Runs E2E tests only
grunt production: Creates a production build in a folder called 'production'
grunt run:production: Serves the 'production' build on:
http://localhost:9000/if it exists.
grunt eslint: Runs an ESLint code check
Running unit test reports
grunt reports: will create and serve the 'reports' folder
- Navigate to
This project follows a "Folders-by-Feature" structure. From the folder structure below you can see that there are 6 separate components, a folder for each component. Each component is treated as a mini Angular app. This structure allows us developers to easily locate code and identify what each file represents at a glance. By retaining this structure the project is much more manageable as it grows.
appfolder contains the individual components:
about: Contains the about page related files.
common: Contains all common services, directives etc. used across the entire app.
home: Contains the home page related files.
layout: Acts as a container for other layout components (about, home, topbar etc.)
sample: A template component that can be duplicated whenever you want to create your own component (Copy and paste).
topbar: Contains the topbar related files.
Each component has its own sub-folder containing files associated with that component:
- e2e tests
- unit tests
Note: Not every component will contain all of these sub-folders, just add them as you need them.
assetsfolder contains the globally used fonts and images.
stylesfolder contains all of the global sass files needed to style the app. Let's have a closer look at each file:
_font-awesome.scss: Contains all of the font awesome icons taken from the
vendor/font-awesomefolder. Check this out to see all available icons.
_mixins.scss: This is where you can put your very own Sass Mixins that can be used globally throughout the app. This should only contain Mixins.
_settings.scss: Allows you to override the default Foundation styles with your own. This is detailed in a section below.
_shared.scss: This is where you can put your very own Sass that can be used globally throughout the app. Typically it's where you would add globally used Sass classes which would then use mixins from the
main.scss: Brings everything together. Contains all of the Sass file imports. It's what tells the app where to grab the styles from.
Adding a new component
As you can see in this boilerpate project we have 6 sample components:
topbar. Check out the wiki to see how you can go about adding your very own component.
Making Foundation Styles your own
Foundation is great because it comes with basic styling, leaving it up to you to give it your very own touch. You can do this by changing the
_settings.scss file inside the
Simply uncomment any of the sections in the
_settings.scss file and you will override the default Foundation styling. Don't like the color of the topbar? No problem, change to a nice bright pink instead. Find out more here.
Even crème de menthe projects have their issues. Here are some problems you may face along with some suggestions on how to resolve them:
1. Issue: I'm getting the following error when running
npm install: "Error: EPERM or operation not permitted or permission denied"
This error means that NPM was not able to install one of the node modules to the file system. There are three major reasons why this could happen:
- You don't have write access to the installation directory.
- The permissions in the NPM cache got messed up.
- You have over-zealous anti-virus software installed, and it's blocking file system writes.
npm cache clean.
2. Issue: I'm getting the following error when running
npm install: "Error: Can't find Python executable 'python', you can set the PYTHON env variable."
Suggestion: This error can be ignored (it's a warning really) as the node modules will install successfully anyway. The reason this error appears is because
some node modules have dependencies on a clunky build tool called
node-gyp that compiles C++ extensions for NodeJS, and it requires python. Long story short,
if you don't have Python installed on your machine you will see these errors but it's nothing to worry about.
3. Issue: I'm getting an error when running the
grunt production task.
Suggestion: Make sure you have administrator permissions to delete folders from the directory. If you're still seeing the issue then manually delete the
production folder and run
grunt production again.
4. Issue: I'm getting the following error when running the
grunt test task: "No selenium server jar found at the specified location"
Suggestion: Run the following command and try again:
5. Issue: I'm still getting an error when running the
grunt test task.
Suggestion: Make sure you have Java installed. Close and re-launch the command line and try again.
6. Issue: I'm getting the following error "Error: Cannot find module 'stylus'"
Suggestion: Run the following command:
npm install stylus -g
7. Issue: I'm getting the following error when running the
grunt watch task: "Error: 'libsass' bindings" not found. Try reinstalling 'node-sass'
Suggestion: Run the following command:
npm install grunt-sass
8. Issue: Bower hangs and cannot fetch the libraries when running
Set Git global options to fetch components over 'https' instead of 'git' by running the following command:
git config --global url."https://".insteadOf git://
9. Issue: None of the above solutions have helped
- Stop the
This project has been tested with the following tools: * NodeJs: 4.2.1 * Npm: 2.14.7
If you are running into issues while installing node packages then ensure you have the versions above installed.
Believe it or not, angularjs-foundation-boilerplate is not perfect. If you want to improve it somehow then by all means go ahead and create a pull request :-)
- 30/10/2015 - Initial release