Rails Apps Composer 2.1

The Rails Apps Composer gem installs a command line tool to assemble a Rails application from a collection of “recipes.”

What you can do with the rails_apps_composer gem:

create a starter app from the command line
make a reusable application template

You can use local recipes as well as recipes supplied with the gem.

The Rails Composer tool is built with the rails_apps_composer gem. The Rails Composer tool creates the example applications for the RailsApps project.

The Guide to the Rails Apps Composer Gem provides complete documentation:

Any issues? Please create a GitHub issue.

Follow on Twitter

Follow the project on Twitter: @rails_apps. Tweet some praise if you like what you’ve found.

What’s New

See the CHANGELOG for details.

Version 2.1

use local recipes

Version 2.0

the Guide provides complete documentation
diagnostics compare your selected recipes and preferences to known working combinations
the generated application README.textile file provides a diagnostics report
an improved “quiz” sets preferences
a new preferences hash makes preferences available to all recipes
recipes and preferences can be set in a defaults file
gems can be added at a prompt or from a defaults file (no need to write a recipe for many gems)
a new ‘copy_from_repo’ method adds powerful downloading of files to any recipe
downloading of files from the example app repos reduces the complexity of recipes
the ‘copy_from_repo’ method converts ERB files to Haml or Slim
recipes have been reorganized for easier maintenance
recipes are based on functionality (e.g., authentication, testing) instead of gems (Devise, RSpec)
a prompt sets -T or -O args when generating an application
the ‘extras’ recipe creates a project-specific gemset and .rvmrc file

Most important, many unsupported or outdated recipes have been removed. If your favorite recipe is missing, please update it and test it with version 2.0, then submit a pull request. I’m happy to add new recipes.

Who This Is For

This gem is for experienced Rails developers who need a tool to create and maintain a Rails starter app or Rails application template. If you’re regularly building Rails applications that use certain popular gems or rely on common functionality such as authentication, you can benefit from the rails_apps_composer gem.

If you are new to Rails, try the Rails Composer tool instead. It provides an application template that is generated from the rails_apps_composer gem’s core recipes. It is easier to use.

Alternatives

The rails_apps_composer gem is derived from Michael Bleigh’s RailsWizard gem. Early versions of the rails_apps_composer gem were a close fork of Michael Bleigh’s gem; rails_apps_composer 2.0 differs substantially. Other 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” for similar projects.

Dependencies

Before using the rails_apps_composer gem, you will need:

The Ruby language (version 1.9.3)
Rails 3.1 or newer

See the article Installing Rails for advice about updating Rails and your development environment.

Installation

I recommend installing and using rvm, the Ruby Version Manager, to create a new gemset for rails_apps_composer. Using an rvm gemset will make it easier to identify and isolate incompatibilities among gems.

Installation is simple:

$ gem install rails_apps_composer

Usage

These commands are summarized here for your reference. See the Guide to the Rails Apps Composer Gem for details.

List Recipes

You can list recipes with short descriptions:


$ rails_apps_composer list

auth           # Add authentication and authorization.
controllers    # Add controllers needed for starter apps.
database       # Set up and initialize database.
email          # Configure email accounts.
extras         # Various extras.
frontend       # Install a front-end framework for HTML5 and CSS.
gems           # Add the gems your application needs.
models         # Add models needed for starter apps.
prelaunch      # Generates a Prelaunch Signup App
readme         # Build a README file for your application.
routes         # Add routes needed for starter apps.
setup          # Make choices for your application.
testing        # Add testing framework.
views          # Add views needed for starter apps.

The above list is current for rails_apps_composer 2.0; later releases will contain more recipes.

You can learn more about the available recipes by examing the source code in the repository recipes directory.

Recipe Order and Interdependency

The order in which you input a list or recipes determines the order of execution unless a recipe contains a requires or run_after directive.

A recipe may contain a requires directive which specifies other recipes which must be present before a recipe can run. The requires constraint will force the rails_apps_composer program to load any required recipes, even if you don’t add them explicitly.

Recipes may also contain a run_after directive. The rails_apps_composer program will organize the order of execution so that any recipes in the run_after list will execute earlier. That is, the recipe will run after everything else in the list.

In general, it’s best to add (or list) recipes in the order they should execute as some recipes may not contain a necessary requires or run_after directive.

See the Anatomy of a Recipe section in the Guide to learn about the format of a recipe.

Skipping Test::Unit or Active Record

If you plan to use RSpec instead of Test::Unit, or use an ORM such as Mongoid instead of Active Record, you can pass the -T or -O flags to the rails new command so it will skip Test::Unit or Active Record.

When you generate an application interactively using the rails_apps_composer gem, the program will ask if you want to skip Test::Unit or Active Record.

When you generate an application template, you will not be asked if you want to skip Test::Unit or Active Record. An application template runs after the rails new command so it cannot set the -T or -O arguments.

Any recipe can set the -T or -O arguments using the args directive. However, this has no affect on application templates and is only useful when an application is generated interactively.

Generate an Application Interactively

You’ll be prompted for recipes and gems:


$ rails_apps_composer new myapp

Would you like to skip Test::Unit? (yes for RSpec) (y/n)
Would you like to skip Active Record? (yes for NoSQL) (y/n)

