Git Product home page Git Product logo

webpack-rails's Introduction

Build Status Gem Version

webpack-rails

webpack-rails gives you tools to integrate Webpack in to an existing Ruby on Rails application.

It will happily co-exist with sprockets but does not use it for production fingerprinting or asset serving. webpack-rails is designed with the assumption that if you're using Webpack you treat Javascript as a first-class citizen. This means that you control the webpack config, package.json, and use npm to install Webpack & its plugins.

In development mode webpack-dev-server is used to serve webpacked entry points and offer hot module reloading. In production entry points are built in to public/webpack. webpack-rails uses stats-webpack-plugin to translate entry points in to asset paths.

It was designed for use at Marketplacer to assist us in migrating our Javascript (and possibly our SCSS) off of Sprockets. It first saw production use in June 2015.

Our examples show webpack-rails co-existing with sprockets (as that's how environment works), but sprockets is not used or required for development or production use of this gem.

This gem has been tested against Rails 4.2 and Ruby 2.2. Earlier versions of Rails (>= 3.2) and Ruby (>= 1.9) may work, but we haven't tested them.

Using webpack-rails

We have a demo application: webpack-rails-demo

Installation

  1. Add webpack-rails to your gemfile
  2. Run bundle install to install the gem
  3. Run bundle exec rails generate webpack_rails:install to copy across example files
  4. Run foreman start to start webpack-dev-server and rails server at the same time
  5. Add the webpack entry point to your layout (see next section)
  6. Edit webpack/application.js and write some code

Adding the entry point to your Rails application

To add your webpacked javascript in to your app, add the following to the <head> section of your to your layout.html.erb:

<%= javascript_include_tag *webpack_asset_paths("application") %>

Take note of the splat (*): webpack_asset_paths returns an array, as one entry point can map to multiple paths, especially if hot reloading is enabled in Webpack.

How it works

Have a look at the files in the examples directory. Of note:

  • We use foreman and a Procfile to run our rails server & the webpack dev server in development at the same time
  • The webpack and gem configuration must be in sync - look at our railtie for configuration options
  • We require that stats-webpack-plugin is loaded to automatically generate a production manifest & resolve paths during development

Configuration Defaults

  • Webpack configuration lives in config/webpack.config.js
  • Webpack & Webpack Dev Server binaries are in node_modules/.bin/
  • Webpack Dev Server will run on port 3808 on localhost
  • Webpack Dev Server is enabled in development & test, but not in production
  • Webpacked assets will be compiled to public/webpack
  • The manifest file is named manifest.json

Working with browser tests

In development, we make sure that the webpack-dev-server is running when browser tests are running. In CI, we manually run webpack to compile the assets to public and set config.webpack.dev_server.enabled to false.

Production Deployment

Add rake webpack:compile to your deployment. It serves a similar purpose as Sprockets' assets:precompile task. If you're using Webpack and Sprockets (as we are at Marketplacer) you'll need to run both tasks - but it doesn't matter which order they're run in.

If you're using [chunkhash] in your build asset filenames (which you should be, if you want to cache them in production), you'll need to persist built assets between deployments. Consider in-flight requests at the time of deployment: they'll receive paths based on the old manifest.json, not the new one.

TODO

  • Drive config via JSON, have webpack.config.js read same JSON?
  • Custom webpack-dev-server that exposes errors, stats, etc
  • react-rails fork for use with this workflow
  • Integration tests

Contributing

Pull requests & issues welcome. Advice & criticism regarding webpack config approach also welcome.

Please ensure that pull requests pass both rubocop & rspec. New functionality should be discussed in an issue first.

Acknowledgements

webpack-rails's People

Contributors

hfwang avatar ktopping avatar lordmortis avatar mattgibson avatar mipearson avatar superhighfives avatar

Watchers

 avatar

Forkers

xpander001

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.