shakapacker 9.3.0 → 9.3.1

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)
@@ -673,47 +673,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 +732,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 +841,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 +851,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
 

data/docs/api-reference.md

@@ -0,0 +1,519 @@
+# Shakapacker API Reference
+
+This document provides a comprehensive reference for Shakapacker's public Ruby API. For JavaScript/webpack configuration, see [Webpack Configuration](./webpack-configuration.md).
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Main Module: Shakapacker](#main-module-shakapacker)
+- [Configuration API](#configuration-api)
+- [View Helpers](#view-helpers)
+- [Manifest API](#manifest-api)
+- [Dev Server API](#dev-server-api)
+- [Compiler API](#compiler-api)
+- [Advanced Usage](#advanced-usage)
+
+## Overview
+
+Shakapacker provides a Ruby API for integrating webpack/rspack with Rails applications. The API is divided into several key areas:
+
+- **Configuration**: Access to `config/shakapacker.yml` settings
+- **View Helpers**: Rails helpers for rendering script/link tags
+- **Manifest**: Asset lookup and resolution
+- **Compilation**: Programmatic asset compilation
+- **Dev Server**: Development server status and management
+
+### What's Public API?
+
+Methods and classes marked with `@api public` in the source code are considered stable public API. Other methods may change between minor versions.
+
+## Main Module: Shakapacker
+
+The `Shakapacker` module provides singleton-style access to all major functionality.
+
+### Configuration Access
+
+```ruby
+# Get the configuration object
+Shakapacker.config
+# => #<Shakapacker::Configuration>
+
+# Access configuration values
+Shakapacker.config.source_path
+# => #<Pathname:/path/to/app/javascript>
+
+Shakapacker.config.public_output_path
+# => "packs"
+```
+
+### Compilation
+
+```ruby
+# Compile all packs
+Shakapacker.compile
+# => true
+
+# Check if compilation is needed
+Shakapacker.compiler.stale?
+# => false
+
+# Get compiler output
+Shakapacker.compiler.compile
+```
+
+### Manifest Lookup
+
+```ruby
+# Look up compiled asset path
+Shakapacker.manifest.lookup("application.js")
+# => "/packs/application-abc123.js"
+
+# Look up with error if not found
+Shakapacker.manifest.lookup!("application.js")
+# => "/packs/application-abc123.js" (or raises Shakapacker::Manifest::MissingEntryError)
+```
+
+### Dev Server Status
+
+```ruby
+# Check if dev server is running
+Shakapacker.dev_server.running?
+# => true
+
+# Get dev server host
+Shakapacker.dev_server.host
+# => "localhost"
+
+# Get dev server port
+Shakapacker.dev_server.port
+# => 3035
+```
+
+### Environment Management
+
+```ruby
+# Get current environment
+Shakapacker.env
+# => #<ActiveSupport::StringInquirer "development">
+
+# Temporarily use different NODE_ENV
+Shakapacker.with_node_env("production") do
+  Shakapacker.compile
+end
+```
+
+### Logging
+
+```ruby
+# Access logger
+Shakapacker.logger
+# => #<Logger>
+
+# Redirect to STDOUT temporarily
+Shakapacker.ensure_log_goes_to_stdout do
+  Shakapacker.compile
+end
+```
+
+## Configuration API
+
+The `Shakapacker::Configuration` class provides access to all settings from `config/shakapacker.yml`.
+
+### Accessing Configuration Data
+
+```ruby
+config = Shakapacker.config
+
+# Get raw configuration hash (public API as of v9.1.0)
+config.data
+# => { "source_path" => "app/javascript", ... }
+
+# Access specific values
+config.data["source_path"]
+# => "app/javascript"
+```
+
+**See Also:** [Configuration Guide](./configuration.md) for all available options.
+
+### Path Configuration
+
+```ruby
+# Source paths
+config.source_path          # => #<Pathname:/app/app/javascript>
+config.source_entry_path    # => #<Pathname:/app/app/javascript/packs>
+config.additional_paths     # => [#<Pathname:/app/app/assets>, ...]
+
+# Output paths
+config.public_path          # => #<Pathname:/app/public>
+config.public_output_path   # => "packs"
+config.public_manifest_path # => #<Pathname:/app/public/packs/manifest.json>
+```
+
+### Bundler Detection
+
+```ruby
+# Check which bundler is configured
+config.webpack?   # => true
+config.rspack?    # => false
+config.bundler    # => "webpack"
+
+# Get bundler config path
+config.assets_bundler_config_path
+# => #<Pathname:/app/config/webpack/webpack.config.js>
+```
+
+### Compilation Settings
+
+```ruby
+config.compile?              # => true (auto-compile enabled?)
+config.cache_manifest?       # => false
+config.extract_css?          # => false (use MiniCssExtractPlugin?)
+config.nested_entries?       # => false
+```
+
+### Dev Server Configuration
+
+```ruby
+dev_server = config.dev_server
+dev_server["host"]           # => "localhost"
+dev_server["port"]           # => 3035
+dev_server["hmr"]            # => true
+dev_server["https"]          # => false
+```
+
+## View Helpers
+
+Shakapacker provides Rails view helpers in the `Shakapacker::Helper` module, automatically included in ActionView.
+
+### JavaScript Pack Tag
+
+```ruby
+# Basic usage
+<%= javascript_pack_tag 'application' %>
+# => <script src="/packs/application-abc123.js" defer></script>
+
+# Multiple packs (handles chunk deduplication)
+<%= javascript_pack_tag 'calendar', 'map' %>
+
+# Custom attributes
+<%= javascript_pack_tag 'application', 'data-turbo-track': 'reload' %>
+
+# Async loading
+<%= javascript_pack_tag 'application', async: true %>
+
+# Disable defer
+<%= javascript_pack_tag 'application', defer: false %>
+
+# Early hints configuration
+<%= javascript_pack_tag 'application', early_hints: 'preload' %>
+<%= javascript_pack_tag 'application', early_hints: false %>
+```
+
+**Important:** Call `javascript_pack_tag` only once per page to avoid duplicate chunks.
+
+### Stylesheet Pack Tag
+
+```ruby
+# Basic usage
+<%= stylesheet_pack_tag 'application' %>
+# => <link rel="stylesheet" href="/packs/application-abc123.css">
+
+# Multiple packs with attributes
+<%= stylesheet_pack_tag 'application', 'calendar', media: 'screen' %>
+
+# Early hints
+<%= stylesheet_pack_tag 'application', early_hints: 'preload' %>
+```
+
+### Dynamic Pack Loading
+
+```ruby
+# In view or partial - queue packs
+<% append_javascript_pack_tag 'calendar' %>
+<% append_stylesheet_pack_tag 'calendar' %>
+
+# Prepend to queue
+<% prepend_javascript_pack_tag 'critical' %>
+
+# In layout - render all queued packs
+<%= javascript_pack_tag 'application' %>
+<%= stylesheet_pack_tag 'application' %>
+```
+
+### Asset Helpers
+
+```ruby
+# Get pack path
+<%= asset_pack_path 'logo.svg' %>
+# => "/packs/logo-abc123.svg"
+
+# Get pack URL
+<%= asset_pack_url 'logo.svg' %>
+# => "https://cdn.example.com/packs/logo-abc123.svg"
+
+# Image pack tag
+<%= image_pack_tag 'logo.png', size: '16x10', alt: 'Logo' %>
+# => <img src="/packs/logo-abc123.png" width="16" height="10" alt="Logo">
+
+# With srcset
+<%= image_pack_tag 'photo.png', srcset: { 'photo-2x.png' => '2x' } %>
+
+# Favicon
+<%= favicon_pack_tag 'icon.png', rel: 'apple-touch-icon' %>
+
+# Preload asset
+<%= preload_pack_asset 'fonts/custom.woff2' %>
+```
+
+## Manifest API
+
+The `Shakapacker::Manifest` class handles asset lookup from the compiled manifest.
+
+### Basic Lookup
+
+```ruby
+manifest = Shakapacker.manifest
+
+# Look up an asset (returns nil if not found)
+manifest.lookup("application.js")
+# => "/packs/application-abc123.js"
+
+# Look up with error on missing
+manifest.lookup!("application.js")
+# => "/packs/application-abc123.js" (raises if missing)
+```
+
+### Lookup with Type
+
+```ruby
+# Lookup stylesheets
+manifest.lookup("application.css")
+# => "/packs/application-abc123.css"
+
+# Lookup images
+manifest.lookup("logo.svg")
+# => "/packs/static/logo-abc123.svg"
+```
+
+### Full Manifest Access
+
+```ruby
+# Get all entries
+manifest.data
+# => { "application.js" => "/packs/application-abc123.js", ... }
+
+# Refresh manifest from disk
+manifest.refresh
+```
+
+## Dev Server API
+
+The `Shakapacker::DevServer` class provides status and configuration for the development server.
+
+### Status Checking
+
+```ruby
+dev_server = Shakapacker.dev_server
+
+# Check if running
+dev_server.running?
+# => true
+
+# Get full status URL
+dev_server.status_url
+# => "http://localhost:3035"
+```
+
+### Configuration
+
+```ruby
+dev_server.host
+# => "localhost"
+
+dev_server.port
+# => 3035
+
+dev_server.https?
+# => false
+
+dev_server.hmr?
+# => true
+```
+
+### Proxying
+
+```ruby
+# Get asset URL (uses dev server if running, otherwise public path)
+dev_server.asset_url("application.js")
+# => "http://localhost:3035/packs/application.js" (or "/packs/application.js")
+```
+
+## Compiler API
+
+The `Shakapacker::Compiler` class handles compilation of webpack/rspack assets.
+
+### Compilation
+
+```ruby
+compiler = Shakapacker.compiler
+
+# Compile all packs
+compiler.compile
+# => true
+
+# Check if compilation needed
+compiler.stale?
+# => false
+
+# Get last compilation time
+compiler.last_compilation_digest
+# => "abc123..."
+```
+
+### Configuration
+
+```ruby
+# Get watched paths
+compiler.watched_paths
+# => [#<Pathname:/app/app/javascript>, ...]
+
+# Get config files
+compiler.config_files
+# => [#<Pathname:/app/config/webpack/webpack.config.js>, ...]
+```
+
+## Advanced Usage
+
+### Multiple Shakapacker Instances
+
+For advanced scenarios like Rails engines with separate webpack configs:
+
+```ruby
+# Create custom instance
+custom_instance = Shakapacker::Instance.new(
+  root_path: Rails.root,
+  config_path: Rails.root.join("config/custom_shakapacker.yml")
+)
+
+# Use in view helper
+def current_shakapacker_instance
+  @custom_instance ||= Shakapacker::Instance.new(...)
+end
+```
+
+### Testing
+
+```ruby
+# In tests, you can stub the instance
+RSpec.describe "my feature" do
+  let(:mock_manifest) { instance_double(Shakapacker::Manifest) }
+  let(:mock_instance) { instance_double(Shakapacker::Instance, manifest: mock_manifest) }
+
+  before do
+    allow(Shakapacker).to receive(:instance).and_return(mock_instance)
+  end
+end
+```
+
+### Programmatic Configuration Access
+
+```ruby
+# Access raw configuration for custom tooling
+config_data = Shakapacker.config.data
+
+# Use in custom rake task
+namespace :assets do
+  task :analyze do
+    config = Shakapacker.config
+    puts "Source: #{config.source_path}"
+    puts "Output: #{config.public_output_path}"
+    puts "Bundler: #{config.bundler}"
+  end
+end
+```
+
+### Custom Webpack Configuration
+
+Access Shakapacker config from your webpack config:
+
+```javascript
+// config/webpack/webpack.config.js
+const { generateWebpackConfig } = require("shakapacker")
+
+// The shakapacker.yml is automatically loaded
+const config = generateWebpackConfig()
+
+console.log(config.output.path) // Uses public_output_path from shakapacker.yml
+```
+
+## Environment Variables
+
+Shakapacker respects these environment variables:
+
+| Variable                     | Purpose                       | Example                   |
+| ---------------------------- | ----------------------------- | ------------------------- |
+| `SHAKAPACKER_CONFIG`         | Custom config file path       | `/custom/shakapacker.yml` |
+| `SHAKAPACKER_PRECOMPILE`     | Enable/disable precompilation | `false`                   |
+| `SHAKAPACKER_ASSET_HOST`     | CDN hostname                  | `https://cdn.example.com` |
+| `SHAKAPACKER_ASSETS_BUNDLER` | Override bundler selection    | `rspack`                  |
+| `RAILS_ENV`                  | Rails environment             | `production`              |
+| `NODE_ENV`                   | Node environment              | `production`              |
+
+## Error Handling
+
+```ruby
+# Manifest lookup errors
+begin
+  path = Shakapacker.manifest.lookup!("missing.js")
+rescue Shakapacker::Manifest::MissingEntryError => e
+  Rails.logger.error "Missing pack: #{e.message}"
+end
+
+# Compilation errors
+begin
+  Shakapacker.compiler.compile
+rescue Shakapacker::Compiler::CompilationError => e
+  Rails.logger.error "Compilation failed: #{e.message}"
+end
+
+# Configuration errors
+begin
+  config = Shakapacker::Configuration.new(...)
+rescue Shakapacker::Configuration::InvalidConfigurationError => e
+  Rails.logger.error "Invalid config: #{e.message}"
+end
+```
+
+## Deprecations
+
+Shakapacker follows semantic versioning. Deprecated methods will:
+
+1. Issue warnings in the current major version
+2. Be removed in the next major version
+
+Check the [CHANGELOG](../CHANGELOG.md) for deprecation notices.
+
+## See Also
+
+- [Configuration Guide](./configuration.md) - All `shakapacker.yml` options
+- [View Helpers](../README.md#view-helpers) - Detailed view helper usage
+- [Webpack Configuration](../README.md#webpack-configuration) - JavaScript API
+- [TypeScript](./typescript.md) - Type definitions for Shakapacker
+- [Troubleshooting](./troubleshooting.md) - Common issues
+
+## Generating Full API Documentation
+
+For complete API documentation with all methods and parameters:
+
+```bash
+# Using YARD (recommended)
+gem install yard
+yard doc
+yard server  # View at http://localhost:8808
+
+# Using RDoc
+rdoc lib/
+open doc/index.html
+```
+
+The generated documentation includes all public and private methods with detailed parameter descriptions.