# 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

## Development

To test while changing the JS files, run

```shell
./cli create_testapp
```

inside the root of the gem. This will generate a testapp directory that
contains a Rails app using the gem from source. All the gulp_assets
specific files are symlinked to the files and directories in the template
directory. If you want to use npm commands you have to run those inside
the template directory, otherwise npm will replace the symlink with a
new package.json.

The rails app has the following features:

- A layout requiring `main.js` and `main.css`.
- A default route rendering a static template in
  `app/views/application/index.html.erb`