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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 173792ac146bcec2bdcea877d9449ab35935ec1cd61b04d8df1d02cf62325a29
-  data.tar.gz: 7d135bb3eb60f7a65723625dbc611c155122b2cd985a99a955f93d0f0f380d24
+  metadata.gz: 65a49f86249eeb2035e56d7f21da2d8e4edbe5a26da50b0a63a9534a720a84cf
+  data.tar.gz: 153cb1df867355c881a3a7fe31b3aed526355ff30f7eaaacb497d231cb5f3bcc
 SHA512:
-  metadata.gz: 97d4f23b01c785a479e53a3e8abcf8df1462243096b4fc14ed3c2b0fbd50096ac5e65b829ecc3dd3d40a6adc072541952ff1af3e74ed8ebce544eb771570c527
-  data.tar.gz: de3fa497d411233f46023ca903f2f7586701a97b4c08de85ec347064c0d2b355570ad9e8988993dc01024663a0c48264513b3a00f23287665c3acfcee25644a0
+  metadata.gz: c237ee4221a14f19ae86067632ad00baaf1f05d3464c21804b8aa3fa7029429bc8d678d630f1762f940ea780f4ff81023c26d26342aa27380a461f1485f50b3d
+  data.tar.gz: b37633ed02a416c423bfb410b189b1ca7c508a162339e9def8401622c2ac198b4649ad0392795a9eb3301d6fc3d9858c2e39f1130b8c6bbd219887566126b91e

data/.eslintignore

