shakapacker 8.0.2 → 9.2.0

data/Rakefile

@@ -14,16 +14,51 @@ namespace :run_spec do
     sh("bundle exec rspec spec/shakapacker/*_spec.rb")
   end
 
-  desc "Run specs in the dummy app"
+  desc "Run specs in the dummy app with webpack"
   task :dummy do
-    puts "Running dummy app specs"
+    puts "Running dummy app specs with webpack"
     spec_dummy_dir = Pathname.new(File.join("spec", "dummy")).realpath
     Bundler.with_unbundled_env do
       sh_in_dir(".", "yalc publish")
       sh_in_dir(spec_dummy_dir, [
         "bundle install",
         "yalc link shakapacker",
-        "yarn install",
+        "npm install",
+        "bin/test-bundler webpack",
+        "NODE_ENV=test RAILS_ENV=test bin/shakapacker",
+        "bundle exec rspec"
+      ])
+    end
+  end
+
+  desc "Run specs in the dummy app with rspack"
+  task :dummy_with_rspack do
+    puts "Running dummy app specs with rspack"
+    spec_dummy_dir = Pathname.new(File.join("spec", "dummy")).realpath
+    Bundler.with_unbundled_env do
+      sh_in_dir(".", "yalc publish")
+      sh_in_dir(spec_dummy_dir, [
+        "bundle install",
+        "yalc link shakapacker",
+        "npm install",
+        "bin/test-bundler rspack",
+        "NODE_ENV=test RAILS_ENV=test bin/shakapacker",
+        "bundle exec rspec"
+      ])
+    end
+  end
+
+  desc "Run specs in the dummy-rspack app"
+  task :dummy_rspack do
+    puts "Running dummy-rspack app specs"
+    spec_dummy_dir = Pathname.new(File.join("spec", "dummy-rspack")).realpath
+    Bundler.with_unbundled_env do
+      sh_in_dir(".", "yalc publish")
+      sh_in_dir(spec_dummy_dir, [
+        "bundle install",
+        "yalc link shakapacker",
+        "npm install",
+        "NODE_ENV=test RAILS_ENV=test npm exec --no -- rspack build --config config/rspack/rspack.config.js",
         "bundle exec rspec"
       ])
     end
@@ -35,7 +70,7 @@ namespace :run_spec do
   end
 
   desc "Run all specs"
-  task all_specs: %i[gem dummy generator] do
+  task all_specs: %i[gem dummy dummy_with_rspack dummy_rspack generator] do
     puts "Completed all RSpec tests"
   end
 end

data/TODO.md

@@ -0,0 +1,50 @@
+# TypeScript Migration Status
+
+## ✅ Completed (PR #602)
+- Enhanced `package/index.d.ts` with comprehensive type definitions
+- Added TypeScript type packages for better IDE support
+- Improved Config and DevServerConfig interfaces
+- Added missing properties (private_output_path, inline_css, env_prefix, etc.)
+- All tests passing
+- Zero JavaScript modifications (no whitespace changes)
+- Full backward compatibility maintained
+
+## 📋 Next Steps (Issue #605)
+
+### Phase 2: Core Module Conversion
+- [ ] Convert `package/config.js` to TypeScript
+- [ ] Convert `package/env.js` to TypeScript  
+- [ ] Convert `package/index.js` to TypeScript
+- [ ] Convert `package/utils/helpers.js` to TypeScript
+
+### Phase 3: Environment & Build System
+- [ ] Convert environment files (base, development, production, test)
+- [ ] Convert dev_server.js
+- [ ] Convert webpackDevServerConfig.js
+
+### Phase 4: Rules & Loaders (PR #620) ✅
+- [x] Convert all files in `package/rules/`
+- [x] Convert all files in `package/plugins/`
+- [x] Convert all files in `package/optimization/`
+
+### Phase 5: Framework-Specific Modules ✅
+- [x] Convert rspack support files
+- [x] Convert swc support files
+- [x] Convert esbuild support files
+- [x] Convert babel preset
+
+### Phase 6: Final Cleanup ✅
+- [x] Add TypeScript linting with @typescript-eslint
+- [x] Verify strict mode is enabled (already configured)
+- [x] Update documentation
+
+## Why Gradual Migration?
+- **Lower risk**: Each phase can be tested independently
+- **Team learning**: Get familiar with TypeScript incrementally
+- **Immediate value**: Type definitions already provide IDE benefits
+- **No breaking changes**: Users unaffected during migration
+
+## Related Links
+- Original issue: #200
+- Initial PR: #602
+- Next steps issue: #605

data/TODO_v9.md

