shakapacker 9.0.0.beta.3 → 9.0.0.beta.5

data/docs/v9_upgrade.md

@@ -1,6 +1,19 @@
 # Shakapacker v9 Upgrade Guide
 
-This guide outlines breaking changes and migration steps for upgrading from Shakapacker v8 to v9.
+This guide outlines new features, breaking changes, and migration steps for upgrading from Shakapacker v8 to v9.
+
+## New Features
+
+### TypeScript Support
+
+Shakapacker v9 includes TypeScript definitions for better IDE support and type safety.
+
+- **No breaking changes** - JavaScript configs continue to work
+- **Optional** - Use TypeScript only if you want it  
+- **Type safety** - Catch configuration errors at compile-time
+- **IDE support** - Full autocomplete for all options
+
+See the [TypeScript Documentation](./typescript.md) for usage examples.
 
 ## Breaking Changes
 
@@ -65,7 +78,50 @@ javascript_transpiler: 'babel'
 
 **Note:** The old `webpack_loader` option is deprecated but still supported with a warning.
 
-### 3. Rspack Support Added
+### 3. SWC is Now the Default JavaScript Transpiler
+
+**What changed:** SWC replaces Babel as the default JavaScript transpiler. Babel is no longer included in peer dependencies.
+
+**Why:** SWC is 20x faster than Babel while maintaining compatibility with most JavaScript and TypeScript code.
+
+**Impact on existing projects:**
+- Your project will continue using Babel if you already have babel packages in package.json
+- To switch to SWC for better performance, see migration options below
+
+**Impact on new projects:**
+- New installations will use SWC by default
+- Babel dependencies won't be installed unless explicitly configured
+
+### Migration Options
+
+#### Option 1 (Recommended): Switch to SWC
+```yml
+# config/shakapacker.yml
+javascript_transpiler: 'swc'
+```
+Then install SWC:
+```bash
+npm install @swc/core swc-loader
+```
+
+#### Option 2: Keep using Babel
+```yml
+# config/shakapacker.yml
+javascript_transpiler: 'babel'
+```
+No other changes needed - your existing babel packages will continue to work.
+
+#### Option 3: Use esbuild
+```yml
+# config/shakapacker.yml
+javascript_transpiler: 'esbuild'
+```
+Then install esbuild:
+```bash
+npm install esbuild esbuild-loader
+```
+
+### 4. Rspack Support Added
 
 **New feature:** Shakapacker v9 adds support for Rspack as an alternative bundler to webpack.
 

data/lib/install/config/shakapacker.yml

@@ -40,8 +40,10 @@ default: &default
   # Reload manifest.json on all requests so we reload latest compiled packs
   cache_manifest: false
 
-  # Select JavaScript transpiler to use, available options are 'babel' (default), 'swc' or 'esbuild'
-  javascript_transpiler: 'babel'
+  # Select JavaScript transpiler to use
+  # Available options: 'swc' (default, 20x faster), 'babel', or 'esbuild'
+  # Note: When using rspack, swc is used automatically regardless of this setting
+  javascript_transpiler: 'swc'
 
   # Select assets bundler to use
   # Available options: 'webpack' (default) or 'rspack'

data/lib/install/package.json

@@ -26,5 +26,13 @@
     "@babel/preset-env": "^7.16.11",
     "@babel/runtime": "^7.17.9",
     "babel-loader": "^8.2.4 || ^9.0.0 || ^10.0.0"
+  },
+  "swc": {
+    "@swc/core": "^1.3.0",
+    "swc-loader": "^0.2.0"
+  },
+  "esbuild": {
+    "esbuild": "^0.24.0",
+    "esbuild-loader": "^4.0.0"
   }
 }

data/lib/install/template.rb

@@ -2,25 +2,56 @@ require "shakapacker/utils/misc"
 require "shakapacker/utils/manager"
 require "shakapacker/utils/version_syntax_converter"
 require "package_json"
+require "yaml"
+require "json"
 
 # Install Shakapacker
 
 force_option = ENV["FORCE"] ? { force: true } : {}
 
