RnStack: The Professional Hybrid Framework

rn_stack is a production-grade Rails Engine that bridges the gap between Ruby on Rails and the modern, high-performance architectural patterns popularized by Next.js and Angular.

It provides a unified integration layer, allowing you to build polyglot applications that seamlessly mix Rails (ERB/Stimulus), React, and TypeScript.

📑 Table of Contents

🚀 Getting Started

1. Installation

Add to your Gemfile:

gem "rn_stack", path: "path/to/rn_stack"

2. Initialization

Run the setup script to configure Rails, Vite, and Databases:

chmod +x bin/setup_script
bin/setup_script

3. Development

Create a Procfile.dev to manage backend and frontend services:

web: bundle exec rails s
vite: bin/vite dev

Run development:

gem install foreman
foreman start -f Procfile.dev

💡 Learning & Examples

Generate runnable, real-world architectural blueprints:

# Scaffold a full blog system
rails generate rn_stack:example blog

# Scaffold a starter dashboard
rails generate rn_stack:example dashboard

🛠️ The CLI Productivity Suite

rn_stack provides a powerful CLI suite for rapid development.

CLI Productivity Suite

Task Command
Pages rails generate rn_stack:page [name]
API Handlers rails generate rn_stack:api [name]
Maintenance bundle exec rake rn_stack:maintenance
MVC Scaffold rails generate rn_stack:scaffold [model] [attrs]
UI Components rails generate rn_stack:ui
Jobs rails generate rn_stack:job [name]

Architecture, Security & Enterprise

Task Command
Services/Stores rails generate rn_stack:service [name] \
Auth/RBAC rails generate rn_stack:auth
Security/I18n rails generate rn_stack:security \
Media/Mailer rails generate rn_stack:media [model] [field] \
Prod/Deploy rails generate rn_stack:production \
Monitoring/Doc/Version rails generate rn_stack:monitor \

🏗️ Core Architecture Concepts

rn_stack enforces a professional separation of concerns:

  • Routing: File-system based (app/pages, app/api).
  • Logic: app/services for business logic, RnStack::Action for data mutations.
  • State: app/frontend/stores for reactive frontend state.
  • Assets: Vite pipeline (Rails, React, TypeScript, Stimulus).
  • Media: Professional helpers (pro_image_tag, pro_audio_tag, pro_video_tag).

📖 Usage Examples

1. File-System Routing (Static & Dynamic)

  • Static: app/pages/about.html.erb -> /about
  • Dynamic: app/pages/users/[id].html.erb -> /users/:id All routes are automatically registered and wrapped in your default layout.

2. High-Performance Media

<%= pro_image_tag @user.avatar, size: [300, 300] %>
<%= pro_audio_tag "track.mp3" %>
<%= pro_video_tag "movie.mp4" %>

2. SEO & Performance

<% set_metadata(title: "My Page", description: "SEO Description") %>

<% with_isr_cache("sidebar", expires_in: 30.minutes) do %>
  <%= render "sidebar" %>
<% end %>

<%= self_hosted_font_tag "my-font" %>

3. Searching & Filtering (using Ransack)

@q = Product.ransack(params[:q])
@products = @q.result(distinct: true)

🚀 Production Readiness Checklist

  1. [ ] Infrastructure: Run rails generate rn_stack:production.
  2. [ ] Observability: Run rails generate rn_stack:monitor.
  3. [ ] Containerization: Run rails generate rn_stack:deployment.
  4. [ ] Security: Run rails generate rn_stack:security.
  5. [ ] Assets: Ensure bin/vite build is configured for production.

🧪 Testing, Debugging & Configuration

  • Testing: Use standard bundle exec rake test and Capybara for full-stack integration.
  • Debugging: Standard Rails logging (Rails.logger) and Vite HMR console.
  • Configuration: Create config/initializers/rn_stack.rb to tune framework defaults.

🚀 CI/CD & Team Conventions

CI/CD Pipeline (GitHub Actions)

Example workflow for rn_stack applications (.github/workflows/ci.yml):

name: CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true
      - name: Run Tests
        run: bundle exec rake test

📝 Architecture Overview

See ARCHITECTURE.md for a deep dive into the design philosophy.

License

MIT