islandjs-rails 0.1.0

data/exe/islandjs-rails

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/islandjs_rails'
+require 'islandjs_rails/cli'
+
+IslandjsRails::CLI.start(ARGV)

data/islandjs-rails.gemspec

@@ -0,0 +1,55 @@
+require_relative "lib/islandjs_rails/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "islandjs-rails"
+  spec.version       = IslandjsRails::VERSION
+  spec.authors       = ["Eric Arnold"]
+  spec.email         = ["ericarnold00+praxisemergent@gmail.com"]
+
+  spec.summary       = "Simple, modern JavaScript islands for Rails"
+  spec.description   = "IslandJS Rails enables React and other JavaScript islands in Rails apps with zero webpack configuration. Load UMD libraries from CDNs, integrate with ERB partials, and render components with Turbo-compatible lifecycle management."
+  spec.homepage      = "https://github.com/praxis-emergent/islandjs-rails"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/praxis-emergent/islandjs-rails"
+  spec.metadata["changelog_uri"] = "https://github.com/praxis-emergent/islandjs-rails/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://github.com/praxis-emergent/islandjs-rails/blob/main/README.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github .claude appveyor Gemfile]) ||
+        f.match?(%r{\A(\.rspec|Rakefile)\z}) ||
+        f.end_with?(".gem")
+    end
+  end
+  
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Post-install message
+  spec.post_install_message = <<~MSG
+    
+    🏝️ IslandJS Rails installed successfully!
+    
+    📋 Next step: Initialize IslandJS in your Rails app
+
+        rails islandjs:init
+    
+  MSG
+
+  # Rails integration
+  spec.add_dependency "rails", ">= 7.0", "< 9.0"
+  spec.add_dependency "thor", "~> 1.0"
+  
+  # Development dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "webmock", "~> 3.0"
+  spec.add_development_dependency "vcr", "~> 6.0"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+end 

data/lib/islandjs-rails.rb

@@ -0,0 +1,3 @@
+# Bridge file for islandjs-rails gem
+# This allows Bundler to auto-require the gem properly
+require_relative 'islandjs_rails' 

data/lib/islandjs_rails/cli.rb

@@ -0,0 +1,57 @@
+require 'thor'
+
+module IslandjsRails
+  class CLI < Thor
+    desc "init", "Initialize IslandJS in this Rails project"
+    def init
+      IslandjsRails.init!
+    end
+
+    desc "install PACKAGE_NAME [VERSION]", "Install a JavaScript island package"
+    def install(package_name, version = nil)
+      IslandjsRails.install!(package_name, version)
+    end
+
+    desc "update PACKAGE_NAME [VERSION]", "Update a JavaScript island package"
+    def update(package_name, version = nil)
+      IslandjsRails.update!(package_name, version)
+    end
+
+    desc "remove PACKAGE_NAME", "Remove a JavaScript island package"
+    def remove(package_name)
+      IslandjsRails.remove!(package_name)
+    end
+
+    desc "sync", "Sync all JavaScript island packages with current package.json"
+    def sync
+      IslandjsRails.sync!
+    end
+
+    desc "status", "Show status of all JavaScript island packages"
+    def status
+      IslandjsRails.status!
+    end
+
+    desc "clean", "Clean all island partials and reset webpack externals"
+    def clean
+      IslandjsRails.clean!
+    end
+
+    desc "config", "Show IslandJS configuration"
+    def config
+      config = IslandjsRails.configuration
+      puts "📊 IslandjsRails Configuration"
+      puts "=" * 40
+      puts "Package.json path: #{config.package_json_path}"
+      puts "Partials directory: #{config.partials_dir}"
+      puts "Webpack config path: #{config.webpack_config_path}"
+      puts "Supported CDNs: #{config.supported_cdns.join(', ')}"
+      puts "Built-in global name overrides: #{IslandjsRails::BUILT_IN_GLOBAL_NAME_OVERRIDES.size} available"
+    end
+
+    desc "version", "Show IslandJS Rails version"
+    def version
+      puts "IslandjsRails #{IslandjsRails::VERSION}"
+    end
+  end
+end

data/lib/islandjs_rails/configuration.rb

