Skip to content

Latest commit

 

History

History
144 lines (103 loc) · 4.94 KB

README.md

File metadata and controls

144 lines (103 loc) · 4.94 KB
Raw

alt text

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.

Installation

  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/javascripts/main.js Input file
  • public/assets/javascripts/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

./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

Configuration

The generator is only supposed to generate a scaffold. Afterwards modify the generated Javascript files at will.

To tinker with the Rails bits, have a look at the railtie.rb file for available configuration options and initializers. If you need to reconfigure livereload (might be necessary in docker dev-environments where the livereload server is running on a different host than the rails server), put this initializer in your application.rb:

initializer "config_livereload", after: 'gulp_assets.livereload' do
  if Rails.env.development?
    config.middleware.delete(Rack::LiveReload)
    config.middleware.insert_after(ActionDispatch::Static, Rack::LiveReload, host: 'localhost')
  end
end

Changelog

See CHANGELOG.md