@@ -0,0 +1,87 @@
+# Shakapacker v9 TODO List
+
+## CSS Modules Configuration Alignment
+
+### Problem
+Current CSS modules configuration causes TypeScript/webpack warnings because of default vs named export mismatch.
+
+### Current Behavior (v8)
+- CSS modules use default export: `import styles from './styles.module.css'`
+- This causes warnings but works at runtime
+- Warning example: `export 'default' (imported as 'style') was not found in './HelloWorld.module.css'`
+
+### Proposed v9 Change
+Align with Next.js and modern tooling by using named exports:
+
+1. **Update css-loader configuration:**
+```javascript
+{
+  loader: 'css-loader',
+  options: {
+    modules: {
+      namedExport: true,
+      exportLocalsConvention: 'camelCaseOnly'  // Must be 'camelCaseOnly' or 'dashesOnly' with namedExport: true
+    }
+  }
+}
+```
+
+**Note:** Using `exportLocalsConvention: 'camelCase'` with `namedExport: true` will cause a build error.
+css-loader only allows `'camelCaseOnly'` or `'dashesOnly'` when named exports are enabled.
+
+2. **Update TypeScript types:**
+- Ensure proper typing for CSS modules with named exports
+- May need to update or generate `.d.ts` files for CSS modules
+
+3. **Migration guide for users:**
+- Document the breaking change
+- Provide codemod or migration script to update imports from:
+  ```javascript
+  import styles from './styles.module.css'
+  styles.className
+  ```
+  to:
+  ```javascript
+  import * as styles from './styles.module.css'
+  // or
+  import { className } from './styles.module.css'
+  ```
+
+### Benefits
+- Eliminates webpack/TypeScript warnings
+- Better tree-shaking potential
+- More explicit about what CSS classes are being used
+- Easier interoperability with frameworks that support named exports
+
+### Implementation Notes
+- This is a BREAKING CHANGE and appropriate for major version bump
+- Need to test with both webpack and rspack
+- Consider providing a compatibility mode via configuration option
+
+---
+
+## Related Issues from PR #597
+
+### React Component Not Rendering (spec/dummy) - RESOLVED ✅
+- **Issue**: React component was not rendering due to CSS module import mismatch
+- **Symptoms**:
+  - Component wasn't rendering "Hello, Stranger!"
+  - Input field not rendered, making interactive test fail
+  - Only the static H1 "Hello, World!" was visible
+- **Resolution**:
+  - Fixed CSS module import syntax from `import style from` to `import * as style from`
+  - This matched webpack's named exports configuration for CSS modules
+  - Tests now pass with both React 18.3.1 and webpack/rspack configurations
+- **Root Cause**: CSS module import/export mismatch
+  - Webpack was configured to use named exports for CSS modules
+  - TypeScript code was using default import syntax
+  - This caused `style` to be undefined, breaking SSR and client rendering
+- **Status**: FIXED
+  - All tests re-enabled and passing
+  - Both SSR and client-side rendering working
+  - Interactive functionality restored
+
+### Test Infrastructure
+- Successfully implemented dual bundler support (webpack/rspack)
+- test-bundler script working well with status command
+- Consider adding more comprehensive tests for both bundlers

data/bin/export-bundler-config

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+// Minimal shim - all logic is in the TypeScript module
+const { run } = require('shakapacker/configExporter')
+
+run(process.argv.slice(2))
+  .then((exitCode) => process.exit(exitCode))
+  .catch((error) => {
+    console.error(error.message)
+    process.exit(1)
+  })

