islandjs-rails 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 161513f810a18384f6f80fd33826774b01027e0a3167e7cdfea5af2903419ccc
-  data.tar.gz: 756c73ddf0f8347c4ca86c484fff6c62cb01600304a04abc84f54b693555062b
+  metadata.gz: 785899eb40416f27f56fa482ab4c3241a2cd1637c81c75c025f3d03d39bb2c23
+  data.tar.gz: 86854c83387842f66a1899795bbfe3be4061190e7814fc4502aaa0727d011f6d
 SHA512:
-  metadata.gz: 3ca585f21d6501f6fca88792b125fdd9f70ed839867509445a59eca25f521919a6918554168f834d3deb36d9e9e7eb39c05d36c32222e8d354f7442ea4ca394e
-  data.tar.gz: 6f6eacf4afa87d6f130a71c88724deaa0e17d9d8e06cde38cb883b2a1bc35253604b5163e8d40580fbe0c40e8811fd723c424b3f769c96a495962a38ff3aedda
+  metadata.gz: 2f8d054fb90b600243af937d36d338b21c5b1c8b658bd775452aeced0db465c02a95a83520578d623705f6e729a9a0b5dd9ec78fbd23c164091f14b7a15591a1
+  data.tar.gz: 3b6e35821a2958438332f84ee34521659fbcaf259cb5753df046822b112af26186842258579f7d07d935935556b770dc1e4609311543195d3add897381c3940d

data/CHANGELOG.md

@@ -5,6 +5,77 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] - 2025-11-05
+
+### 🎉 Major Release: Webpack → Vite Migration
+
+This release replaces webpack with Vite for a dramatically faster, more modern build system.
+
+### ⚠️ BREAKING CHANGES
+
+**Build System**:
+- Replaced webpack with Vite as the build tool
+- Config file changed: `webpack.config.js` → `vite.config.islands.ts`
+- Build command changed: `yarn build` → `yarn build:islands`
+- Watch command changed: `yarn watch` → `yarn watch:islands`
+- Manifest location changed: `public/islands_manifest.json` → `public/islands/.vite/manifest.json`
+
+**Dependencies**:
+- Removed: `webpack`, `webpack-cli`, `webpack-manifest-plugin`
+- Added: `vite`, `@vitejs/plugin-react`
+- Note: Uses Vite directly via npm/yarn, not the `vite_rails` Ruby gem
+
+**Files**:
+- `app/javascript/islands/index.js` is no longer created (Vite uses entrypoints directly)
+- New file: `vite.config.islands.ts` for Islands-specific Vite configuration
+
+### ✅ What Stays the Same
+
+**No code changes needed!** All runtime APIs remain identical:
+- All Rails helpers work the same (`react_component`, `island_partials`, etc.)
+- Island components don't need any changes
+- ERB templates don't need any changes
+- UMD vendor system works identically
+- All `rails islandjs:*` commands work the same way
+
+### 🚀 Benefits
+
+- ⚡ **2-10x faster builds** compared to webpack
+- 🔥 **Instant Hot Module Replacement (HMR)** during development
+- 📦 **Smaller bundle sizes** with superior tree-shaking
+- 🎯 **Simpler configuration** - no complex webpack setup needed
+- 🌐 **Modern tooling** - built for ES modules and modern JavaScript
+- 🔧 **Lightweight integration** - uses Vite directly without additional Ruby dependencies
+
+### 📚 Upgrade Guide
+
+See [UPGRADING.md](UPGRADING.md) for detailed migration instructions. Summary:
+
+1. Update gem: `bundle update islandjs-rails`
+2. Remove webpack files: `rm webpack.config.js`
+3. Reinitialize: `rails islandjs:init`
+4. Rebuild: `yarn build:islands`
+
+### Changed
+
+- Updated all documentation to reference Vite instead of webpack
+- CLI and Rake task descriptions now mention "Vite externals" instead of "webpack externals"
+- Build output messages updated for Vite workflow
+- Error messages and hints updated to reference Vite commands
+
+### Removed
+
+- Webpack configuration template
+- Webpack-related dependencies from package.json template
+- `ESSENTIAL_DEPENDENCIES` constant (replaced with inline Vite deps)
+- References to webpack in README, gemspec, and all documentation
+
+## [0.7.0] - 2025-10-27
+
+### Added
+- **CleanIslandsPlugin**: Build plugin that automatically removes old island bundle files from the public directory after new builds, preventing stale file accumulation
+- Simplified build scripts by removing manual cleanup commands
+
 ## [0.6.0] - 2025-10-24
 
 - **React 19 Support Added**

