Potassium

A Rails application generator from Platanus, inspired by Suspenders.

Installation

Just install it globally:

$ gem install potassium

Usage

Use the potassium command to create a new project:

$ potassium create project-name

It's important to note that it will perform a version check before running to ensure that you're using the latest potassium.

What's inside Potassium?

Potassium Rails apps includes the following gems and technologies:

rbenv for managing the project's ruby version.
rbenv-vars for keeping secrets and by-server configurations.
Bower for frontend assets packages.
EditorConfig for keeping all our editor configurations the same.
pry and pry-byebug for a less painful debugging experience.
RSpec for unit and integration testing.
FactoryGirl for test factories.
Guard for continuous testing and other watch-related tasks.
AWS-SDK for file uploads, sdks, etc and because we use AWS.

The following optional integrations are added too:

PostgreSQL or MySQL for the database.
Devise for authentication.
ActiveAdmin for admin interfaces.
ActiveAdminAddons for some help with ActiveAdmin.
Pundit for role-based authorization.

And, finally, we also include optional API support, which includes:

Responders for dry-ing our api controllers.
Versionist for some flexible api versioning.
ActiveModel::Serializers for record serialization.
Simple Token Authentication for stateless API authentication.

Contributing

How do I add something new to Potassium?

In the lib/potassium/templates/application folder, you will find the template. You should follow the next conventions to add something:

NOTE: If you only want to use Potassium but not to add something new, the next parts can be easily skipped.

Ask

If you need to ask something to the user before doing something, follow the next steps:

Create a ruby file on the recipes/asks folder.
Then, ask something using the methods defined in Inquirer, that we use by default. Use the DSL to store some information.
Finally, register the ask you created in the template:

  run_action(:asking) do
    # ...
    eval_file "recipes/asks/my_ask.rb"
  end

Install

Now, to add some behavior, thanks to the DSL we have a kind of standard flow of what happens when a new project is created. To understand this better, please read the template. The structure looks like this:

Clean the Gemfile and add the base gems that rails needs to work.
Run all the asks recipes.
Execute all the recipes, that are ruby files stored on the recipes folder. They specify what gems are needed and registers callbacks based on this process, usually to execute things after the gem installation happened or after some other recipe finished his work.
Install the gems, filling the Gemfile before with all the gathered gems.
Finally, create the database.

The main step is the 3rd, when we run the recipes. A recipe can do anything (because is a ruby script) but their responsability should be to gather gems and register callbacks for the process.

For example, if we want to create an optional recipe to add a gem called banana_split that needs to run a generator, we can do the following.

Create the ask file:

  # application/recipes/ask/banana_split.rb
  use_banana_split = Ask.confirm("Do you want to use Banana Split?")
  set(:use_banana_split, true) if use_banana_split

Then, register the ask:

  run_action(:asking) do
    # ...
    eval_file "recipes/asks/banana_split.rb"
  end

Create the recipe. Register a gem using gather_gem and create a callback to be called after the gem_install action succeded to run the generator. gem_install is one of the main actions that should be easily visible with a sneak peek in the template.

  # application/recipes/banana_split.rb
  if get(:use_banana_split)
    gather_gem('banana_split', '~> 1.2')

    after(:gem_install) do
      generate('banana_split:install')
    end
  end

  run_action(:recipe_loading) do
    # ...
    eval_file "recipes/banana_split.rb"
  end

Ready, let's start working on your new project.

The DSL

To see further documentation of what we added to the rails template's DSL, check the DSL documentation. Remember that the DSL we are documenting is an extension over the Rails Application Template DSL, that itself is a dsl based on Thor.

Credits

Thank you contributors!

Platanus

potassium is maintained by platanus.