data/conductor-setup.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "🔧 Setting up Shakapacker workspace..."
+
+# Set up Ruby version if asdf is available
+if command -v asdf &> /dev/null; then
+    echo "📝 Using asdf Ruby version management..."
+    # Ensure we have the right Ruby version file
+    echo "ruby 3.3.4" > .tool-versions
+    # Use asdf exec to run commands with the right Ruby version
+    BUNDLE_CMD="asdf exec bundle"
+else
+    BUNDLE_CMD="bundle"
+fi
+
+# Check for required tools
+if ! $BUNDLE_CMD --version &> /dev/null; then
+    echo "❌ Error: Ruby bundler is not installed"
+    echo "Please install bundler first: gem install bundler"
+    exit 1
+fi
+
+if ! command -v yarn &> /dev/null; then
+    echo "❌ Error: Yarn is not installed"
+    echo "Please install yarn first"
+    exit 1
+fi
+
+# Install Ruby dependencies
+echo "📦 Installing Ruby dependencies..."
+$BUNDLE_CMD install
+
+# Install JavaScript dependencies
+echo "📦 Installing JavaScript dependencies..."
+yarn install
+
+# Set up Husky git hooks
+echo "🪝 Setting up Husky git hooks..."
+npx husky
+if [ ! -f .husky/pre-commit ]; then
+    echo "Creating pre-commit hook..."
+    cat > .husky/pre-commit << 'EOF'
+#!/usr/bin/env sh
+npx lint-staged
+EOF
+    chmod +x .husky/pre-commit
+fi
+
+# Copy environment files if they exist in root
+if [ -n "${CONDUCTOR_ROOT_PATH:-}" ]; then
+    if [ -f "$CONDUCTOR_ROOT_PATH/.env" ]; then
+        echo "📋 Copying .env file from root..."
+        cp "$CONDUCTOR_ROOT_PATH/.env" .env
+    fi
+    
+    if [ -f "$CONDUCTOR_ROOT_PATH/.env.local" ]; then
+        echo "📋 Copying .env.local file from root..."
+        cp "$CONDUCTOR_ROOT_PATH/.env.local" .env.local
+    fi
+fi
+
+echo "✅ Workspace setup complete!"
+echo ""
+echo "Available commands:"
+echo "  - Run tests: bundle exec rspec"
+echo "  - Run specific test suites: bundle exec rake run_spec:gem"
+echo "  - Run JavaScript tests: yarn test"
+echo "  - Lint JavaScript: yarn lint"
+echo "  - Lint Ruby: bundle exec rubocop"

data/conductor.json

@@ -0,0 +1,7 @@
+{
+  "scripts": {
+    "setup": "./conductor-setup.sh",
+    "run": "bundle exec rspec",
+    "archive": ""
+  }
+}

data/docs/cdn_setup.md