@@ -0,0 +1,49 @@
+require 'pathname'
+
+module IslandjsRails
+  class Configuration
+    attr_accessor :package_json_path, :partials_dir, :webpack_config_path, :supported_cdns,
+                  :vendor_script_mode, :vendor_order, :vendor_dir, :combined_basename
+
+    def initialize
+      @package_json_path = Rails.root.join('package.json')
+      @partials_dir = Rails.root.join('app', 'views', 'shared', 'islands')
+      @webpack_config_path = Rails.root.join('webpack.config.js')
+      @vendor_script_mode = :external_split  # :external_split or :external_combined
+      @vendor_order = %w[react react-dom]    # combine order for :external_combined
+      @vendor_dir = Rails.root.join('public', 'islands', 'vendor')
+      @combined_basename = 'islands-vendor'
+      @supported_cdns = [
+        'https://unpkg.com',
+        'https://cdn.jsdelivr.net/npm'
+      ]
+    end
+
+
+    # Scoped package name mappings
+    SCOPED_PACKAGE_MAPPINGS = {
+      '@solana/web3.js' => 'solana-web3.js',
+      '@babel/core' => 'babel-core',
+      '@babel/preset-env' => 'babel-preset-env',
+      '@babel/preset-react' => 'babel-preset-react'
+    }.freeze
+
+    # Vendor file helper methods
+    def vendor_manifest_path
+      @vendor_dir.join('manifest.json')
+    end
+
+    def vendor_partial_path
+      @partials_dir.join('_vendor_umd.html.erb')
+    end
+
+    def vendor_file_path(package_name, version)
+      safe_name = package_name.gsub(/[@\/]/, '_').gsub(/-/, '_')
+      @vendor_dir.join("#{safe_name}-#{version}.min.js")
+    end
+
+    def combined_vendor_path(hash)
+      @vendor_dir.join("#{@combined_basename}-#{hash}.js")
+    end
+  end
+end

data/lib/islandjs_rails/core.rb

