npm-pipeline-rails 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 46d50e558878bb7067e545c5e6d23b8bab48c620
-  data.tar.gz: d4af91051596cb74e6125ea7c88b770d5ee9555f
+  metadata.gz: cf569c96c85c02b65915d854b5ed6023012bc7aa
+  data.tar.gz: d0e38db04bb99ed44153f96d65740caddda891a2
 SHA512:
-  metadata.gz: 7ab31053f7879fc3575446561e3b6aaa2170bc807fea510bea2dcf13c8a8bb196047df4dcc2261d0a8ea21e42a70867126e6fe56182f4f022785abbce1560d82
-  data.tar.gz: 9e8f5151e74246cbca3cb474f91ed359c54af627ed59e41492ecaf21acb9868cddfbabd463ff48c08ee0ddabc741b60be4be302b8c89ce553b6e42c95e653439
+  metadata.gz: 1ef48bbe254b7960785f489b19401423419baa51776ebbe69837810c9bc78094fcd95107fc28376ca7a3b00f82a9b48b96d000c550fce141f5b57fa7ca5378ed
+  data.tar.gz: b8f655d71c5eab1cd5b1ecc7bd1fc8832a44e035fae1435b2e16fd9e7ee36d0315fcf2a1d2183f7ab7902ac239bab37809b348777a10b03946e423f7ce9bfbf6

data/HISTORY.md

@@ -1,3 +1,10 @@
+## [v1.1.0]
+> Mar 22, 2016
+
+- Add Gulp generator (`rails g npm_pipeline:gulp`).
+
+[v1.1.0]: https://github.com/rstacruz/npm-pipeline-rails/compare/v1.0.0...v1.1.0
+
 ## [v1.0.0]
 > Mar 22, 2016
 

data/README.md

@@ -2,36 +2,49 @@
 
 > Use npm as part of your Rails asset pipeline
 
-npm-pipeline-rails allows you to use any toolchain to bulid your asset files. This allows you to:
+npm-pipeline-rails allows you to use any toolchain to bulid your asset files in [Rails] 4.2+. This allows you to:
 
-- Use [webpack][] with Rails
-- Use [brunch][] with Rails ([instructions](docs/brunch.md))
-- Use [browserify][] with Rails
+- Use [Brunch][] with Rails ([instructions](docs/brunch.md))
+- Use [Gulp][] with Rails ([instructions](docs/gulp.md))
+- Use [Grunt][] with Rails
+- Use [Webpack][] with Rails
+- Use [Browserify][] with Rails
 - Use any other asset tool with Rails
 
-[webpack]: https://webpack.github.io/
-[brunch]: http://brunch.io/
-[browserify]: http://browserify.org/
+[Rails]: http://rubyonrails.org/
+[Webpack]: https://webpack.github.io/
+[Brunch]: http://brunch.io/
+[Browserify]: http://browserify.org/
+[Gulp]: http://gulpjs.com/
+[Grunt]: http://gruntjs.com/
 
-> ![](docs/screenshots/full.png)
+<br>
 
