shakapacker 9.0.0.beta.4 → 9.0.0.beta.6

data/docs/optional-peer-dependencies.md

@@ -0,0 +1,198 @@
+# Optional Peer Dependencies in Shakapacker
+
+## Overview
+
+As of Shakapacker v9, all peer dependencies are marked as optional via `peerDependenciesMeta`. This design provides maximum flexibility while maintaining clear version constraints.
+
+## Key Benefits
+
+1. **No Installation Warnings** - Package managers (npm, yarn, pnpm) won't warn about missing peer dependencies
+2. **Install Only What You Need** - Users only install packages for their chosen configuration
+3. **Clear Version Constraints** - When packages are installed, version compatibility is still enforced
+4. **Smaller Node Modules** - Reduced disk usage by not installing unnecessary packages
+
+## Implementation Details
+
+### Package.json Structure
+
+```json
+{
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "path-complete-extname": "^1.0.0",
+    "webpack-merge": "^5.8.0"  // Direct dependency - always available
+  },
+  "peerDependencies": {
+    "webpack": "^5.76.0",
+    "@rspack/core": "^1.0.0",
+    // ... all build tools
+  },
+  "peerDependenciesMeta": {
+    "webpack": { "optional": true },
+    "@rspack/core": { "optional": true },
+    // ... all marked as optional
+  }
+}
+```
+
+### TypeScript Type-Only Imports
+
+To prevent runtime errors when optional packages aren't installed, all webpack imports use type-only syntax:
+
+```typescript
+// @ts-ignore: webpack is an optional peer dependency (using type-only import)
+import type { Configuration } from "webpack"
+```
+
+Type-only imports are erased during compilation and don't trigger module resolution at runtime.
+
+## Configuration Examples
+
+### Webpack + Babel (Traditional)
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "webpack": "^5.76.0",
+    "webpack-cli": "^5.0.0",
+    "babel-loader": "^8.2.4",
+    "@babel/core": "^7.17.9",
+    "@babel/preset-env": "^7.16.11"
+  }
+}
+```
+
+### Webpack + SWC (20x Faster)
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "webpack": "^5.76.0",
+    "webpack-cli": "^5.0.0",
+    "@swc/core": "^1.3.0",
+    "swc-loader": "^0.2.0"
+  }
+}
+```
+
+### Rspack + SWC (10x Faster Bundling)
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "@rspack/core": "^1.0.0",
+    "@rspack/cli": "^1.0.0",
+    "rspack-manifest-plugin": "^5.0.0"
+  }
+}
+```
+
+## Migration Guide
+
+### From v8 to v9
+
+If upgrading from Shakapacker v8:
+
+1. **No action required** - Your existing dependencies will continue to work
+2. **No more warnings** - Peer dependency warnings will disappear after upgrading
+3. **Option to optimize** - You can now remove unused dependencies (e.g., remove Babel if using SWC)
+
+### New Installations
+
+The installer (`rails shakapacker:install`) only adds packages needed for your configuration:
+- Detects your preferred bundler (webpack/rspack)
+- Installs appropriate JavaScript transpiler (babel/swc/esbuild)
+- Adds only required dependencies
+
+## Version Constraints
+
+Version ranges are carefully chosen for compatibility:
+
+- **Broader ranges for peer deps** - Allows flexibility (e.g., `^5.76.0` for webpack)
+- **Specific versions in devDeps** - Ensures testing against known versions
+- **Forward compatibility** - Ranges include future minor versions (e.g., `^5.0.0 || ^6.0.0`)
+
+## Testing
+
+### Installation Tests
+
+Test that no warnings appear during installation:
+
+```bash
+# Test script available at test/peer-dependencies.sh
+./test/peer-dependencies.sh
+```
+
+### Runtime Tests
+
+Verify Shakapacker loads without optional dependencies:
+
+```javascript
+// This works even without webpack installed (when using rspack)
+const shakapacker = require('shakapacker');
+```
+
+### CI Integration
+
+The test suite includes:
+- `spec/shakapacker/optional_dependencies_spec.rb` - Package.json structure validation
+- `spec/shakapacker/doctor_optional_peer_spec.rb` - Doctor command validation
+- `test/peer-dependencies.sh` - Installation warning tests
+
+## Troubleshooting
+
+### Still seeing peer dependency warnings?
+
+1. Ensure you're using Shakapacker v9.0.0 or later
+2. Clear your package manager cache:
+   - npm: `npm cache clean --force`
+   - yarn: `yarn cache clean`
+   - pnpm: `pnpm store prune`
+3. Reinstall dependencies
+
+### Module not found errors?
+
+1. Check you've installed required dependencies for your configuration
+2. Refer to the configuration examples above
+3. Run `rails shakapacker:doctor` for diagnostics
+
+### TypeScript errors?
+
+The `@ts-ignore` comments are intentional and necessary for optional dependencies.
+They prevent TypeScript errors when optional packages aren't installed.
+
+## Contributing
+
+When adding new dependencies:
+
+1. Add to `peerDependencies` with appropriate version range
+2. Mark as optional in `peerDependenciesMeta`
+3. Use type-only imports in TypeScript: `import type { ... }`
+4. Test with all package managers (npm, yarn, pnpm)
+5. Update this documentation if needed
+
+## Design Rationale
+
+This approach balances several concerns:
+
+1. **User Experience** - No confusing warnings during installation
+2. **Flexibility** - Support multiple configurations without forcing unnecessary installs
+3. **Compatibility** - Maintain version constraints for safety
+4. **Performance** - Reduce installation time and disk usage
+5. **Type Safety** - TypeScript support without runtime dependencies
+
+## Future Improvements
+
+Potential enhancements for future versions:
+
+1. **Conditional exports** - Use package.json exports field for better tree-shaking
+2. **Dynamic imports** - Load bundler-specific code only when needed
+3. **Doctor updates** - Enhance doctor command to better understand optional dependencies
+4. **Automated testing** - Add CI jobs testing each configuration combination
+
+## References
+
+- [npm: peerDependenciesMeta](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#peerdependenciesmeta)
+- [TypeScript: Type-Only Imports](https://www.typescriptlang.org/docs/handbook/modules.html#type-only-imports-and-exports)
+- [Shakapacker Issue #565](https://github.com/shakacode/shakapacker/issues/565)
+- [Pull Request #615](https://github.com/shakacode/shakapacker/pull/615)

data/docs/typescript.md

@@ -0,0 +1,99 @@
+# TypeScript Support
+
+Shakapacker v9 includes TypeScript support, providing type safety and better IDE experience for your webpack configurations.
+
+## Quick Start
+
+### Using TypeScript Config
+
+```typescript
+// webpack.config.ts
+import { generateWebpackConfig } from 'shakapacker'
+import type { Configuration } from 'webpack'
+
+const config: Configuration = generateWebpackConfig({
+  // Your config with full type safety
+})
+
+export default config
+```
+
+### Using JSDoc (JavaScript)
+
+```javascript
+// webpack.config.js
+const { generateWebpackConfig } = require('shakapacker')
+
+/** @type {import('webpack').Configuration} */
+const config = {
+  // Still get autocomplete in JS files!
+}
+
+module.exports = generateWebpackConfig(config)
+```
+
+## Benefits
+
+- **Compile-time error detection** - Catch config errors before runtime
+- **IDE autocomplete** - Full IntelliSense for all options
+- **Type safety** - Prevents 85-100% of common configuration errors
+- **No breaking changes** - Fully backward compatible
+
+## Migration
+
+1. **No migration required** - Existing JavaScript configs continue to work
+2. **Optional TypeScript** - Use it only if you want the benefits
+3. **Gradual adoption** - Start with JSDoc comments, move to TypeScript later
+
+## IDE Setup
+
+### VS Code
+- Install TypeScript extension (built-in)
+- Set `"typescript.tsdk": "node_modules/typescript/lib"` in settings
+
+### WebStorm/IntelliJ
+- Enable TypeScript service in Settings → Languages & Frameworks → TypeScript
+
+## Common Patterns
+
+### Environment-Specific Config
+
+```typescript
+import { generateWebpackConfig, env } from 'shakapacker'
+
+const config = generateWebpackConfig({
+  optimization: {
+    minimize: env.isProduction
+  }
+})
+```
+
+### Rspack Config
+
+```typescript
+import { generateRspackConfig } from 'shakapacker/rspack'
+import type { RspackOptions } from '@rspack/core'
+
+const config: RspackOptions = {
+  // Rspack-specific config
+}
+
+export default generateRspackConfig(config)
+```
+
+## Troubleshooting
+
+**Cannot find module 'shakapacker'**
+```typescript
+/// <reference types="shakapacker" />
+```
+
+**Type errors with custom loaders**
+```typescript
+use: [require.resolve('custom-loader') as any]
+```
+
+## Further Reading
+
+- [Webpack TypeScript Documentation](https://webpack.js.org/configuration/configuration-languages/#typescript)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)

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
 
@@ -117,6 +130,35 @@ npm install esbuild esbuild-loader
 assets_bundler: 'rspack'  # or 'webpack' (default)
 ```
 
