Base or "skeleton" application for Ruby on Rails 5.1 projects. Built to minimize the time spent writing boilerplate code and performing repetitive setup tasks.
It comes with a preselected set of tools which I believe to be the most efficient and widely used. If you are looking for greater flexibility, an application template which uses Rails's templating system such as Rails Composer should be a better fit as it allows the user to choose which templating engine, test framework, JS framework and other tools to use.
Although this project is opinionated regarding tool choices, community feedback and contributions are always welcome and highly appreciated.
It consists of a Rails 5.1.3 app, including:
-
A selection of useful gems for development and debugging such as rubocop, brakeman, awesome_print, byebug, and better_errors.
-
Preconfigured test environment, including:
- RSpec, FactoryGirl, Capybara configured to work with Selenium and ChromeDriver, Database Cleaner, and SimpleCov.
- General purpose test helpers, custom matchers and shared examples in spec/support.
-
Preconfigured authentication with the Devise gem.
-
Preconfigured authorization with the Pundit gem.
-
Internationalization (i18n)
- All of the base application's strings are in YML dictionaries. This is arguably a good practice even for single language applications. Having an internationalized base application makes it easier and faster to translate elements like Devise, the layout and error messages when creating a single language app in a non-English language.
- Methods for translating enum attributes, including the generation of translated options for select boxes. Implemented and documented in app/models/application_record.rb
-
jQuery
-
HTML Layouts developed with Bootstrap 3 (bootstrap-sass gem) to use as a starting point, including:
- Navigation bar;
- Displaying of flash messages and validation errors as Bootstrap alerts;
- Role-based layout switching: different layouts for guests (unauthenticated users), ordinary users and admins;
-
Controller concerns such as
SkipAuthorization
. -
User-friendly error messages (flash) on exceptions such as
ActiveRecord::DeleteRestrictionError
andPundit::NotAuthorizedErrorand
. -
User management interface for admins in
/admin/users
with pagination (kaminari gem) and searching/filtering (ransack gem). Accessible only by users with "admin" role. -
Seed users for the development environment. Run
rails db:seed
to create them:- Ordinary user: email:
[email protected]
/ password:Devpass1
- Admin user: email:
[email protected]
/ password:Devpass1
- Ordinary user: email:
-
Contact form built with the mail_form gem.
-
E-mails "sent" in the development environment are saved as html files in
tmp/letter_opener
(letter_opener gem). -
The following JavaScript libraries:
- Select2 for better select boxes.
- SweetAlert2 for better JS popups,
including the replacement of the default
data-confirm
confirmation by a better-looking version. - ZenUtils: a small JavaScript library consisting of utility functions. See app/assets/javascripts/zen-utils.js.
-
SCSS utility classes for alignment, spacing and font size standardization. See app/assets/stylesheets/utility-classes.scss.
-
High test coverage.
- Ruby 2.3+
- Yarn
- Required for running JavaScript-enabled feature specs:
- Selenium
- ChromeDriver
- Xvfb if running feature specs on a console-only (no graphical interface) *nix environment.
Consider using my Zen Rails Development Environment. It consists of a Ubuntu 16.04 (Xenial Xerus) Vagrant VM with all of the above dependencies preinstalled.
Setup tasks such as configuring time zones, default locale and action mailer (e.g., SMTP or transactional e-mail service) are not included in the following steps as they are not specific to this base app.
-
Fork this repository.
-
Clone the forked repository to your machine.
-
Rename the application:
- Required: change the module name in
config/application.rb
fromZenRailsBaseApp
to your application name, in camel case. - Optional: Use your IDE's "search all files" feature to find and
replace the following strings:
- Replace
zen_rails_base_app
byyour_app_name
- Replace
ZEN_RAILS_BASE_APP
byYOUR_APP_NAME
- Replace
Project Name
by the project's name - Replace
[email protected]
manually by the different e-mail addresses that should send and receive e-mails in various parts of the application.
- Replace
- Required: change the module name in
-
Run
bundle install
to install the gems listed in theGemfile
and their dependencies. -
Run
yarn install
to install the front end (JavaScript) packages listed inpackages.json
and their dependencies. -
Configure the databases:
-
If using PostgreSQL, uncomment the
pg
gem from theGemfile
. If using MySQL, uncomment themysql2
gem. -
Uncomment the section of
config/database.yml
corresponding to your chosen DBMS.
-
-
Customise the authentication setup. You may want to change one or more of the following items:
- Aside from Devise's default attributes,
the
User
model also hasrole
,first_name
, andlast_name
attributes. - Aside from the Devise's default modules, this app also uses Confirmable, Timeoutable and Lockable.
- Pundit is used for for authorization. The
User
model has an enum attribute calledrole
. Its possible values are:user
and:admin
. The default value is:user
.
- Aside from Devise's default attributes,
the
-
Customize the application colors by overwriting Bootstrap's variables in
app/assets/stylesheets/global.scss
. -
Remove unused items from the application, such as gems from the
Gemfile
, RSpec helpers, custom matchers and shared examples fromspec/support
.
- Set up CodeClimate with Rubocop, Reek, Brakeman, and ESLint engines.
- Set up continuous integration.
- Use Yarn instead of gems to install front end libraries such as jQuery and Select2.
- Add an asterisk to the labels of required form fields.
- Internationalize and translate the JS front end, mainly
global.js
andzen-utils.js
.
Bug reports
Please use the issue tracker to report any bugs.
Developing
- Create an issue and describe your idea
- Fork it
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -m 'Add some feature')
- Publish the branch (git push origin my-new-feature)
- Create a Pull Request
Released under the MIT License.