@@ -0,0 +1,379 @@
+# CDN Setup Guide for Shakapacker
+
+This guide explains how to configure Shakapacker to serve your JavaScript bundles and other assets from a Content Delivery Network (CDN) like CloudFlare, CloudFront, or Fastly.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Configuration Methods](#configuration-methods)
+- [Step-by-Step Setup](#step-by-step-setup)
+- [CloudFlare Specific Setup](#cloudflare-specific-setup)
+- [Verification](#verification)
+- [Troubleshooting](#troubleshooting)
+- [Advanced Configuration](#advanced-configuration)
+
+## Overview
+
+When using a CDN with Shakapacker, your compiled JavaScript bundles and other assets will be served from the CDN's edge servers instead of your application server. This provides:
+
+- **Reduced latency** for users around the world
+- **Decreased load** on your application servers
+- **Better caching** and faster asset delivery
+- **Improved scalability** for high-traffic applications
+
+## Configuration Methods
+
+Shakapacker supports CDN configuration through three methods (in order of precedence):
+
+1. **Environment Variable** (highest priority): `SHAKAPACKER_ASSET_HOST`
+2. **Shakapacker Configuration File**: `asset_host` setting in `config/shakapacker.yml`
+3. **Rails Configuration**: `Rails.application.config.asset_host`
+
+## Step-by-Step Setup
+
+### 1. Configure Your CDN
+
+First, set up your CDN to pull assets from your application's `/packs` directory. The exact steps depend on your CDN provider, but generally you'll need to:
+
+1. Create a CDN distribution/zone
+2. Set your application's domain as the origin server
+3. Configure the CDN to cache files from `/packs/*` path
+4. Note your CDN URL (e.g., `https://cdn.example.com` or `https://d1234567890.cloudfront.net`)
+
+### 2. Configure Shakapacker Asset Host
+
+Choose one of the following methods:
+
+#### Option A: Using Environment Variable (Recommended for Production)
+
+Set the `SHAKAPACKER_ASSET_HOST` environment variable:
+
+```bash
+# For production deployment
+export SHAKAPACKER_ASSET_HOST=https://cdn.example.com
+
+# Or in your .env file
+SHAKAPACKER_ASSET_HOST=https://cdn.example.com
+```
+
+#### Option B: Using shakapacker.yml
+
+Add the `asset_host` setting to your `config/shakapacker.yml`:
+
+```yaml
+production:
+  # ... other settings ...
+  asset_host: https://cdn.example.com
+  
+  # You can also set different CDN hosts per environment
+staging:
+  asset_host: https://staging-cdn.example.com
+```
+
+#### Option C: Using Rails Configuration
+
+Configure in your Rails environment file (e.g., `config/environments/production.rb`):
+
+```ruby
+Rails.application.configure do
+  # ... other settings ...
+  
+  # This will be used by Shakapacker if SHAKAPACKER_ASSET_HOST 
+  # and asset_host in shakapacker.yml are not set
+  config.action_controller.asset_host = 'https://cdn.example.com'
+end
+```
+
+### 3. Compile Assets
+
+During deployment, compile your assets as usual:
+
+```bash
+# The SHAKAPACKER_ASSET_HOST will be used during compilation
+# to set the webpack publicPath
+RAILS_ENV=production bundle exec rails assets:precompile
+```
+
+This ensures that:
+- Webpack's `publicPath` is set to your CDN URL
+- Dynamic imports and code-split chunks load from the CDN
+- Asset manifest references use CDN URLs
+
+### 4. Deploy and Sync Assets
+
+After compilation, ensure your compiled assets in `public/packs` are accessible to your CDN:
+
+- **Push CDN**: Upload the files to your CDN's storage
+- **Pull CDN**: Deploy your application normally; the CDN will pull assets on first request
+
+## CloudFlare Specific Setup
+
+For CloudFlare CDN setup:
+
+### 1. Create a CloudFlare Account and Add Your Domain
+
+1. Sign up for CloudFlare (if you haven't already)
+2. Add your domain to CloudFlare
+3. Update your domain's nameservers to CloudFlare's
+
+### 2. Configure Page Rules for Assets
+
+Create a page rule for your assets:
+
+1. Go to **Page Rules** in CloudFlare dashboard
+2. Create a new rule for `*yourdomain.com/packs/*`
+3. Set the following settings:
+   - **Cache Level**: Cache Everything
+   - **Edge Cache TTL**: 1 month (or your preference)
+   - **Browser Cache TTL**: 1 month
+
+### 3. Set Up CloudFlare for Assets Only (Optional)
+
+If you want CloudFlare to only serve your assets (not your entire site):
+
+1. Create a CNAME record: `cdn.yourdomain.com` → `yourdomain.com`
+2. Set CloudFlare proxy (orange cloud) ON for this record
+3. Configure Shakapacker:
+
+```bash
+export SHAKAPACKER_ASSET_HOST=https://cdn.yourdomain.com
+```
+
+### 4. Configure CloudFlare Settings
+
+Recommended CloudFlare settings for assets:
+
+- **SSL/TLS**: Full or Full (Strict)
+- **Caching Level**: Standard or Aggressive
+- **Browser Cache TTL**: Respect Existing Headers
+- **Always Online**: On
+- **Auto Minify**: OFF (Shakapacker already minifies)
+
+## Verification
+
+To verify your CDN setup is working:
+
+### 1. Check Compiled Assets
+
+After compilation, inspect a compiled JavaScript file:
+
+```bash
+# Look for the publicPath setting in your compiled bundles
+grep -r "publicPath" public/packs/js/
+```
+
+You should see your CDN URL in the publicPath configuration.
+
+### 2. Check Page Source
+
+In production, view your page source and verify script tags use CDN URLs:
+
+```html
+<!-- Correct: Assets loading from CDN -->
+<script src="https://cdn.example.com/packs/js/application-abc123.js"></script>
+
+<!-- Wrong: Assets loading from relative path -->
+<script src="/packs/js/application-abc123.js"></script>
+```
+
+### 3. Check Network Tab
+
+1. Open browser DevTools
+2. Go to Network tab
+3. Reload the page
+4. Verify JavaScript files are loaded from CDN domain
+
+### 4. Check Dynamic Imports
+
+If using code splitting, verify dynamic chunks load from CDN:
+
+```javascript
+// This dynamic import should load from CDN
+import('./components/HeavyComponent').then(module => {
+  // Check Network tab - chunk should load from CDN
+});
+```
+
+## Troubleshooting
+
+### Assets Not Loading from CDN
+
+**Problem**: Assets are still loading from your application domain.
+
+**Solutions**:
+1. Ensure you set `SHAKAPACKER_ASSET_HOST` **before** running `assets:precompile`
+2. Clear Rails cache: `rails tmp:cache:clear`
+3. Check the manifest.json file includes CDN URLs:
+   ```bash
+   cat public/packs/manifest.json
+   ```
+
+### CORS Errors
+
+**Problem**: Browser shows CORS errors when loading assets from CDN.
+
+**Solutions**:
+1. Configure your CDN to add CORS headers:
+   ```
+   Access-Control-Allow-Origin: *
+   ```
+2. Or configure for specific domain:
+   ```
+   Access-Control-Allow-Origin: https://yourdomain.com
+   ```
+
+### Fonts Not Loading
+
+**Problem**: Web fonts fail to load from CDN due to CORS.
+
+**Solutions**:
+1. Ensure CDN sends proper CORS headers for font files
+2. In CloudFlare, create a page rule for `*.woff2`, `*.woff`, `*.ttf` files with CORS headers
+3. Consider hosting fonts separately or using base64 encoding
+
+### Development Environment Issues
+
+**Problem**: CDN URLs appearing in development environment.
+
+**Solution**: Only set `SHAKAPACKER_ASSET_HOST` in production:
+
+```ruby
+# config/environments/development.rb
+# Ensure asset_host is NOT set in development
+
+# config/environments/production.rb
+# Set asset_host only in production
+```
+
+## Advanced Configuration
+
+### Using Different CDNs for Different Assets
+
+You can use Rails asset host proc for dynamic CDN selection:
+
+```ruby
+# config/environments/production.rb
+config.action_controller.asset_host = Proc.new do |source|
+  if source =~ /\.(js|css)$/
+    'https://js-css-cdn.example.com'
+  else
+    'https://images-cdn.example.com'
+  end
+end
+```
+
+### CDN with Integrity Hashes
+
+When using Subresource Integrity (SRI) with CDN:
+
+```yaml
+# config/shakapacker.yml
+production:
+  asset_host: https://cdn.example.com
+  integrity:
+    enabled: true
+    hash_functions: ["sha384"]
+    cross_origin: "anonymous"
+```
+
+Ensure your CDN serves files with CORS headers:
+```
+Access-Control-Allow-Origin: *
+```
+
+### Multiple CDN Domains for Parallel Downloads
+
+For HTTP/1.1 optimization (less relevant with HTTP/2):
+
+```ruby
+# config/environments/production.rb
+config.action_controller.asset_host = Proc.new do |source|
+  "https://cdn#{Digest::MD5.hexdigest(source)[0..2].to_i(16) % 4}.example.com"
+end
+# This creates cdn0.example.com through cdn3.example.com
+```
+
+### Cache Busting
+
+Shakapacker automatically includes content hashes in production:
+
+```yaml
+# config/shakapacker.yml
+production:
+  # This is already true by default in production
+  useContentHash: true
+```
+
+This ensures CDN caches are invalidated when content changes.
+
+### Preloading Critical Assets
+
+Use Rails helpers to preload critical assets from CDN:
+
+```erb
+<%= preload_pack_asset 'application.js' %>
+<%= preload_pack_asset 'application.css' %>
+```
+
+## Security Considerations
+
+1. **Use HTTPS**: Always use HTTPS for your CDN URL to prevent mixed content warnings
+2. **Configure CSP**: Update Content Security Policy headers to allow CDN domain:
+   ```ruby
+   # config/initializers/content_security_policy.rb
+   Rails.application.config.content_security_policy do |policy|
+     policy.script_src :self, 'https://cdn.example.com'
+     policy.style_src :self, 'https://cdn.example.com'
+   end
+   ```
+3. **Use SRI**: Enable Subresource Integrity for additional security
+4. **Monitor CDN**: Set up monitoring for CDN availability and performance
+
+## Example Configuration
+
+Here's a complete example for a production setup with CloudFlare:
+
+```yaml
+# config/shakapacker.yml
+production:
+  compile: false
+  cache_manifest: true
+  asset_host: <%= ENV.fetch('SHAKAPACKER_ASSET_HOST', 'https://cdn.example.com') %>
+  
+  # Enable integrity checking
+  integrity:
+    enabled: true
+    hash_functions: ["sha384"]
+    cross_origin: "anonymous"
+```
+
+```ruby
+# config/environments/production.rb
+Rails.application.configure do
+  # Fallback if SHAKAPACKER_ASSET_HOST is not set
+  config.action_controller.asset_host = 'https://cdn.example.com'
+  
+  # Ensure proper headers for CDN
+  config.public_file_server.headers = {
+    'Cache-Control' => 'public, max-age=31536000',
+    'X-Content-Type-Options' => 'nosniff'
+  }
+end
+```
+
+```bash
+# Deployment script
+export SHAKAPACKER_ASSET_HOST=https://cdn.example.com
+RAILS_ENV=production bundle exec rails assets:precompile
+```
+
+## Summary
+
+Setting up a CDN with Shakapacker involves:
+
+1. Configuring your CDN service
+2. Setting the `SHAKAPACKER_ASSET_HOST` environment variable
+3. Compiling assets with the CDN URL
+4. Deploying and verifying the setup
+
+The key is ensuring `SHAKAPACKER_ASSET_HOST` is set during asset compilation so webpack's `publicPath` is configured correctly for dynamic imports and code-split chunks.