Inertia Rails Best Practices

Inertia Rails Best Practices

A comprehensive guide to building high-quality Inertia.js applications with Ruby on Rails. This skill provides 50+ rules across 8 categories, prioritized by impact on application quality, performance, and maintainability.

When to Use This Skill

• Writing new Inertia Rails controllers or pages
• Reviewing existing Inertia Rails code
• Refactoring Rails applications to use Inertia
• Optimizing performance of Inertia applications
• Implementing authentication/authorization patterns
• Building forms with validation
• Setting up testing for Inertia responses

Categories Overview

| # | Category | Priority | Impact | |---|----------|----------|--------| | 1 | [Server-Side Setup & Configuration](#1-server-side-setup--configuration) | CRITICAL | Foundation for all Inertia functionality | | 2 | [Props & Data Management](#2-props--data-management) | CRITICAL | 2-5× performance improvement, security | | 3 | [Forms & Validation](#3-forms--validation) | HIGH | User experience, data integrity | | 4 | [Navigation & Routing](#4-navigation--routing) | HIGH | SPA experience, performance | | 5 | [Performance Optimization](#5-performance-optimization) | MEDIUM-HIGH | 30-70% faster page loads | | 6 | [Security](#6-security) | MEDIUM-HIGH | Protection against common vulnerabilities | | 7 | [Testing](#7-testing) | MEDIUM | Code quality, maintainability | | 8 | [Advanced Patterns](#8-advanced-patterns) | MEDIUM | Scalability, complex use cases |

Quick Reference

Server-Side Setup & Configuration (CRITICAL)

| ID | Rule | Context | |----|------|---------| | setup-01 | Use the Rails generator for initial setup | New projects | | setup-02 | Configure asset versioning for cache busting | All projects | | setup-03 | Set up proper layout inheritance | Multi-layout apps | | setup-04 | Configure flash keys appropriately | Flash messaging | | setup-05 | Use environment variables for configuration | Deployment | | setup-06 | Set up default render behavior thoughtfully | Convention over configuration |

Props & Data Management (CRITICAL)

| ID | Rule | Context | |----|------|---------| | props-01 | Return only necessary data in props | All responses | | props-02 | Use shared data for global props | Auth, settings | | props-03 | Leverage lazy evaluation with lambdas | Expensive operations | | props-04 | Use deferred props for non-critical data | Performance | | props-05 | Implement partial reloads correctly | Data refreshing | | props-06 | Never expose sensitive data in props | Security | | props-07 | Use proper serialization with as_json | Data formatting | | props-08 | Implement deep merge when appropriate | Nested data | | props-09 | Use once props for stable data | Navigation performance | | props-10 | Use prop transformer for consistent naming | camelCase conversion |

Forms & Validation (HIGH)

| ID | Rule | Context | |----|------|---------| | forms-01 | Use useForm helper for complex forms | Programmatic control | | forms-02 | Use Form component for simple forms | Declarative forms | | forms-03 | Handle validation errors properly | User feedback | | forms-04 | Implement error bags for multiple forms | Multi-form pages | | forms-05 | Use redirect pattern after form submission | PRG pattern | | forms-06 | Handle file uploads correctly | Multipart forms | | forms-07 | Preserve form state on validation errors | User experience | | forms-08 | Use dotted notation for nested data | Complex forms | | forms-09 | Use precognition for real-time validation | Server validation | | forms-10 | Use useHttp for non-navigating requests | API calls |

Navigation & Routing (HIGH)

| ID | Rule | Context | |----|------|---------| | nav-01 | Use Link component for internal navigation | SPA behavior | | nav-02 | Use inertia_location for external redirects | External URLs | | nav-03 | Implement preserve-scroll appropriately | Scroll position | | nav-04 | Use preserve-state for component state | Form preservation | | nav-05 | Configure proper HTTP methods on links | RESTful actions | | nav-06 | Use the inertia route helper for static pages | Simple routes | | nav-07 | Handle 303 redirects correctly | POST/PUT/PATCH/DELETE | | nav-08 | Use instant visits for perceived performance | Fast navigation |

Performance Optimization (MEDIUM-HIGH)

| ID | Rule | Context | |----|------|---------| | perf-01 | Implement code splitting with dynamic imports | Bundle size | | perf-02 | Use prefetching for likely navigation | Perceived performance | | perf-03 | Configure stale-while-revalidate caching | Data freshness | | perf-04 | Use polling only when necessary | Real-time updates | | perf-05 | Implement infinite scrolling with merge props | Large datasets | | perf-06 | Optimize progress indicators | User feedback | | perf-07 | Use async visits for non-blocking operations | Background tasks | | perf-08 | Use InfiniteScroll component for pagination | Large datasets | | perf-09 | Enable view transitions for smooth animations | Page transitions |

Security (MEDIUM-HIGH)

| ID | Rule | Context | |----|------|---------| | sec-01 | Implement authentication server-side | Auth patterns | | sec-02 | Pass authorization results as props | Permission checks | | sec-03 | Use history encryption for sensitive data | Browser history | | sec-04 | Rely on Rails CSRF protection | Form security | | sec-05 | Validate and sanitize all input server-side | Data validation | | sec-06 | Use strong parameters in controllers | Mass assignment |

Testing (MEDIUM)

| ID | Rule | Context | |----|------|---------| | test-01 | Use RSpec matchers for Inertia responses | RSpec testing | | test-02 | Use Minitest assertions for Inertia | Minitest testing | | test-03 | Test partial reloads and deferred props | Advanced features | | test-04 | Implement end-to-end tests with Capybara | Integration testing | | test-05 | Test flash messages after redirects | Flash testing | | test-06 | Verify component rendering | Response validation |

Advanced Patterns (MEDIUM)

| ID | Rule | Context | |----|------|---------| | adv-01 | Implement persistent layouts | State preservation | | adv-02 | Use custom component path resolvers | Non-standard paths | | adv-03 | Configure prop transformers | Data transformation | | adv-04 | Handle SSR appropriately | SEO requirements | | adv-05 | Implement view transitions | Modern animations | | adv-06 | Use scroll regions for complex layouts | Scroll management | | adv-07 | Handle events system effectively | Lifecycle hooks | | adv-08 | Use layout props for page-layout communication | Layout data | | adv-09 | Configure the Vite plugin for optimal DX | Project setup |

---

For detailed explanations, code examples, and implementation guidance for each rule, see [AGENTS.md](references/AGENTS.md).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cole-robertson
• Source: cole-robertson/inertia-rails-skills
• License: MIT

Install and usage instructions live in the source repository linked above.