Copilot instructions

1---
2description: Rails Import Maps Guide
3applyTo: "config/importmap.rb"
4---
5 
6# Rails Import Maps Guide
7 
8## Core Philosophy
9 
10- Eliminate JavaScript build steps while maintaining modern development practices
11- Send JavaScript modules directly to the browser without bundling or transpiling
12- Reference external modules using standardized module specifiers
13- Embrace simplicity and developer happiness - this is the Rails Way™
14 
15## Configuration Principles
16 
17- Define all JavaScript dependencies in `config/importmap.rb`
18- Pin external libraries to specific versions for production stability
19- Use semantic versioning when pinning dependencies
20- Prefer CDN URLs for popular libraries to leverage browser caching
21- Vendor critical dependencies that cannot tolerate CDN failures
22- Always specify `preload: true` for essential modules
23 
24## File Organization
25 
26- Keep all JavaScript files in the `app/javascript` directory
27- Use `controllers/` subdirectory exclusively for Stimulus controllers
28- Create `components/` for reusable UI JavaScript modules
29- Create `utilities/` for shared helper functions
30- Follow Rails naming conventions consistently
31 
32## Naming Conventions for AI Agents
33 
34- Name Stimulus controllers with `*_controller.js` suffix
35- Use descriptive nouns for component files (`modal.js`, `dropdown.js`)
36- Use action-based names for utilities (`debounce.js`, `format_currency.js`)
37- Maintain consistent naming patterns across the codebase
38- Document module purpose at the top of each file
39 
40## Module Management
41 
42- Import modules using standard ESM syntax
43- Avoid polluting the global namespace
44- Use named exports for better code discoverability
45- Keep modules focused on a single responsibility
46- Export only what needs to be public
47 
48## Dependency Management
49 
50- Pin to exact versions in production for stability
51- Use version ranges only in development
52- Regularly audit and update dependencies
53- Remove unused dependencies promptly
54- Document why each dependency is needed
55 
56## Performance Optimization
57 
58- Use `preload: true` only for critical dependencies
59- Implement lazy loading for features not needed on initial load
60- Leverage browser caching by using CDN URLs
61- Evaluate module size before adding dependencies
62- Consider vendoring large libraries that change infrequently
63 
64## Security Best Practices
65 
66- Pin to specific versions to prevent supply chain attacks
67- Include subresource integrity hashes for CDN resources
68- Validate external scripts before including them
69- Use Content Security Policy headers appropriately
70- Regularly update dependencies for security patches
71 
72## Integration with Rails
73 
74- Import Turbo and Stimulus at the application root
75- Register Stimulus controllers automatically
76- Use import maps for all JavaScript dependencies
77- Avoid mixing import maps with other bundling solutions
78- Keep initialization code in `application.js`
79 
80## Testing Considerations
81 
82- Test JavaScript behavior through system tests
83- Use Capybara for integration testing
84- Test Stimulus controllers in isolation when complex
85- Ensure all imports resolve correctly
86- Verify lazy-loaded modules load properly
87 
88## Migration Strategy
89 
90- Remove Node.js dependencies incrementally
91- Convert webpack/esbuild imports to import map pins
92- Delete package.json and node_modules after migration
93- Update deployment scripts to remove build steps
94- Verify all functionality works without bundling
95 
96## Development Workflow
97 
98- Run `bin/importmap` to manage dependencies
99- Use `pin` command to add new libraries
100- Use `unpin` command to remove libraries
101- Audit pins regularly for unused dependencies
102- Keep import map file organized and commented
103 
104## Debugging Guidelines
105 
106- Check browser console for module loading errors
107- Verify all pinned URLs are accessible
108- Ensure import paths match exactly
109- Use browser developer tools to inspect loaded modules
110- Check for version conflicts between dependencies
111 
112## Best Practices
113 
114- Prefer simplicity over clever abstractions
115- Write modules that work without transpilation
116- Use modern JavaScript features supported by target browsers
117- Keep import map configuration readable and well-organized
118- Document any non-obvious pinning decisions
119