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.