islandjs-rails 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84e5fc3b8895ea40c7a38238d4bfb2fdeda1d26bcd765bed555dfbbc87cac018
-  data.tar.gz: 9a8e734d7da2b42657f7a746e43f147f4e77b433c3c63ca258c09bdd98fa8fa3
+  metadata.gz: 3efc622c722a226faf6ab715f92302e3476aa46be3c186dabd7ec8e51cf49166
+  data.tar.gz: 5c6fa3546df97f4c8430e6b9c06b320a6cd06432b6493025bc05a5c4242f88e9
 SHA512:
-  metadata.gz: 894d239d321d52b0d090c0e417953a07576ee370f2a1bb9c1514265311f0994fd3f61baa79d0c52460e3c002d3bfda63dac2f63797f031a14d1bfb8b17095d02
-  data.tar.gz: 9a6c71e8c42d5b8fc1d8a3ec1ffceb6af2acfbe61102122d00c733b7732709a2b97851eb28dca67e67fef502ca0bf9b21635eed555640e0b1dcc2901d174a735
+  metadata.gz: ec382c1d892648a353afed3dec2420b895bf14eae349f3b4a2877aade87bcf8dd2954f3bf1715aa93c6e9fd1f4b3ffed2089c86c356957b0b830aca71387fa03
+  data.tar.gz: 6fd2a2440a750bf0b284452b6faf5835d6a5635e5fef7e4213eb439d77ae95d7667e934eec36e5ff077ea7f1e58d9fbe2d60c140d49ec3c795eae7fe429fe9ad

data/CHANGELOG.md

@@ -5,6 +5,21 @@ 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).
 
+## [0.4.0] - 2025-08-10
+
+### Added
+- Add ENV flag to control the dev UMD bundle info footer. The floating footer is now disabled by default and only shows in development when `ISLANDJS_RAILS_SHOW_UMD_DEBUG` is truthy.
+
+## [0.3.0] - 2025-08-09
+
+### Added
+- **Vendor Script Helper**: New `extra_vendor_tag` helper method for including third-party JavaScript libraries from the vendor directory
+- **Enhanced Package Template**: Updated `lib/templates/package.json` with improved webpack configuration and dependencies
+
+### Enhanced
+- Simplified vendor asset integration with automatic Turbo tracking
+- Better support for third-party library inclusion in Rails applications
+
 ## [0.2.1] - 2025-08-06
 
 ### Fixed

data/README.md

