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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4e7529c9a1e2dee69667d688581f6c684c775c18a17ac527a3328876d45c523
-  data.tar.gz: 305d71e3efd30913c856066b7195ff259094bafb2cc2f7fa7f1730cdbfc49cdf
+  metadata.gz: ca5207ce21d40303f0a0250d140763ca93000a318ba28a9ac8efff358ce59310
+  data.tar.gz: f494c9a43b2c9fc704ca6dc1e3110f0c7048759a13e3f8254c44735e91a58da0
 SHA512:
-  metadata.gz: cdba0281b3a0bc4e43d50ac4e84fa1a9b029ff6999afeabea56eada8ffded1c366e4b084734758566f009c1214ac36d7da874ea4887c70010551330f678bccbc
-  data.tar.gz: 97a96fa177348c19929aae4fe53865f9f738f21c060e77863dfd79c3cc22869c4a6eb78af34d2139eb842baf61f59b3a9040b1e42cec3ed2fa216d1818124ca1
+  metadata.gz: a13fd3b73ffb91546e25c8226731efd4cdf6e8024893011795e32f379d2c3ffd14a4b5286b2a32499447405a01624b50805aafd6749112538e560ab21bc58e7e
+  data.tar.gz: d9911ec4c3a53a6baf3598e48b29e74684113a6514e979c73b69479905399e94abc67c0792a51c1cf12c5961a771c9de1f19e1800991f9a638dfab5ebcd1e606

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/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/.github/workflows/test-bundlers.yml

@@ -27,8 +27,8 @@ 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
@@ -47,7 +47,7 @@ jobs:
       - name: Install dependencies
         run: |
           yalc link shakapacker
-          npm ci
+          yarn install
 
       - name: Switch to Webpack
         run: bin/test-bundler webpack
@@ -80,8 +80,8 @@ 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
@@ -100,7 +100,7 @@ jobs:
       - name: Install dependencies
         run: |
           yalc link shakapacker
-          npm ci
+          yarn install
 
       - name: Switch to RSpack
         run: bin/test-bundler rspack
@@ -133,8 +133,8 @@ 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
@@ -153,7 +153,7 @@ jobs:
       - name: Install dependencies
         run: |
           yalc link shakapacker
-          npm ci
+          yarn install
 
       - name: Test switching between bundlers
         run: |

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/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.5)
+    shakapacker (9.0.0.beta.7)
       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:
@@ -645,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/optional-peer-dependencies.md