-copy_file "#{__dir__}/config/shakapacker.yml", "config/shakapacker.yml", force_option
+# Initialize variables for use throughout the template
+# Using instance variable to avoid method definition issues in Rails templates
+@package_json ||= PackageJson.new
+install_dir = File.expand_path(File.dirname(__FILE__))
+
+# Installation strategy:
+# - USE_BABEL_PACKAGES installs both babel AND swc for compatibility
+# - Otherwise install only the specified transpiler
+if ENV["USE_BABEL_PACKAGES"] == "true" || ENV["USE_BABEL_PACKAGES"] == "1"
+  @transpiler_to_install = "babel"
+  say "📦 Installing Babel packages (USE_BABEL_PACKAGES is set)", :yellow
+  say "✨ Also installing SWC packages for default config compatibility", :green
+elsif ENV["JAVASCRIPT_TRANSPILER"]
+  @transpiler_to_install = ENV["JAVASCRIPT_TRANSPILER"]
+  say "📦 Installing #{@transpiler_to_install} packages", :blue
+else
+  # Default to swc (matches the default in shakapacker.yml)
+  @transpiler_to_install = "swc"
+  say "✨ Installing SWC packages (20x faster than Babel)", :green
+end
+
+# Copy config file
+copy_file "#{install_dir}/config/shakapacker.yml", "config/shakapacker.yml", force_option
+
+# Update config if USE_BABEL_PACKAGES is set to ensure babel is used at runtime
+if @transpiler_to_install == "babel" && !ENV["JAVASCRIPT_TRANSPILER"]
+  # When USE_BABEL_PACKAGES is set, update the config to use babel
+  gsub_file "config/shakapacker.yml", "javascript_transpiler: 'swc'", "javascript_transpiler: 'babel'"
+  say "   📝 Updated config/shakapacker.yml to use Babel transpiler", :green
+end
 
 say "Copying webpack core config"
-directory "#{__dir__}/config/webpack", "config/webpack", force_option
+directory "#{install_dir}/config/webpack", "config/webpack", force_option
 
 if Dir.exist?(Shakapacker.config.source_path)
   say "The packs app source directory already exists"
 else
   say "Creating packs app source directory"
   empty_directory "app/javascript/packs"
-  copy_file "#{__dir__}/application.js", "app/javascript/packs/application.js"
+  copy_file "#{install_dir}/application.js", "app/javascript/packs/application.js"
 end
 
-apply "#{__dir__}/binstubs.rb"
+apply "#{install_dir}/binstubs.rb"
 
 git_ignore_path = Rails.root.join(".gitignore")
 if File.exist?(git_ignore_path)
@@ -43,17 +74,8 @@ else
   say %(        Add <%= javascript_pack_tag "application" %> within the <head> tag in your custom layout.)
 end
 
-def package_json
-  @package_json ||= PackageJson.new
-end
-
 # setup the package manager with default values
-package_json.merge! do |pj|
-  babel = pj.fetch("babel", {})
-
-  babel["presets"] ||= []
-  babel["presets"].push("./node_modules/shakapacker/package/babel/preset.js")
-
+@package_json.merge! do |pj|
   package_manager = pj.fetch("packageManager") do
     "#{Shakapacker::Utils::Manager.guess_binary}@#{Shakapacker::Utils::Manager.guess_version}"
   end
@@ -62,7 +84,6 @@ package_json.merge! do |pj|
     "name" => "app",
     "private" => true,
     "version" => "0.1.0",
-    "babel" => babel,
     "browserslist" => [
       "defaults"
     ],
@@ -74,7 +95,7 @@ Shakapacker::Utils::Manager.error_unless_package_manager_is_obvious!
 
 # Ensure there is `system!("bin/yarn")` command in `./bin/setup` file
 if (setup_path = Rails.root.join("bin/setup")).exist?
-  native_install_command = package_json.manager.native_install_command.join(" ")
+  native_install_command = @package_json.manager.native_install_command.join(" ")
 
   say "Run #{native_install_command} during bin/setup"
 
@@ -103,42 +124,61 @@ if (setup_path = Rails.root.join("bin/setup")).exist?
   end
 end
 
-def add_dependencies(dependencies, type)
-  package_json.manager.add!(dependencies, type: type)
-rescue PackageJson::Error
-  say "Shakapacker installation failed 😭 See above for details.", :red
-  exit 1
-end
-
-def fetch_peer_dependencies
-  PackageJson.read("#{__dir__}").fetch(ENV["SHAKAPACKER_BUNDLER"] || "webpack")
-end
-
-def fetch_common_dependencies
-  ENV["SKIP_COMMON_LOADERS"] ? {} : PackageJson.read("#{__dir__}").fetch("common")
-end
-
-def fetch_babel_dependencies
-  ENV["USE_BABEL_PACKAGES"] ? PackageJson.read("#{__dir__}").fetch("babel") : {}
-end
-
 Dir.chdir(Rails.root) do
   npm_version = Shakapacker::Utils::VersionSyntaxConverter.new.rubygem_to_npm(Shakapacker::VERSION)
   say "Installing shakapacker@#{npm_version}"