@@ -0,0 +1,462 @@
+require 'json'
+require 'open3'
+require 'net/http'
+require 'uri'
+require 'fileutils'
+
+module IslandjsRails
+  class Core
+    attr_reader :configuration
+
+    def initialize
+      @configuration = IslandjsRails.configuration
+    end
+
+    # Essential dependencies for IslandJS webpack setup
+    ESSENTIAL_DEPENDENCIES = [
+      'webpack@^5.88.2',
+      'webpack-cli@^5.1.4', 
+      'terser-webpack-plugin@^5.3.14',
+      'webpack-manifest-plugin@^5.0.1',
+      'babel-loader@^9.1.3',
+      '@babel/core@^7.23.0',
+      '@babel/preset-env@^7.23.0',
+      '@babel/preset-react@^7.23.0'
+    ].freeze
+
+    # Initialize IslandJS in a Rails project
+    def init!
+      puts "🚀 Initializing IslandjsRails..."
+      
+      # Step 1: Check for required tools
+      check_node_tools!
+      
+      # Step 2: Ensure package.json exists
+      ensure_package_json!
+      
+      # Step 3: Install essential webpack dependencies
+      install_essential_dependencies!
+      
+      # Step 4: Create scaffolded structure
+      create_scaffolded_structure!
+      
+      # Step 5: Create directories
+      FileUtils.mkdir_p(configuration.partials_dir)
+      FileUtils.mkdir_p(configuration.vendor_dir)
+      puts "✓ Created #{configuration.partials_dir}"
+      puts "✓ Created #{configuration.vendor_dir}"
+      
+      # Step 6: Generate webpack config if it doesn't exist
+      unless File.exist?(configuration.webpack_config_path)
+        generate_webpack_config!
+        puts "✓ Generated webpack.config.js"
+      else
+        puts "✓ webpack.config.js already exists"
+      end
+      
+      # Step 7: Set up vendor system and inject into layout
+      setup_vendor_system!
+      inject_islands_helper_into_layout!
+      
+      # Step 8: Add node_modules to .gitignore
+      ensure_node_modules_gitignored!
+      
+      puts "\n🎉 IslandjsRails initialized successfully!"
+      puts "\n📋 Next steps:"
+      puts "1. Install libraries:  rails \"islandjs:install[react,18.3.1]\""
+      puts "                       rails \"islandjs:install[react-dom,18.3.1]\"  "
+      puts "2. Start dev:          yarn watch"
+      puts "3. Use components:     <%= react_component('HelloWorld') %>"
+      puts "4. Build for prod:     yarn build"
+      puts "5. Commit assets:      git add public/islands_* && git add public/islands/*"
+  
+      puts "\n🚀 Rails 8 Ready: Commit your built assets for bulletproof deploys!"
+      puts "💡 IslandjsRails is framework-agnostic - use React, Vue, or any UMD library!"
+      puts "🎉 Ready to build!"
+    end
+
+    # Install a new island package
+    def install!(package_name, version = nil)
+      puts "📦 Installing UMD package: #{package_name}"
+      
+      # Check if React ecosystem was incomplete before this install
+      was_react_ecosystem_incomplete = !react_ecosystem_complete?
+      
+      # Add to package.json via yarn if not present
+      add_package_via_yarn(package_name, version) unless package_installed?(package_name)
+      
+      # Install to vendor directory
+      vendor_manager = IslandjsRails.vendor_manager
+      success = vendor_manager.install_package!(package_name, version)
+      
+      return false unless success
+      
+      global_name = detect_global_name(package_name)
+      update_webpack_externals(package_name, global_name)
+      
+      puts "✅ Successfully installed #{package_name}!"
+      
+      # Auto-scaffold React if ecosystem just became complete
+      if was_react_ecosystem_incomplete && react_ecosystem_complete? && 
+         (package_name == 'react' || package_name == 'react-dom')
+        activate_react_scaffolding!
+      end
+    end
+
+    # Update an existing package
+    def update!(package_name, version = nil)
+      puts "🔄 Updating UMD package: #{package_name}"
+      
+      unless package_installed?(package_name)
+        raise IslandjsRails::PackageNotFoundError, "#{package_name} is not installed. Use 'install' instead."
+      end
+      
+      # Update package.json via yarn
+      yarn_update!(package_name, version)
+      
+      # Re-install to vendor directory
+      vendor_manager = IslandjsRails.vendor_manager
+      vendor_manager.install_package!(package_name, version)
+      
+      # Update webpack externals
+      global_name = detect_global_name(package_name)
+      update_webpack_externals(package_name, global_name)
+      
+      puts "✅ Successfully updated #{package_name}!"
+    end
+
+    # Remove a specific package
+    def remove!(package_name)
+      puts "🗑️  Removing island package: #{package_name}"
+      
+      unless package_installed?(package_name)
+        raise IslandjsRails::PackageNotFoundError, "Package #{package_name} is not installed"
+      end
+      
+      remove_package_via_yarn(package_name)
+      
+      # Remove from vendor directory
+      vendor_manager = IslandjsRails.vendor_manager
+      vendor_manager.remove_package!(package_name)
+      
+      update_webpack_externals
+      puts "✅ Successfully removed #{package_name}!"
+    end
+
+    # Sync all packages
+    def sync!
+      puts "🔄 Syncing all UMD packages..."
+      
+      packages = installed_packages
+      if packages.empty?
+        puts "📦 No packages found in package.json"
+        return
+      end
+      
+      vendor_manager = IslandjsRails.vendor_manager
+      
+      packages.each do |package_name|
+        next unless supported_package?(package_name)
+        puts "  📦 Processing #{package_name}..."
+        
+        # Get version from package.json
+        version = version_for(package_name)
+        
+        # Install to vendor system
+        vendor_manager.install_package!(package_name, version)
+        
+        # Update webpack externals
+        global_name = detect_global_name(package_name)
+        update_webpack_externals(package_name, global_name)
+      end
+      
+      puts "✅ Sync completed!"
+    end
+
+    # Show status of all packages
+    def status!
+              puts "📊 IslandjsRails Status"
+      puts "=" * 40
+      
+      packages = installed_packages
+      if packages.empty?
+        puts "📦 No packages found in package.json"
+        return
+      end
+      
+      # Check vendor system instead of partials
+      vendor_manager = IslandjsRails.vendor_manager
+      manifest = vendor_manager.send(:read_manifest)
+      vendor_packages = manifest['libs'].map { |lib| lib['name'] }
+      
+      packages.each do |package_name|
+        version = version_for(package_name)
+        has_vendor = vendor_packages.include?(package_name)
+        status_icon = has_vendor ? "✅" : "❌"
+        puts "#{status_icon} #{package_name}@#{version} #{has_vendor ? '(vendor ready)' : '(missing vendor)'}"
+      end
+    end
+
+    # Clean vendor files and rebuild
+  def clean!
+    puts "🧹 Cleaning vendor files..."
+    
+    vendor_manager = IslandjsRails.vendor_manager
+    
+    # Clean vendor files
+    if Dir.exist?(configuration.vendor_dir)
+      Dir.glob(File.join(configuration.vendor_dir, '*.js')).each do |file|
+        File.delete(file)
+        puts "  ✓ Removed #{File.basename(file)}"
+      end
+    end
+    
+    # Reset vendor manifest by writing empty manifest
+    empty_manifest = { 'libs' => [] }
+    vendor_manager.send(:write_manifest, empty_manifest)
+    puts "  ✓ Reset vendor manifest"
+    
+    # Regenerate vendor partial
+    vendor_manager.send(:regenerate_vendor_partial!)
+    puts "  ✓ Regenerated vendor partial"
+    
+    # Reset webpack externals
+    reset_webpack_externals
+    puts "  ✓ Reset webpack externals"
+    
+    # Reinstall all packages from package.json
+    installed_packages.each do |package_name, version|
+      puts "  📦 Reinstalling #{package_name}@#{version}..."
+      vendor_manager.install_package!(package_name, version)
+      global_name = detect_global_name(package_name)
+      update_webpack_externals(package_name, global_name)
+    end
+    
+    puts "✅ Clean completed!"
+  end
+
+    # Public methods for external access
+    def package_installed?(package_name)
+      return false unless File.exist?(configuration.package_json_path)
+      
+      begin
+        package_data = JSON.parse(File.read(configuration.package_json_path))
+        dependencies = package_data.dig('dependencies') || {}
+        dev_dependencies = package_data.dig('devDependencies') || {}
+        
+        dependencies.key?(package_name) || dev_dependencies.key?(package_name)
+      rescue JSON::ParserError, Errno::ENOENT
+        false
+      end
+    end
+
+    def detect_global_name(package_name, url = nil)
+      # Check built-in overrides first
+      override = IslandjsRails::BUILT_IN_GLOBAL_NAME_OVERRIDES[package_name]
+      return override if override
+      
+      # For scoped packages, use the package name part
+      clean_name = package_name.include?('/') ? package_name.split('/').last : package_name
+      
+      # Convert kebab-case to camelCase
+      clean_name.split('-').map.with_index { |part, i| i == 0 ? part : part.capitalize }.join
+    end
+
+    def version_for(library_name)
+      package_data = package_json
+      return nil unless package_data
+      
+      dependencies = package_data.dig('dependencies') || {}
+      dev_dependencies = package_data.dig('devDependencies') || {}
+      
+      version = dependencies[library_name] || dev_dependencies[library_name]
+      return nil unless version
+      
+      version.gsub(/[\^~>=<]/, '')
+    end
+
+    def find_working_island_url(package_name, version)
+      puts "🔍 Searching for island build..."
+      
+      version ||= version_for(package_name)
+      return nil unless version
+      
+      # Use original package name for URL, but get clean name for {name} substitution
+      clean_name = (Configuration::SCOPED_PACKAGE_MAPPINGS[package_name] || package_name).split('/').last
+      
+      configuration.supported_cdns.each do |cdn_base|
+        IslandjsRails::UMD_PATH_PATTERNS.each do |pattern|
+          # Handle both {name} substitution patterns and fixed filename patterns
+          path = if pattern.include?('{name}')
+                   pattern.gsub('{name}', clean_name)
+                 else
+                   pattern  # Use pattern as-is for fixed filenames like IIFE
+                 end
+          url = "#{cdn_base}/#{package_name}@#{version}/#{path}"
+
+          
+          if url_accessible?(url)
+            puts "✓ Found island: #{url}"
+            return url
+          end
+        end
+      end
+      
+      puts "❌ No island build found for #{package_name}@#{version}"
+      nil
+    end
+
+    def download_umd_content(url)
+      require 'net/http'
+      require 'uri'
+      
+      uri = URI(url)
+      response = Net::HTTP.get_response(uri)
+      
+      unless response.code == '200'
+        raise IslandjsRails::Error, "Failed to download UMD from #{url}: #{response.code}"
+      end
+      
+      response.body
+    end
+
+    def find_working_umd_url(package_name, version)
+      puts "  🔍 Searching for UMD build..."
+      
+      # Get package name without scope for path patterns
+      clean_name = package_name.split('/').last
+      
+      IslandjsRails::CDN_BASES.each do |cdn_base|
+        IslandjsRails::UMD_PATH_PATTERNS.each do |pattern|
+          # Replace placeholders in pattern only if they exist
+          path = if pattern.include?('{name}')
+                   pattern.gsub('{name}', clean_name)
+                 else
+                   pattern  # Use pattern as-is for fixed filenames like IIFE
+                 end
+          url = "#{cdn_base}/#{package_name}@#{version}/#{path}"
+
+          
+          if url_accessible?(url)
+            puts "  ✓ Found UMD: #{url}"
+            
+            # Try to detect global name from the UMD content
+            global_name = detect_global_name(package_name, url)
+            
+            return [url, global_name]
+          end
+        end
+      end
+      
+      puts "  ❌ No UMD build found for #{package_name}@#{version}"
+      [nil, nil]
+    end
+
+    private
+
+    # Check if a URL is accessible (returns 200 status)
+    def url_accessible?(url)
+      require 'net/http'
+      require 'uri'
+      
+      uri = URI(url)
+      response = Net::HTTP.get_response(uri)
+      response.code == '200'
+    rescue => e
+      false
+    end
+    
+    # Check if a package has a partial file
+    def has_partial?(package_name)
+      File.exist?(partial_path_for(package_name))
+    end
+    
+    # Get global name for a package (used by webpack externals)
+    def get_global_name_for_package(package_name)
+      detect_global_name(package_name)
+    end
+
+    def react_ecosystem_complete?
+      package_installed?('react') && package_installed?('react-dom')
+    end
+
+    def activate_react_scaffolding!
+      puts "\n🎉 React ecosystem is now complete (React + React-DOM)!"
+      
+      uncomment_react_imports!
+      create_hello_world_component!
+      build_bundle!
+      offer_demo_route!
+    end
+
+    def uncomment_react_imports!
+      index_js_path = File.join(Dir.pwd, 'app', 'javascript', 'islands', 'index.js')
+      return unless File.exist?(index_js_path)
+      
+      content = File.read(index_js_path)
+      
+      # Check if this looks like our commented template
+      if content.include?('// import HelloWorld from') && content.include?('// HelloWorld')
+        # Uncomment the import
+        updated_content = content.gsub('// import HelloWorld from', 'import HelloWorld from')
+        # Uncomment the export within the window.islandjsRails object
+        updated_content = updated_content.gsub(/(\s+)\/\/ HelloWorld/, '\1HelloWorld')
+        
+        File.write(index_js_path, updated_content)
+        puts "✓ Activated React imports in index.js"
+      else
+        puts "⚠️  index.js has been modified - please add HelloWorld manually"
+      end
+    end
+
+    def create_hello_world_component!
+      components_dir = File.join(Dir.pwd, 'app', 'javascript', 'islands', 'components')
+      FileUtils.mkdir_p(components_dir)
+      
+      # Create turbo.js utility first
+      create_turbo_utility!
+      
+      hello_world_path = File.join(components_dir, 'HelloWorld.jsx')
+      
+      if File.exist?(hello_world_path)
+        puts "✓ HelloWorld.jsx already exists"
+        return
+      end
+
+      # Copy from gem's template file instead of hardcoded string
+      gem_template_path = File.join(__dir__, '..', 'templates', 'app', 'javascript', 'islands', 'components', 'HelloWorld.jsx')
+      
+      if File.exist?(gem_template_path)
+        FileUtils.cp(gem_template_path, hello_world_path)
+        puts "✓ Created HelloWorld.jsx component"
+      else
+        puts "⚠️  Template file not found: #{gem_template_path}"
+      end
+    end
+
+    def create_turbo_utility!
+      utils_dir = File.join(Dir.pwd, 'app', 'javascript', 'islands', 'utils')
+      FileUtils.mkdir_p(utils_dir)
+      
+      turbo_path = File.join(utils_dir, 'turbo.js')
+      
+      if File.exist?(turbo_path)
+        puts "✓ turbo.js utility already exists"
+        return
+      end
+      
+      # Copy from gem's template file instead of hardcoded string
+      gem_template_path = File.join(__dir__, '..', 'templates', 'app', 'javascript', 'islands', 'utils', 'turbo.js')
+      
+      if File.exist?(gem_template_path)
+        FileUtils.cp(gem_template_path, turbo_path)
+        puts "✓ Created turbo.js utility"
+      else
+        puts "⚠️  Template file not found: #{gem_template_path}"
+      end
+    end
+  end
+end
+
+# Load additional core methods
+require_relative 'core_methods'