Want to use Gulp on your Rails application? Here's some sample configuration.
It includes:
- JavaScript transpiling with Babel.js (with Browserify for ES6 module support)
- Stylesheet generation using Sass
- Assets with cache bursting for production
- Template compilation using Handlebars
- ES6 linting with JSHint
- Tests using QUnit and Phantom.js
- Tests using testem
All tasks are available at ./gulp/tasks/*
.
Install the gem:
$ gem install gulp-rails
Then from your project's root directory:
$ gulp-rails install # default to qunit
$ gulp-rails install -t qunit
$ gulp-rails install -t jasmine
$ gulp-rails install /some/other/path
You can start the watch
script for development:
$ npm run-script watch
When you're ready to deploy, run the build
script. This will generate the minified version with cache burst.
$ npm run-script build
Browserify requires you load each and every file in order to create the module structure. This is handled by the (tests|specs)-manifest
task, which will create a file at ./tmp/(tests|specs)-loader.js
.
Then we compile this file using our JavaScript pipeline; the generated file will be available at ./tmp/(tests|specs).js
. This file is loaded by the test runner.
To see sourcemaps when running tests, you must start a local server. You can execute something like:
python -m SimpleHTTPServer
php -S localhost:8000
ruby -run -e httpd . -p 8000
The you can visit http://localhost:8000/test/javascript/test_runner.html (QUnit) or http://localhost:8000/spec/javascript/spec_runner.html (Jasmine).
If you want to use testem, just run npm run-script testem
.
You can have as many bundles as you need; just create root files at app/frontend/styles/
and app/frontend/scripts
. By default, this setup comes with app/frontend/styles/application.scss
and app/frontend/scripts/application.js
.
For asset cache bursting to work, you'll have to copy the helper methods available at app/helpers/application_helper.rb
.
This file will replace the path_to_asset
method, which is used by all methods that require an asset path. I'm using the gulp-rev
package creating the manifest, instead of using the one created by asset pipeline.
Talking about asset pipeline... you don't have to disable it, and I honestly don't encourage you to do so because you may have engines that need this feature.
You don't want to expose your sourcemaps in production, but you may want to allow having this for an exception tracking service like Rollbar. We generate a name like sm-<uuid>
, but you can change the sourcemapsOutput
option at ./gulp/config.js
to whatever you want.
After checking out the repo, run bin/setup
to install dependencies. Then, run rake test
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment. Run bundle exec gulp-rails
to use the gem in this directory, ignoring other installed copies of this gem.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/fnando/gulp-rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.