data/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [year] [fullname]
+Copyright (c) 2024-2025 Eric Arnold
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -30,14 +30,17 @@ rails islandjs:init
 ```
 
 ### Install React
+
+> **Note:** Currently limited to React 19.1.0 until [umd-react](https://github.com/lofcz/umd-react) workflow is fixed (PR pending) to publish newer versions to unpkg.com properly.
+
 ```bash
-rails "islandjs:install[react,19.2.0]"
-rails "islandjs:install[react-dom,19.2.0]"
+rails "islandjs:install[react,19.1.0]"
+rails "islandjs:install[react-dom,19.1.0]"
 ```
 
 ### Run Yarn In Development
 ```bash
-yarn watch
+yarn watch:islands
 ```
 
 ### Render React Components
@@ -53,7 +56,7 @@ yarn watch
 
 ### Build For Production
 ```bash
-yarn build # you may remove any stale islandjs bundles before committing
+yarn build:islands
 ```
 
 > 💡 **Turbo Cache Compatible**: React components automatically persist state across Turbo navigation! See [Turbo Cache Integration](#turbo-cache-integration) for details.
@@ -114,15 +117,15 @@ Modern Rails developers face a painful choice:
 
 ### The IslandJS Rails Solution
 ```bash
-# Instead of complex vite/webpack configuration:
-rails "islandjs:install[react,19.2.0]"
+# Instead of complex build configuration:
+rails "islandjs:install[react,19.1.0]"
 rails "islandjs:install[react-beautiful-dnd]"
 rails "islandjs:install[quill]"
 rails "islandjs:install[recharts]"
 rails "islandjs:install[lodash]"
 ```
 
-**Result**: Zero-to-no webpack configuration, instant prod builds, access to hundreds of UMD packages.
+**Result**: Zero build configuration, instant prod builds, access to hundreds of UMD packages.
 
 ### Access UMD installed JS packages via the window from within React components:
 ```bash
@@ -154,7 +157,7 @@ If you absolutely need a package that doesn't ship UMD builds, you have a few op
 - **Package.json Integration** - (npm + yarn)
 - **CDN Downloads** - Fetches UMD builds from unpkg.com and jsdelivr.net
 - **Rails Integration** - Serves auto-generated vendor UMD files for seamless integration
-- **Webpack Externals** - Updates webpack config to prevent duplicate bundling while allowing development in jsx or other formats
+- **Vite Externals** - Updates vite.config.islands.ts to prevent duplicate bundling while allowing development in jsx or other formats
 - **Placeholder Support** - Eliminate layout shift with automatic placeholder management ⚡ *New in v0.2.0*
 - **Flexible Architecture** - Compose and namespace libraries as needed
 
@@ -170,12 +173,12 @@ rails islandjs:init
 
 # Install packages (adds to package.json + saves to vendor directory)
 rails "islandjs:install[react]"
-rails "islandjs:install[react,19.2.0]"       # With specific version
+rails "islandjs:install[react,19.1.0]"       # With specific version
 rails "islandjs:install[lodash]"
 
 # Update packages (updates package.json + refreshes vendor files)
 rails "islandjs:update[react]"
-rails "islandjs:update[react,19.2.0]"       # To specific version
+rails "islandjs:update[react,19.1.0]"       # To specific version
 
 # Remove packages (removes from package.json + deletes vendor files)
 rails "islandjs:remove[react]"
@@ -216,27 +219,24 @@ For development and building your JavaScript:
 
 ```bash
 # Development - watch for changes and rebuild automatically
-yarn watch
-# Or with npm: npm run watch
+yarn watch:islands
 
 # Production - build optimized bundle for deployment
-yarn build
-# Or with npm: npm run build
+yarn build:islands
 
 # Install dependencies (after adding packages via islandjs:install)
 yarn install
-# Or with npm: npm install
 ```
 
 **Development Workflow:**
-1. Run `yarn watch` (or `npm run watch`) in one terminal
+1. Run `yarn watch:islands` in one terminal
 2. Edit your components in `app/javascript/islands/components/`
-3. Changes are automatically compiled to `public/`
+3. Changes are automatically compiled and fingerprinted
 
 **Production Deployment:**
-1. Run `yarn build` (or `npm run build`) to create optimized bundle
-2. Commit the built assets: `git add public/islands_* && git add public/islands/*`
-3. Deploy with confidence - assets are prebuilt
+1. Run `yarn build:islands` to create optimized bundle with content hashing
+2. Commit the built assets: `git add public/islands/`
+3. Deploy - Vite's content hashing ensures automatic cache busting
 
 ## 📦 Working with Scoped Packages
 