@@ -0,0 +1,198 @@
+# Optional Peer Dependencies in Shakapacker
+
+## Overview
+
+As of Shakapacker v9, all peer dependencies are marked as optional via `peerDependenciesMeta`. This design provides maximum flexibility while maintaining clear version constraints.
+
+## Key Benefits
+
+1. **No Installation Warnings** - Package managers (npm, yarn, pnpm) won't warn about missing peer dependencies
+2. **Install Only What You Need** - Users only install packages for their chosen configuration
+3. **Clear Version Constraints** - When packages are installed, version compatibility is still enforced
+4. **Smaller Node Modules** - Reduced disk usage by not installing unnecessary packages
+
+## Implementation Details
+
+### Package.json Structure
+
+```json
+{
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "path-complete-extname": "^1.0.0",
+    "webpack-merge": "^5.8.0"  // Direct dependency - always available
+  },
+  "peerDependencies": {
+    "webpack": "^5.76.0",
+    "@rspack/core": "^1.0.0",
+    // ... all build tools
+  },
+  "peerDependenciesMeta": {
+    "webpack": { "optional": true },
+    "@rspack/core": { "optional": true },
+    // ... all marked as optional
+  }
+}
+```
+
+### TypeScript Type-Only Imports
+
+To prevent runtime errors when optional packages aren't installed, all webpack imports use type-only syntax:
+
+```typescript
+// @ts-ignore: webpack is an optional peer dependency (using type-only import)
+import type { Configuration } from "webpack"
+```
+
+Type-only imports are erased during compilation and don't trigger module resolution at runtime.
+
+## Configuration Examples
+
+### Webpack + Babel (Traditional)
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "webpack": "^5.76.0",
+    "webpack-cli": "^5.0.0",
+    "babel-loader": "^8.2.4",
+    "@babel/core": "^7.17.9",
+    "@babel/preset-env": "^7.16.11"
+  }
+}
+```
+
+### Webpack + SWC (20x Faster)
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "webpack": "^5.76.0",
+    "webpack-cli": "^5.0.0",
+    "@swc/core": "^1.3.0",
+    "swc-loader": "^0.2.0"
+  }
+}
+```
+
+### Rspack + SWC (10x Faster Bundling)
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "@rspack/core": "^1.0.0",
+    "@rspack/cli": "^1.0.0",
+    "rspack-manifest-plugin": "^5.0.0"
+  }
+}
+```
+
+## Migration Guide
+
+### From v8 to v9
+
+If upgrading from Shakapacker v8:
+
+1. **No action required** - Your existing dependencies will continue to work
+2. **No more warnings** - Peer dependency warnings will disappear after upgrading
+3. **Option to optimize** - You can now remove unused dependencies (e.g., remove Babel if using SWC)
+
+### New Installations
+
+The installer (`rails shakapacker:install`) only adds packages needed for your configuration:
+- Detects your preferred bundler (webpack/rspack)
+- Installs appropriate JavaScript transpiler (babel/swc/esbuild)
+- Adds only required dependencies
+
+## Version Constraints
+
+Version ranges are carefully chosen for compatibility:
+
+- **Broader ranges for peer deps** - Allows flexibility (e.g., `^5.76.0` for webpack)
+- **Specific versions in devDeps** - Ensures testing against known versions
+- **Forward compatibility** - Ranges include future minor versions (e.g., `^5.0.0 || ^6.0.0`)
+
+## Testing
+
+### Installation Tests
+
+Test that no warnings appear during installation:
+
+```bash
+# Test script available at test/peer-dependencies.sh
+./test/peer-dependencies.sh
+```
+
+### Runtime Tests
+
+Verify Shakapacker loads without optional dependencies:
+
+```javascript
+// This works even without webpack installed (when using rspack)
+const shakapacker = require('shakapacker');
+```
+
+### CI Integration
+
+The test suite includes:
+- `spec/shakapacker/optional_dependencies_spec.rb` - Package.json structure validation
+- `spec/shakapacker/doctor_optional_peer_spec.rb` - Doctor command validation
+- `test/peer-dependencies.sh` - Installation warning tests
+
+## Troubleshooting
+
+### Still seeing peer dependency warnings?
+
+1. Ensure you're using Shakapacker v9.0.0 or later
+2. Clear your package manager cache:
+   - npm: `npm cache clean --force`
+   - yarn: `yarn cache clean`
+   - pnpm: `pnpm store prune`
+3. Reinstall dependencies
+
+### Module not found errors?
+
+1. Check you've installed required dependencies for your configuration
+2. Refer to the configuration examples above
+3. Run `rails shakapacker:doctor` for diagnostics
+
+### TypeScript errors?
+
+The `@ts-ignore` comments are intentional and necessary for optional dependencies.
+They prevent TypeScript errors when optional packages aren't installed.
+
+## Contributing
+
+When adding new dependencies:
+
+1. Add to `peerDependencies` with appropriate version range
+2. Mark as optional in `peerDependenciesMeta`
+3. Use type-only imports in TypeScript: `import type { ... }`
+4. Test with all package managers (npm, yarn, pnpm)
+5. Update this documentation if needed
+
+## Design Rationale
+
+This approach balances several concerns:
+
+1. **User Experience** - No confusing warnings during installation
+2. **Flexibility** - Support multiple configurations without forcing unnecessary installs
+3. **Compatibility** - Maintain version constraints for safety
+4. **Performance** - Reduce installation time and disk usage
+5. **Type Safety** - TypeScript support without runtime dependencies
+
+## Future Improvements
+
+Potential enhancements for future versions:
+
+1. **Conditional exports** - Use package.json exports field for better tree-shaking
+2. **Dynamic imports** - Load bundler-specific code only when needed
+3. **Doctor updates** - Enhance doctor command to better understand optional dependencies
+4. **Automated testing** - Add CI jobs testing each configuration combination
+
+## References
+
+- [npm: peerDependenciesMeta](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#peerdependenciesmeta)
+- [TypeScript: Type-Only Imports](https://www.typescriptlang.org/docs/handbook/modules.html#type-only-imports-and-exports)
+- [Shakapacker Issue #565](https://github.com/shakacode/shakapacker/issues/565)
+- [Pull Request #615](https://github.com/shakacode/shakapacker/pull/615)