+### 5. All Peer Dependencies Now Optional
+
+**What changed:** All peer dependencies are now marked as optional via `peerDependenciesMeta`.
+
+**Benefits:**
+- **No installation warnings** - You won't see peer dependency warnings for packages you don't use
+- **Install only what you need** - Using webpack? Don't install rspack. Using SWC? Don't install Babel.
+- **Clear version constraints** - When you do install a package, version compatibility is still enforced
+
+**What this means for you:**
+- **Existing projects:** No changes needed. Your existing dependencies will continue to work.
+- **New projects:** The installer only adds the packages you actually need based on your configuration.
+- **Package manager behavior:** npm, yarn, and pnpm will no longer warn about missing peer dependencies.
+
+**Example:** If you're using SWC with webpack, you only need:
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "@swc/core": "^1.3.0",
+    "swc-loader": "^0.2.0",
+    "webpack": "^5.76.0",
+    "webpack-cli": "^5.0.0",
+    "webpack-dev-server": "^5.0.0"
+  }
+}
+```
+You won't get warnings about missing Babel, Rspack, or esbuild packages.
+
 ## Migration Steps
 
 ### Step 1: Update Dependencies
@@ -211,6 +253,41 @@ Update your global type definitions as shown in Step 2.
 
 If you see warnings about CSS module exports, ensure you've updated all imports to use named exports or have properly configured the override.
 
+### Unexpected Peer Dependency Warnings After Upgrade
+
+If you experience unexpected peer dependency warnings after upgrading to v9, you may need to clear your package manager's cache and reinstall dependencies. This ensures the new optional peer dependency configuration takes effect properly.
+
+**For npm:**
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+**For Yarn:**
+```bash
+rm -rf node_modules yarn.lock
+yarn install
+```
+
+**For pnpm:**
+```bash
+rm -rf node_modules pnpm-lock.yaml
+pnpm install
+```
+
+**For Bun:**
+```bash
+rm -rf node_modules bun.lockb
+bun install
+```
+
+**When is this necessary?**
+- If you see peer dependency warnings for packages you don't use (e.g., warnings about Babel when using SWC)
+- If your package manager cached the old dependency resolution from v8
+- After switching transpilers or bundlers (e.g., from Babel to SWC, or webpack to rspack)
+
+**Note:** This is typically only needed once after the v8 → v9 upgrade. Subsequent installs will use the correct dependency resolution.
+
 ## Need Help?
 
 - See [CSS Modules Export Mode documentation](./css-modules-export-mode.md) for detailed configuration options
@@ -225,4 +302,4 @@ If you have a large codebase and need to migrate gradually:
 2. Migrate files incrementally
 3. Remove the override once migration is complete
 
-This allows you to upgrade to v9 immediately while taking time to update your CSS module imports.
+This allows you to upgrade to v9 immediately while taking time to update your CSS module imports.

data/lib/install/template.rb

@@ -167,6 +167,11 @@ Dir.chdir(Rails.root) do
     # 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)
@@ -187,7 +192,9 @@ Dir.chdir(Rails.root) do
       entry = "#{package}@#{version}"
     else
       # Extract major version from complex version strings like ">= 4 || 5"
-      major_version = version.split("||").last.match(/(\d+)/)[1]
+      # 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
 

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)