shakapacker 8.4.0 → 9.0.0

data/CONTRIBUTING.md

@@ -3,6 +3,7 @@
 Thank you for your interest in contributing to Shakapacker! We welcome all contributions that align with our project goals and values. To ensure a smooth and productive collaboration, please follow these guidelines.
 
 ## Contents
+
 - [Reporting Issues](#reporting-issues)
 - [Submitting Pull Requests](#submitting-pull-requests)
 - [Setting Up a Development Environment](#setting-up-a-development-environment)
@@ -10,46 +11,121 @@ Thank you for your interest in contributing to Shakapacker! We welcome all contr
 - [Testing the generator](#testing-the-generator)
 
 ## Reporting Issues
+
 If you encounter any issues with the project, please first check the existing issues (including closed ones). If the issues is not reported before, please opening an issue on our GitHub repository. Please provide a clear and detailed description of the issue, including steps to reproduce it. Creating a demo repository to demonstrate the issue would be ideal (and in some cases necessary).
 
 If looking to contribute to the project by fixing existing issues, we recommend looking at issues, particularly with the "[help wanted](https://github.com/shakacode/shakapacker/issues?q=is%3Aissue+label%3A%22help+wanted%22)" label.
 
 ## Submitting Pull Requests
+
 We welcome pull requests that fix bugs, add new features, or improve existing ones. Before submitting a pull request, please make sure to:
 
-  - Open an issue about what you want to propose before start working on.
-  - Fork the repository and create a new branch for your changes.
-  - Write clear and concise commit messages.
-  - Follow our code style guidelines.
-  - Write tests for your changes and [make sure all tests pass](#making-sure-your-changes-pass-all-tests).
-  - Update the documentation as needed.
-  - Update CHANGELOG.md if the changes affect public behavior of the project.
+- Open an issue about what you want to propose before start working on.
+- Fork the repository and create a new branch for your changes.
+- Write clear and concise commit messages.
+- Follow our code style guidelines.
+- Write tests for your changes and [make sure all tests pass](#making-sure-your-changes-pass-all-tests).
+- Update the documentation as needed.
+- Update CHANGELOG.md if the changes affect public behavior of the project.
+
+---
+
+## Git Hooks (Optional)
+
+This project includes configuration for git hooks via `husky` and `lint-staged`, but they are **opt-in for contributors**.
+
+**Why are hooks optional?** As a library project, we don't enforce git hooks because:
+
+- Different contributors may have different workflows
+- Forcing hooks can interfere with contributor tooling
+- CI/CD handles the final validation
+
+To enable pre-commit hooks locally:
+
+```bash
+npx husky install
+npx husky add .husky/pre-commit "npx lint-staged"
+```
+
+---
+
+## Linting and Code Quality
+
+### Running Linters
+
+```bash
+# Full linting with type checking (slower but thorough)
+yarn lint
+
+# Fast linting without type checking (for quick feedback)
+yarn lint:fast
+
+# With caching for better performance
+yarn lint --cache
+```
+
+**Performance Note:** TypeScript ESLint uses type-aware linting for better type safety, which can be slower on large codebases. Use `yarn lint:fast` during development for quick feedback.
 
 ---
+
 ## Setting Up a Development Environment
 
 1. Install [Yarn](https://classic.yarnpkg.com/)
 2. To test your changes on a Rails test project do the following steps:
+
    - For Ruby gem, update `Gemfile` and point the `shakapacker` to the locally developing Shakapacker project:
-      ```ruby
-      gem 'shakapacker', path: "relative_or_absolute_path_to_local_shakapacker"
-      ```
+     ```ruby
+     gem 'shakapacker', path: "relative_or_absolute_path_to_local_shakapacker"
+     ```
    - For npm package, use `yalc` with following steps:
-      ```bash
-      # In Shakapacker root directory
-      yalc publish
-      # In Rails app for testing
-      yalc link shakapacker
-
-      # After every change in shakapacker, run the following in Shakapacker directory
-      yalc push # or yalc publish --push
-      ```
+
+     ```bash
+     # In Shakapacker root directory
+     yalc publish
+     # In Rails app for testing
+     yalc link shakapacker
+
+     # After every change in shakapacker, run the following in Shakapacker directory
+     yalc push # or yalc publish --push
+     ```
+
 3. Run the following commands to set up the development environment.
    ```
    bundle install
    yarn install
+   yarn prepare:husky  # Set up pre-commit hooks for linting
    ```
 
+## 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.
@@ -101,6 +177,7 @@ bundle exec rake run_spec:gem
 ```
 
 #### 4.4 Run only Shakapacker gem specs for backward compatibility
+
 These specs are to check Shakapacker v7 backward compatibility with v6.x
 
 ```
@@ -108,6 +185,7 @@ bundle exec rake run_spec:gem_bc
 ```
 
 #### 4.5 Run dummy app test
+
 For this, you need `yalc` to be installed on your local machine
 
 ```
@@ -115,6 +193,7 @@ bundle exec rake run_spec:dummy
 ```
 
 #### 4.6 Testing the installer
+
 To ensure that your installer works as expected, either you can run `bundle exec rake run_spec:install`, or take the following manual testing steps:
 
 1. Update the `Gemfile` so that gem `shakapacker` has a line like this, pointing to your developing Shakapacker:
@@ -124,4 +203,43 @@ To ensure that your installer works as expected, either you can run `bundle exec
 2. Run `bundle install` to install the updated gem.
 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.
+**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 (8.4.0)
+    shakapacker (9.0.0)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)
@@ -217,7 +217,7 @@ GEM
       rubocop-ast (>= 1.31.1, < 2.0)
     ruby-progressbar (1.13.0)
     securerandom (0.3.1)
-    semantic_range (3.0.0)
+    semantic_range (3.1.0)
     stringio (3.1.1)
     thor (1.3.2)
     timeout (0.4.1)
@@ -248,4 +248,4 @@ DEPENDENCIES
   shakapacker!
 
 BUNDLED WITH
-   2.5.18
+   2.5.23

data/README.md

@@ -1,8 +1,14 @@
-# Shakapacker (v8)
+# Shakapacker (v9)
+---
+
+_🚀 Shakapacker 9 supports [Rspack](https://rspack.rs/)! 10x faster than webpack!_
+
+---
 
 _Official, actively maintained successor to [rails/webpacker](https://github.com/rails/webpacker). ShakaCode stands behind the long-term maintenance and development of this project for the Rails community._
 
 * ⚠️ See the [6-stable](https://github.com/shakacode/shakapacker/tree/6-stable) branch for Shakapacker v6.x code and documentation. :warning:
+* **See [V9 Upgrade](./docs/v9_upgrade.md) for upgrading from the v8 release.**
 * See [V8 Upgrade](./docs/v8_upgrade.md) for upgrading from the v7 release.
 * See [V7 Upgrade](./docs/v7_upgrade.md) for upgrading from the v6 release.
 * See [V6 Upgrade](./docs/v6_upgrade.md) for upgrading from v5 or prior v6 releases.
@@ -194,6 +200,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:
@@ -640,6 +723,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:
@@ -652,11 +739,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
@@ -926,6 +1015,30 @@ source_path: frontend # packs are the files in frontend/
 public_output_path: assets/packs # outputs to => public/assets/packs
 ```
 
+For server-side rendering (SSR) scenarios where you need to generate bundles that should not be served publicly, you can use the `private_output_path` configuration:
+
+```yml
+# config/shakapacker.yml
+private_output_path: ssr-generated # outputs to => ssr-generated/
+```
+
+This is particularly useful when working with libraries like React on Rails where server bundles need to be kept separate from client bundles.
+
+#### Migration Guide for React on Rails Users
+
+If you're using React on Rails with separate client and server bundles, you can now leverage the `private_output_path` configuration instead of using custom webpack configurations:
+
+1. Update your `config/shakapacker.yml`:
+   ```yml
+   # Before: both client and server bundles in public/
+   # After: separate directories
+   public_output_path: packs        # Client bundles (publicly served)
+   private_output_path: ssr-bundles  # Server bundles (not publicly served)
+   ```
+
+2. Update your webpack configuration to use the appropriate output path based on the bundle type
+3. The validation ensures `private_output_path` and `public_output_path` are different to prevent configuration errors
+
 Similarly, you can also control and configure `webpack-dev-server` settings from `config/shakapacker.yml` file:
 
 ```yml
@@ -993,7 +1106,19 @@ pnpm install --frozen-lockfile
 bun install --frozen-lockfile
 ```
 
-If you are using a CDN setup, Shakapacker does NOT use the `ASSET_HOST` environment variable to prefix URLs for assets during bundle compilation. You must use the `SHAKAPACKER_ASSET_HOST` environment variable instead (`WEBPACKER_ASSET_HOST` if you're using any version of Webpacker or Shakapacker before Shakapacker v7).
+### CDN
+
+Shakapacker supports serving JavaScript bundles and assets from a CDN. The key configuration is setting the `SHAKAPACKER_ASSET_HOST` environment variable (NOT the Rails `ASSET_HOST` variable).
+
+For detailed CDN setup instructions, including CloudFlare configuration, troubleshooting, and advanced setups, see the [CDN Setup Guide](./docs/cdn_setup.md).
+
+**Quick example:**
+```bash
+export SHAKAPACKER_ASSET_HOST=https://cdn.example.com
+RAILS_ENV=production bundle exec rails assets:precompile
+```
+
+For more deployment documentation, see [Deployment](./docs/deployment.md).
 
 ## Example Apps
 * [React on Rails Tutorial With SSR, HMR fast refresh, and TypeScript](https://github.com/shakacode/react_on_rails_tutorial_with_ssr_and_hmr_fast_refresh)
@@ -1018,8 +1143,8 @@ The following companies support our Open Source projects, and ShakaCode uses the
 <br />
 <br />
 
-<a href="https://www.jetbrains.com">
-  <img src="https://user-images.githubusercontent.com/4244251/184881139-42e4076b-024b-4b30-8c60-c3cd0e758c0a.png" alt="JetBrains" height="120px">
+<a href="https://jb.gg/OpenSource" style="margin-right: 20px;">
+  <img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.png" alt="JetBrains" height="120px">
 </a>
 <a href="https://scoutapp.com">
   <picture>

data/Rakefile

@@ -14,16 +14,51 @@ namespace :run_spec do
     sh("bundle exec rspec spec/shakapacker/*_spec.rb")
   end
 
-  desc "Run specs in the dummy app"
+  desc "Run specs in the dummy app with webpack"
   task :dummy do
-    puts "Running dummy app specs"
+    puts "Running dummy app specs with webpack"
     spec_dummy_dir = Pathname.new(File.join("spec", "dummy")).realpath
     Bundler.with_unbundled_env do
       sh_in_dir(".", "yalc publish")
       sh_in_dir(spec_dummy_dir, [
         "bundle install",
         "yalc link shakapacker",
-        "yarn install",
+        "npm install",
+        "bin/test-bundler webpack",
+        "NODE_ENV=test RAILS_ENV=test bin/shakapacker",
+        "bundle exec rspec"
+      ])
+    end
+  end
+
+  desc "Run specs in the dummy app with rspack"
+  task :dummy_with_rspack do
+    puts "Running dummy app specs with rspack"
+    spec_dummy_dir = Pathname.new(File.join("spec", "dummy")).realpath
+    Bundler.with_unbundled_env do
+      sh_in_dir(".", "yalc publish")
+      sh_in_dir(spec_dummy_dir, [
+        "bundle install",
+        "yalc link shakapacker",
+        "npm install",
+        "bin/test-bundler rspack",
+        "NODE_ENV=test RAILS_ENV=test bin/shakapacker",
+        "bundle exec rspec"
+      ])
+    end
+  end
+
+  desc "Run specs in the dummy-rspack app"
+  task :dummy_rspack do
+    puts "Running dummy-rspack app specs"
+    spec_dummy_dir = Pathname.new(File.join("spec", "dummy-rspack")).realpath
+    Bundler.with_unbundled_env do
+      sh_in_dir(".", "yalc publish")
+      sh_in_dir(spec_dummy_dir, [
+        "bundle install",
+        "yalc link shakapacker",
+        "npm install",
+        "NODE_ENV=test RAILS_ENV=test npm exec --no -- rspack build --config config/rspack/rspack.config.js",
         "bundle exec rspec"
       ])
     end
@@ -35,7 +70,7 @@ namespace :run_spec do
   end
 
   desc "Run all specs"
-  task all_specs: %i[gem dummy generator] do
+  task all_specs: %i[gem dummy dummy_with_rspack dummy_rspack generator] do
     puts "Completed all RSpec tests"
   end
 end

data/TODO.md

@@ -0,0 +1,50 @@
+# TypeScript Migration Status
+
+## ✅ Completed (PR #602)
+- Enhanced `package/index.d.ts` with comprehensive type definitions
+- Added TypeScript type packages for better IDE support
+- Improved Config and DevServerConfig interfaces
+- Added missing properties (private_output_path, inline_css, env_prefix, etc.)
+- All tests passing
+- Zero JavaScript modifications (no whitespace changes)
+- Full backward compatibility maintained
+
+## 📋 Next Steps (Issue #605)
+
+### Phase 2: Core Module Conversion
+- [ ] Convert `package/config.js` to TypeScript
+- [ ] Convert `package/env.js` to TypeScript  
+- [ ] Convert `package/index.js` to TypeScript
+- [ ] Convert `package/utils/helpers.js` to TypeScript
+
+### Phase 3: Environment & Build System
+- [ ] Convert environment files (base, development, production, test)
+- [ ] Convert dev_server.js
+- [ ] Convert webpackDevServerConfig.js
+
+### Phase 4: Rules & Loaders (PR #620) ✅
+- [x] Convert all files in `package/rules/`
+- [x] Convert all files in `package/plugins/`
+- [x] Convert all files in `package/optimization/`
+
+### Phase 5: Framework-Specific Modules ✅
+- [x] Convert rspack support files
+- [x] Convert swc support files
+- [x] Convert esbuild support files
+- [x] Convert babel preset
+
+### Phase 6: Final Cleanup ✅
+- [x] Add TypeScript linting with @typescript-eslint
+- [x] Verify strict mode is enabled (already configured)
+- [x] Update documentation
+
+## Why Gradual Migration?
+- **Lower risk**: Each phase can be tested independently
+- **Team learning**: Get familiar with TypeScript incrementally
+- **Immediate value**: Type definitions already provide IDE benefits
+- **No breaking changes**: Users unaffected during migration
+
+## Related Links
+- Original issue: #200
+- Initial PR: #602
+- Next steps issue: #605

data/TODO_v9.md

@@ -0,0 +1,87 @@
+# Shakapacker v9 TODO List
+
+## CSS Modules Configuration Alignment
+
+### Problem
+Current CSS modules configuration causes TypeScript/webpack warnings because of default vs named export mismatch.
+
+### Current Behavior (v8)
+- CSS modules use default export: `import styles from './styles.module.css'`
+- This causes warnings but works at runtime
+- Warning example: `export 'default' (imported as 'style') was not found in './HelloWorld.module.css'`
+
+### Proposed v9 Change
+Align with Next.js and modern tooling by using named exports:
+
+1. **Update css-loader configuration:**
+```javascript
+{
+  loader: 'css-loader',
+  options: {
+    modules: {
+      namedExport: true,
+      exportLocalsConvention: 'camelCaseOnly'  // Must be 'camelCaseOnly' or 'dashesOnly' with namedExport: true
+    }
+  }
+}
+```
+
+**Note:** Using `exportLocalsConvention: 'camelCase'` with `namedExport: true` will cause a build error.
+css-loader only allows `'camelCaseOnly'` or `'dashesOnly'` when named exports are enabled.
+
+2. **Update TypeScript types:**
+- Ensure proper typing for CSS modules with named exports
+- May need to update or generate `.d.ts` files for CSS modules
+
+3. **Migration guide for users:**
+- Document the breaking change
+- Provide codemod or migration script to update imports from:
+  ```javascript
+  import styles from './styles.module.css'
+  styles.className
+  ```
+  to:
+  ```javascript
+  import * as styles from './styles.module.css'
+  // or
+  import { className } from './styles.module.css'
+  ```
+
+### Benefits
+- Eliminates webpack/TypeScript warnings
+- Better tree-shaking potential
+- More explicit about what CSS classes are being used
+- Easier interoperability with frameworks that support named exports
+
+### Implementation Notes
+- This is a BREAKING CHANGE and appropriate for major version bump
+- Need to test with both webpack and rspack
+- Consider providing a compatibility mode via configuration option
+
+---
+
+## Related Issues from PR #597
+
+### React Component Not Rendering (spec/dummy) - RESOLVED ✅
+- **Issue**: React component was not rendering due to CSS module import mismatch
+- **Symptoms**:
+  - Component wasn't rendering "Hello, Stranger!"
+  - Input field not rendered, making interactive test fail
+  - Only the static H1 "Hello, World!" was visible
+- **Resolution**:
+  - Fixed CSS module import syntax from `import style from` to `import * as style from`
+  - This matched webpack's named exports configuration for CSS modules
+  - Tests now pass with both React 18.3.1 and webpack/rspack configurations
+- **Root Cause**: CSS module import/export mismatch
+  - Webpack was configured to use named exports for CSS modules
+  - TypeScript code was using default import syntax
+  - This caused `style` to be undefined, breaking SSR and client rendering
+- **Status**: FIXED
+  - All tests re-enabled and passing
+  - Both SSR and client-side rendering working
+  - Interactive functionality restored
+
+### Test Infrastructure
+- Successfully implemented dual bundler support (webpack/rspack)
+- test-bundler script working well with status command
+- Consider adding more comprehensive tests for both bundlers