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
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.
