Rails Apps Composer Gem
What you can do with the rails_apps_composer gem:
- Create and maintain a starter app.
- Make an application template that generates a complex Rails app in seconds.
We use the rails_apps_composer gem to create the Rails Example Apps for the RailsApps project.
Any issues? Please create a GitHub issue.
Based on Michael Bleigh’s RailsWizard Gem
The rails_apps_composer gem is a fork of Michael Bleigh’s RailsWizard gem (see credits below). The purpose of the fork is to provide recipes for ready-to-run Rails starter apps. Several recipes provided by the rails_apps_composer gem are different from those provided by the rails_wizard gem. Applications generated with the rails_apps_composer gem are more complete; for example, they may include a home page with sign-in, sign-out navigation links.
Alternatives
Notable alternatives are Dr. Nic Williams’s App Scrolls and Daniel Davey’s app_drone.
See a list of Rails Application Template Projects, particularly a list of “Application template-generating gems.”
Follow on Twitter
Follow the project on Twitter: @rails_apps. Tweet some praise if you like what you’ve found.
Purpose
Any developer can quickly generate a Rails web application using the rails new command. In practice, experienced Rails developers typically add an assortment of useful additional packages (gems) before beginning development of any web application. A developer often uses the same set of packages to get started and may create a “starter app” that can be copied and reused for any new project.
It can be a hassle to integrate some of the most commonly used gems, particularly when new versions are released and there are minor “gotchas” that interfere with gems working together. Despite the apparent convenience of creating a starter app, it can be time consuming to maintain and update a starter app as component packages evolve. This project aims to simplify the process of building and maintaining a starter app by providing mix-and-match recipes to assemble the most commonly used Rails packages.
Issues
Hundreds of developers are using this gem to build starter apps. As you can see from the commit log, the gem is actively maintained and the collection of recipes is growing.
There is problem with all this activity, however. No developer who uses the rails_apps_composer gem uses all the recipes. And it would be very difficult to test a recipe in every possible combination. Consequently, combining some recipes may not work. We’ve provided some examples from the RailsApps project that are known to work together (see “Examples”). If you’re combining recipes, you’ll have to experiment. Add recipes one-by-one and realize that some recipes may not be compatible.
Have you found problems? Please create a GitHub issue.
Dependencies
Before generating a new Rails app, you will need:
- The Ruby language (version 1.9.3)
- Rails 3.1 or newer
See Installing Rails for detailed instructions and advice.
Installation
Installation is simple:
$ gem install rails_apps_composer
Usage
List Recipes
$ rails_apps_composer list
You can learn more about the available recipes by browsing the repository recipes directory.
Generate an App
$ rails_apps_composer new myapp -r haml home_page html5
The command with the -r flag followed by a list of recipes generates an app.
Generate an App from Defaults
$ rails_apps_composer --defaults=~/.rac
Use the ~/.rac file to specify a list of recipes and recipe preferences. See details below concerning the format of the defaults file.
Generate a Template
You may want a template to customize or share with others. See various application templates from the RailsApps project.
$ rails_apps_composer template ~/Desktop/template.txt -r haml home_page html5
The command with the template argument followed by a filename and a list of recipes generates an application template.
Generate an app from the template at any time:
$ rails new myapp -m ~/Desktop/template.txt
Here is more information about usage of the gem.
Generate an App
Mix and match recipes to create your own customized starter app. See an annotated list of available recipes for the rails_apps_composer gem. For an up-to-date list, browse the repository recipes directory to see what is available. Then provide your list of recipes to the rails_apps_composer gem using the -r option and generate an app as needed. Here’s an example that creates a simple app using haml:
$ rails_apps_composer new myapp -r haml home_page html5
Replace myapp with the name you want for your application.
Generate an App from Defaults
If you frequently generate an app and always use the same recipes and preferences, create a defaults file and produce the same app every time. A big thank you to Bryan Stearns for contributing this feature!
$ rails_apps_composer --defaults=~/.rac
If you create a shell alias such as builditnow for the command, you’ll have even less to remember.
Here’s the format of a typical defaults file:
recipes: - activerecord - home_page - html5 - sass - rspec - capybara - guard - extras - git activerecord: database: sqlite3 auto_create: true devise: devise: standard authorization: false extras: footnotes: false ban_spiders: true paginate: false jsruntime: false guard: guard: standard html5: css_option: bootstrap_sass rspec: rspec: true fixtures: factory_girl sass: sass: true
You’ll have to look in the recipe files to determine the attribute (such as css_option) used to specify preferences.
The list of recipes at the top will be included whenever you generate an app. The remaining hashes will be used to respond to prompts (questions) that recipes display. If there is no preference specified in the defaults file, rails_apps_composer will ask you to respond with a preference. That way, you can give yourself flexibility if you don’t always have the same preference.
When you run the command with the --defaults option and no recipes specified on the command line, you’ll see the prompt, “Which recipe would you like to add? (blank to finish)”. If you want to use only your default recipes, just hit return. If you want to add a recipe for the app you are generating, just type the recipe name at the prompt. If you’ve provided your preferences for the recipe in your defaults file, you won’t be prompted for preferences. If you haven’t provided default preferences for the additional recipe, you’ll be prompted normally.
Generate a Template
The rails_apps_composer gem creates an application template as an intermediate step before generating an application. You can generate and save the application template. You may want a template to customize or share with others.
Here’s an example of generating an application template and saving the template to a file:
$ rails_apps_composer template ~/Desktop/template.txt -r haml home_page html5
The command with the template argument followed by a filename and a list of recipes generates an application template.
The rails_apps_composer gem creates an application template that can be used by the rails new command with the -m option. You can specify a local file as a template. For example:
$ rails new myapp -m ~/Desktop/template.txt
The raisl new command allows you to specify the -T -O flags as needed to skip Test::Unit files and Active Record files.
The -m option also allows you to specify a file that can be downloaded via HTTP. This makes it possible to host a template on GitHub (for example) and allow anyone to generate an application from the hosted template. For example:
$ rails new myapp -m https://raw.github.com/RailsApps/rails3-application-templates/master/rails3-haml-html5-template.rb
That’s all it takes. You’ll have a ready-to-use Rails web application in seconds.
Recipe Compatibility
Our goal is to offer a collection of recipes that are known to work well together. The most commonly used recipes will likely work together because many developers have used the recipes and resolved any integration issues.
Some of the recipes in the repository are contributed by developers who use only a few of the recipes. For example, the repository has recipes for Mongoid and OmniAuth that are known to work together. However, we don’t know (for example) if the Mongoid and RailsAdmin recipes work together.
The maintainers and contributors to the project can’t test every combination of recipes. We rely on contributors to alert us to issues and contribute patches as needed. If you find recipes that don’t combine properly, please alert us with a GitHub issue and contribute a fix if you can.
Examples
We use the rails_apps_composer gem to create the Rails Example Apps for the RailsApps project. These example apps have been used by thousands of Rails developers. The recipes used for the RailsApps examples are well-integrated and known to work in the specific combinations listed below.
Template for Rails 3 + Haml + HTML5
This application template will offer you a choice of Haml or ERB, give you options for a CSS front-end framework such as Twitter Bootstrap, and create a default application layout using HTML5:
$ rails_apps_composer template ~/Desktop/template.txt -r haml home_page html5 cleanup extras git
Then generate the application:
$ rails new myapp -m ~/Desktop/template.txt
Template for Prelaunch Signup App
To build an application template for the rails-prelaunch-signup example application, run the command:
$ rails_apps_composer template ~/Desktop/template.txt -r prelaunch_signup
Then generate the application using the -T flag.
$ rails new rails-prelaunch-signup -m ~/Desktop/template.txt -T
Template for Rails 3 + Devise + RSpec + Cucumber
To build an application template for the rails3-devise-rspec-cucumber example application, run the command:
$ rails_apps_composer template ~/Desktop/template.txt -r haml rspec cucumber guard action_mailer devise add_user home_page home_page_users seed_database users_page html5 simple_form cleanup extras git
Then generate the application using the -T flag.
$ rails new rails3-devise-rspec-cucumber -m ~/Desktop/template.txt -T
Template for Rails 3 + Mongoid + Devise
To build an application template for the rails3-mongoid-devise example application, run the command:
$ rails_apps_composer template ~/Desktop/template.txt -r haml rspec cucumber guard mongoid action_mailer devise add_user home_page home_page_users seed_database users_page html5 simple_form cleanup extras git
Then generate the application using the -T -O flags.
$ rails new rails3-mongoid-devise -m ~/Desktop/template.txt -T -O
Template for Rails 3 + Mongoid + OmniAuth
To build an application template for the rails3-mongoid-omniauth example application, run the command:
$ rails_apps_composer template ~/Desktop/template.txt -r haml rspec cucumber guard mongoid seed_database omniauth home_page home_page_users html5 simple_form users_page omniauth_email cleanup extras git
Then generate the application using the -T -O flags.
$ rails new rails3-mongoid-omniauth -m ~/Desktop/template.txt -T -O
Template for Rails 3 + Subdomains
To build an application template for the rails3-subdomains example application, run the command:
$ rails_apps_composer template ~/Desktop/template.txt -r haml rspec cucumber guard mongoid action_mailer devise add_user home_page home_page_users seed_database users_page subdomains html5 simple_form cleanup extras git
Then generate the application using the -T -O flags.
$ rails new rails3-subdomains -m ~/Desktop/template.txt -T -O
Changing the Gem
Your patches and improvements are welcome. Fork the repository and clone the project locally.
You’ll need to install the gems that are dependencies for development:
$ gem install activesupport i18n thor mg
Add or modify recipes as needed.
To build and install the modified gem locally:
$ gem uninstall rails_apps_composer $ rake gem $ rake gem:install
When you are happy with your changes, submit a pull request and I will review your contribution and publish an updated version of the gem for everyone to use.
Writing New Recipes
You can find the rails_apps_composer recipe collection in the GitHub repository’s recipes directory. If you find errors or improve a recipe you can contribute to the project by submitting a pull request or creating a Github issue.
Warning: Gnarly Code Ahead!
The best (and only) way to create a new recipe (or customize an existing one) is to examine several recipes to learn how they work. The extras recipe is a good place to start. Some recipes, such as the add_user recipe, are very complex with multiple preferences and dependencies on other recipes.
Frankly, the recipe code (and the resulting application template) can be ugly. The code is not much more than a long procedural script with conditional statements to resolve dependencies or enable preferences, interspersed with snippets of template code that is injected into files. The inline template code (for example, code that sets up a Rails “view” file) is particularly ugly because it has to be indented to conform to its destination file, often making the recipe difficult to read. Nevertheless, the project has value and many developers have contributed recipes and added features.
Rails Wizard Basics
For more information on all available options for authoring recipes that can be read by the rails_wizard or rails_apps_composer gems, please see the wiki for Michael Bleigh’s RailsWizard gem.
Recipes are made of up template code and YAML back-matter stored in a ruby file. The __END__ parsing convention is used so that each recipe is actually a valid, parseable Ruby file. The structure of a recipe looks something like this:
gem 'supergem' after_bundler do generate "supergem:install" end __END__ category: templating name: SuperGem description: Installs SuperGem which is useful for things author: mbleigh
Rails_apps_composer Differences
The rails_apps_composer gem is very similar to the rails_wizard gem, with one significant difference. The rails_wizard gem is supposed to allow specification of execution order for recipes with run_before and run_after configuration flags (though the rails_wizard implentation has been reported as buggy). The rails_apps_composer gem supports only the run_after flag; additionally, the order in which you provide the recipes sets the execution order. This makes it easier to chain a series of recipes in the order you prefer. For example,
$ rails_apps_composer new myapp -r git haml
installs git before haml.
Rails Wizard RSpec Tests
The gem has RSpec tests that automatically validate each recipe in the repository, so you should run rake spec as a basic syntax check. Note that these don’t verify that your recipe code itself works, just that the gem could properly parse and understand your recipe file.
How It Works
Rails generators can use any methods provided by the Thor::Actions module. The flexibility of mixing “recipes” for application templates comes from use of the apply method from the Thor::Actions module. Given a web address or a local filepath, the apply method loads and executes a file within the context of the generator script.
Documentation and Support
This is the only documentation.
Writing Recipes
To understand the code in these templates, take a look at Thor::Actions. Your recipes can use any methods provided by Thor::Actions or Rails::Generators::Actions.
About Rails Application Templates
Cooking Up A Custom Rails 3 Template (11 Oct 2010) by Andrea Singh
Rails Application Templates (16 Sept 2010) by Collin Schaafsma
Application templates in Rails 3 (18 Sept 2009) by Ben Scofield
Railscasts: App Templates in Rails 2.3 (9 Feb 2009) by Ryan Bates
Rails templates (4 Dec 2008) by Pratik Naik
Credits
Daniel Kehoe maintains this gem as part of the RailsApps Project.
This gem is based on Michael Bleigh’s RailsWizard gem. The original idea for a RailsWizard and the innovative implementation is the work of Michael Bleigh.
Please see the CHANGELOG for a list of contributors.
What You Can Do
Is the gem useful to you? Follow the project on Twitter:
@rails_apps
and tweet some praise. I’d love to know you were helped out by the gem.
License
MIT License
The rails_apps_composer gem and its recipes are distributed under the MIT License.