Please note I cannot release a gem version of iridium until
rake-pipeline releases a new version. This means you must specify git
dependencies in your
First create a
source 'https://rubygems.org' gem 'iridium', :github => 'radiumsoftware/iridium' gem 'hydrogen', :github => 'radiumsoftware/hydrogen' gem 'rake-pipeline', :github => 'livingsocial/rake-pipeline'
$ bundle $ bundle exec iridium g:application
Don't forget you must use bundle exec!
Iridium: A Toolchain for JS Application Development
- CLI driven interactions
- Focus on JS/CSS/HTML
- Make JS testable
Iridium makes choices for you by default. These choices work well together. All Iridium apps get all this right out of the box:
- jQuery for DOM manipulation
- Handlebars for templating
- Minispade for simple modules and
- Qunit or Jasmine for unit tests
- GZip assets in production
- Fully cache all assets in production
- Generate an HTML5 cache manifest for production
The first step is to use the built-in generator to create the structure:
$ iridium generate app todos
Now your application is ready. You can use the built in development server to edit your JS/CSS files and reload the browser.
$ cd todos $ iridium server >> Thin web server (v1.4.1 codename Chromeo) >> Maximum connections set to 1024 >> Listening on 0.0.0.0:9292, CTRL+C to stop
http://localhost:9292 in your browser and you'll see a
Iridium compiles all
.coffee files to
.js. All files inside
app/. All files inside
app are wrapped in minispade
modules. The module name comes from the file name.
require calls are
rewritten to use
minispade.require. Files inside
app/config/initializers are also compiled, but not wrapped in
modules. Files inside vendor code are not wrapped in modules. All of
application.js. The compiled
application.js has this order:
- The file in
app/configmatching the current environment. Example:
app/config/development.coffeein development or
- All files in
app/config/initializerswrapped in IFFEs
- All the files from
lib/wrapped in minispade modules
- All the code in
- I18n code
You can inspect the final
application.js to verify everything is
working as you expected.
Here are some examples:
All files in this directory are loaded before your app code in
alphabetical order unless an order is specified. You don't have to
specify the order for all files. You can declare files that should be
included before all others and not worry about the others. For example,
you have 10 files in
jquery_ui are loaded first. All the other
files will be included after those.
Loading External Scripts
You may want to pull in external scripts via CDN instead of bundling
them inside your application. Configured scripts are written in as
<script> tags before your application code. Here's an example:
# application.rb Todos.configure do config.scripts.load "http://www.mycdn.com/script.js" end
Everything works as you expect. All
.sass files are
compiled correctly. You can use
@import as you'd expect.
app/stylesheets is added to the sass load path.
Create a directory for each set of sprites you need. Then
as usual with compass. Here's an example. Create a directory named
app/sprites/icons. Dump all the individual icon png's in that
directory. Inside your stylesheet you can write:
import('icons/*.png') to generate the icons sprite.
Handlebars templates are named using the same semantics as application
app/templates are processed.
The templates are also precompiled depending on the environment.
Iridium makes testing your JS easy. It does all the manual work for you.
It compiles all the tests into
tests.html. You open
tests.html in your browser or use it with phantomjs. The test
command will compile your tests and check them with phantomjs. Qunit
and Jasmine are supported out of the box.
$ iridium test # Running Tests: ................................................................. 2998 Test(s), 2998 Passed, 0 Error(s)
You can use
iridium test --debug if you want to see
messages in the report.
Coffescript is generated by default. You can write in Javscript if you like. Iridium can run all your files through JSLint if you like.
Iridium supports localization via
i18n.js. The i18n implementation is
taken from here. All files in
app/locales/*.yml are merged into i18n translations. Here's an
# app/locales/en.yml en: greeting: Hello!
# app/locales/fi.yml fi: greeting: Terve!
I18n.locale = 'en' I18n.t('greeting') // "Hello!" I18n.locale = 'fi' I18n.t('gretting') // "Terve!"
Configuration, Middleware, and Proxying
Your Iridium app is served as a rack app. You can inject your own middleware as you like. Here's an example:
# application.rb YourApp.configure do # config.middleware mimics the Rack::Builder api config.middleware.use MyCustomMiddleware end
Iridium also has basic proxy support for handling your backend API. You should only use this proxy if the API does not support CORs or there is some other issue with it. You may want to use this proxy in test mode to point your app to a test server intead. Here's an example:
# application.rb YourApp.configure do proxy "/api", "http://api.myproduct.com" end
Proxies can be overwritten per env like this:
# application.rb YourApp.configure do proxy "/api", "http://api.myproduct.com" end # config/test.rb YourApp.configure do proxy "/api", "http://test-api.myproduct.com" end
Customizing The Unit Test Loader
Iridium uses a generated HTML file to load your test code into. You can
override this behavior by creating:
Here's what the default ERB template looks like:
<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Unit Tests</title> <!--[if lt IE 9]> <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script> <![endif]--> </head> <body> <% app.config.dependencies.each do |script| %> <script src="<%= script.url %>"></script> <% end %> <script src="application.js"></script> </body> </html>
JS applications are simply a collection of static assets in a diretory.
This is trival to serve up with Rack. Iridium apps are rack apps for
serving up the compiled directory. The server also handles caching,
proxying, and custom middleware. All you need to do is create a
config.ru file and you can deploy your app! You can also deploy your
app for free on Heroku out of the box.
# config.ru require File.expand_path('../application', __FILE__) run MyApp
Or if you don't care about that, you can run the generator:
$ cd my_app $ iridium generate rackup
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Added some feature')
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request