Skip to content

README.md

Latest commit

 

History

History
277 lines (217 loc) · 11.1 KB

README.md

File metadata and controls

277 lines (217 loc) · 11.1 KB

Rails Application Template

A comprehensive Rails application template with modern best practices, testing tools, and development utilities.

Features

Core Stack

  • PostgreSQL 18+ database
  • RSpec for testing
  • StandardRB for Ruby linting
  • CSS framework of your choice (Bootstrap or Tailwind)
  • Esbuild for JavaScript (with --javascript=esbuild)

Development & Debugging Tools

  • debug - Modern Ruby debugger (breakpoints with debugger)
  • pry - Enhanced REPL (bundle exec pry -r ./config/environment)
  • (Temporarily disabled) better_errors + binding_of_caller - Better error pages with REPL (waiting on Ruby 4 compatibility)
  • amazing_print - Pretty-print Ruby objects (replaces deprecated awesome_print)
  • bullet - N+1 query detection
  • goldiloader - Automatic N+1 prevention (optional, default: enabled)
  • rack-mini-profiler - Performance profiling (optional, default: enabled)

Testing Suite

  • RSpec Rails with proper configuration
  • Capybara + Selenium for system testing
  • Factory Bot for test factories
  • Shoulda Matchers for one-liner tests (optional, default: enabled)
  • Faker for test data generation (optional, default: enabled)
  • SimpleCov for code coverage reporting (optional, default: enabled)
  • WebMock for HTTP request stubbing (optional, default: disabled)

Code Quality & Linting

  • StandardRB + Standard-Rails for Ruby
  • Herb - HTML+ERB linting and analysis
  • Prettier for JavaScript/CSS formatting (optional, default: disabled)
  • ESLint with Thoughtbot configuration (optional, default: disabled)
  • Stylelint with Thoughtbot configuration (optional, default: disabled)
  • erb_lint + better_html for ERB template linting (only when full linting stack is enabled)

Documentation & Visualization

  • AnnotateRb - Automatic model schema annotations (replaces deprecated annotate gem)
  • Rails ERD - Entity relationship diagram generation (optional, default: enabled)
  • rails_db - Web UI for database browsing (optional, default: disabled)

Security & Safety

  • Brakeman - Security vulnerability scanning
  • Brakeman & Bundler Audit - Security scanning (Rails 8.1 defaults)

Monitoring & Analytics

  • Error Monitoring - Choose between Rollbar (default), Honeybadger, or None (optional)
  • Skylight - Production performance monitoring (optional, default: enabled)
  • Ahoy + Blazer - Analytics tracking and SQL-based dashboard (optional, default: enabled)

Environment & Configuration

  • dotenv - Environment variable management (replaces dotenv-rails)
  • Force SSL in production
  • Enhanced production logging
  • Database Options:
    • Optional UUID primary keys (UUIDv7 default when enabled; UUIDv4 available)
    • Optional Rails 8 multi-database setup (separate databases for cache/queue/cable) - defaults to single database for simpler deployment

Project Files

  • Comprehensive README template
  • CONTRIBUTING.md guidelines
  • .env.example with common configurations
  • .node-version for Node.js version management

Usage

With Bootstrap

rails new my_app \
  --database=postgresql \
  --javascript=esbuild \
  --css=bootstrap \
  --skip-test \
  --skip-kamal \
  --skip-rubocop \
  --template=https://raw.githubusercontent.com/firstdraft/rails_application_template/main/template.rb

With Tailwind

rails new my_app \
  --database=postgresql \
  --javascript=esbuild \
  --css=tailwind \
  --skip-test \
  --skip-kamal \
  --skip-rubocop \
  --template=https://raw.githubusercontent.com/firstdraft/rails_application_template/main/template.rb

Tailwind customization is handled through the tailwind.config.js file that Rails generates automatically. See Tailwind's configuration docs for details.

Recommended Flags

  • --database=postgresql - Use PostgreSQL (required)
  • --javascript=esbuild - Fast JavaScript bundling
  • --css=bootstrap or --css=tailwind - CSS framework of your choice
  • --skip-test - Skip Minitest (we use RSpec)
  • --skip-rubocop - Skip default RuboCop (we use StandardRB)
  • --skip-kamal - Skip Kamal deployment (unless you need it)

Interactive Options

The template offers two modes:

  1. Default Configuration (recommended): Includes most tools with sensible defaults
  2. Custom Configuration: Interactive prompts to choose which tools to include

If you choose custom configuration, you'll be prompted for:

  • Testing Tools: SimpleCov, Shoulda Matchers, Faker, WebMock
  • Performance Tools: Goldiloader, rack-mini-profiler, Skylight
  • Analytics: Ahoy + Blazer for tracking and dashboards
  • Documentation Tools: Rails ERD, rails_db browser
  • Error Monitoring: Rollbar, Honeybadger, or None
  • Frontend Tools: Bootstrap overrides (only when using --css=bootstrap), full linting stack (Prettier, ESLint, Stylelint)
  • Database Configuration:
    • UUID primary keys vs. standard integers (choose UUIDv7 or UUIDv4; default is UUIDv7)
    • Rails 8 multi-database setup (separate databases for cache/queue/cable) vs. single database
  • Deployment: Render.com-specific configuration (build script, render.yaml blueprint, tier/database provider selection, optional worker service, optional custom domain checklist)
  • CI/CD: GitHub Actions CI workflow (.github/workflows/ci.yml)