@@ -313,21 +313,24 @@ function SolanaComponent() {
 export default SolanaComponent;
 ```
 
-### Webpack Externals
+### Vite Externals
 
-IslandJS Rails automatically configures webpack externals for scoped packages:
+IslandJS Rails automatically configures Vite externals for scoped packages:
 
-```javascript
-// webpack.config.js (auto-generated)
-module.exports = {
-  externals: {
-    // IslandJS Rails managed externals - do not edit manually
-    "@solana/web3.js": "solanaWeb3",
-    "react": "React",
-    "react-dom": "ReactDOM"
-  },
-  // ... rest of config
-};
+```typescript
+// vite.config.islands.ts (auto-generated)
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      external: ['@solana/web3.js'],
+      output: {
+        globals: {
+          '@solana/web3.js': 'solanaWeb3'
+        }
+      }
+    }
+  }
+});
 ```
 
 ### Troubleshooting Scoped Packages
@@ -354,7 +357,7 @@ rails "islandjs:install[@solana/web3]"     # ❌ Wrong
 | Command | What it does | Example |
 |---------|--------------|---------|
 | `install` | Adds package via yarn + downloads UMD + saves to vendor | `rails islandjs:install[react]` |
-| `update` | Updates package version + refreshes UMD | `rails islandjs:update[react,19.2.0]` |
+| `update` | Updates package version + refreshes UMD | `rails islandjs:update[react,19.1.0]` |
 | `remove` | Removes package via yarn + deletes vendor files | `rails islandjs:remove[react]` |
 | `clean` | Removes ALL vendor files (destructive!) | `rails islandjs:clean` |
 
@@ -366,8 +369,7 @@ IslandjsRails.configure do |config|
   # Directory for ERB partials (default: app/views/shared/islands)
   config.partials_dir = Rails.root.join('app/views/shared/islands')
   
-  # Webpack configuration path
-  config.webpack_config_path = Rails.root.join('webpack.config.js')
+  # Vite Islands configuration is at vite.config.islands.ts (auto-managed)
   
   # Vendor file delivery mode (default: :external_split)
   config.vendor_script_mode = :external_split    # One file per library
@@ -389,7 +391,7 @@ end
 ### Helpers
 
 #### `islands`
-Single helper that includes all UMD vendor scripts and your webpack bundle.
+Single helper that includes all UMD vendor scripts and your Vite bundle.
 
 ```erb
 <%= islands %>
@@ -397,7 +399,7 @@ Single helper that includes all UMD vendor scripts and your webpack bundle.
 
 This automatically loads:
 - All UMD libraries from vendor files (either split or combined mode)
-- Your webpack bundle
+- Your Vite bundle
 - Debug information in development
 
 #### `react_component(name, props, options, &block)`
@@ -606,18 +608,25 @@ window.islandjsRails = {
 const { React, UI, Utils } = window.islandjsRails;
 ```
 
-### Webpack Integration
+### Vite Integration
 
-IslandJS Rails automatically updates your webpack externals:
+IslandJS Rails automatically updates your Vite externals:
 
-```javascript
-// webpack.config.js (auto-generated)
-module.exports = {
-  externals: {
-    'react': 'React',
-    'lodash': '_'
+```typescript
+// vite.config.islands.ts (auto-generated)
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      external: ['react', 'react-dom'],
+      output: {
+        globals: {
+          'react': 'React',
+          'react-dom': 'ReactDOM'
+        }
+      }
+    }
   }
-};
+});
 ```
 
 ### Configuration Options
@@ -627,8 +636,7 @@ IslandjsRails.configure do |config|
   # Directory for ERB partials (default: app/views/shared/islands)
   config.partials_dir = Rails.root.join('app/views/shared/islands')
   
-  # Path to webpack config (default: webpack.config.js)
-  config.webpack_config_path = Rails.root.join('webpack.config.js')
+  # Vite Islands config is at vite.config.islands.ts (auto-managed)
   
   # Path to package.json (default: package.json)
   config.package_json_path = Rails.root.join('package.json')
@@ -665,11 +673,11 @@ end
 **Global name conflicts:**
 IslandJS Rails includes built-in mappings for common libraries. For packages with unusual global names, check the library's documentation or browser console to find the correct global variable name.
 
-**Webpack externals not updating:**
+**Vite externals not updating:**
 ```bash
 # Sync to update externals
 rails islandjs:sync
