shakapacker 9.0.0.beta.4 → 9.0.0.beta.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 173792ac146bcec2bdcea877d9449ab35935ec1cd61b04d8df1d02cf62325a29
-  data.tar.gz: 7d135bb3eb60f7a65723625dbc611c155122b2cd985a99a955f93d0f0f380d24
+  metadata.gz: c4e7529c9a1e2dee69667d688581f6c684c775c18a17ac527a3328876d45c523
+  data.tar.gz: 305d71e3efd30913c856066b7195ff259094bafb2cc2f7fa7f1730cdbfc49cdf
 SHA512:
-  metadata.gz: 97d4f23b01c785a479e53a3e8abcf8df1462243096b4fc14ed3c2b0fbd50096ac5e65b829ecc3dd3d40a6adc072541952ff1af3e74ed8ebce544eb771570c527
-  data.tar.gz: de3fa497d411233f46023ca903f2f7586701a97b4c08de85ec347064c0d2b355570ad9e8988993dc01024663a0c48264513b3a00f23287665c3acfcee25644a0
+  metadata.gz: cdba0281b3a0bc4e43d50ac4e84fa1a9b029ff6999afeabea56eada8ffded1c366e4b084734758566f009c1214ac36d7da874ea4887c70010551330f678bccbc
+  data.tar.gz: 97a96fa177348c19929aae4fe53865f9f738f21c060e77863dfd79c3cc22869c4a6eb78af34d2139eb842baf61f59b3a9040b1e42cec3ed2fa216d1818124ca1

data/.github/workflows/dummy.yml

@@ -29,8 +29,12 @@ jobs:
       - name: Install dependencies
         run: |
           bundle install
+          yarn install --frozen-lockfile --production=false
           npm install -g yalc
           cd spec/dummy && npm install
+      
+      - name: Build TypeScript
+        run: yarn build
 
       - name: Run tests
         run: bundle exec rake run_spec:dummy

data/.github/workflows/generator.yml

@@ -57,4 +57,11 @@ jobs:
         with:
           node-version: 20.x
           cache: yarn
+      
+      - name: Install Node dependencies
+        run: yarn install --frozen-lockfile --production=false
+
+      - name: Build TypeScript
+        run: yarn build
+
       - run: bundle exec rake run_spec:generator

data/.github/workflows/node.yml

@@ -30,6 +30,25 @@ jobs:
 
       - name: Node eslint
         run: yarn lint
+
+  type-check:
+    name: TypeScript Type Checking
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn --frozen-lockfile --non-interactive --prefer-offline
+
+      - name: TypeScript type check
+        run: yarn type-check
   test:
     name: Testing
     strategy:
@@ -52,5 +71,8 @@ jobs:
       - name: Install dependencies
         run: yarn --frozen-lockfile --non-interactive --prefer-offline
 
+      - name: Build TypeScript
+        run: yarn build
+
       - name: Jest Specs
         run: yarn test

data/.github/workflows/ruby.yml

@@ -85,6 +85,17 @@ jobs:
           ruby-version: ${{ matrix.ruby }}
           rubygems: latest
           bundler-cache: true
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: yarn
+
+      - name: Install Node dependencies
+        run: yarn install --frozen-lockfile --production=false
+
+      - name: Build TypeScript
+        run: yarn build
 
       - name: Ruby specs
         run: bundle exec rake run_spec:gem

data/.github/workflows/test-bundlers.yml

@@ -33,6 +33,12 @@ jobs:
       - name: Install yalc
         run: npm install -g yalc
 
+      - name: Build TypeScript
+        run: |
+          cd ../..
+          yarn install --frozen-lockfile --production=false
+          yarn build
+
       - name: Publish shakapacker to yalc
         run: |
           cd ../..
@@ -80,6 +86,12 @@ jobs:
       - name: Install yalc
         run: npm install -g yalc
 
+      - name: Build TypeScript
+        run: |
+          cd ../..
+          yarn install --frozen-lockfile --production=false
+          yarn build
+
       - name: Publish shakapacker to yalc
         run: |
           cd ../..
@@ -127,6 +139,12 @@ jobs:
       - name: Install yalc
         run: npm install -g yalc
 
+      - name: Build TypeScript
+        run: |
+          cd ../..
+          yarn install --frozen-lockfile --production=false
+          yarn build
+
       - name: Publish shakapacker to yalc
         run: |
           cd ../..

data/.gitignore

@@ -14,3 +14,23 @@ gemfiles/*.lock
 
 .yalc
 yalc.lock
+
+# TypeScript generated files
+package/**/*.d.ts
+package/**/*.d.ts.map
+package/**/*.js.map
+# Ignore compiled JS files from TypeScript sources
+package/**/*.js
+# Keep specific files that are not TypeScript-generated
+!package/index.d.ts
+!package/loaders.d.ts
+!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
+!package/__mocks__/*.js
+!package/utils/get_style_rule.js
+!package/utils/node_modules.js

data/.yalcignore

@@ -0,0 +1,26 @@
+# Yalc-specific ignore file
+# Unlike .gitignore, we want to include generated JS files for yalc publish
+
+# Ignore source TypeScript files since we're publishing compiled JS
+package/**/*.ts
+!package/**/*.d.ts
+
+# Ignore map files
+package/**/*.js.map
+package/**/*.d.ts.map
+
+# Ignore test files
+**/*.test.js
+**/*.spec.js
+**/__tests__
+**/__mocks__
+
+# Ignore config and build files
+.github
+.vscode
+.idea
+*.log
+node_modules
+tmp
+coverage
+.DS_Store

