rails-instructions rails-importmaps.instructions.md

Rails Import Maps Guide

Core Philosophy

• Eliminate JavaScript build steps while maintaining modern development practices
• Send JavaScript modules directly to the browser without bundling or transpiling
• Reference external modules using standardized module specifiers
• Embrace simplicity and developer happiness - this is the Rails Way™

Configuration Principles

• Define all JavaScript dependencies in config/importmap.rb
• Pin external libraries to specific versions for production stability
• Use semantic versioning when pinning dependencies
• Prefer CDN URLs for popular libraries to leverage browser caching
• Vendor critical dependencies that cannot tolerate CDN failures
• Always specify preload: true for essential modules

File Organization

• Keep all JavaScript files in the app/javascript directory
• Use controllers/ subdirectory exclusively for Stimulus controllers
• Create components/ for reusable UI JavaScript modules
• Create utilities/ for shared helper functions
• Follow Rails naming conventions consistently

Naming Conventions for AI Agents

• Name Stimulus controllers with *_controller.js suffix
• Use descriptive nouns for component files (modal.js, dropdown.js)
• Use action-based names for utilities (debounce.js, format_currency.js)
• Maintain consistent naming patterns across the codebase
• Document module purpose at the top of each file

Module Management

• Import modules using standard ESM syntax
• Avoid polluting the global namespace
• Use named exports for better code discoverability
• Keep modules focused on a single responsibility
• Export only what needs to be public

Dependency Management

• Pin to exact versions in production for stability
• Use version ranges only in development
• Regularly audit and update dependencies
• Remove unused dependencies promptly
• Document why each dependency is needed

Performance Optimization

• Use preload: true only for critical dependencies
• Implement lazy loading for features not needed on initial load
• Leverage browser caching by using CDN URLs
• Evaluate module size before adding dependencies
• Consider vendoring large libraries that change infrequently