-
+```
 # Or clean and reinstall
 rails islandjs:clean
 rails islandjs:install[react]
@@ -734,6 +742,6 @@ Planned features for future releases:
 - **Fast Deploys**: CDN libraries cache globally
 
 ### 🎯 **Developer Experience**
-- **Zero Webpack Expertise**: Rails developers stay in Rails
+- **Zero Build Expertise**: Rails developers stay in Rails
 - **Turbo Compatible**: Seamless navigation and caching
 - **Progressive Enhancement**: Start with Hotwire, add React islands

data/lib/islandjs_rails/cli.rb

@@ -32,7 +32,7 @@ module IslandjsRails
       IslandjsRails.status!
     end
 
-    desc "clean", "Clean all island partials and reset webpack externals"
+    desc "clean", "Clean all island partials and reset Vite externals"
     def clean
       IslandjsRails.clean!
     end
@@ -44,7 +44,7 @@ module IslandjsRails
       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 "Vite Islands config: vite.config.islands.ts"
       puts "Supported CDNs: #{config.supported_cdns.join(', ')}"
       puts "Built-in global name overrides: #{IslandjsRails::BUILT_IN_GLOBAL_NAME_OVERRIDES.size} available"
     end

data/lib/islandjs_rails/configuration.rb

@@ -2,16 +2,15 @@ require 'pathname'
 
 module IslandjsRails
   class Configuration
-    attr_accessor :package_json_path, :partials_dir, :webpack_config_path, :supported_cdns,
+    attr_accessor :package_json_path, :partials_dir, :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')
+      @vendor_dir = Rails.root.join('public', 'vendor', 'islands')
       @combined_basename = 'islands-vendor'
       @supported_cdns = [
         'https://unpkg.com',

data/lib/islandjs_rails/core.rb

@@ -12,67 +12,14 @@ module IslandjsRails
       @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
+    # No longer needed - Vite handles bundling
 
     # 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,19.2.0]\""
-      puts "                       rails \"islandjs:install[react-dom,19.2.0]\"  "
-      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!"
+      # Use new Vite-based installer
+      require_relative 'vite_installer'
+      installer = ViteInstaller.new
+      installer.install!
     end
 
     # Install a new island package
@@ -92,7 +39,7 @@ module IslandjsRails
       return false unless success
       
       global_name = detect_global_name(package_name)
-      update_webpack_externals(package_name, global_name)
+      update_vite_externals(package_name, global_name)
       
       puts "✅ Successfully installed #{package_name}!"
       
@@ -118,9 +65,9 @@ module IslandjsRails
       vendor_manager = IslandjsRails.vendor_manager
       vendor_manager.install_package!(package_name, version)
       
-      # Update webpack externals
+      # Update Vite externals
       global_name = detect_global_name(package_name)
-      update_webpack_externals(package_name, global_name)
+      update_vite_externals(package_name, global_name)
       
       puts "✅ Successfully updated #{package_name}!"
     end
@@ -139,7 +86,7 @@ module IslandjsRails
       vendor_manager = IslandjsRails.vendor_manager
       vendor_manager.remove_package!(package_name)
       
-      update_webpack_externals
+      update_vite_externals
       puts "✅ Successfully removed #{package_name}!"
     end
 
@@ -165,9 +112,9 @@ module IslandjsRails
         # Install to vendor system
         vendor_manager.install_package!(package_name, version)
         
-        # Update webpack externals
+        # Update Vite externals
         global_name = detect_global_name(package_name)
-        update_webpack_externals(package_name, global_name)
+        update_vite_externals(package_name, global_name)
       end
       
       puts "✅ Sync completed!"
@@ -220,16 +167,15 @@ module IslandjsRails
     vendor_manager.send(:regenerate_vendor_partial!)
     puts "  ✓ Regenerated vendor partial"
     
-    # Reset webpack externals
-    reset_webpack_externals
-    puts "  ✓ Reset webpack externals"
+    # Vite externals will be updated as packages are reinstalled
+    puts "  ✓ Vite externals will be updated as packages are reinstalled"
     
     # 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)
+      update_vite_externals(package_name, global_name)
     end
     
     puts "✅ Clean completed!"
@@ -347,7 +293,7 @@ module IslandjsRails
       File.exist?(partial_path_for(package_name))
     end
     
-    # Get global name for a package (used by webpack externals)
+    # Get global name for a package (used by Vite externals)
     def get_global_name_for_package(package_name)
       detect_global_name(package_name)
     end