Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,13 @@ Changes since the last non-beta release.
- **Config count validation for build outputs**. [PR #752](https://github.com/shakacode/shakapacker/pull/752) by [justin808](https://github.com/justin808). Validates webpack/rspack config array length matches `outputs` array with clear error messages and suggested fixes.
- **`precompile_hook` configuration option** to run custom commands during asset precompilation. [PR #678](https://github.com/shakacode/shakapacker/pull/678) by [justin808](https://github.com/justin808). Configure in `shakapacker.yml` with `precompile_hook: "command to run"`.
- **`assets_bundler_config_path` configuration option** for custom bundler config locations. [PR #710](https://github.com/shakacode/shakapacker/pull/710) by [justin808](https://github.com/justin808). Allows specifying a custom path for webpack/rspack configuration files.
- **YAML output format support for `bin/export-bundler-config`**. [PR #704](https://github.com/shakacode/shakapacker/pull/704) by [justin808](https://github.com/justin808). New `--format yaml` option exports bundler configuration as YAML.
- **YAML output format support for `bin/shakapacker-config`** (formerly `bin/export-bundler-config`). [PR #704](https://github.com/shakacode/shakapacker/pull/704) by [justin808](https://github.com/justin808). New `--format yaml` option exports bundler configuration as YAML.
- **Plugin names displayed in YAML config export**. [PR #750](https://github.com/shakacode/shakapacker/pull/750) by [justin808](https://github.com/justin808). Shows plugin constructor names in exported configuration to help identify which plugins are active.
- **Custom help messages for `bin/shakapacker` commands**. [PR #702](https://github.com/shakacode/shakapacker/pull/702) by [justin808](https://github.com/justin808). Improved help output for better command discoverability with clear usage examples.
- **HMR client config export in doctor mode**. [PR #701](https://github.com/shakacode/shakapacker/pull/701) by [justin808](https://github.com/justin808). `bin/export-bundler-config --doctor` now includes HMR client configuration to help debug Hot Module Replacement issues.
- **HMR client config export in doctor mode**. [PR #701](https://github.com/shakacode/shakapacker/pull/701) by [justin808](https://github.com/justin808). `bin/shakapacker-config --doctor` now includes HMR client configuration to help debug Hot Module Replacement issues.
- **Build timing logs** for webpack and rspack. [PR #706](https://github.com/shakacode/shakapacker/pull/706) by [justin808](https://github.com/justin808). Shows duration of build operations to help identify performance bottlenecks.
- **Named build configurations with `--build` flag**. [PR #728](https://github.com/shakacode/shakapacker/pull/728) by [justin808](https://github.com/justin808). Allows specifying custom build configurations like `bin/shakapacker --build=production` or `bin/shakapacker --build=test`.
- **Build validation in `bin/export-bundler-config`**. [PR #717](https://github.com/shakacode/shakapacker/pull/717) by [justin808](https://github.com/justin808). Validates webpack/rspack configuration before export to catch errors early.
- **Build validation in `bin/shakapacker-config`**. [PR #717](https://github.com/shakacode/shakapacker/pull/717) by [justin808](https://github.com/justin808). Validates webpack/rspack configuration before export to catch errors early.
- **Backward compatibility for rspack config in `config/webpack/`**. [PR #734](https://github.com/shakacode/shakapacker/pull/734) by [justin808](https://github.com/justin808). Rspack configurations can now be placed in `config/webpack/` directory for easier migration.
- **Merge option for WebpackAssetsManifestPlugin**. [PR #760](https://github.com/shakacode/shakapacker/pull/760) by [justin808](https://github.com/justin808). Adds `merge` option to control manifest merging behavior, useful for multi-compiler setups.
- Support for esbuild-loader v5. [PR #758](https://github.com/shakacode/shakapacker/pull/758) by [justin808](https://github.com/justin808).
Expand All @@ -62,7 +62,7 @@ Changes since the last non-beta release.
### Added

- **New config export utility for debugging webpack/rspack configurations** [PR #647](https://github.com/shakacode/shakapacker/pull/647) by [justin808](https://github.com/justin808).
- Adds `bin/export-bundler-config` utility with three modes:
- Adds `bin/shakapacker-config` utility (originally named `bin/export-bundler-config`, renamed in PR #728) with three modes:
- **Doctor mode** (`--doctor`): Exports all configs (dev + prod, client + server) to `shakapacker-config-exports/` directory - best for troubleshooting
- **Save mode** (`--save`): Export current environment configs to files
- **Stdout mode** (default): View configs in terminal
Expand All @@ -74,7 +74,7 @@ Changes since the last non-beta release.
- Validates bundler value and output paths
- Sanitizes filenames to prevent path traversal
- Helpful `.gitignore` suggestions
- **Usage:** `bin/export-bundler-config --doctor` or `bundle exec rake shakapacker:export_bundler_config`
- **Usage:** `bin/shakapacker-config --doctor` or `bundle exec rake shakapacker:export_bundler_config`
- Works seamlessly with `rake shakapacker:switch_bundler` for comparing webpack vs rspack configs
- Lays groundwork for future config diff feature (tracked in [#667](https://github.com/shakacode/shakapacker/issues/667))

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -809,7 +809,7 @@ Shakapacker provides a powerful utility to export and analyze your webpack/rspac

```bash
# Export all configs for troubleshooting (recommended)
bin/export-bundler-config --doctor
bin/shakapacker-config --doctor

# Or via rake task
bundle exec rake shakapacker:export_bundler_config -- --doctor
Expand Down
4 changes: 2 additions & 2 deletions docs/rspack_migration_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -601,13 +601,13 @@ To compare your webpack and rspack configurations during migration:

```bash
# Export webpack configs before switching
bin/export-bundler-config --doctor
bin/shakapacker-config --doctor

# Switch to rspack
rails shakapacker:switch_bundler rspack --install-deps

# Export rspack configs to compare
bin/export-bundler-config --doctor
bin/shakapacker-config --doctor

# Compare the files in shakapacker-config-exports/
diff shakapacker-config-exports/webpack-production-client.yaml \
Expand Down
42 changes: 21 additions & 21 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo

4. You can also pass additional options to the command to run the webpack-dev-server and start the webpack-dev-server with the option `--debug-shakapacker`

5. **Export your full webpack/rspack configuration for analysis**: Use the `bin/export-bundler-config` utility to export your complete resolved configuration. This is especially helpful for:
5. **Export your full webpack/rspack configuration for analysis**: Use the `bin/shakapacker-config` utility to export your complete resolved configuration. This is especially helpful for:
- **Migrations**: Comparing configurations before and after migrating between webpack and rspack, or between different Shakapacker versions
- **Debugging**: Inspecting the exact configuration webpack/rspack is using, including all merged settings
- **AI Analysis**: Uploading the exported config to ChatGPT or other AI tools for troubleshooting
Expand All @@ -35,7 +35,7 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
rake shakapacker:binstubs

# Export EVERYTHING for troubleshooting (dev + prod, annotated YAML)
bin/export-bundler-config --doctor
bin/shakapacker-config --doctor
# Creates: webpack-development-client.yaml, webpack-development-server.yaml,
# webpack-production-client.yaml, webpack-production-server.yaml
```
Expand All @@ -44,38 +44,38 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo

```bash
# Save current environment configs with auto-generated names
bin/export-bundler-config --save
bin/shakapacker-config --save
# Creates: webpack-development-client.yaml, webpack-development-server.yaml

# Save to specific directory
bin/export-bundler-config --save --save-dir=./debug-configs
bin/shakapacker-config --save --save-dir=./debug-configs

# Export only client config for production
bin/export-bundler-config --save --env=production --client-only
bin/shakapacker-config --save --env=production --client-only
# Creates: webpack-production-client.yaml

# Compare development vs production configs
bin/export-bundler-config --save --save-dir=./configs
bin/shakapacker-config --save --save-dir=./configs
diff configs/webpack-development-client.yaml configs/webpack-production-client.yaml

# View config in terminal (no files created)
bin/export-bundler-config
bin/shakapacker-config

# Export without inline documentation annotations
bin/export-bundler-config --save --no-annotate
bin/shakapacker-config --save --no-annotate

# Export in JSON format for programmatic analysis
bin/export-bundler-config --save --format=json
bin/shakapacker-config --save --format=json
```

**Config files are automatically named:** `{bundler}-{env}-{type}.{ext}`
- Examples: `webpack-development-client.yaml`, `rspack-production-server.yaml`
- YAML format includes inline documentation explaining each config key
- Separate files for client and server bundles (cleaner than combined)

See `bin/export-bundler-config --help` for all available options.
See `bin/shakapacker-config --help` for all available options.

6. **Validate your webpack/rspack builds**: Use `bin/export-bundler-config --validate` to test that all your build configurations compile successfully. This is especially useful for:
6. **Validate your webpack/rspack builds**: Use `bin/shakapacker-config --validate` to test that all your build configurations compile successfully. This is especially useful for:
- **CI/CD pipelines**: Catch configuration errors before deployment
- **Migration testing**: Verify builds work after upgrading webpack, rspack, or Shakapacker
- **Multi-environment testing**: Ensure all build configurations (dev, prod, HMR) compile correctly
Expand All @@ -84,13 +84,13 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo

```bash
# Validate all builds defined in .bundler-config.yml
bin/export-bundler-config --validate
bin/shakapacker-config --validate

# Validate with full output logs (shows all webpack/rspack compilation output)
bin/export-bundler-config --validate --verbose
bin/shakapacker-config --validate --verbose

# Validate a specific build
bin/export-bundler-config --validate-build=dev-hmr
bin/shakapacker-config --validate-build=dev-hmr
```

**Verbose Mode:**
Expand All @@ -108,13 +108,13 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo

```bash
# Create a .bundler-config.yml file with example builds
bin/export-bundler-config --init
bin/shakapacker-config --init

# List all available builds
bin/export-bundler-config --list-builds
bin/shakapacker-config --list-builds

# Validate all builds
bin/export-bundler-config --validate
bin/shakapacker-config --validate
```

**Advanced options:**
Expand Down Expand Up @@ -177,9 +177,9 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
💡 Debugging Tips:
To get more details, run individual builds with --verbose:

bin/export-bundler-config --validate-build prod --verbose
bin/shakapacker-config --validate-build prod --verbose

Or validate all builds with full output: bin/export-bundler-config --validate --verbose
Or validate all builds with full output: bin/shakapacker-config --validate --verbose
================================================================================
```

Expand All @@ -189,13 +189,13 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
1. **Run a specific build with verbose output** to see full webpack/rspack logs:

```bash
bin/export-bundler-config --validate-build prod --verbose
bin/shakapacker-config --validate-build prod --verbose
```

2. **Validate all builds with verbose output** to see everything:

```bash
bin/export-bundler-config --validate --verbose
bin/shakapacker-config --validate --verbose
```

3. **Test individual builds manually** using the same configuration:
Expand Down
8 changes: 4 additions & 4 deletions lib/shakapacker/doctor.rb
Original file line number Diff line number Diff line change
Expand Up @@ -391,7 +391,7 @@ def check_binstub
expected_binstubs = {
"bin/shakapacker" => "Main Shakapacker binstub",
"bin/shakapacker-dev-server" => "Development server binstub",
"bin/export-bundler-config" => "Config export binstub"
"bin/shakapacker-config" => "Config export binstub"
}

expected_binstubs.each do |path, description|
Expand Down Expand Up @@ -1013,7 +1013,7 @@ def print_binstub_status
binstubs = [
"bin/shakapacker",
"bin/shakapacker-dev-server",
"bin/export-bundler-config"
"bin/shakapacker-config"
]

existing_binstubs = binstubs.select { |b| doctor.root_path.join(b).exist? }
Expand Down Expand Up @@ -1171,10 +1171,10 @@ def print_fix_instructions
puts " #{package_manager_install_command(package_manager)}"
puts ""
puts "For debugging configuration issues, export your webpack/rspack config:"
puts " bin/export-bundler-config --doctor"
puts " bin/shakapacker-config --doctor"
puts " (Exports annotated YAML configs for dev and production - best for troubleshooting)"
puts ""
puts " See 'bin/export-bundler-config --help' for more options"
puts " See 'bin/shakapacker-config --help' for more options"
end

def package_manager_install_command(manager)
Expand Down
2 changes: 1 addition & 1 deletion lib/tasks/shakapacker/doctor.rake
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ namespace :shakapacker do
• Required and optional npm dependencies
• JavaScript transpiler (Babel, SWC, esbuild) configuration
• CSS, CSS Modules, and stylesheet preprocessor setup
• Binstubs presence (shakapacker, shakapacker-dev-server, export-bundler-config)
• Binstubs presence (shakapacker, shakapacker-dev-server, shakapacker-config)
• Version consistency between gem and npm package
• Legacy Webpacker file detection

Expand Down
8 changes: 4 additions & 4 deletions lib/tasks/shakapacker/export_bundler_config.rake
Original file line number Diff line number Diff line change
Expand Up @@ -42,18 +42,18 @@ namespace :shakapacker do
Note: When using 'rake', you must use '--' to separate rake options from task arguments.
Example: rake shakapacker:export_bundler_config -- --doctor

The task automatically falls back to the gem version if bin/export-bundler-config
The task automatically falls back to the gem version if bin/shakapacker-config
binstub is not installed. To install all binstubs, run: rails shakapacker:binstubs
DESC
task :export_bundler_config do
# Try to use the binstub if it exists, otherwise use the gem's version
bin_path = Rails.root.join("bin/export-bundler-config")
bin_path = Rails.root.join("bin/shakapacker-config")

unless File.exist?(bin_path)
# Binstub not installed, use the gem's version directly
gem_bin_path = File.expand_path("../../install/bin/export-bundler-config", __dir__)
gem_bin_path = File.expand_path("../../install/bin/shakapacker-config", __dir__)

$stderr.puts "Note: bin/export-bundler-config binstub not found."
$stderr.puts "Note: bin/shakapacker-config binstub not found."
$stderr.puts "Using gem version directly. To install the binstub, run: rake shakapacker:binstubs"
$stderr.puts ""

Expand Down
2 changes: 1 addition & 1 deletion package/configExporter/cli.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// This will be a substantial file - the main CLI entry point
// Migrating from bin/export-bundler-config but streamlined for TypeScript
// Originally migrated from bin/export-bundler-config, now bin/shakapacker-config

import { existsSync, readFileSync, writeFileSync } from "fs"
import { resolve, dirname, sep, delimiter, basename } from "path"
Expand Down
8 changes: 4 additions & 4 deletions spec/shakapacker/doctor_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -678,7 +678,7 @@ def warning_messages
describe "binstub checks" do
let(:binstub_path) { root_path.join("bin/shakapacker") }
let(:dev_server_binstub_path) { root_path.join("bin/shakapacker-dev-server") }
let(:export_config_binstub_path) { root_path.join("bin/export-bundler-config") }
let(:export_config_binstub_path) { root_path.join("bin/shakapacker-config") }

context "when all binstubs exist" do
before do
Expand Down Expand Up @@ -707,7 +707,7 @@ def warning_messages
end
end

context "when export-bundler-config binstub does not exist" do
context "when shakapacker-config binstub does not exist" do
before do
FileUtils.mkdir_p(binstub_path.dirname)
File.write(binstub_path, "#!/usr/bin/env ruby")
Expand All @@ -716,14 +716,14 @@ def warning_messages

it "adds missing binstubs warning" do
doctor.send(:check_binstub)
expect(warning_messages).to include(match(/Missing binstubs:.*bin\/export-bundler-config/))
expect(warning_messages).to include(match(/Missing binstubs:.*bin\/shakapacker-config/))
end
end

context "when no binstubs exist" do
it "adds missing binstubs warning for all three" do
doctor.send(:check_binstub)
expect(warning_messages).to include(match(/Missing binstubs:.*bin\/shakapacker.*bin\/shakapacker-dev-server.*bin\/export-bundler-config/))
expect(warning_messages).to include(match(/Missing binstubs:.*bin\/shakapacker.*bin\/shakapacker-dev-server.*bin\/shakapacker-config/))
end
end
end
Expand Down