@@ -1,14 +1,15 @@
-# IslandJS Rails
+# IslandJS Rails — Turbo compatible JSX in seconds
+
+**Launch quickly:** *upgrade with vite only if necessary (MYAGNI).*
 
 [![CI](https://github.com/praxis-emergent/islandjs-rails/actions/workflows/github-actions-demo.yml/badge.svg)](https://github.com/praxis-emergent/islandjs-rails/actions/workflows/github-actions-demo.yml)
 [![Test Coverage](https://img.shields.io/badge/coverage-89.09%25-brightgreen.svg)](coverage/index.html)
 [![RSpec Tests](https://img.shields.io/badge/tests-162%20passing-brightgreen.svg)](spec/)
 [![Rails 8 Ready](https://img.shields.io/badge/Rails%208-Ready-brightgreen.svg)](#rails-8-ready)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-red.svg)](https://www.ruby-lang.org/)
 
-IslandJS Rails supports the development of React (or other JS library) islands in Rails apps by synchronizing `package.json` defined dependencies with UMD libraries served in `public/islands/vendor`.
+IslandJS Rails supports the development of React islands in Rails apps by synchronizing `package.json` dependencies with UMD libraries served in `public/islands/vendor`.
 
-Write Turbo compatible JSX in `app/javascript/islands/components/` and render it with a `react_component` helper in ERB templates (including Turbo Stream partials) — Vue and other framework support can be added with a bit of work.
+Write Turbo compatible JSX in `app/javascript/islands/components/` and render it with a `react_component` helper in ERB templates (including Turbo Stream partials) — **Vue and other framework support can be added with a bit of work**.
 
 ## Quick Start
 
@@ -34,6 +35,11 @@ rails "islandjs:install[react,18.3.1]"
 rails "islandjs:install[react-dom,18.3.1]"
 ```
 
+### Run Yarn In Development
+```bash
+yarn watch
+```
+
 ### Render React Components
 ```erb
 <!-- In any view -->
@@ -45,6 +51,11 @@ rails "islandjs:install[react-dom,18.3.1]"
 <% end %>
 ```
 
+### Build For Production
+```bash
+yarn build # you may remove any stale islandjs bundles before committing
+```
+
 > 💡 **Turbo Cache Compatible**: React components automatically persist state across Turbo navigation! See [Turbo Cache Integration](#turbo-cache-integration) for details.
 
 ### Write Modern JSX (with Turbo Cache Support)
@@ -96,10 +107,10 @@ IslandJS Rails aligns perfectly with **Rails 8's philosophy** of simplicity and
 
 ### The Problem IslandJS Rails Solves
 Modern Rails developers face a painful choice:
-- **Bundle everything**: Massive webpack configs, slow builds, bundle bloat
-- **Skip modern JS**: Miss out on React and popular npm packages
+- **Bundle everything**: Complicated configs, slow builds, bundle bloat
+- **Skip modern JS**: Miss out on React and other modern frontend tools
 
-**Important Note:** IslandJS Rails works with packages that ship UMD builds. Many popular packages have UMD builds, but some modern packages do not — React 19+ removed UMD builds entirely. Future versions of IslandJS Rails will support local UMD generation for some packages (such as [React 19+](https://github.com/lofcz/umd-react)).
+**IslandJS Rails offers a middle way:** a simple, zero-config solution for adding React and other JS libraries to your Rails app. Get 80% of reactive use cases covered for 5% of the hassle. Most apps don't even need the other 20% anyway.
 
 ### The IslandJS Rails Solution
 ```bash
@@ -121,7 +132,16 @@ const quill = new window.Quill("#editor", {
 });
 ```
 
-## Rails 8 Ready
+**Important Note:** IslandJS Rails works with packages that ship UMD builds. Many popular packages have UMD builds, but some modern packages do not — React 19+ removed UMD builds entirely. Future versions of IslandJS Rails will support local UMD generation for some packages (such as [React 19+](https://github.com/lofcz/umd-react)).
+
+If you absolutely need a package that doesn't ship UMD builds, you have a few options:
+
+- Option A: Find an alternative lib that supports UMD builds
+- Option B: Build the UMD yourself & serve it like a normal `islandjs-rails` install
+- Option C: Write vanilla JS for the use case
+- Option D: Set up `vite` with [turbo-mount](https://github.com/skryukov/turbo-mount) & write your component that way. You can migrate incrementally from `islandj-rails` to `turbo-mount` if preferred — they can coexist in the same app.
+
+## IslandJS Rails is Rails 8 Ready
 
 ✅ **Tested against Rails 8**  
 ✅ **Compatible with Rails 8 asset pipeline**  
@@ -211,7 +231,7 @@ yarn install
 **Development Workflow:**
 1. Run `yarn watch` (or `npm run watch`) in one terminal
 2. Edit your components in `app/javascript/islands/components/`
-3. Changes are automatically compiled to `public/islands_bundle.js`
+3. Changes are automatically compiled to `public/`
 
 **Production Deployment:**
 1. Run `yarn build` (or `npm run build`) to create optimized bundle
@@ -231,13 +251,13 @@ When installing scoped packages, you **must** include the full package name with
 
 ```bash
 # ✅ Correct - Full scoped package name
-rails "islandjs:install[@solana/web3.js,1.98.2]"
+rails "islandjs:install[@solana/web3.js,1.98.4]"
 
 # ❌ Incorrect - Missing .js suffix
-rails "islandjs:install[@solana/web3,1.98.2]"
+rails "islandjs:install[@solana/web3,1.98.4]"
 
 # ❌ Incorrect - Missing scope
-rails "islandjs:install[web3.js,1.98.2]"
+rails "islandjs:install[web3.js,1.98.4]"
 ```
 
 ### Shell Escaping
@@ -249,7 +269,7 @@ The `@` symbol is handled automatically by Rails task syntax when using double q
 rails "islandjs:install[@solana/web3.js]"
 
 # ✅ Also works (with version)
-rails "islandjs:install[@solana/web3.js,1.98.2]"
+rails "islandjs:install[@solana/web3.js,1.98.4]"
 
 # ⚠️ May not work in some shells without quotes
 rails islandjs:install[@solana/web3.js]  # Avoid this
@@ -534,16 +554,6 @@ const HelloWorld = ({ containerId }) => {
 }) %>
 ```
 
-### Live Demo
-
-See the complete demo: [`react.html.erb`](app/views/islandjs_demo/react.html.erb)
-
-The demo shows:
-- ✅ **State persistence** across Turbo navigation
-- ✅ **Automatic state restoration** when navigating back
-- ✅ **Zero configuration** - works out of the box
-- ✅ **Compatible with Turbo Drive** and all Hotwire features
-
 ### Turbo Utility Functions
 
 IslandJS Rails provides utility functions for Turbo compatibility:
@@ -640,99 +650,6 @@ IslandjsRails.configure do |config|
 end
 ```
 
-## Real-World Examples
-
-### React Dashboard Component
-
-```bash
-# Install dependencies
-rails islandjs:install[react]
-rails islandjs:install[react-dom]  
-rails islandjs:install[chart.js]
-```
-
-```jsx
-// jsx/components/Dashboard.jsx
-import React, { useState, useEffect } from 'react';
-import { useTurboProps, useTurboCache } from '../utils/turbo.js';
-
-function Dashboard({ containerId }) {
-  const initialProps = useTurboProps(containerId);
-  
-  const [data, setData] = useState(initialProps.data || []);
-  const [loading, setLoading] = useState(false);
-
-  // Setup turbo cache persistence
-  useEffect(() => {
-    const cleanup = useTurboCache(containerId, { data }, true);
-    return cleanup;
-  }, [containerId, data]);
-
-  useEffect(() => {
-    // Fetch dashboard data if not cached
-    if (data.length === 0) {
-      setLoading(true);
-      fetch('/api/dashboard')
-        .then(res => res.json())
-        .then(fetchedData => {
-          setData(fetchedData);
-          setLoading(false);
-        });
-    }
-  }, []);
-
-  if (loading) return <div>Loading dashboard...</div>;
-
-  return (
-    <div>
-      <h1>Dashboard</h1>
-      {/* Chart component here */}
-      <p>Data points: {data.length}</p>
-    </div>
-  );
-}
-
-export default Dashboard;
-```
-
-```erb
-<!-- app/views/dashboard/show.html.erb -->
-<%= islands %>
-<%= react_component('Dashboard', { data: @dashboard_data }) %>
-```
-
-### Turbo + React Integration
-
-**⭐ Recommended: Use Built-in Turbo Cache**
-
-IslandJS Rails now includes automatic Turbo cache compatibility! See the [Turbo Cache Integration](#turbo-cache-integration) section above for the modern approach with zero manual setup.
-
-**Alternative: Manual Turbo Integration**
-
-For custom scenarios, you can manually handle Turbo events:
-
-```javascript
-// Manual approach (not needed with react_component helper)
-document.addEventListener('turbo:load', () => {
-  const container = document.getElementById('react-component');
-  if (container && !container.hasChildNodes()) {
-    ReactDOM.render(
-      React.createElement(MyComponent, {
-        data: JSON.parse(container.dataset.props)
-      }),
-      container
-    );
-  }
-});
-
-document.addEventListener('turbo:before-cache', () => {
-  // Cleanup React components before Turbo caches
-  document.querySelectorAll('[data-react-component]').forEach(el => {
-    ReactDOM.unmountComponentAtNode(el);
-  });
-});
-```
-
 ## Troubleshooting
 
 ### Common Issues
@@ -770,30 +687,6 @@ rails islandjs:install[react]
 
 MIT License - see LICENSE file for details.
 
-## Structure
-
-```
-lib/islandjs_rails/
-├── spec/
-│   ├── spec_helper.rb                    # Test setup and mocking
-│   ├── lib/
-│   │   ├── islandjs_rails_spec.rb             # Main module tests
-│   │   └── islandjs_rails/
-│   │       ├── core_spec.rb             # Core functionality tests
-│   │       ├── rails_helpers_spec.rb    # Rails helpers tests
-│   │       ├── configuration_spec.rb    # Configuration tests
-│   │       ├── cli_spec.rb             # CLI tests
-│   │       ├── tasks_spec.rb           # Rake tasks tests
-│   │       ├── railtie_spec.rb         # Rails integration tests
-│   │       └── rails8_integration_spec.rb # Rails 8 specific tests
-│   ├── fixtures/                        # Test fixtures
-│   └── support/                         # Test support files
-├── coverage/                            # SimpleCov coverage reports
-├── Gemfile                              # Test dependencies
-├── Rakefile                             # Test runner configuration
-└── README.md                            # This file
-```
-
 ## Running Tests
 
 ### From the gem directory:
@@ -814,16 +707,6 @@ bundle exec rspec
 open coverage/index.html
 ```
 
-## Adding New Tests
-
-When adding new IslandJS Rails functionality:
-
-1. Add tests to the appropriate test file
-2. Use the provided test helpers for consistency
-3. Mock external dependencies (CDN calls, file system operations)
-4. Test both success and failure scenarios
-5. Ensure tests are isolated and don't affect each other
-
 ## Future Enhancements
 
 Planned features for future releases:
@@ -834,8 +717,6 @@ Planned features for future releases:
 - **TypeScript Support**: First-class TypeScript support for UMD packages
 - **Local UMD Generation**: Generate UMD builds for packages that don't ship them
 - **Multi-framework Support**: Vue, Svelte, and other frameworks
-- **Build-time Optimization**: Optional build-time bundling for production
-- **Edge Computing**: Cloudflare Workers and similar platform support
 
 ---
 

data/lib/islandjs_rails/rails_helpers.rb

@@ -5,7 +5,7 @@ module IslandjsRails
       output = []
       output << island_partials  # Now uses vendor UMD partial
       output << island_bundle_script
-      output << umd_versions_debug if Rails.env.development?
+      output << umd_versions_debug if umd_debug_enabled?
       output.compact.join("\n").html_safe
     end
 
@@ -181,7 +181,7 @@ module IslandjsRails
 
     # Legacy UMD helper methods for backward compatibility with tests
     def umd_versions_debug
-      return unless Rails.env.development?
+      return unless umd_debug_enabled?
       
       begin
         installed = IslandjsRails.core.send(:installed_packages)
@@ -229,8 +229,24 @@ module IslandjsRails
       html_safe_string(partials)
     end
 
+    # Generate a script tag for vendor JavaScript files
+    # Useful for including third-party libraries from the vendor directory
+    def extra_vendor_tag(name, extension = ".min.js")
+      "<script src='/vendor/#{name}#{extension}' data-turbo-track='reload'></script>".html_safe
+    end
+
     private
 
+    # Whether the floating UMD versions debug footer should render
+    def umd_debug_enabled?
+      return false unless Rails.env.development?
+
+      env_value = ENV['ISLANDJS_RAILS_SHOW_UMD_DEBUG']
+      return false if env_value.nil?
+
+      %w[1 true yes on].include?(env_value.to_s.strip.downcase)
+    end
+
     # Find the bundle file path (with manifest support)
     def find_bundle_path
       # Try manifest first (production)

data/lib/islandjs_rails/version.rb

@@ -1,3 +1,3 @@
 module IslandjsRails
-  VERSION = "0.2.1"
+  VERSION = "0.4.0"
 end

data/lib/templates/package.json

@@ -3,8 +3,8 @@
   "version": "1.0.0",
   "private": true,
   "scripts": {
-    "build": "rm -f public/islands_bundle.*.js && NODE_ENV=production webpack",
-    "build:dev": "rm -f public/islands_bundle.*.js && NODE_ENV=production webpack",
+    "build": "rm -f public/islands_* && NODE_ENV=production webpack",
+    "build:dev": "rm -f public/islands_* && NODE_ENV=production webpack",
     "watch": "NODE_ENV=development webpack --watch"
   },
   "dependencies": {},

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: islandjs-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Eric Arnold