What Gets Configured

Testing

  • RSpec with random test order
  • Test example persistence for re-running failed tests
  • SimpleCov for coverage (run with COVERAGE=true bundle exec rspec)
  • WebMock configured with Chrome driver whitelisting
  • Factory Bot and Shoulda Matchers support files

Linting

  • StandardRB configuration for Ruby
  • Herb configuration for HTML+ERB
  • Optional full frontend linting stack (Prettier, ESLint, Stylelint) and erb_lint/better_html
  • All with proper ignore patterns and configurations

Development Tools

  • Bullet enabled with console and footer output
  • AnnotateRb configuration for model annotations
  • Rails ERD with Bachman notation

Git Workflow

  • Incremental commits after each configuration step
  • Clean git history showing the setup progression

CI/CD (Optional)

  • GitHub Actions workflow with Postgres service, asset build, security scans, linting, and RSpec

Available Commands

After creating your app, these commands are available:

Development

bin/dev                        # Start development server (includes web, JS/CSS compilation, and SolidQueue worker)
rails console                  # Enhanced console with Pry

Note: When using bin/dev (apps with JavaScript/CSS compilation), the template automatically configures SolidQueue to run in development, matching production behavior and helping catch job-related issues early.

Testing

bundle exec rspec              # Run test suite
COVERAGE=true bundle exec rspec # Run with coverage report

Linting & Formatting

# Ruby
bundle exec standardrb         # Check Ruby code
bundle exec standardrb --fix   # Fix Ruby issues

# HTML+ERB
bundle exec herb analyze .     # Analyze HTML+ERB (views/components)

# JavaScript/CSS (only if full linting stack is enabled)
yarn lint                      # Check JS/CSS
yarn fix:prettier              # Fix JS/CSS formatting

# ERB Templates (only if full linting stack is enabled)
bundle exec erb_lint --lint-all              # Check ERB
bundle exec erb_lint --lint-all --autocorrect # Fix ERB

Security

bundle exec brakeman           # Security scan
bundle exec bundle-audit check # Check for vulnerable gems

Documentation

bundle exec erd                # Generate ERD diagram
bundle exec annotaterb models  # Update model annotations

Database

Visit /rails_db in development for web UI (if enabled)

Analytics & Monitoring

Visit /blazer for analytics dashboard (if Ahoy + Blazer enabled)

Background Jobs

The template uses Rails 8's default Solid Queue for background job processing.

Development

  • When using bin/dev (apps with JS/CSS compilation), SolidQueue runs automatically as a worker process
  • Development environment is configured to use :solid_queue adapter
  • This matches production behavior and helps catch job-related issues early

Production

Deployment

This template creates apps configured for generic production deployment, suitable for any modern hosting platform.

Render.com (Optional)

When enabled during setup, the template generates Render.com-specific configuration:

  • bin/render-build.sh - Automated build script for dependencies and assets (migrations run in preDeployCommand)
  • render.yaml - Blueprint file with web service configuration and optional database provisioning
  • Health check endpoint (/up) configuration
  • Tier selection (free vs paid) that adjusts defaults like WEB_CONCURRENCY
  • Database provider selection (Render Postgres or Supabase; free tier defaults to Supabase)
  • Choice between Solid Queue as a Puma plugin or separate worker service
  • Environment variable guidance for RAILS_MASTER_KEY and WEB_CONCURRENCY
  • RENDER_DEPLOYMENT.md - Per-project checklist (includes optional Supabase setup steps and optional custom domain DNS guidance)

See Render's Rails 8 deployment guide for more details.

Other Platforms

The template works with minimal or no configuration changes on:

  • Fly.io
  • Railway
  • Heroku
  • Any platform supporting Rails 8 and PostgreSQL 18+

Differences from Original

This is an enhanced version of the original firstdraft template with:

  • Interactive Customization: Choose which tools to include or use sensible defaults
  • Updated Gems: amazing_print, annotaterb, dotenv (replacing deprecated versions)
  • Testing Tools: SimpleCov, WebMock, Shoulda Matchers, Faker
  • Linting Stack: StandardRB + Standard-Rails, Herb; optional Prettier, ESLint, Stylelint, erb_lint
  • Security Tools: Brakeman, bundler-audit (Rails 8.1 defaults)
  • Performance Tools: Goldiloader, rack-mini-profiler, Skylight
  • Monitoring & Analytics: Error monitoring (Rollbar/Honeybadger), Ahoy + Blazer
  • Database Flexibility: Single vs. multi-database setup, UUID support
  • Deployment Options: Render.com-specific configuration available
  • CI/CD: Optional GitHub Actions workflow
  • Modern Production Configuration: Generic setup for any platform
  • Comprehensive Documentation: Detailed README and contributing guidelines

Contributing

Pull requests are welcome! Please ensure any new gems or configurations:

  1. Are actively maintained
  2. Add clear value for most Rails applications
  3. Include appropriate documentation
  4. Follow the incremental commit pattern

License

MIT