shakapacker 9.3.0 → 9.3.2

data/README.md

@@ -85,7 +85,7 @@ Read the [full review here](https://clutch.co/profile/shakacode#reviews?sort_by=
     - [Automatic Webpack Code Building](#automatic-webpack-code-building)
     - [Compiler strategies](#compiler-strategies)
     - [Common Development Commands](#common-development-commands)
-  - [API Documentation](#api-documentation)
+  - [Ruby API Reference](#ruby-api-reference)
   - [Webpack Configuration](#webpack-configuration)
   - [Babel configuration](#babel-configuration)
   - [SWC configuration](#swc-configuration)
@@ -163,7 +163,7 @@ Then run the following to install Shakapacker:
 
 ```bash
 ./bin/bundle install
-./bin/rails shakapacker:install
+bundle exec rake shakapacker:install
 ```
 
 Before initiating the installation process, ensure you have committed all the changes. While installing Shakapacker, there might be some conflict between the existing file content and what Shakapacker tries to copy. You can either approve all the prompts for overriding these files or use the `FORCE=true` environment variable before the installation command to force the override without any prompt.
@@ -282,12 +282,10 @@ Depending on your setup, you'll need different subsets of the optional peer depe
 **Quick tip:** You can easily switch between webpack and rspack using:
 
 ```bash
-rails shakapacker:switch_bundler rspack --install-deps
-# or with rake (note the -- separator)
-rake shakapacker:switch_bundler rspack -- --install-deps
+bundle exec rake shakapacker:switch_bundler rspack -- --install-deps
 
 # For faster switching, use --no-uninstall to keep both bundlers installed
-rails shakapacker:switch_bundler webpack --install-deps --no-uninstall
+bundle exec rake shakapacker:switch_bundler webpack -- --install-deps --no-uninstall
 ```
 
 See the [Rspack Migration Guide](./docs/rspack_migration_guide.md) for details.
@@ -673,47 +671,55 @@ end
 
 **Note:** Don't forget to prefix `ruby` when running these binstubs on Windows
 
-### API Documentation
+### Ruby API Reference
 
-Shakapacker's Ruby API is documented using RDoc comments. You can generate the API documentation locally using either RDoc or YARD:
+**📚 For comprehensive Ruby API documentation, see the [API Reference Guide](./docs/api-reference.md).**
 
-#### Using RDoc (Standard Ruby Documentation)
+This guide covers:
 
-```bash
-# Generate documentation in the doc/ directory
-rdoc lib/
+- **Main Shakapacker Module** - Configuration, compilation, and manifest access
+- **Configuration API** - Accessing `config/shakapacker.yml` settings programmatically
+- **View Helpers** - Complete reference for all Rails helpers
+- **Manifest API** - Asset lookup and resolution methods
+- **Dev Server API** - Development server status and management
+- **Advanced Usage** - Multiple instances, testing, custom configurations
 
-# View the generated documentation
-open doc/index.html
+#### Quick Examples
+
+```ruby
+# Access configuration
+Shakapacker.config.source_path
+# => #<Pathname:/app/app/javascript>
+
+# Get raw configuration hash
+Shakapacker.config.data
+# => { "source_path" => "app/javascript", ... }
+
+# Look up compiled assets
+Shakapacker.manifest.lookup("application.js")
+# => "/packs/application-abc123.js"
+
+# Check dev server status
+Shakapacker.dev_server.running?
+# => true
 ```
 
-#### Using YARD (Enhanced Documentation)
+#### Generating Full API Documentation
 
-YARD provides better formatting and supports additional tags used in the codebase:
+For complete API documentation with all methods and parameters:
 
 ```bash
-# Install YARD if you don't have it
+# Using YARD (recommended - better formatting)
 gem install yard
-
-# Generate documentation
 yard doc
+yard server  # Browse at http://localhost:8808
 
-# View the generated documentation
+# Using RDoc (standard Ruby documentation)
+rdoc lib/
 open doc/index.html
-
-# Or start a local documentation server
-yard server
 ```
 
-The API documentation covers:
-
-- **Shakapacker** - Main module with configuration, compilation, and manifest access
-- **Shakapacker::Configuration** - All configuration options from `shakapacker.yml`
-- **Shakapacker::Manifest** - Asset lookup methods used by view helpers
-- **Shakapacker::DevServer** - Development server status and configuration
-- **Shakapacker::Instance** - Instance management and lifecycle
-
-For the most up-to-date API reference, generate the documentation from the source code as shown above.
+The generated documentation includes all public and private methods with detailed descriptions.
 
 ### Webpack Configuration
 
@@ -724,6 +730,21 @@ First, you don't _need_ to use Shakapacker's webpack configuration. However, the
 
 The webpack configuration used by Shakapacker lives in `config/webpack/webpack.config.js`; this makes it easy to customize the configuration beyond what's available in `config/shakapacker.yml` by giving you complete control of the final configuration. By default, this file exports the result of `generateWebpackConfig` which handles generating a webpack configuration based on `config/shakapacker.yml`.
 
+#### Using a Completely Custom Webpack Configuration
+
+If you're providing a completely custom webpack configuration without using `generateWebpackConfig()`, you should set `javascript_transpiler: 'none'` in your `config/shakapacker.yml` to skip Shakapacker's transpiler validation and dependency checks:
+
+```yml
+# config/shakapacker.yml
+default: &default
+  javascript_transpiler: "none" # Skip Shakapacker's transpiler setup
+  # ... other config
+```
+
+This is useful when you're managing your own transpiler configuration entirely outside of Shakapacker's defaults.
+
+**Note:** Only use `javascript_transpiler: 'none'` if you're providing a completely custom webpack configuration without using `generateWebpackConfig()`. If you're using Shakapacker's webpack generation (which is the common case), use one of the supported transpilers (`'babel'`, `'swc'`, or `'esbuild'`) instead.
+
 The easiest way to modify this config is to pass your desired customizations to `generateWebpackConfig` which will use [webpack-merge](https://github.com/survivejs/webpack-merge) to merge them with the configuration generated from `config/shakapacker.yml`:
 
 ```js
@@ -818,7 +839,7 @@ fileRule.type = "asset"
 
 ### Babel configuration
 
-By default, you will find the Shakapacker preset in your `package.json`. Note, you need to use the new NPM package name, `shakapacker`.
+If you choose to use Babel instead of the default SWC transpiler, you will need to configure it in your `package.json`:
 
 ```json
 "babel": {
@@ -828,19 +849,21 @@ By default, you will find the Shakapacker preset in your `package.json`. Note, y
 },
 ```
 
-Optionally, you can change your Babel configuration by removing these lines in your `package.json` and adding [a Babel configuration file](https://babeljs.io/docs/en/config-files) to your project. For an example of customization based on the original, see [Customizing Babel Config](./docs/customizing_babel_config.md).
+You can also change your Babel configuration by removing these lines in your `package.json` and adding [a Babel configuration file](https://babeljs.io/docs/en/config-files) to your project. For an example of customization based on the original, see [Customizing Babel Config](./docs/customizing_babel_config.md).
 
 ### SWC configuration
 
-You can try out experimental integration with the SWC loader. You can read more at [SWC usage docs](./docs/using_swc_loader.md).
+SWC is the recommended JavaScript transpiler in Shakapacker v9+ (20x faster than Babel). New installations use SWC by default via the installation template. You can read more at [SWC usage docs](./docs/using_swc_loader.md).
+
+**Note on defaults**: The installation template explicitly sets `javascript_transpiler: "swc"` for new projects. However, for backward compatibility, webpack's runtime default (when no explicit config exists) remains `"babel"`. Rspack always defaults to `"swc"`.
 
-Please note that if you want opt-in to use SWC, you can skip [React](#react) integration instructions as it is supported out of the box.
+Please note that SWC supports [React](#react) integration out of the box - no additional configuration needed.
 
 ### esbuild loader configuration
 
-You can try out experimental integration with the esbuild-loader. You can read more at [esbuild-loader usage docs](./docs/using_esbuild_loader.md).
+You can use esbuild as an alternative JavaScript transpiler. You can read more at [esbuild-loader usage docs](./docs/using_esbuild_loader.md).
 
-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.
+Please note that esbuild supports [React](#react) integration out of the box - no additional configuration needed.
 
 ### Switching between transpilers
 
@@ -1092,13 +1115,13 @@ Otherwise, Shakapacker will use the production environment as a fallback environ
 For example, the below command will compile assets in production mode but will use staging configurations from `config/shakapacker.yml` if available or use fallback production environment configuration:
 
 ```bash
-RAILS_ENV=staging bundle exec rails assets:precompile
+RAILS_ENV=staging bundle exec rake assets:precompile
 ```
 
 And, this will compile in development mode and load configuration for the cucumber environment if defined in `shakapacker.yml` or fallback to production configuration
 
 ```bash
-RAILS_ENV=cucumber NODE_ENV=development bundle exec rails assets:precompile
+RAILS_ENV=cucumber NODE_ENV=development bundle exec rake assets:precompile
 ```
 
 Please note, binstubs compiles in development mode however rake tasks compiles in production mode.
@@ -1109,8 +1132,8 @@ Please note, binstubs compiles in development mode however rake tasks compiles i
 ./bin/shakapacker-dev-server
 
 # Compiles in production mode by default unless NODE_ENV is specified, per `lib/tasks/shakapacker/compile.rake`
-bundle exec rails assets:precompile
-bundle exec rails shakapacker:compile
+bundle exec rake assets:precompile
+bundle exec rake shakapacker:compile
 ```
 
 ### Upgrading
@@ -1122,7 +1145,7 @@ You can run the following commands to upgrade Shakapacker to the latest stable v
 bundle update shakapacker
 
 # overwrite your changes to the default install files and revert any unwanted changes from the install
-rails shakapacker:install
+bundle exec rake shakapacker:install
 
 # using npm
 npm install shakapacker@latest
@@ -1269,7 +1292,7 @@ For detailed CDN setup instructions, including CloudFlare configuration, trouble
 
 ```bash
 export SHAKAPACKER_ASSET_HOST=https://cdn.example.com
-RAILS_ENV=production bundle exec rails assets:precompile
+RAILS_ENV=production bundle exec rake assets:precompile
 ```
 
 For more deployment documentation, see [Deployment](./docs/deployment.md).
@@ -1323,3 +1346,10 @@ The following companies support our Open Source projects, and ShakaCode uses the
 <a href="https://www.honeybadger.io">
   <img src="https://user-images.githubusercontent.com/4244251/184881133-79ee9c3c-8165-4852-958e-31687b9536f4.png" alt="Honeybadger" height="55px">
 </a>
+<a href="https://coderabbit.ai">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://victorious-bubble-f69a016683.media.strapiapp.com/White_Typemark_7229870ac5.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://victorious-bubble-f69a016683.media.strapiapp.com/Orange_Typemark_7958cfa790.svg">
+    <img alt="CodeRabbit" src="https://victorious-bubble-f69a016683.media.strapiapp.com/Orange_Typemark_7958cfa790.svg" height="55px">
+  </picture>
+</a>