Copilot instructions

1---
2description: Rails Hotwire Guide
3applyTo: "app/views/**/*.html.erb,app/javascript/controllers/**/*.js"
4---
5 
6# Rails Hotwire Guide
7 
8## Core Philosophy
9 
10- Send HTML over the wire, not JSON - let the server do the rendering
11- Achieve SPA-like speed without complex JavaScript frameworks
12- Use progressive enhancement - functionality works without JavaScript
13- Keep client-side logic minimal and server-side logic rich
14- Embrace the simplicity of multi-page applications with the speed of SPAs
15 
16## Turbo Drive Principles
17 
18- Enable fast page navigation without full page reloads automatically
19- Intercept all clicks and form submissions by default
20- Maintain scroll position and focus between navigations
21- Cache pages intelligently for instant back/forward navigation
22- Preserve JavaScript state between page visits
23 
24## Turbo Drive Configuration
25 
26- Disable Turbo Drive selectively with `data-turbo="false"`
27- Control navigation behavior with `data-turbo-action` attributes
28- Use `data-turbo-permanent` to persist elements across navigations
29- Configure cache behavior with meta tags
30- Handle navigation events for custom behavior
31 
32## Turbo Frames Principles
33 
34- Decompose pages into independent segments that update separately
35- Scope navigation to frame boundaries automatically
36- Enable partial page updates without custom JavaScript
37- Support lazy loading for performance optimization
38- Maintain proper URL and history management
39 
40## Turbo Frames Best Practices
41 
42- Use meaningful frame IDs that describe their content
43- Keep frames focused on a single concern
44- Lazy load below-the-fold content with `loading="lazy"`
45- Break out of frames with `data-turbo-frame="_top"` when needed
46- Cache frame responses independently for better performance
47 
48## Turbo Streams Principles
49 
50- Update multiple page elements in a single response
51- Support real-time updates via WebSockets or SSE
52- Use semantic actions: append, prepend, replace, update, remove
53- Target elements by ID for surgical updates
54- Broadcast changes from models automatically
55 
56## Turbo Streams Implementation
57 
58- Return Turbo Stream responses from form submissions
59- Use `turbo_stream` format in controllers
60- Broadcast model changes with Action Cable
61- Target multiple elements in one response
62- Keep stream templates simple and focused
63 
64## Stimulus Philosophy
65 
66- Enhance HTML with just enough JavaScript behavior
67- Connect JavaScript objects to DOM elements declaratively
68- Use conventions to minimize configuration
69- Keep controllers small and focused
70- Leverage the power of mutation observers
71 
72## Stimulus Controller Principles
73 
74- Name controllers based on their behavior, not their content
75- Keep controllers focused on a single responsibility
76- Use data attributes for all configuration
77- Prefer composition over inheritance
78- Write controllers that can be reused across pages
79 
80## Stimulus Targets
81 
82- Define targets for elements the controller will manipulate
83- Use semantic target names that describe their purpose
84- Check for target existence before using them
85- Use singular targets for single elements
86- Use plural targets for collections of elements
87 
88## Stimulus Actions
89 
90- Declare all event handling in HTML with data attributes
91- Use descriptive action names that explain the behavior
92- Handle events at the appropriate level in the DOM
93- Prevent default behavior explicitly when needed
94- Keep action methods small and focused
95 
96## Stimulus Values
97 
98- Use values for controller configuration and state
99- Define value types for automatic parsing
100- React to value changes with callbacks
101- Set sensible defaults for all values
102- Keep values primitive and serializable
103 
104## Stimulus Classes
105 
106- Define CSS classes as data attributes for flexibility
107- Use classes for styling state changes
108- Keep class names semantic and reusable
109- Allow classes to be configured per instance
110- Document required CSS classes clearly
111 
112## Hotwire Integration Patterns
113 
114- Use Turbo Frames for partial page updates
115- Use Turbo Streams for multi-element updates
116- Use Stimulus for client-side interactivity
117- Combine all three for rich, responsive interfaces
118- Keep each tool focused on its strength
119 
120## Progressive Enhancement
121 
122- Build features that work without JavaScript first
123- Enhance with Turbo for better navigation
124- Add Stimulus for rich interactions
125- Test with JavaScript disabled
126- Provide meaningful fallbacks
127 
128## Performance Optimization
129 
130- Use Turbo Frames to update only what changes
131- Lazy load expensive content
132- Cache aggressively with proper cache keys
133- Minimize Stimulus controller complexity
134- Preload critical resources
135 
136## Testing Strategies
137 
138- Write system tests for user flows
139- Test Turbo Frame interactions
140- Test Turbo Stream responses
141- Test Stimulus controllers in isolation
142- Ensure graceful degradation
143 
144## Error Handling
145 
146- Handle Turbo visit errors gracefully
147- Provide feedback for failed form submissions
148- Show meaningful error messages
149- Implement retry mechanisms for failed requests
150- Log errors appropriately for debugging
151 
152## Mobile Considerations
153 
154- Ensure touch targets are appropriately sized
155- Handle touch events properly in Stimulus
156- Test on real devices, not just responsive mode
157- Optimize for slower network connections
158- Consider offline capabilities
159 
160## Security Practices
161 
162- Always verify permissions server-side
163- Use CSRF tokens in all forms
164- Sanitize any user-generated content
165- Don't trust client-side validation
166- Implement proper authentication checks
167 
168## Development Workflow
169 
170- Use Rails generators for Stimulus controllers
171- Organize controllers by feature
172- Keep JavaScript minimal and focused
173- Test JavaScript behavior through system tests
174- Document complex interactions
175 
176## Debugging Techniques
177 
178- Use Turbo debugging events in development
179- Log Stimulus lifecycle methods when troubleshooting
180- Inspect Turbo Frame sources in browser tools
181- Monitor WebSocket connections for streams
182- Use browser console for interactive debugging
183 
184## Best Practices
185 
186- Let the server handle complex logic
187- Keep JavaScript simple and declarative
188- Use semantic HTML as the foundation
189- Follow Rails conventions consistently
190- Write code that's a joy to maintain
191 
192Remember: Hotwire is about sending HTML over the wire. Keep your client-side code minimal and let Rails do what it does best - render HTML on the server.
193