# GulpAssets

Rails Plugin to augment frontend development with a gulp/webpack based
workflow.

- Installs Javascript infrastructure in your Rails project to manage
  frontend assets
- Provides view helpers to Rails that allow you to easily reference
  gulp generated assets from Rails views
- Puts Livereload into the Rails middleware stack. This injects the
  Livereload client into Rails-renderd pages, updates are triggered from
  gulp.

## Usage

1. Add `gem 'gulp_assets' to your Gemfile and run `bundle install`.
2. Run `rails generate gulp_assets` to generate all necessary files.
3. Develop your frontend code in the `frontend` directory
4. Reference files generated by gulp using the `gulp_asset_path` helper
5. Run `npm start` during development for livereload/Webpack
   Hot Module replacement.

## Structure

`frontend/assets` contains static assets (images, fonts, icons). A
static asset is a file that is not processed and that does not contain
references to other files. They are simply copied to
`public/assets/assets`.

`frontend/stylesheets` contains SCSS files which are compiled to
`public/assets/stylesheets`. Files beginning with underscores are
ignored.

`frontend/javascripts/main.js` is the entry point for the client-side
Javascript. This is picked up by Webpack, bundled and copied to
`public/assets/javascripts`. If you need additional entry points,
please adjust the webpack configuration accordingly.

## Gulp Commands

### `gulp default`

Runs the webpack development server which will watch files, trigger
livereload and serve static assets.

This also runs if you execute `npm start`.

### `gulp precompile`

Compiles assets for production, hashes their names and generates a
`rev-mainfest.json`, which is used by the `gulp_asset_path` helper to
generate the correct links with the hash in the filename.

## Referencing gulp assets from Rails views

The `gulp_assets_path` helper takes a partial path as a parameter that
sits inside the `public/assets` folder. It then operates differently,
depending on the `RAILS_ENV`:

- development: Prepend the path with the correct location on the webpack
  dev server, usually `//localhost:8080/assets`. `javascripts/main.js`
  would become `//localhost:8080/assets/javascripts/main.js`.
- production: Prepend the path with the correct asset path and replace
  the filename with the hashed version. `javascripts/main.js` would
  become `/assets/javascripts/main-a42bb48a5f83.js`.

### Shortcuts

To include a gulp-generated javascript or stylesheet, use the `gulp_javascript` or
`gulp_stylesheet` helper:

    <%= gulp_javascript "main" %>
    <%= gulp_stylesheet "main" %>

Since "main" is the default name, you can omit it:

    <%= gulp_javascript %>
    <%= gulp_stylesheet %>

Both accept a second parameter for overwriting attributes. This can be
used for example to change the `media` attribute for a stylesheet.

## Examples

### CSS
 
 - `frontend/stylesheets/main.scss` Input file
 - `public/assets/stylesheets/main.css` Output File
 - `<link rel="stylesheet" media="all" href="<%=gulp_asset_path('stylesheets/main.css')%>"/>` Used to link to the file.
 - `<%= gulp_stylesheet "main" %>` or `<%= gulp_stylesheet %>` also generate correct links

### JS

 - `frontend/javscripts/main.js` Input file
 - `public/assets/javscripts/main.js` Output File
 -  `<script src="<%=gulp_asset_path('javascripts/main.js')%>"></script>`
 - `<%= gulp_javascript "main" %>` or `<%= gulp_javascript %>` also generate correct links