shakapacker 9.0.0.beta.5 → 9.0.0.beta.7

data/docs/transpiler-migration.md

@@ -0,0 +1,191 @@
+# JavaScript Transpiler Configuration
+
+## Default Transpilers
+
+Shakapacker uses different default JavaScript transpilers based on the bundler:
+
+- **Webpack**: `babel` (default) - Maintains backward compatibility
+- **Rspack**: `swc` (default) - Modern, faster transpiler for new bundler
+
+## Available Transpilers
+
+- `babel` - Traditional JavaScript transpiler with wide ecosystem support
+- `swc` - Rust-based transpiler, 20-70x faster than Babel
+- `esbuild` - Go-based transpiler, extremely fast
+- `none` - No transpilation (use native JavaScript)
+
+## Configuration
+
+Set the transpiler in your `config/shakapacker.yml`:
+
+```yaml
+default: &default
+  # For webpack users (babel is default, no change needed)
+  javascript_transpiler: babel
+  
+  # To opt-in to SWC for better performance
+  javascript_transpiler: swc
+  
+  # For rspack users (swc is default, no change needed)
+  assets_bundler: rspack
+  javascript_transpiler: swc
+```
+
+## Migration Guide
+
+### Migrating from Babel to SWC
+
+SWC offers significant performance improvements while maintaining high compatibility with Babel.
+
+#### 1. Install SWC dependencies
+
+```bash
+yarn add --dev @swc/core swc-loader
+```
+
+#### 2. Update your configuration
+
+```yaml
+# config/shakapacker.yml
+default: &default
+  javascript_transpiler: swc
+```
+
+#### 3. Create SWC configuration (optional)
+
+If you need custom transpilation settings, create `.swcrc`:
+
+```json
+{
+  "$schema": "https://json.schemastore.org/swcrc",
+  "jsc": {
+    "parser": {
+      "syntax": "ecmascript",
+      "jsx": true,
+      "dynamicImport": true
+    },
+    "transform": {
+      "react": {
+        "runtime": "automatic"
+      }
+    },
+    "target": "es2015"
+  },
+  "module": {
+    "type": "es6"
+  }
+}
+```
+
+#### 4. Update React configuration (if using React)
+
+For React projects, ensure you have the correct refresh plugin:
+
+```bash
+# For webpack
+yarn add --dev @pmmmwh/react-refresh-webpack-plugin
+
+# For rspack
+yarn add --dev @rspack/plugin-react-refresh
+```
+
+### Performance Comparison
+
+Typical build time improvements when migrating from Babel to SWC:
+
+| Project Size | Babel | SWC | Improvement |
+|-------------|-------|-----|-------------|
+| Small (<100 files) | 5s | 1s | 5x faster |
+| Medium (100-500 files) | 20s | 3s | 6.7x faster |
+| Large (500+ files) | 60s | 8s | 7.5x faster |
+
+### Compatibility Notes
+
+#### Babel Features Not Yet in SWC
+
+- Some experimental/stage-0 proposals
+- Custom Babel plugins (need SWC equivalents)
+- Babel macros
+
+#### Migration Checklist
+
+- [ ] Back up your current configuration
+- [ ] Install SWC dependencies
+- [ ] Update `shakapacker.yml`
+- [ ] Test your build locally
+- [ ] Run your test suite
+- [ ] Check browser compatibility
+- [ ] Deploy to staging environment
+- [ ] Monitor for any runtime issues
+
+### Rollback Plan
+
+If you encounter issues, rolling back is simple:
+
+```yaml
+# config/shakapacker.yml
+default: &default
+  javascript_transpiler: babel  # Revert to babel
+```
+
+Then rebuild your application:
+
+```bash
+bin/shakapacker clobber
+bin/shakapacker compile
+```
+
+## Environment Variables
+
+You can also control the transpiler via environment variables:
+
+```bash
+# Override config file setting
+SHAKAPACKER_JAVASCRIPT_TRANSPILER=swc bin/shakapacker compile
+
+# For debugging
+SHAKAPACKER_DEBUG_CACHE=true bin/shakapacker compile
+```
+
+## Troubleshooting
+
+### Issue: Build fails after switching to SWC
+
+**Solution**: Ensure all SWC dependencies are installed:
+
+```bash
+yarn add --dev @swc/core swc-loader
+```
+
+### Issue: React Fast Refresh not working
+
+**Solution**: Install the correct refresh plugin for your bundler:
+
+```bash
+# Webpack
+yarn add --dev @pmmmwh/react-refresh-webpack-plugin
+
+# Rspack  
+yarn add --dev @rspack/plugin-react-refresh
+```
+
+### Issue: Decorators not working
+
+**Solution**: Enable decorator support in `.swcrc`:
+
+```json
+{
+  "jsc": {
+    "parser": {
+      "decorators": true,
+      "decoratorsBeforeExport": true
+    }
+  }
+}
+```
+
+## Further Reading
+
+- [SWC Documentation](https://swc.rs/docs/getting-started)
+- [Babel to SWC Migration Guide](https://swc.rs/docs/migrating-from-babel)
+- [Rspack Configuration](https://www.rspack.dev/config/index)

data/docs/typescript-migration.md

@@ -0,0 +1,378 @@
+# TypeScript Migration Guide for Shakapacker
+
+This guide helps you adopt TypeScript types in your Shakapacker configuration files for better type safety and IDE support.
+
+## Table of Contents
+- [Benefits](#benefits)
+- [Quick Start](#quick-start)
+- [Migration Steps](#migration-steps)
+- [Common Patterns](#common-patterns)
+- [Troubleshooting](#troubleshooting)
+
+## Benefits
+
+Using TypeScript with Shakapacker provides:
+- **Type Safety**: Catch configuration errors at compile time
+- **IDE Support**: Get autocompletion and inline documentation
+- **Better Refactoring**: Safely rename and restructure configurations
+- **Self-documenting**: Types serve as inline documentation
+
+## Quick Start
+
+### 1. Install TypeScript Dependencies
+
+```bash
+yarn add --dev typescript @types/node @types/webpack
+# or
+npm install --save-dev typescript @types/node @types/webpack
+```
+
+### 2. Create a tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "allowJs": true,
+    "checkJs": false,
+    "noEmit": true
+  },
+  "include": ["config/webpack/**/*"],
+  "exclude": ["node_modules"]
+}
+```
+
+### 3. Convert Your Webpack Config to TypeScript
+
+Rename `config/webpack/webpack.config.js` to `config/webpack/webpack.config.ts`:
+
+```typescript
+// config/webpack/webpack.config.ts
+import { generateWebpackConfig, merge } from 'shakapacker'
+import type { WebpackConfigWithDevServer } from 'shakapacker/types'
+import type { Configuration } from 'webpack'
+
+const customConfig: Configuration = {
+  resolve: {
+    extensions: ['.css', '.ts', '.tsx']
+  }
+}
+
+const config: Configuration = generateWebpackConfig(customConfig)
+
+export default config
+```
+
+## Migration Steps
+
+### Step 1: Import Types
+
+Start by importing the types you need:
+
+```typescript
+import type {
+  Config,
+  WebpackConfigWithDevServer,
+  RspackConfigWithDevServer,
+  CompressionPluginOptions
+} from 'shakapacker/types'
+```
+
+### Step 2: Type Your Configuration Objects
+
+Add type annotations to your configuration objects:
+
+```typescript
+// Before (JavaScript)
+const customConfig = {
+  resolve: {
+    extensions: ['.css', '.ts', '.tsx']
+  }
+}
+
+// After (TypeScript)
+import type { Configuration } from 'webpack'
+
+const customConfig: Configuration = {
+  resolve: {
+    extensions: ['.css', '.ts', '.tsx']
+  }
+}
+```
+
+### Step 3: Type Your Custom Functions
+
+If you have custom configuration functions, add type annotations:
+
+```typescript
+// Before (JavaScript)
+function modifyConfig(config) {
+  config.plugins.push(new MyPlugin())
+  return config
+}
+
+// After (TypeScript)
+import type { Configuration } from 'webpack'
+import type { WebpackPluginInstance } from 'shakapacker/types'
+
+function modifyConfig(config: Configuration): Configuration {
+  const plugins = config.plugins as WebpackPluginInstance[]
+  plugins.push(new MyPlugin())
+  return config
+}
+```
+
+### Step 4: Handle Environment-Specific Configurations
+
+```typescript
+// config/webpack/development.ts
+import { generateWebpackConfig } from 'shakapacker'
+import type { WebpackConfigWithDevServer } from 'shakapacker/types'
+
+const developmentConfig: WebpackConfigWithDevServer = generateWebpackConfig({
+  devtool: 'eval-cheap-module-source-map',
+  devServer: {
+    hot: true,
+    port: 3035
+  }
+})
+
+export default developmentConfig
+```
+
+## Common Patterns
+
+### Pattern 1: Custom Loaders
+
+```typescript
+import type { RuleSetRule } from 'webpack'
+
+const customLoader: RuleSetRule = {
+  test: /\.svg$/,
+  use: ['@svgr/webpack']
+}
+
+const config: Configuration = generateWebpackConfig({
+  module: {
+    rules: [customLoader]
+  }
+})
+```
+
+### Pattern 2: Plugin Configuration
+
+```typescript
+import CompressionPlugin from 'compression-webpack-plugin'
+import type { CompressionPluginOptions } from 'shakapacker/types'
+
+const compressionOptions: CompressionPluginOptions = {
+  filename: '[path][base].gz',
+  algorithm: 'gzip',
+  test: /\.(js|css|html|json|ico|svg|eot|otf|ttf)$/
+}
+
+const config: Configuration = generateWebpackConfig({
+  plugins: [new CompressionPlugin(compressionOptions)]
+})
+```
+
+### Pattern 3: Conditional Configuration
+
+```typescript
+import type { Configuration } from 'webpack'
+import { env } from 'shakapacker'
+
+const config: Configuration = generateWebpackConfig()
+
+if (env.isProduction) {
+  // TypeScript knows config.optimization exists
+  config.optimization = {
+    ...config.optimization,
+    minimize: true,
+    sideEffects: false
+  }
+}
+
+export default config
+```
+
+### Pattern 4: Rspack Configuration
+
+```typescript
+// config/rspack/rspack.config.ts
+import type { RspackConfigWithDevServer } from 'shakapacker/types'
+import { generateWebpackConfig } from 'shakapacker'
+
+const rspackConfig: RspackConfigWithDevServer = generateWebpackConfig({
+  mode: 'development',
+  devServer: {
+    hot: true,
+    port: 3036
+  }
+})
+
+export default rspackConfig
+```
+
+## Type-checking Your Configuration
+
+Add a script to your package.json to type-check your configuration:
+
+```json
+{
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "webpack:type-check": "tsc --noEmit config/webpack/*.ts"
+  }
+}
+```
+
+Run type checking:
+
+```bash
+yarn type-check
+# or
+npm run type-check
+```
+
+## Available Types Reference
+
+### Core Types
+- `Config` - Shakapacker configuration from shakapacker.yml
+- `Env` - Environment variables and helpers
+- `DevServerConfig` - Development server configuration
+
+### Webpack/Rspack Types
+- `WebpackConfigWithDevServer` - Webpack configuration with dev server
+- `RspackConfigWithDevServer` - Rspack configuration with dev server
+- `WebpackPluginInstance` - Webpack plugin instance type
+- `RspackPlugin` - Rspack plugin interface
+
+### Helper Types
+- `CompressionPluginOptions` - Compression plugin configuration
+- `ReactRefreshWebpackPlugin` - React refresh for Webpack
+- `ReactRefreshRspackPlugin` - React refresh for Rspack
+
+## Troubleshooting
+
+### Issue: "Cannot find module 'shakapacker/types'"
+
+**Solution**: Make sure you're using Shakapacker v9.0.0 or later:
+
+```bash
+yarn upgrade shakapacker
+```
+
+### Issue: Type errors with plugins
+
+**Solution**: Cast plugin arrays when needed:
+
+```typescript
+const plugins = (config.plugins || []) as WebpackPluginInstance[]
+plugins.push(new MyPlugin())
+```
+
+### Issue: Missing types for custom loaders
+
+**Solution**: Install type definitions or declare them:
+
+```typescript
+// If types aren't available, declare them
+declare module 'my-custom-loader' {
+  const loader: any
+  export default loader
+}
+```
+
+### Issue: Conflicting types between webpack versions
+
+**Solution**: Ensure your webpack types match your webpack version:
+
+```bash
+yarn add --dev @types/webpack@^5
+```
+
+## Gradual Migration
+
+You don't need to convert everything at once. Start with:
+
+1. Convert your main webpack.config.js to TypeScript
+2. Add types to the most complex configurations
+3. Gradually type other configuration files
+4. Add type checking to your CI pipeline
+
+## Example: Full Configuration
+
+Here's a complete example of a typed webpack configuration:
+
+```typescript
+// config/webpack/webpack.config.ts
+import { generateWebpackConfig, merge, config as shakapackerConfig } from 'shakapacker'
+import type { Configuration } from 'webpack'
+import type { WebpackConfigWithDevServer } from 'shakapacker/types'
+import CompressionPlugin from 'compression-webpack-plugin'
+import { resolve } from 'path'
+
+// Type-safe custom configuration
+const customConfig: Configuration = {
+  resolve: {
+    extensions: ['.css', '.ts', '.tsx'],
+    alias: {
+      '@': resolve(__dirname, '../../app/javascript'),
+      'components': resolve(__dirname, '../../app/javascript/components'),
+      'utils': resolve(__dirname, '../../app/javascript/utils')
+    }
+  },
+  module: {
+    rules: [
+      {
+        test: /\.svg$/,
+        use: ['@svgr/webpack'],
+        issuer: /\.(tsx?|jsx?)$/
+      }
+    ]
+  }
+}
+
+// Generate the final configuration
+const webpackConfig: Configuration = generateWebpackConfig(customConfig)
+
+// Type-safe modifications based on environment
+if (shakapackerConfig.env === 'production') {
+  const plugins = (webpackConfig.plugins || []) as WebpackPluginInstance[]
+
+  plugins.push(
+    new CompressionPlugin({
+      filename: '[path][base].br',
+      algorithm: 'brotliCompress',
+      test: /\.(js|css|html|json|ico|svg|eot|otf|ttf)$/
+    })
+  )
+}
+
+export default webpackConfig
+```
+
+## Next Steps
+
+After migrating to TypeScript:
+
+1. **Enable strict checks**: Gradually enable stricter TypeScript options
+2. **Add custom types**: Create type definitions for your application-specific configurations
+3. **Share types**: Export reusable configuration types for your team
+4. **Document with types**: Use JSDoc comments with your types for better documentation
+
+## Resources
+
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
+- [Webpack TypeScript Configuration](https://webpack.js.org/configuration/configuration-languages/#typescript)
+- [Shakapacker Types Documentation](./types/README.md)
+- [Migration Examples](https://github.com/shakacode/shakapacker/tree/main/examples/typescript-config)

data/docs/v9_upgrade.md

@@ -130,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
@@ -224,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
@@ -238,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

@@ -125,13 +125,60 @@ if (setup_path = Rails.root.join("bin/setup")).exist?
 end
 
 Dir.chdir(Rails.root) do
-  npm_version = Shakapacker::Utils::VersionSyntaxConverter.new.rubygem_to_npm(Shakapacker::VERSION)
-  say "Installing shakapacker@#{npm_version}"
-  begin
-    @package_json.manager.add!(["shakapacker@#{npm_version}"], type: :production)
-  rescue PackageJson::Error
-    say "Shakapacker installation failed 😭 See above for details.", :red
-    exit 1
+  # In CI, use the pre-packed tarball if available
+  if ENV["SHAKAPACKER_NPM_PACKAGE"]
+    package_path = ENV["SHAKAPACKER_NPM_PACKAGE"]
+
+    # Validate package path to prevent directory traversal and invalid file types
+    begin
+      # Resolve to absolute path
+      absolute_path = File.expand_path(package_path)
+
+      # Reject paths containing directory traversal
+      if package_path.include?("..") || absolute_path.include?("..")
+        say "❌ Security Error: Package path contains directory traversal: #{package_path}", :red
+        exit 1
+      end
+
+      # Ensure filename ends with .tgz or .tar.gz
+      unless absolute_path.end_with?(".tgz", ".tar.gz")
+        say "❌ Security Error: Package must be a .tgz or .tar.gz file: #{package_path}", :red
+        exit 1
+      end
+
+      # Check existence only after validation
+      if File.exist?(absolute_path)
+        say "📦 Installing shakapacker from local package: #{absolute_path}", :cyan
+        begin
+          @package_json.manager.add!([absolute_path], type: :production)
+        rescue PackageJson::Error
+          say "Shakapacker installation failed 😭 See above for details.", :red
+          exit 1
+        end
+      else
+        say "⚠️  SHAKAPACKER_NPM_PACKAGE set but file not found: #{absolute_path}", :yellow
+        say "Falling back to npm registry...", :yellow
+        npm_version = Shakapacker::Utils::VersionSyntaxConverter.new.rubygem_to_npm(Shakapacker::VERSION)
+        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
+      end
+    rescue => e
+      say "❌ Error validating package path: #{e.message}", :red
+      exit 1
+    end
+  else
+    npm_version = Shakapacker::Utils::VersionSyntaxConverter.new.rubygem_to_npm(Shakapacker::VERSION)
+    say "Installing shakapacker@#{npm_version}"
+    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
   end
 
   @package_json.merge! do |pj|