-  add_dependencies(["shakapacker@#{npm_version}"], :production)
-
-  package_json.merge! do |pj|
-    {
-      "dependencies" => pj["dependencies"].merge({
-        # TODO: workaround for test suite - long-run need to actually account for diff pkg manager behaviour
-        "shakapacker" => pj["dependencies"]["shakapacker"].delete_prefix("^")
-      })
-    }
+  begin
+    @package_json.manager.add!(["shakapacker@#{npm_version}"], type: :production)
+  rescue PackageJson::Error
+    say "Shakapacker installation failed 😭 See above for details.", :red
+    exit 1
   end
 
-  peers = fetch_peer_dependencies
-  peers = peers.merge(fetch_common_dependencies)
-  peers = peers.merge(fetch_babel_dependencies)
+  @package_json.merge! do |pj|
+    if pj["dependencies"] && pj["dependencies"]["shakapacker"]
+      {
+        "dependencies" => pj["dependencies"].merge({
+          # TODO: workaround for test suite - long-run need to actually account for diff pkg manager behaviour
+          "shakapacker" => pj["dependencies"]["shakapacker"].delete_prefix("^")
+        })
+      }
+    else
+      pj
+    end
+  end
+
+  # Inline fetch_peer_dependencies and fetch_common_dependencies
+  peers = PackageJson.read(install_dir).fetch(ENV["SHAKAPACKER_BUNDLER"] || "webpack")
+  common_deps = ENV["SKIP_COMMON_LOADERS"] ? {} : PackageJson.read(install_dir).fetch("common")
+  peers = peers.merge(common_deps)
+
+  # Add transpiler-specific dependencies based on detected/configured transpiler
+  # Inline the logic here since methods can't be called before they're defined in Rails templates
+
+  # Install transpiler-specific dependencies
+  # When USE_BABEL_PACKAGES is set, install both babel AND swc
+  # This ensures backward compatibility while supporting the default config
+  if @transpiler_to_install == "babel"
+    # Install babel packages
+    babel_deps = PackageJson.read(install_dir).fetch("babel")
+    peers = peers.merge(babel_deps)
+
+    # Also install SWC since that's what the default config uses
+    # This ensures the runtime works regardless of config
+    swc_deps = PackageJson.read(install_dir).fetch("swc")
+    peers = peers.merge(swc_deps)
+
+    say "ℹ️  Installing both Babel and SWC packages for compatibility:", :blue
+    say "   - Babel packages are installed as requested via USE_BABEL_PACKAGES", :blue
+    say "   - SWC packages are also installed to ensure the default config works", :blue
+    say "   - Your actual transpiler will be determined by your shakapacker.yml configuration", :blue
+  elsif @transpiler_to_install == "swc"
+    swc_deps = PackageJson.read(install_dir).fetch("swc")
+    peers = peers.merge(swc_deps)
+  elsif @transpiler_to_install == "esbuild"
+    esbuild_deps = PackageJson.read(install_dir).fetch("esbuild")
+    peers = peers.merge(esbuild_deps)
+  end
 
   dev_dependency_packages = ["webpack-dev-server"]
 
@@ -146,8 +186,17 @@ Dir.chdir(Rails.root) do
   dev_dependencies_to_add = []
 
   peers.each do |(package, version)|
-    major_version = version.split("||").last.match(/(\d+)/)[1]
-    entry = "#{package}@#{major_version}"
+    # Handle versions like "^1.3.0" or ">= 4 || 5"
+    if version.start_with?("^", "~") || version.match?(/^\d+\.\d+/)
+      # Already has proper version format, use as-is
+      entry = "#{package}@#{version}"
+    else
+      # Extract major version from complex version strings like ">= 4 || 5"
+      # Fallback to "latest" if no version number found
+      version_match = version.split("||").last.match(/(\d+)/)
+      major_version = version_match ? version_match[1] : "latest"
+      entry = "#{package}@#{major_version}"
+    end
 
     if dev_dependency_packages.include? package
       dev_dependencies_to_add << entry
