ngmin-rails replacement for managing AngularJS minification in Rails assets pipeline
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
test
travis
vendor
.gitignore
.ruby-gemset
.ruby-version
.travis.yml
Gemfile
LICENSE.txt
README.md
Rakefile
ngannotate-rails.gemspec

README.md

ngannotate-rails

Use https://github.com/olov/ng-annotate in the Rails asset pipeline.

Installation

Add this line to your application's Gemfile:

gem 'ngannotate-rails'

And then execute:

$ bundle

That's it! ngannotate-rails integrates seamlessly into the Rails asset pipeline; your JavaScript or CoffeeScript assets will automatically be run through the ng-annotate pre-minifier.

Usage

By default ng-annotate processing is disabled in development and test environments. Processing, however, can be enforced by specifying NG_FORCE=true option.

NOTES

Javascript runtime

Issue with OSX javascript runtime

Use "therubyracer" as javascript runtime

Gemfile

gem 'therubyracer',  platforms: :ruby

For faster transpiling, can try to utilize miniracer

Gemfile

#gem 'therubyracer',  platforms: :ruby
gem 'libv8', '~> 5.0'
gem 'mini_racer', '~> 0.1.4'

# HACK KI due to "mini_racer"
gem 'sprockets-babel', git: 'https://github.com/kikonen/sprockets-babel.git', tag: '0.0.6.2'

ES2015+/coffeescript support

If using ES2015+ or coffeescript, it's recommended to use explicit "ngInject;" for classes.

test_controller.es6

"use strict";
export class TestController {
  constructor($q) {
    "ngInject";

    this.$q = $q;
  }
}

Heroku

Issue with Heroku

When pushing to heroku its important to invalidate all of your assets.

Rails.application.config.assets.version = '1.0'
Rails.application.config.assets.version = '1.1'

Environment options

  • NG_REGEXP
    • regexp passed to ng-annotate
    • see ng-annotate documentation
  • NG_OPT
    • comma separate list of "opt=value" key pairs passed as options to ng-annotate
    • see ng-annotate documentation
  • NG_FORCE
    • force ng-annotate processing in development/test environment

For example,

# Test assets compile in rails development environment
# (assuming config/environments/development.rb is adjusted approriately)

# with rails 3.2
NG_FORCE=true RAILS_ENV=development bundle exec rake assets:clean assets:precompile

# with rails 4.1
NG_FORCE=true RAILS_ENV=development bundle exec rake assets:clobber assets:precompile

Rails configuration options

Defined in "config.ng_annotate"

  • process
    • Is annotation processing done for current environment (NG_FORCE=true takes precedence over this)
    • default: true for production, false for development and test
  • options
    • Options for ngannotate (NG_OPT and NG_REGEXP env variables take precedence over this)
    • default: {}
  • paths
    • Asset paths, which are handled. Paths in ignore_paths override this setting Values can be [String | Regexp | Proc] instances
    • default: [/.*/]
  • ignore_paths
    • List of asset paths, which are ignored from ngannotate processing. Values can be [String | Regexp | Proc] instances
    • default: ['/vendor/']

For example,

config/environments/development.rb

Rails.application.configure do
...
    config.ng_annotate.process = true
    config.ng_annotate.options = {
      key1: 'value',
      regexp: '...',
    }
    config.ng_annotate.paths = [
      Rails.root.to_s,
    ]
    config.ng_annotate.ignore_paths = [
      '/vendor/',
      '/some/path/'
    ]
...
end

Testing assets locally

To allow testing precompiled assets locally in development environment.

config/environments/development.rb

#
# to allow testing assets:precompile in development environment
# Usage:
#   time NG_FORCE=true RAILS_ENV=development bundle exec rake assets:clean assets:precompile:primary
#   NG_FORCE=true rails s -p 3001
#
if ENV['NG_FORCE'] == 'true'
  config.assets.compress = true
  config.assets.compile = false
  config.assets.digest = true
  config.assets.debug = false
end

precompile & start server

time NG_FORCE=true RAILS_ENV=development bundle exec rake assets:clean assets:precompile:primary
NG_FORCE=true rails s -p 3001

Versioning

Originally version numbering of this gem followed ng-annotate. However, in order to improve handling of possibly compatibility breaking fixes and improvements, version schema is now separated from ng-annotate. Instead of matching versions, changelog in wiki will indicate which is currently matching ng-annotate version.

Every released version is tagged with tag "vX.Y.Z".

Release Process

For ngannotate update (or any other improvements/fixes):

git checkout master
git pull
# if ngannotate update
rake ngannotate:build
git citool
# check that result makes sense and if so,
# use comment: ngannotate: vX.Y.Z
git tag vX.Y.Z
git push
git push --tags
gem build ngannotate-rails.gemspec
gem push ngannotate-rails-X.Y.Z.gems

Help

  • Q: I installed ngannotate-rails, but my assets aren't getting processed with ng-annotate.

    A: Remember to delete tmp/cache/assets or touch all the related asset files so that the cached versions get regenerated. If you've precompiled your assets into public/assets, you'll need to re-precompile them.

Hacking

Upgrading ng-annotate

The actual ngannotate project is bundled into this gem via Browserify. You can update to the latest version of ng-annotate via Rake:

rake ngannotate:build

Test Application

There is a Rails 3 application bundled in example/ that you can use to test the asset pipeline integration. Don't forget to remove tmp/cache/assets after upgrading to the latest version of ng-annotate.

Credits

This gem is based into https://github.com/jasonm/ngmin-rails