@@ -2,3 +2,4 @@ lib/*
 node_modules/*
 vendor/*
 spec/*
+package/*

data/.github/workflows/claude-code-review.yml

@@ -50,5 +50,5 @@ jobs:
           
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
-          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+          claude_args: '--model claude-sonnet-4-5-20250929 --allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
 

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

@@ -27,12 +27,18 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: '20'
-          cache: 'npm'
-          cache-dependency-path: spec/dummy/package-lock.json
+          cache: 'yarn'
+          cache-dependency-path: spec/dummy/yarn.lock
 
       - 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 ../..
@@ -41,7 +47,7 @@ jobs:
       - name: Install dependencies
         run: |
           yalc link shakapacker
-          npm ci
+          yarn install
 
       - name: Switch to Webpack
         run: bin/test-bundler webpack
@@ -74,12 +80,18 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: '20'
-          cache: 'npm'
-          cache-dependency-path: spec/dummy/package-lock.json
+          cache: 'yarn'
+          cache-dependency-path: spec/dummy/yarn.lock
 
       - 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 ../..
@@ -88,7 +100,7 @@ jobs:
       - name: Install dependencies
         run: |
           yalc link shakapacker
-          npm ci
+          yarn install
 
       - name: Switch to RSpack
         run: bin/test-bundler rspack
@@ -121,12 +133,18 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: '20'
-          cache: 'npm'
-          cache-dependency-path: spec/dummy/package-lock.json
+          cache: 'yarn'
+          cache-dependency-path: spec/dummy/yarn.lock
 
       - 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 ../..
@@ -135,7 +153,7 @@ jobs:
       - name: Install dependencies
         run: |
           yalc link shakapacker
-          npm ci
+          yarn install
 
       - name: Test switching between bundlers
         run: |

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/CONTRIBUTING.md

@@ -50,6 +50,34 @@ We welcome pull requests that fix bugs, add new features, or improve existing on
    yarn install
    ```
 
+## Understanding Optional Peer Dependencies
+
+Shakapacker uses optional peer dependencies (via `peerDependenciesMeta`) for maximum flexibility:
+
+- **All peer dependencies are optional** - Users only install what they need
+- **No installation warnings** - Package managers won't warn about missing optional dependencies
+- **Version constraints still apply** - When a package is installed, version compatibility is enforced
+
+### When modifying dependencies:
+1. Add new peer dependencies to both `peerDependencies` and `peerDependenciesMeta` (marking as optional)
+2. Keep version ranges synchronized between `devDependencies` and `peerDependencies`
+3. Test with multiple package managers: `npm`, `yarn`, and `pnpm`
+
+### Testing peer dependency changes:
+```bash
+# Test with npm (no warnings expected)
+cd /tmp && mkdir test-npm && cd test-npm
+npm init -y && npm install /path/to/shakapacker
+
+# Test with yarn (no warnings expected)
+cd /tmp && mkdir test-yarn && cd test-yarn
+yarn init -y && yarn add /path/to/shakapacker
+
+# Test with pnpm (no warnings expected)
+cd /tmp && mkdir test-pnpm && cd test-pnpm
+pnpm init && pnpm add /path/to/shakapacker
+```
+
 ## Making sure your changes pass all tests
 
 There are several specs, covering different aspects of Shakapacker gem. You may run them locally or rely on GitHub CI actions configured to test the gem functionality if different Ruby, Rails, and Node environment.
@@ -125,3 +153,39 @@ To ensure that your installer works as expected, either you can run `bundle exec
 3. Run `bundle exec rails shakapacker:install` to confirm that you got the right changes.
 
  **Note:** Ensure that you use bundle exec otherwise the installed shakapacker gem will run and not the one you are working on.
+
+## CI Workflows
+
+Shakapacker uses GitHub Actions for continuous integration. The CI workflows use **Yarn** as the package manager for consistency and reliability.
+
+### Package Manager Choice
+
+The project uses Yarn in CI workflows for the following reasons:
+- Deterministic dependency resolution with `yarn.lock`
+- Faster installation with offline mirror support
+- Better workspace support for monorepo-style testing
+- Consistent behavior across different Node.js versions
+
+### Key CI Workflow Files
+
+- `.github/workflows/test-bundlers.yml` - Tests webpack, rspack, and bundler switching
+- `.github/workflows/ruby.yml` - Ruby test suite across Ruby/Rails versions
+- `.github/workflows/node.yml` - Node.js test suite across Node versions
+- `.github/workflows/generator.yml` - Generator installation tests
+
+All workflows use:
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    cache: 'yarn'
+    cache-dependency-path: spec/dummy/yarn.lock
+```
+
+And install dependencies with:
+```bash
+yarn install
+```
+
+### Testing with Other Package Managers
+
+While CI uses Yarn, the gem supports all major package managers (npm, yarn, pnpm, bun). Generator specs test against all package managers to ensure compatibility.

data/Gemfile.lock

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

data/README.md

@@ -199,6 +199,83 @@ Note, in v6+, most JS packages are peer dependencies. Thus, the installer will a
 Previously, these "webpack" and "babel" packages were direct dependencies for `shakapacker`. By
 making these peer dependencies, you have control over the versions used in your webpack and babel configs.
 
+### Optional Peer Dependencies
+
+All peer dependencies in Shakapacker are marked as optional via `peerDependenciesMeta`. This design decision ensures:
+- **No warnings during package installation** when dependencies are not needed
+- **Clear visibility of supported package versions** for upgrades
+- **Flexibility to choose only the tools you need** (webpack vs rspack, babel vs swc vs esbuild)
+
+The optional peer dependencies approach means you only install what you actually use, while still maintaining
+version compatibility constraints when you do install those packages.
+
+#### Required Dependencies by Configuration
+
+Depending on your setup, you'll need different subsets of the optional peer dependencies:
+
+**For Webpack + Babel (traditional setup):**
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "@babel/core": "^7.17.9",
+    "@babel/plugin-transform-runtime": "^7.17.0",
+    "@babel/preset-env": "^7.16.11",
+    "@babel/runtime": "^7.17.9",
+    "babel-loader": "^8.2.4",
+    "compression-webpack-plugin": "^9.0.0",
+    "terser-webpack-plugin": "^5.3.1",
+    "webpack": "^5.76.0",
+    "webpack-assets-manifest": "^5.0.6",
+    "webpack-cli": "^5.0.0",
+    "webpack-dev-server": "^5.0.0"
+  }
+}
+```
+
+**For Webpack + SWC (faster alternative):**
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "@swc/core": "^1.3.0",
+    "swc-loader": "^0.2.0",
+    "compression-webpack-plugin": "^9.0.0",
+    "terser-webpack-plugin": "^5.3.1",
+    "webpack": "^5.76.0",
+    "webpack-assets-manifest": "^5.0.6",
+    "webpack-cli": "^5.0.0",
+    "webpack-dev-server": "^5.0.0"
+  }
+}
+```
+
+**For Rspack + SWC (10x faster bundling):**
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "@rspack/core": "^1.0.0",
+    "@rspack/cli": "^1.0.0",
+    "@swc/core": "^1.3.0",
+    "swc-loader": "^0.2.0",
+    "rspack-manifest-plugin": "^5.0.0"
+  }
+}
+```
+
+**For CSS/Sass processing (add to any config above):**
+```json
+{
+  "dependencies": {
+    "css-loader": "^6.8.1",
+    "mini-css-extract-plugin": "^2.0.0",
+    "sass": "^1.50.0",
+    "sass-loader": "^13.0.0"
+  }
+}
+```
+
 ## Concepts
 
 At its core, Shakapacker's essential function is to:
@@ -657,11 +734,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