@@ -157,8 +206,36 @@ Dir.chdir(Rails.root) do
   end
 
   say "Adding shakapacker peerDependencies"
-  add_dependencies(dependencies_to_add, :production)
+  begin
+    @package_json.manager.add!(dependencies_to_add, type: :production)
+  rescue PackageJson::Error
+    say "Shakapacker installation failed 😭 See above for details.", :red
+    exit 1
+  end
 
   say "Installing webpack-dev-server for live reloading as a development dependency"
-  add_dependencies(dev_dependencies_to_add, :dev)
+  begin
+    @package_json.manager.add!(dev_dependencies_to_add, type: :dev)
+  rescue PackageJson::Error
+    say "Shakapacker installation failed 😭 See above for details.", :red
+    exit 1
+  end
+
+  # Configure babel preset in package.json if babel is being used
+  if @transpiler_to_install == "babel"
+    @package_json.merge! do |pj|
+      babel = pj.fetch("babel", {})
+      babel["presets"] ||= []
+      unless babel["presets"].include?("./node_modules/shakapacker/package/babel/preset.js")
+        babel["presets"].push("./node_modules/shakapacker/package/babel/preset.js")
+      end
+      { "babel" => babel }
+    end
+  end
+end
+
+# Helper methods defined at the end (Rails template convention)
+
+def package_json
+  @package_json
 end

data/lib/shakapacker/configuration.rb

@@ -1,4 +1,5 @@
 require "yaml"
+require "json"
 require "active_support/core_ext/hash/keys"
 require "active_support/core_ext/hash/indifferent_access"
 
@@ -123,7 +124,12 @@ class Shakapacker::Configuration
     end
 
     # Use explicit config if set, otherwise default based on bundler
-    fetch(:javascript_transpiler) || fetch(:webpack_loader) || default_javascript_transpiler
+    transpiler = fetch(:javascript_transpiler) || fetch(:webpack_loader) || default_javascript_transpiler
+
+    # Validate transpiler configuration
+    validate_transpiler_configuration(transpiler) unless self.class.installing
+
+    transpiler
   end
 
   # Deprecated: Use javascript_transpiler instead
@@ -138,6 +144,57 @@ class Shakapacker::Configuration
       rspack? ? "swc" : "babel"
     end
 
+    def validate_transpiler_configuration(transpiler)
+      return unless ENV["NODE_ENV"] != "test" # Skip validation in test environment
+
+      # Check if package.json exists
+      package_json_path = root_path.join("package.json")
+      return unless package_json_path.exist?
+
+      begin
+        package_json = JSON.parse(File.read(package_json_path))
+        all_deps = (package_json["dependencies"] || {}).merge(package_json["devDependencies"] || {})
+
+        # Check for transpiler mismatch
+        has_babel = all_deps.keys.any? { |pkg| pkg.start_with?("@babel/", "babel-") }
+        has_swc = all_deps.keys.any? { |pkg| pkg.include?("swc") }
+        has_esbuild = all_deps.keys.any? { |pkg| pkg.include?("esbuild") }
+
+        case transpiler
+        when "babel"
+          if !has_babel && has_swc
+            warn_transpiler_mismatch("Babel", "SWC packages found but Babel is configured")
+          end
+        when "swc"
+          if !has_swc && has_babel
+            warn_transpiler_mismatch("SWC", "Babel packages found but SWC is configured")
+          end
+        when "esbuild"
+          if !has_esbuild && (has_babel || has_swc)
+            other = has_babel ? "Babel" : "SWC"
+            warn_transpiler_mismatch("esbuild", "#{other} packages found but esbuild is configured")
+          end
+        end
+      rescue JSON::ParserError
+        # Ignore if package.json is malformed
+      end
+    end
+
+    def warn_transpiler_mismatch(configured, message)
+      $stderr.puts <<~WARNING
+        ⚠️  Transpiler Configuration Mismatch Detected:
+           #{message}
+           Configured transpiler: #{configured}
+        #{'   '}
+           This might cause unexpected behavior or build failures.
+        #{'   '}
+           To fix this:
+           1. Run 'rails shakapacker:migrate_to_swc' to migrate to SWC (recommended for 20x faster builds)
+           2. Or install the correct packages for #{configured}
+           3. Or update your shakapacker.yml to match your installed packages
+      WARNING
+    end
+
   public
 
   def fetch(key)