data/CHANGELOG.md

@@ -9,54 +9,71 @@
 ## [Unreleased]
 Changes since the last non-beta release.
 
-### Added
-- Rspack support as an alternative assets bundler to webpack. Configure `assets_bundler: 'rspack'` in `shakapacker.yml` to use Rspack's faster Rust-based bundling with webpack-compatible APIs, built-in SWC loader, and CSS extraction. Automatic assets bundler detection in `bin/shakapacker` with fallback support for webpack configurations.
-- Add `private_output_path` configuration option for server-side rendering bundles. This allows specifying a separate output directory for private server bundles that shouldn't be served publicly. [PR 592](https://github.com/shakacode/shakapacker/pull/592) by [justin808](https://github.com/justin808).
-- Enhanced TypeScript type definitions for better IDE support and type safety. Improved Config and DevServerConfig interfaces with additional properties. [PR 602](https://github.com/shakacode/shakapacker/pull/602) by [justin808](https://github.com/justin808).
+## [v9.0.0-beta.4] - Unreleased
+
+### ⚠️ Breaking Changes
+
+1. **SWC is now the default JavaScript transpiler instead of Babel** ([PR 603](https://github.com/shakacode/shakapacker/pull/603) by [justin808](https://github.com/justin808))
+   - Babel dependencies are no longer included as peer dependencies
+   - Improves compilation speed by 20x
+   - **Migration for existing projects:**
+     - **Option 1 (Recommended):** Switch to SWC:
+       ```yaml
+       # config/shakapacker.yml
+       javascript_transpiler: 'swc'
+       ```
+       Then install: `npm install @swc/core swc-loader`
+     - **Option 2:** Keep using Babel:
+       ```yaml
+       # config/shakapacker.yml
+       javascript_transpiler: 'babel'
+       ```
+
+2. **CSS Modules now use named exports by default**
+   - Configured with `namedExport: true` and `exportLocalsConvention: 'camelCase'`
+   - **JavaScript:** Use named imports: `import { className } from './styles.module.css'`
+   - **TypeScript:** Use namespace imports: `import * as styles from './styles.module.css'`
+   - Default imports (`import styles from '...'`) no longer work
+   - See [CSS Modules Export Mode documentation](./docs/css-modules-export-mode.md) for migration details
+
+3. **Configuration option renamed from `webpack_loader` to `javascript_transpiler`**
+   - Better reflects its purpose of configuring JavaScript transpilation
+   - Old `webpack_loader` option deprecated but still supported with warning
 
-### Changed
-- Configuration option renamed from `bundler` to `assets_bundler` to avoid confusion with Ruby's Bundler gem manager. The old `bundler` option is deprecated but still supported with a warning (not a breaking change).
-- BREAKING CHANGE: Configuration option renamed from `webpack_loader` to `javascript_transpiler` to better reflect its purpose of configuring JavaScript transpilation regardless of the bundler used. The old `webpack_loader` option is deprecated but still supported with a warning.
-- **BREAKING CHANGE**: SWC is now the default JavaScript transpiler instead of Babel. Babel dependencies are no longer included as peer dependencies. They are installed automatically only when `javascript_transpiler` is set to 'babel'. This reduces node_modules size and improves compilation speed by 20x. [PR 603](https://github.com/shakacode/shakapacker/pull/603) by [justin808](https://github.com/justin808).
-  
-  **Migration for existing projects:**
-  - **Option 1 (Recommended):** Switch to SWC for 20x faster compilation:
-    ```yaml
-    # config/shakapacker.yml
-    javascript_transpiler: 'swc'
-    ```
-    Then install SWC: `npm install @swc/core swc-loader`
-    
-  - **Option 2:** Keep using Babel (no changes needed):
-    ```yaml
-    # config/shakapacker.yml
-    javascript_transpiler: 'babel'
-    ```
-    Your existing babel packages in package.json will continue to work.
-  
-  **For new projects:**
-  - SWC is installed by default (20x faster than Babel)
-  - To use Babel instead: Set `javascript_transpiler: 'babel'` before running `rails shakapacker:install`
-  - To use esbuild: Set `javascript_transpiler: 'esbuild'` and install with `npm install esbuild esbuild-loader`
-- **BREAKING CHANGE**: CSS Modules are now configured with named exports (`namedExport: true` and `exportLocalsConvention: 'camelCase'`) to align with Next.js and modern tooling standards.
-  - **JavaScript**: Use named imports (`import { className } from './styles.module.css'`)
-  - **TypeScript**: Requires namespace imports (`import * as styles from './styles.module.css'`) due to TypeScript's inability to type dynamic named exports
-  - Note: Default imports (`import styles from '...'`) will no longer work as css-loader with `namedExport: true` doesn't generate a default export
-  - See the [CSS Modules Export Mode documentation](./docs/css-modules-export-mode.md) for detailed migration instructions and override options
-
-## [v9.0.0.beta.2] - September 25, 2025
 ### Added
+- **Rspack support** as an alternative assets bundler to webpack
+  - Configure `assets_bundler: 'rspack'` in `shakapacker.yml`
+  - Faster Rust-based bundling with webpack-compatible APIs
+  - Built-in SWC loader and CSS extraction
+  - Automatic bundler detection in `bin/shakapacker`
+- **Private output path** for server-side rendering bundles ([PR 592](https://github.com/shakacode/shakapacker/pull/592) by [justin808](https://github.com/justin808))
+  - Configure `private_output_path` for private server bundles
+- **Enhanced TypeScript definitions** ([PR 602](https://github.com/shakacode/shakapacker/pull/602) by [justin808](https://github.com/justin808))
+  - Better IDE support and type safety
+- **`rake shakapacker:doctor` diagnostic command** ([PR 609](https://github.com/shakacode/shakapacker/pull/609) by [justin808](https://github.com/justin808))
+  - Check for configuration issues and missing dependencies
+  - Identify missing loaders that cause build errors
+  - Particularly useful when migrating to v9 where peer dependencies are removed
+  - Detects transpiler-specific issues based on v9 changes
 
-* Support for subresource integrity. [PR 570](https://github.com/shakacode/shakapacker/pull/570) by [panagiotisplytas](https://github.com/panagiotisplytas)
+### Changed
+- Configuration option renamed from `bundler` to `assets_bundler` (deprecated but supported)
+- **Babel dependencies are now optional** instead of peer dependencies ([PR 603](https://github.com/shakacode/shakapacker/pull/603) by [justin808](https://github.com/justin808))
+  - Installed automatically only when `javascript_transpiler` is set to 'babel'
 
 ### Fixed
+- Update webpack-dev-server to secure versions (^4.15.2 || ^5.2.2) ([PR 585](https://github.com/shakacode/shakapacker/pull/585) by [justin808](https://github.com/justin808))
+
+## [v8.4.0] - September 8, 2024
 
+### Added
+- Support for subresource integrity. [PR 570](https://github.com/shakacode/shakapacker/pull/570) by [panagiotisplytas](https://github.com/panagiotisplytas).
+
+### Fixed
 - Install the latest major version of peer dependencies [PR 576](https://github.com/shakacode/shakapacker/pull/576) by [G-Rath](https://github.com/g-rath).
-- Remove duplicate word in comment from generated `shakapacker.yml` config [PR 572](https://github.com/shakacode/shakapacker/pull/572) by [G-Rath](https://github.com/g-rath).
-- fix: update webpack-dev-server to secure versions (^4.15.2 || ^5.2.2) [PR 585](https://github.com/shakacode/shakapacker/pull/585) by [justin808](https://github.com/justin808)
 
 
-## [v8.3.0] - April 25, 2025
+## [v8.3.0] - April 28, 2024
 ### Added
 
 - Allow `webpack-assets-manifest` v6. [PR 562](https://github.com/shakacode/shakapacker/pull/562) by [tagliala](https://github.com/tagliala), [shoeyn](https://github.com/shoeyn).
@@ -467,7 +484,8 @@ Note: [Rubygem is 6.3.0.pre.rc.1](https://rubygems.org/gems/shakapacker/versions
 ## v5.4.3 and prior changes from rails/webpacker
 See [CHANGELOG.md in rails/webpacker (up to v5.4.3)](https://github.com/rails/webpacker/blob/master/CHANGELOG.md)
 
-[Unreleased]: https://github.com/shakacode/shakapacker/compare/v8.4.0...main
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.0.0-beta.4...main
+[v9.0.0-beta.4]: https://github.com/shakacode/shakapacker/compare/v8.4.0...v9.0.0-beta.4
 [v8.4.0]: https://github.com/shakacode/shakapacker/compare/v8.3.0...v8.4.0
 [v8.3.0]: https://github.com/shakacode/shakapacker/compare/v8.2.0...v8.3.0
 [v8.2.0]: https://github.com/shakacode/shakapacker/compare/v8.1.0...v8.2.0

data/Gemfile.lock

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

data/README.md

@@ -657,11 +657,13 @@ See also [Customizing Babel Config](./docs/customizing_babel_config.md) for an e
 
 #### TypeScript
 
+**📚 TypeScript Support:** See the **[TypeScript Documentation](./docs/typescript.md)** for type-safe configuration.
+
 ```bash
 npm install typescript @babel/preset-typescript
 ```
 
-Babel won’t perform any type-checking on TypeScript code. To optionally use type-checking run:
+Babel won't perform any type-checking on TypeScript code. To optionally use type-checking run:
 
 ```bash
 npm install fork-ts-checker-webpack-plugin

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
 

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)