Available Recipes:
apps: prelaunch
auth: auth
configuration: email, gems, readme, setup
example: example
frontend: frontend
initialize: database
mvc: controllers, models, routes, views
other: extras
testing: testing

Which recipe would you like to add? (blank to finish)
What gem would you like to add? (blank to finish)

Generating basic application, using:
"rails new myapp -m <temp_file>"

You will only be able to choose recipes that are contained in the rails_apps_composer gem.

You can specify any gem. Any string you enter will be added as a gem in the starter app Gemfile.

Generate an Application from a List of Recipes

Provide a list of recipes:


$ rails_apps_composer new myapp -r setup readme gems testing auth email models controllers views routes frontend database extras

Would you like to skip Test::Unit? (yes for RSpec) (y/n)
Would you like to skip Active Record? (yes for NoSQL) (y/n)
What gem would you like to add? (blank to finish) 

Generating basic application, using:
"rails new myapp -m <temp_file>"

The program will prompt you for your preferences before generating an application.

Generate an Application from Defaults

Use a defaults file for recipes, preferences, and extra gems so you don’t have to provide them interactively. Then generate an application with:


$ rails_apps_composer new myapp --defaults=my_defaults.yaml

Use the my_defaults.yaml file to specify a list of recipes, preferences, and extra gems. You can use any name (and file extension) for the file. See the Defaults File section in the Guide to learn about the format of the defaults file.

Generate an Application Template Interactively

You may want an application template to share with others. For an example of an application template, see the Rails Composer tool or various application templates from the RailsApps project.

Specify a filename for the template:


$ rails_apps_composer template ~/Desktop/template.rb

Available Recipes:
apps: prelaunch
auth: auth
configuration: email, gems, readme, setup
example: example
frontend: frontend
initialize: database
mvc: controllers, models, routes, views
other: extras
testing: testing

Which recipe would you like to add? (blank to finish) 
What gem would you like to add? (blank to finish)
Generating and saving application template...
Done.

The command with the template argument followed by a filename generates an application template. You can add additional recipes or gems when prompted.

Generate an Application Template from a List of Recipes

Specify a filename for the template and provide a list of recipes:


$ rails_apps_composer template ~/Desktop/template.rb -r setup readme gems testing auth email models controllers views routes frontend database extras

What gem would you like to add? (blank to finish)
Generating and saving application template...
Done.

The command with the template argument followed by a filename and a list of recipes generates an application template.

Generate an Application Template from Defaults

Generate an application template using a defaults file:


$ rails_apps_composer template ~/Desktop/template.rb --defaults=my_defaults.yaml

Generate an Application from a Template

After you’ve created a template file, you can generate an application from a template at any time using the rails new command with the -m option:


$ rails new myapp -m ~/Desktop/template.rb

The application template will prompt you for any configuration preferences requested by the recipes.

The rails new command allows you to specify the -T -O flags to skip Test::Unit files and Active Record files when you use an application template.


$ rails new myapp -m ~/Desktop/template.rb -T -O

The rails new command with the -m option also allows you to specify an application template 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/rails-composer/master/composer.rb

Diagnostics

The rails_apps_composer program runs diagnostics to reveal whether you’ve picked recipes and preferences that are known to work together.

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 a drawback to 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 or preferences may not work.

The rails_apps_composer gem contains an internal database of combinations of recipes and preferences that are known to work together. If you’ve picked recipes and preferences that are known to work together, you’ll get a confirmation:


WOOT! The recipes you've selected are known to work together.
If they don't, open an issue for rails_apps_composer on GitHub.
WOOT! The preferences you've selected are known to work together.
If they don't, open an issue for rails_apps_composer on GitHub.

You’ll get a warning if you’ve picked a combination we don’t know about:


WARNING! The recipes you've selected might not work together.
Help us out by reporting whether this combination works or fails.
WARNING! The preferences you've selected might not work together.
Help us out by reporting whether this combination works or fails.

Go to the GitHub repository to create an issue and let us know if you’ve found a combination of recipes or preferences that work together. If you’ve found a combination that works together, we’ll update the gem’s internal database for the next public release.

When you generate an application, the application’s README.textile file will contain a diagnostics report. Here’s an example of the diagnostics report:


Recipes:
["gems", "readme", "setup"]

Preferences:
{:database=>"sqlite", :templates=>"erb", :email=>"none"}

Please include the diagnostics report when you create an issue on GitHub.

Hacking the Gem

See the Guide to the Rails Apps Composer Gem to learn how to customize the gem either for your own use or to share with others.

Issues

Any issues? Please create an issue on GitHub. Reporting issues (and patching!) helps everyone.

When you generate an application, the application’s README.textile file will contain a diagnostics report. Please include the diagnostics report when you create an issue on GitHub.

Credits

Daniel Kehoe maintains this gem as part of the RailsApps Project.

This gem is derived from Michael Bleigh’s RailsWizard gem. The original idea and the innovative implementation is the work of Michael Bleigh.

Please see the CHANGELOG for a list of contributors.

Is the gem useful to you? Follow the project on Twitter: @rails_apps. I’d love to know you were helped out by the gem.

MIT License (with restriction)

The rails_apps_composer program is licensed under the terms of the MIT License, except portions of the program authored by Daniel Kehoe may not be used to build a website that generates an application template that can be downloaded or used to generate a web application online (for such use, ask for permission).

githalytics.com alpha