shakapacker 9.0.0.beta.6 → 9.0.0.beta.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65a49f86249eeb2035e56d7f21da2d8e4edbe5a26da50b0a63a9534a720a84cf
-  data.tar.gz: 153cb1df867355c881a3a7fe31b3aed526355ff30f7eaaacb497d231cb5f3bcc
+  metadata.gz: ca5207ce21d40303f0a0250d140763ca93000a318ba28a9ac8efff358ce59310
+  data.tar.gz: f494c9a43b2c9fc704ca6dc1e3110f0c7048759a13e3f8254c44735e91a58da0
 SHA512:
-  metadata.gz: c237ee4221a14f19ae86067632ad00baaf1f05d3464c21804b8aa3fa7029429bc8d678d630f1762f940ea780f4ff81023c26d26342aa27380a461f1485f50b3d
-  data.tar.gz: b37633ed02a416c423bfb410b189b1ca7c508a162339e9def8401622c2ac198b4649ad0392795a9eb3301d6fc3d9858c2e39f1130b8c6bbd219887566126b91e
+  metadata.gz: a13fd3b73ffb91546e25c8226731efd4cdf6e8024893011795e32f379d2c3ffd14a4b5286b2a32499447405a01624b50805aafd6749112538e560ab21bc58e7e
+  data.tar.gz: d9911ec4c3a53a6baf3598e48b29e74684113a6514e979c73b69479905399e94abc67c0792a51c1cf12c5961a771c9de1f19e1800991f9a638dfab5ebcd1e606

data/.github/workflows/generator.yml

@@ -64,4 +64,10 @@ jobs:
       - name: Build TypeScript
         run: yarn build
 
+      - name: Pack npm package for testing
+        run: |
+          TARBALL=$(npm pack)
+          echo "SHAKAPACKER_NPM_PACKAGE=$(pwd)/$TARBALL" >> $GITHUB_ENV
+          echo "Created package: $TARBALL"
+
       - run: bundle exec rake run_spec:generator

data/.gitignore

@@ -27,7 +27,6 @@ package/**/*.js
 !package/webpack-types.d.ts
 !package/babel/preset.js
 !package/babel/preset-react.js
-!package/environments/*.js
 !package/rules/*.js
 !package/loaders/*.js
 !package/plugins/*.js

data/.npmignore

@@ -0,0 +1,55 @@
+# .npmignore
+# This file controls what gets published to npm
+# It overrides .gitignore for npm publishing
+
+# Exclude development and test files
+/.bundle
+/pkg
+/spec
+/test
+/gemfiles
+/.github
+/.circleci
+/.byebug_history
+.DS_Store
+yarn-debug.log*
+yarn-error.log*
+.yarn-integrity
+.yalc
+yalc.lock
+.yalcignore
+
+# Exclude Ruby files not needed for npm package
+Gemfile
+Gemfile.lock
+Rakefile
+*.gemspec
+.rubocop.yml
+.ruby-version
+
+# Exclude TypeScript config
+tsconfig.json
+
+# Exclude source maps (optional - remove these lines to include source maps)
+*.js.map
+*.d.ts.map
+
+# Exclude git and editor files
+.git
+.gitignore
+.gitattributes
+.editorconfig
+.vscode
+.idea
+
+# Exclude CI/CD files
+.travis.yml
+appveyor.yml
+
+# Exclude documentation source files (keep compiled docs if any)
+docs/
+
+# CRITICAL: Exclude TypeScript source files (must be at the end)
+# Only include compiled .js and .d.ts files
+*.ts
+!*.d.ts

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shakapacker (9.0.0.beta.6)
+    shakapacker (9.0.0.beta.7)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)

data/README.md

@@ -722,6 +722,10 @@ You can try out experimental integration with the esbuild-loader. You can read m
 
 Please note that if you want opt-in to use esbuild-loader, you can skip [React](#react) integration instructions as it is supported out of the box.
 
+### Switching between transpilers
+
+To switch between Babel, SWC, or esbuild, or to configure environment-specific transpiler settings, see the [Transpiler Migration Guide](./docs/transpiler-migration.md).
+
 ### Integrations
 
 Shakapacker out of the box supports JS and static assets (fonts, images etc.) compilation. To enable support for CoffeeScript or TypeScript install relevant packages:

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)