BoBrSASS is a modifiable boilerplate combining some of our common tools and practices:
- Gulp for fast builds
- Browserify for bundling CommonJS modules
- Sass & Compass stylesheets
- Runs in background (watching changes), supports live reload
- Supports source maps for both JavaScript and Sass
- Spaces instead of tabs
- Headless protractor acceptance tests
The latest version of BoBrSASS should work with recent versions of Ruby, Sass, Compass and Git. Please check the correct versions, maintained in our Travis configuration. If you insist on using an older version of dependencies, earlier versions of the boilerplate may work.
For system level deps, install Node.js 0.10 or later and Ruby 2.1 or later and Git. When using Git on Windows, remember to enable usage from command prompt.
Clone the project and trigger installation of the project dependencies by
> git clone https://github.com/SC5/gulp-bobrsass-boilerplate.git
> npm install --debug
> npm run deps
If deps fails on Ruby gem dependencies, try updating rubygems as follows:
> gem update --system
BoBrSASS uses Gulp internally, but you can use npm scripts to trigger them. Build, test etc. tasks utilise npm development dependencies, so one should set 'NODE_ENV' to something else than 'production' or install the npm dependencies with a '--debug' flag. All the development dependencies are moved into devDependencies to avoid slow installs of the actual released software.
> npm install --debug # to force development dependencies
> npm run build # to trigger bower install, build and tests
> npm run build -- --debug # to trigger bower install, debug build and tests
After this you should have a working, tested build in 'dist' directory.
To trigger debug build or other features, run the build with a combination of the following flags:
> npm run watch -- --debug # to disable optimisations, turn on debugging
> npm run watch -- --test # to turn on tests when building
> npm run watch -- --nolint # to disable linting
The above extra flags '-- [--]' syntax syntax only works for npm 2.0 or later. If you have an earlier version of dislike the syntax, trigger the same gulp tasks with your local Gulp installation:
> npm install -g gulp # to install Gulp CLI locally
> gulp install
> gulp build --debug
> gulp watch --debug --test --nolint
To update your package version, you eventually want to do one of the following:
> gulp bump --patch
> gulp bump --minor
> gulp bump --major
> gulp bump # defaults to minor
The boilerplate includes a minimal stub Express server in 'server/' directory. Its primary purpose is testing the frontend as part of the build, but nothing blocks you from expanding it into a full-blown server.
> npm start # to start the server through npm
> node server # to start the server
The server should respond your http requests on local port 8080.
The resulting web application (contents of dist) can be deployed to an Amazon S3 bucket. You'll need to have
1. an S3 bucket set up to AWS.
2. the bucket configured in package.json (config.bucket)
3. the region for the bucket can be configured in package.json (config.bucketRegion)
4. AWS credentials set up as required by aws-sdk (sample .aws/credentials file below)
[default]
aws_access_key_id=Access key from AWS console
aws_secret_access_key=Secret key from AWS console
To create the bucket, run:
> npm run createBucket
To deploy to S3, run:
> npm run build # To build the application (to dist/)
> npm run deploy # To deploy to Amazon S3
Boilerplate also comes with Docker support. To have a minimal Docker image and speed up the containerization, the whole app is built before the packaging, and only the Node.js production dependencies get packaged. To build and run the container, run:
> npm run build # to build the application in production mode
> docker build -t bobrsass . # to build the Docker image with name "docker"
> docker run -d -P bobrsass # to star the app
To access the service, check the dynamically allocated port (for example: 0.0.0.0:49164->8080/tcp) and use it in browser URL
> docker ps # --> http://localhost:49164/
Localhost works in Linux environment, but if you are using boot2docker, you need to use VM IP
instead. Check the IP and replace localhost with it:
> boot2docker ip
# --> http://192.168.59.103:49164/
Live reloading is enabled when running gulp watch in another window. Just change any of your JavaScript or Sass files to trigger reload. The reload monitors 'dist' directory and pushes the changes as needed.
src/ The client-side source code
src/index.html The HTML entry point, stub page
src/app Application source code
src/app/main.js The app JS entry point
src/components The 3rd party JS dependencies
src/css The CSS templates
gulpfile.js The Gulp build configuration
bower.json The Bower components
.bowerrc The Bower directory overrides
package.json The build level dependencies
dist/ The build results (debug and release builds)
Upgrading the boilerplate in your project may be tedious work. Once BoBrSASS directory structure becomes stable (it might be already, but no guarantees!), you can use it directly as an upstream (here with a name 'bobrsass').
> git remote add -f bobrsass git@github.com:SC5/gulp-bobrsass-boilerplate.git
Now synchronizing with BoBrSASS becomes easier:
> git pull bobrsass master
It is possible to use BoBrSASS as a subtree, too:
> git subtree add --prefix client --squash git@github.com:SC5/gulp-bobrsass-boilerplate.git master --squash
> git remote add -f bobrsass git@github.com:SC5/gulp-bobrsass-boilerplate.git
> git fetch bobrsass master
Note that you need to use a recent version of git that supports subtrees.
The example pulls BoBrSASS master branch into 'client' subdirectory. The key here is to use '--prefix client' to keep the boilerplate in its own subdirectory. Later on, sync by:
> git subtree pull --prefix client bobrsass master
Run tests with PhantomJS:
> gulp test
Or in debug mode with chromedriver in a browser:
> gulp test --debug
Plase see project GitHub issue tracker.
- 2014/02/12 - v0.1.0 - Initial commit (partially working stub)
- 2014/02/24 - v0.1.1 - Fix the build errors, update README
- 2014/05/08 - v0.2.0 - Update dependecies, add linting and plugin loader, update README
- 2014/05/09 - v0.3.0 - Add Protractor test framework, update README
- 2014/05/14 - v0.3.1 - Better linting
- 2014/08/01 - v0.4.0 - Clear separation of dev. and product dependencies
- 2014/10/20 - v0.5.0 - Migrate to Compass 1.0.1, sourcemaps, better linting, updated deps
Copyright (c) 2014 SC5, licensed for users and contributors under MIT license. https://github.com/sc5/grunt-bobrsass-boilerplate/blob/master/LICENSE-MIT
