shakapacker 9.0.0.beta.6 → 9.0.0.beta.8

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/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|

data/lib/shakapacker/version.rb

@@ -1,4 +1,4 @@
 module Shakapacker
   # Change the version in package.json too, please!
-  VERSION = "9.0.0.beta.6".freeze
+  VERSION = "9.0.0.beta.8".freeze
 end

data/package/.npmignore

@@ -0,0 +1,4 @@
+# Exclude TypeScript source files from the package directory
+*.ts
+# But keep the TypeScript declaration files
+!*.d.ts

data/package/babel/preset.ts

@@ -0,0 +1,56 @@
+import { moduleExists, packageFullVersion } from "../utils/helpers"
+import type { ConfigAPI, PluginItem } from "@babel/core"
+
+const CORE_JS_VERSION_REGEX = /^\d+\.\d+/
+
+const coreJsVersion = (): string => {
+  try {
+    const version = packageFullVersion("core-js").match(CORE_JS_VERSION_REGEX)
+    return version?.[0] ?? "3.8"
+  } catch (e) {
+    const error = e as NodeJS.ErrnoException
+    if (error.code !== "MODULE_NOT_FOUND") {
+      throw e
+    }
+
+    return "3.8"
+  }
+}
+
+export = function config(api: ConfigAPI): { presets: PluginItem[]; plugins: PluginItem[] } {
+  const validEnv = ["development", "test", "production"]
+  const currentEnv = api.env()
+  const isDevelopmentEnv = api.env("development")
+  const isProductionEnv = api.env("production")
+  const isTestEnv = api.env("test")
+
+  if (!validEnv.includes(currentEnv)) {
+    throw new Error(
+      `Please specify a valid NODE_ENV or BABEL_ENV environment variable. Valid values are "development", "test", and "production". Instead, received: "${currentEnv}".`
+    )
+  }
+
+  const presets: PluginItem[] = [
+    isTestEnv && ["@babel/preset-env", { targets: { node: "current" } }],
+    (isProductionEnv || isDevelopmentEnv) && [
+      "@babel/preset-env",
+      {
+        useBuiltIns: "entry",
+        corejs: coreJsVersion(),
+        modules: "auto",
+        bugfixes: true,
+        exclude: ["transform-typeof-symbol"]
+      }
+    ],
+    moduleExists("@babel/preset-typescript") && "@babel/preset-typescript"
+  ].filter(Boolean) as PluginItem[]
+
+  const plugins: PluginItem[] = [["@babel/plugin-transform-runtime", { helpers: false }]].filter(
+    Boolean
+  ) as PluginItem[]
+
+  return {
+    presets,
+    plugins
+  }
+}