-## Usage
+![](docs/screenshots/full.png)
+
+> _See [§ How it Works](#how-it-works) for an explanation of the diagram above._
 
-Add to your `Gemfile`.
+<br>
 
-  ```rb
-  gem 'npm-pipeline-rails'
-  ```
+## Usage
 
-You may do a manual setup:
+Add this line below to your `Gemfile`. After that, proceed with an automated or manual setup.
 
-* Create a `package.json` with `start` and `build` commands.
-* Add compiled assets to `.gitignore`.
+```rb
+gem 'npm-pipeline-rails'
+```
 
-Or an automated setup:
+#### Automated setup
 
 * Run `./bin/rails generate npm_pipeline:brunch` to add a sample integration with [Brunch]. ([info](docs/brunch.md))
 
+#### Manual setup
+
+* Create a `package.json` with `start` and `build` scripts. ([See example](lib/generators/npm_pipeline/brunch/package.json))
+* Add your expected compiled assets to `.gitignore`.
+
+<br>
+
 ## Configuration
 
 npm-pipeline-rails provides these configuration options:
@@ -43,7 +56,7 @@ Rails.application.configure do
   # Command to install dependencies
   config.npm.install = ['npm install']
 
-  # Command to build production
+  # Command to build production assets
   config.npm.build = ['npm run build']
 
   # Command to start a file watcher
@@ -57,10 +70,14 @@ Rails.application.configure do
 end
 ```
 
+<br>
+
 ## How it works
 
 npm-pipeline-rails allows you to hook certain commands, usually npm scripts, during the Rails app lifecycle. It assumes that your tool will build plain JS and CSS files into `vendor/assets`, allowing it to be picked up by Rails's asset pipeline.
 
+It does __not__ replace the Rails asset pipeline, but rather it works with it. The files you build with your npm pipeline will be available as regular files in the Rails asset pipeline.
+
 #### In development
 
 When starting a Rails development server (`bundle exec rails s`), it runs the `install` command. After that, it starts a background process that runs your `watch` command.
@@ -69,10 +86,25 @@ When starting a Rails development server (`bundle exec rails s`), it runs the `i
 
 When running `rake assets:precompile`, it will first run the `install` command then the `build` command.
 
+#### More info
+
+Consult [railtie.rb](https://github.com/rstacruz/npm-pipeline-rails/blob/master/lib/npm-pipeline-rails/railtie.rb) for the actual code that makes all these happen.
+
+<br>
+
 ## Integration examples
 
 * [Brunch](docs/brunch.md)
-* more to come soon
+
+<br>
+
+## Motivation
+
+Rails's asset pipeline was a great step forward for Rails 3. For today's requirements however, it doesn't always come with all the tools you need. npm-pipeline-rails lets you outsource asset building complexities to Node.js-based tools.
+
+> __[Read more →](docs/motivation.md)__
+
+<br>
 
 ## Thanks
 

data/docs/brunch.md

@@ -1,4 +1,4 @@
-# Brunch example
+# Brunch integration
 
 Run `./bin/rails generate npm_pipeline:brunch`.
 
@@ -6,57 +6,27 @@ Run `./bin/rails generate npm_pipeline:brunch`.
 
 If you don't want to use the generator, here's what it does.
 
-### `brunch-config.js`
+### brunch-config.js
 
 Set it up to watch source files in `app/brunch`, then put built files into `vendor/assets`.
+[See example.](../lib/generators/npm_pipeline/brunch/brunch-config.js)
 
-```js
-// See http://brunch.io for documentation.
-module.exports = {
-  paths: {
-    watched: ['app/brunch'],
-    public: 'vendor/assets'
-  },
-
-  files: {
-    javascripts: {joinTo: 'javascripts/brunch/app.js'},
-    stylesheets: {joinTo: 'stylesheets/brunch/app.css'}
-  }
-}
-```
+### package.json
 
-### `package.json`
-
-```js
-{
-  "name": "brunch-app",
-  "description": "Description",
-  "author": "Your Name",
-  "version": "0.1.0",
-  "scripts": {
-    "start": "brunch watch",
-    "build": "brunch build --production"
-  },
-  "dependencies": {},
-  "devDependencies": {
-    "brunch": "^2.5.1",
-    "javascript-brunch": "^2.0.0",
-    "css-brunch": "^2.0.0",
-    "auto-reload-brunch": "^2.0.0"
-  }
-}
-```
+Set it up with `brunch` and some basic plugins.
+[See example.](../lib/generators/npm_pipeline/brunch/package.json)
 
-### `.gitignore`
+### .gitignore
 
 Set it up to ignore Brunch's built files.
 
 ```
-/vendor/assets/stylesheets/brunch/
-/vendor/assets/javascripts/brunch/
+/node_modules
+/vendor/assets/stylesheets/brunch
+/vendor/assets/javascripts/brunch
 ```
 
-### `app/assets/stylesheets/application.css`
+### app/assets/stylesheets/application.css
 
 Set it up to include Brunch's built files. This will load from `vendor/assets/stylesheets`, as built by Brunch.
 
@@ -66,7 +36,7 @@ Set it up to include Brunch's built files. This will load from `vendor/assets/st
  */
 ```
 
-### `app/assets/javascripts/application.js`
+### app/assets/javascripts/application.js
 
 Set it up to include Brunch's built files. This will load from `vendor/assets/javascripts`, as built by Brunch.
 
@@ -74,7 +44,7 @@ Set it up to include Brunch's built files. This will load from `vendor/assets/ja
 //= require brunch/app
 ```
 
-### `app/brunch`
+### app/brunch/
 
 Put your source files into `app/brunch`. For instance:
 

data/docs/gulp.md

@@ -0,0 +1,60 @@
+# Gulp integration
+
+Run `./bin/rails generate npm_pipeline:gulp`.
+
+## Manual setup
+
+If you don't want to use the generator, here's what it does.
+
+### package.json
+
+Set up `gulp`, `gulp-cli`, and some basic Gulp plugins.
+[See example.](../lib/generators/npm_pipeline/gulp/package.json)
+
+### gulpfile.js
+
+Set it up to watch source files in `app/gulp`, then put built files into `vendor/assets`. [See example.](../lib/generators/npm_pipeline/gulp/gulpfile.js)
+
+### .gitignore
+
+Set it up to ignore Gulp's built files.
+
+```
+/node_modules
+/vendor/assets/stylesheets/gulp
+/vendor/assets/javascripts/gulp
+```
+
+### app/assets/stylesheets/application.css
+
+Set it up to include Gulp's built files. This will load from `vendor/assets/stylesheets/gulp/app.css`, as built by Gulp.
+
+```css
+/*
+ *= require gulp/app
+ */
+```
+
+### app/assets/javascripts/application.js
+
+Set it up to include Gulp's built files. This will load from `vendor/assets/javascripts/gulp/app.js`, as built by Gulp.
+
+```css
+//= require gulp/app
+```
+
+### app/gulp/
+
+Put your source files into `app/gulp`. For instance:
+
+* `app/brunch/example.css`
+
+ ```css
+  * { color: blue }
+  ```
+
+* `app/brunch/example.js`
+
+  ```js
+  alert('it works!')
+  ```

data/docs/motivation.md

@@ -0,0 +1,35 @@
+# Motivation
+
+Rails's asset pipeline was a great step forward for Rails 3. For today's requirements however, it doesn't always come with all the tools you need. Here's a portrait of Rails's shortcomings with respect to CSS/JS development in 2016:
+
+* __npm assets:__ Frontend packages are now usually hosted in [npm], but there's no easy solution to integrate npm with Rails. Putting files into `vendor/assets` should be a thing of the past.
+
+* __Auto-reload:__ Automatic CSS reloading can be done with [guard-livereload], but is unwieldy at best. They require too much configuration and mental overhead to maintain.
+
+* __Modern CSS tools:__ Integrating modern CSS tools like [libsass] and [postcss] can be done, but is hackish and slow. It has to invoke a separate Node.js process for each CSS file rather than keeping those tools running in the background. Some newer CSS pre/post processors like [Myth](http://www.myth.io/) don't have production-grade integrations with Rails.
+
+* __Modern JS tools:__ Working with complex frontends typically need [Webpack] or [Browserify]. While integrations for these exist, they can be slow and unreliable.
+
+## Using Node.js
+
+npm-pipeline-rails lets you outsource asset building complexities to Node.js-based tools, which is the gold stardard for asset tooling nowadays.
+
+It doesn't lock you into one specific solution; you can use npm-pipeline-rails for any task manager. I recommend [Brunch] for its ease-of-use and familiarity with Rails's asset pipeline's features. [Gulp] and [Grunt] are also popular choices.
+
+## Brunch
+
+You can use [Brunch] with Rails with ease using npm-pipeline-rails. With Brunch, you get [automatic code reloading][auto-reload-brunch], easier integration with [postcss][postcss-brunch], `require()` support, and more. You may even hook [Browserify][browserify-brunch] if you need it.
+
+[guard-livereload]: http://rubygems.org/gems/guard-livereload
+[npm]: http://npmjs.com/
+[libsass]: http://sass-lang.com/libsass
+[postcss]: https://github.com/postcss/postcss
+[auto-reload-brunch]: https://www.npmjs.com/package/auto-reload-brunch
+[postcss-brunch]: https://www.npmjs.com/package/postcss-brunch
+[browserify-brunch]: https://www.npmjs.com/package/browserify-brunch
+[Grunt]: http://gruntjs.com/
+[Webpack]: https://webpack.github.io/
+[Brunch]: http://brunch.io/
+[Browserify]: http://browserify.org/
+[Gulp]: http://gulpjs.com/
+[Grunt]: http://gruntjs.com/

data/lib/generators/npm_pipeline/brunch_generator.rb

@@ -33,6 +33,7 @@ module NpmPipeline
 
       def update_gitignore
         append_to_file '.gitignore',
+          "/node_modules\n" +
           "/vendor/assets/stylesheets/brunch\n" +
           "/vendor/assets/javascripts/brunch\n"
       end

data/lib/generators/npm_pipeline/gulp/gulpfile.js

@@ -0,0 +1,24 @@
+var gulp = require('gulp')
+var concat = require('gulp-concat')
+
+gulp.task('build:js', function () {
+  return gulp.src('app/gulp/js/**/*.js')
+    .pipe(concat('app.js'))
+    .pipe(gulp.dest('vendor/assets/javascripts/gulp/'))
+})
+
+gulp.task('build:css', function () {
+  return gulp.src('app/gulp/css/**/*.css')
+    .pipe(gulp.dest('vendor/assets/stylesheets/gulp/'))
+})
+
+gulp.task('watch:js', function () {
+  gulp.watch('app/gulp/js/**/*.js', ['build:js'])
+})
+
+gulp.task('watch:css', function () {
+  gulp.watch('app/gulp/css/**/*.css', ['build:css'])
+})
+
+gulp.task('watch', ['watch:js', 'watch:css'])
+gulp.task('build', ['build:js', 'build:css'])

data/lib/generators/npm_pipeline/gulp/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "gulp-app",
+  "description": "Description",
+  "author": "Your Name",
+  "version": "0.1.0",
+  "scripts": {
+    "start": "gulp watch",
+    "build": "gulp build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "gulp": "^3.9.1",
+    "gulp-cli": "^1.2.1",
+    "gulp-concat": "^2.6.0"
+  }
+}

data/lib/generators/npm_pipeline/gulp_generator.rb

@@ -0,0 +1,42 @@
+require 'rails/generators/base'
+
+module NpmPipeline
+  module Generators
+    class GulpGenerator < Rails::Generators::Base
+      desc 'Creates'
+      source_root File.expand_path('../gulp', __FILE__)
+
+      def create_package_json
+        template 'package.json', 'package.json'
+      end
+
+      def create_gulpfile
+        template 'gulpfile.js', 'gulpfile.js'
+      end
+
+      def update_assets
+        append_to_file 'app/assets/stylesheets/application.css',
+          "/*\n *= require gulp/app\n */\n"
+        append_to_file 'app/assets/javascripts/application.js',
+          "//= require gulp/app\n"
+      end
+
+      def create_sample_css
+        create_file 'app/gulp/css/example.css',
+          %(html:before { content: 'Gulp assets added successfully! Edit app/gulp/example.css or remove it.'; display: block; padding: 20px; background: #ffc; color: #111; position: fixed; top: 16px; right: 16px; max-width: 600px; z-index: 10000; font-family: sans-serif; font-size: 14px; line-height: 1.6; }\n)
+      end
+
+      def create_sample_js
+        create_file 'app/gulp/js/example.js',
+          "alert('Gulp works!')"
+      end
+
+      def update_gitignore
+        append_to_file '.gitignore',
+          "/node_modules\n" +
+          "/vendor/assets/stylesheets/gulp\n" +
+          "/vendor/assets/javascripts/gulp\n"
+      end
+    end
+  end
+end

data/lib/npm-pipeline-rails/railtie.rb

@@ -7,7 +7,6 @@ module NpmPipelineRails
       [*commands].each do |cmd|
         system cmd
         exit $? unless $? == 0
-
       end
     end
   end
@@ -16,14 +15,13 @@ module NpmPipelineRails
     include ::NpmPipelineRails::Utils
 
     config.npm = ActiveSupport::OrderedOptions.new
-
     config.npm.build = ['npm run build']
     config.npm.watch = ['npm run start']
     config.npm.install = ['npm install']
 
     rake_tasks do |app|
       namespace :assets do
-        desc 'Build assets prerequisites using npm'
+        desc 'Build asset prerequisites using npm'
         task :npm_build do
           do_system app.config.npm.install
           do_system app.config.npm.build
@@ -36,7 +34,6 @@ module NpmPipelineRails
     initializer 'npm_pipeline.watch' do |app|
       if ::Rails.env.development? && ::Rails.const_defined?(:Server)
         do_system app.config.npm.install
-        exit $? unless $? == 0
         [*app.config.npm.watch].each do |cmd|
           fork { do_system [cmd] }
         end

data/lib/npm-pipeline-rails/version.rb

@@ -1,3 +1,3 @@
 module NpmPipelineRails
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/npm-pipeline-rails.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/rstacruz/npm-pipeline-rails'
   spec.license       = 'MIT'
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(example|test|spec|features)/}) }
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(examples|test|spec|features)/}) }
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: npm-pipeline-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Rico Sta. Cruz
@@ -106,12 +106,17 @@ files:
 - HISTORY.md
 - README.md
 - docs/brunch.md
+- docs/gulp.md
+- docs/motivation.md
 - docs/screenshots/build.png
 - docs/screenshots/full.png
 - docs/screenshots/server.png
 - lib/generators/npm_pipeline/brunch/brunch-config.js
 - lib/generators/npm_pipeline/brunch/package.json
 - lib/generators/npm_pipeline/brunch_generator.rb
+- lib/generators/npm_pipeline/gulp/gulpfile.js
+- lib/generators/npm_pipeline/gulp/package.json
+- lib/generators/npm_pipeline/gulp_generator.rb
 - lib/npm-pipeline-rails.rb
 - lib/npm-pipeline-rails/railtie.rb
 - lib/npm-pipeline-rails/version.rb