shakapacker 9.6.0.beta.0 → 9.6.0.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16a87e8e339c085afc34f5f70af6fee7aa534590949f02faa1863d9c5e7f9f7d
-  data.tar.gz: 19d1f859e00dc29bfe4c593ba1b4a1e5b64c6347fc1b56a2cbabcc8c8020205b
+  metadata.gz: 68ba8fdde7f793bee53354a639cf21695963ff564e3478de1e19711f9e71704d
+  data.tar.gz: f5baa408e07f17e89cb0ba19abe652a4eeba151400b5014b4381156221e25811
 SHA512:
-  metadata.gz: f4286284b7cbbec5324ce2ad26c6d6892cfcecae96e31c7324ff0a533f332301b4008e7083592b3b4b639be131758ab6fa5bc81ed46ac0903f2370f20a05fae0
-  data.tar.gz: e4e6bfdd5837dabfd9f5d031e5a1d905ca88b6c1d50b1f3d440fb3f3c6a23d0abbec1d8839a769536af52d67eed5657ec602786c824dd57156f1678026ec300e
+  metadata.gz: 3845c0fd8e02339a077dd2a385bc2ed32905e62f56f786177c5761ddca3fab1b521bb92aeb1469458657cb139273137079a33e1ebbffba9574cf1e192e56fac2
+  data.tar.gz: 81d6113206160b9184bc1a0016cbe52d0c0ee565cd951da3b613ae99dd58ea83279d6ee60bfa6be8f14a2d524900941ed7568c8169ba2d855a9734c856260cc3

data/.github/workflows/claude-code-review.yml

@@ -3,31 +3,20 @@ name: Claude Code Review
 on:
   pull_request:
     types: [opened, synchronize, ready_for_review, reopened]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
 
 jobs:
   claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
-
+    if: github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pull-requests: read
-      issues: read
+      pull-requests: write
+      issues: write
       id-token: write
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 
@@ -36,9 +25,21 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
-          plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://code.claude.com/docs/en/cli-reference for available options
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Please review this pull request with a focus on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Security implications
+            - Performance considerations
+
+            Note: The PR branch is already checked out in the current working directory.
+
+            Use `gh pr comment` for top-level feedback.
+            Use `mcp__github_inline_comment__create_inline_comment` to highlight specific code issues.
+            Only post GitHub comments - don't submit review text as messages.
 
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

data/.github/workflows/claude.yml

@@ -24,6 +24,8 @@ jobs:
       issues: read
       id-token: write
       actions: read # Required for Claude to read CI results on PRs
+      checks: read
+      statuses: read
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -34,11 +36,14 @@ jobs:
         id: claude
         uses: anthropics/claude-code-action@v1
         with:
+          github_token: ${{ github.token }}
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 
           # This is an optional setting that allows Claude to read CI results on PRs
           additional_permissions: |
             actions: read
+            checks: read
+            statuses: read
 
           # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
           # prompt: 'Update the pull request description to include a summary of changes.'

data/CHANGELOG.md

@@ -11,8 +11,34 @@
 
 Changes since the last non-beta release.
 
+## [v9.6.0-rc.0] - March 5, 2026
+
+### Security
+
+- Removed default `Access-Control-Allow-Origin: *` header from dev server configuration. This header allowed any website to access dev server resources. **If your setup runs webpack-dev-server on a different port from your Rails server, uncomment the `headers` section in `config/shakapacker.yml` to restore cross-origin asset loading.** [PR #936](https://github.com/shakacode/shakapacker/pull/936) by [justin808](https://github.com/justin808). Fixes [#935](https://github.com/shakacode/shakapacker/issues/935).
+
+### Added
+
+- **Added `SKIP=true` installer mode to preserve existing files**. [PR #926](https://github.com/shakacode/shakapacker/pull/926) by [justin808](https://github.com/justin808). Running `rails shakapacker:install SKIP=true` now skips conflicting files instead of overwriting them. This is useful for CI/CD pipelines and automated setups where you want to install only missing files without touching existing configuration.
+- **Export bundler utility functions for Webpack/Rspack compatibility**. [PR #922](https://github.com/shakacode/shakapacker/pull/922) by [justin808](https://github.com/justin808). New utility functions that make it easier to write bundler-agnostic configuration code: `isRspack`, `isWebpack`, `getBundler()`, `getCssExtractPlugin()`, `getCssExtractPluginLoader()`, `getDefinePlugin()`, `getEnvironmentPlugin()`, and `getProvidePlugin()`. Users no longer need to write conditional logic to handle differences between Webpack and Rspack.
+
+  ```javascript
+  // Before: manual conditional logic
+  const { config } = require("shakapacker")
+  const CssPlugin =
+    config.assets_bundler === "rspack"
+      ? require("@rspack/core").CssExtractRspackPlugin
+      : require("mini-css-extract-plugin")
+
+  // After: use bundler utilities
+  const { getCssExtractPlugin } = require("shakapacker")
+  const CssPlugin = getCssExtractPlugin()
+  ```
+
 ### Changed
 
+- **Changed default file rule type from `asset/resource` to `asset`**. [PR #901](https://github.com/shakacode/shakapacker/pull/901) by [justin808](https://github.com/justin808). Static assets (images, fonts, SVGs) now use webpack/rspack's `asset` type instead of `asset/resource`, allowing the bundler to automatically inline small files as data URIs for better performance.
+- Allow `compression-webpack-plugin` v12. [PR #937](https://github.com/shakacode/shakapacker/pull/937) by [G-Rath](https://github.com/G-Rath).
 - **BREAKING: sass-loader now defaults to modern Sass API**. [PR #879](https://github.com/shakacode/shakapacker/pull/879) by [justin808](https://github.com/justin808). The sass-loader configuration now uses `api: "modern"` instead of the deprecated legacy API. This improves compatibility with plugins like sass-resources-loader that require the modern API. If you experience issues after upgrading, you can revert to the legacy API by customizing your webpack config:
 
   ```javascript
@@ -36,9 +62,17 @@ Changes since the last non-beta release.
 
 ### Fixed
 
+- **Fixed hidden dotfiles and dot-directories being treated as entrypoints**. [PR #915](https://github.com/shakacode/shakapacker/pull/915) by [justin808](https://github.com/justin808). Entry discovery now ignores files and directories whose names start with `.` when traversing `source_entry_path`, preventing unintended bundles from being created. Closes [#853](https://github.com/shakacode/shakapacker/issues/853).
 - **Fixed orphaned webpack/rspack processes when foreman receives SIGTERM**. [PR #888](https://github.com/shakacode/shakapacker/pull/888) by [jordan-brough](https://github.com/jordan-brough). When running under foreman, sending SIGTERM to foreman (e.g. `kill <pid>`) would kill the Ruby shakapacker process but leave the webpack/rspack child process running as an orphan. DevServerRunner now uses `exec` to replace the Ruby process entirely, and Runner uses `spawn` with SIGTERM forwarding to ensure the child process is properly terminated.
+- **Fixed missing-environment fallback to use production instead of development**. [PR #894](https://github.com/shakacode/shakapacker/pull/894) by [justin808](https://github.com/justin808). When a Rails environment (e.g., staging) is not defined in `shakapacker.yml`, Shakapacker now falls back to the `production` configuration instead of `development`. This ensures unknown environments get production-optimized webpack/rspack builds by default.
 - **Fixed installer writing wrong shakapacker version in package.json**. [PR #899](https://github.com/shakacode/shakapacker/pull/899) by [justin808](https://github.com/justin808). The `shakapacker:install` generator now keeps the `package.json` dependency value in sync with the exact version or path that was requested, instead of relying on the post-install value which could differ.
+- **Fixed `privateOutputPath` not being computed in JavaScript config**. [PR #891](https://github.com/shakacode/shakapacker/pull/891) by [ihabadham](https://github.com/ihabadham). The `private_output_path` setting from `shakapacker.yml` is now properly resolved to an absolute path and exposed as `privateOutputPath` in the JavaScript configuration, matching the behavior already present in the Ruby configuration.
+- **Fixed installer not updating `shakapacker.yml` when selecting a non-default transpiler**. [PR #895](https://github.com/shakacode/shakapacker/pull/895) by [codex-rs](https://github.com/apps/codex-rs). Installing with `JAVASCRIPT_TRANSPILER=babel` (or `esbuild`) now correctly updates `config/shakapacker.yml` to match the selected transpiler instead of leaving it set to `swc`. Previously, a quote mismatch in the `gsub_file` call meant the config was never actually updated, and the condition also excluded `JAVASCRIPT_TRANSPILER=babel` from the update entirely. Additionally, `JAVASCRIPT_TRANSPILER=babel` no longer installs SWC packages.
+- **Fixed ENOENT crash on clean builds when using `webpack-assets-manifest` v6 with `merge: true`**. [PR #931](https://github.com/shakacode/shakapacker/pull/931) by [justin808](https://github.com/justin808). Seeds an empty `{}` manifest file before instantiating the plugin, so the merge read succeeds on first build rather than throwing an unhandled ENOENT.
+- **Improved error message when manifest is empty or missing**. [PR #872](https://github.com/shakacode/shakapacker/pull/872) by [justin808](https://github.com/justin808). When the bundler is still compiling (empty manifest) or hasn't run yet (missing manifest file), users now see clear, actionable error messages instead of the generic 7-point checklist.
 - **Fixed NODE_ENV=test causing DefinePlugin warnings**. [PR #870](https://github.com/shakacode/shakapacker/pull/870) by [justin808](https://github.com/justin808). When RAILS_ENV=test, Shakapacker now sets NODE_ENV=development instead of NODE_ENV=test. This prevents webpack/rspack DefinePlugin conflicts since these bundlers only recognize "development" and "production" as valid NODE_ENV values.
+- **Fixed `--json` flag output being corrupted by log messages**. [PR #869](https://github.com/shakacode/shakapacker/pull/869) by [justin808](https://github.com/justin808). When `--json` is in the command arguments, `[Shakapacker]` log messages are now written to stderr instead of stdout, keeping stdout clean for valid JSON output. This allows `bin/shakapacker --profile --json` to be piped to tools like `webpack-bundle-analyzer`. Normal (non-JSON) usage is unchanged. Resolves [#868](https://github.com/shakacode/shakapacker/issues/868).
+- **Require explicit truthy values for `SKIP` and `FORCE` installer env vars**. [PR #926](https://github.com/shakacode/shakapacker/pull/926) by [justin808](https://github.com/justin808). Previously, any set value (including `"false"` or `"0"`) would activate skip/force mode. Now only explicit truthy values (`true`, `1`, `yes`, case-insensitive) are recognized. This behavior change may require CI/scripts that relied on `FORCE=<any non-empty value>` to switch to `FORCE=true`.
 
 ### Documentation
 
@@ -86,7 +120,7 @@ Changes since the last non-beta release.
 
 - **Added `SHAKAPACKER_SKIP_PRECOMPILE_HOOK` environment variable to skip precompile hook**. [PR #850](https://github.com/shakacode/shakapacker/pull/850) by [justin808](https://github.com/justin808). Set `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to skip the precompile hook during compilation. This is useful when using process managers like Foreman or Overmind to run the hook once before starting multiple webpack processes, preventing duplicate hook execution. **Migration tip:** If you have a custom `bin/dev` script that starts multiple webpack processes, you can now run the precompile hook once in the script and set this environment variable to prevent each webpack process from running the hook again. See the [precompile hook documentation](./docs/precompile_hook.md#skipping-the-hook) for implementation examples.
 
-## [v9.3.4-beta.0] - November 17, 2025
+## [v9.3.4] - November 17, 2025
 
 ### Fixed
 
@@ -834,10 +868,11 @@ Note: [Rubygem is 6.3.0.pre.rc.1](https://rubygems.org/gems/shakapacker/versions
 
 See [CHANGELOG.md in rails/webpacker (up to v5.4.3)](https://github.com/rails/webpacker/blob/master/CHANGELOG.md)
 
-[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.5.0...main
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.6.0-rc.0...main
+[v9.6.0-rc.0]: https://github.com/shakacode/shakapacker/compare/v9.5.0...v9.6.0-rc.0
 [v9.5.0]: https://github.com/shakacode/shakapacker/compare/v9.4.0...v9.5.0
 [v9.4.0]: https://github.com/shakacode/shakapacker/compare/v9.3.4...v9.4.0
-[v9.3.4-beta.0]: https://github.com/shakacode/shakapacker/compare/v9.3.3...v9.3.4-beta.0
+[v9.3.4]: https://github.com/shakacode/shakapacker/compare/v9.3.3...v9.3.4
 [v9.3.3]: https://github.com/shakacode/shakapacker/compare/v9.3.2...v9.3.3
 [v9.3.2]: https://github.com/shakacode/shakapacker/compare/v9.3.1...v9.3.2
 [v9.3.1]: https://github.com/shakacode/shakapacker/compare/v9.3.0...v9.3.1

data/CLAUDE.md

@@ -40,6 +40,14 @@
 - **Version management**: Run `bundle exec rake update_changelog` after releases to update version headers
 - **Examples**: Run `grep -A 3 "^### " CHANGELOG.md | head -30` to see real formatting examples
 
+## Open Source Maintainability
+
+- **Prefer removing complexity over adding configuration.** If a default causes problems, consider removing the default rather than adding an option to disable it.
+- **Every config option is maintenance surface.** Prefer convention over configuration. Don't add options for <10% of users — let them customize via existing extension points (e.g., custom webpack config).
+- **"No is temporary, yes is forever."** Adding a feature creates a permanent maintenance obligation. Reject features that solve one user's niche problem but add complexity for everyone.
+- **Security-safe defaults over convenient defaults.** Don't ship permissive defaults (e.g., `Access-Control-Allow-Origin: *`) just for convenience — make users opt in to less-secure configurations.
+- **Don't refactor adjacent code in feature PRs.** Keep PRs focused. If you spot something to clean up, do it in a separate PR.
+
 ## Shakapacker-Specific
 
 - This gem supports both webpack and rspack configurations

data/README.md

@@ -166,7 +166,7 @@ Then run the following to install Shakapacker:
 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.
+Before initiating the installation process, ensure you have committed all changes. During install, Shakapacker may encounter conflicts with existing files. You can approve prompts interactively, use `FORCE=true` to overwrite without prompting, or use `SKIP=true` to preserve existing files and only create missing ones. Accepted truthy values are `true`, `1`, and `yes` (case-insensitive). If both are set, `FORCE` takes precedence.
 
 Shakapacker uses the [`package_json`](https://github.com/shakacode/package_json) gem to handle updating the `package.json` and interacting with the underlying package manager of choice for managing dependencies and running commands; the package manager is managed using the [`packageManager`](https://nodejs.org/api/packages.html#packagemanager) property in the `package.json`, otherwise falling back to the value of `PACKAGE_JSON_FALLBACK_MANAGER` if set or otherwise `npm`.
 

data/docs/configuration.md

@@ -362,9 +362,11 @@ dev_server:
     #   pathname: '/ws'
     #   port: 8080
 
-  # Headers for CORS
-  headers:
-    "Access-Control-Allow-Origin": "*"
+  # Custom headers for dev server responses
+  # Uncomment to enable CORS (e.g., when webpack-dev-server runs on a different
+  # port than your Rails server and the browser blocks cross-origin asset requests):
+  # headers:
+  #   "Access-Control-Allow-Origin": "*"
 
   # Static file serving
   static:

data/docs/precompile_hook.md

@@ -35,13 +35,13 @@ before launching long-running processes instead of using `precompile_hook`.
 
 ### Comparison
 
-| Aspect | `precompile_hook` | Explicit setup in `bin/dev` |
-|--------|-------------------|-------------------------------|
-| Best for | Default/consistent pre-build tasks | Custom multi-step dev boot flows |
-| Runs when | Immediately before compilation starts | Wherever you place it in startup script |
-| Production integration | Automatic via `assets:precompile` | Requires explicit production wiring |
-| Process manager complexity | Lower | Higher (you own orchestration) |
-| Debugging | Centralized hook command | Fully explicit command-by-command flow |
+| Aspect                     | `precompile_hook`                     | Explicit setup in `bin/dev`             |
+| -------------------------- | ------------------------------------- | --------------------------------------- |
+| Best for                   | Default/consistent pre-build tasks    | Custom multi-step dev boot flows        |
+| Runs when                  | Immediately before compilation starts | Wherever you place it in startup script |
+| Production integration     | Automatic via `assets:precompile`     | Requires explicit production wiring     |
+| Process manager complexity | Lower                                 | Higher (you own orchestration)          |
+| Debugging                  | Centralized hook command              | Fully explicit command-by-command flow  |
 
 ### `shakapacker_precompile` Interaction
 

data/docs/releasing.md

@@ -9,6 +9,7 @@ This guide is for Shakapacker maintainers who need to publish a new release.
    ```bash
    bundle install              # Installs gem-release
    yarn global add release-it  # Installs release-it for npm publishing
+   gh --version                # Required only if you plan to run sync_github_release
    ```
 
 2. **Ensure you have publishing access:**
@@ -18,6 +19,8 @@ This guide is for Shakapacker maintainers who need to publish a new release.
 3. **Enable 2FA on both platforms:**
    - npm: 2FA is required for publishing
    - RubyGems: 2FA is required for publishing
+4. **If you plan to run `sync_github_release`, authenticate GitHub CLI:**
+   - Run `gh auth login` and ensure your account/token has write access to this repository
 
 ## Release Process
 
@@ -26,9 +29,7 @@ This guide is for Shakapacker maintainers who need to publish a new release.
 Before running the release task:
 
 1. Ensure all desired changes are merged to `main` branch
-2. Update `CHANGELOG.md` with the new version and release notes
-3. Commit the CHANGELOG changes
-4. Ensure your working directory is clean (`git status` shows no uncommitted changes)
+2. Ensure your working directory is clean (`git status` shows no uncommitted changes)
 
 ### 2. Run the Release Task
 
@@ -36,38 +37,89 @@ The automated release task handles the entire release process:
 
 ```bash
 # For a specific version (e.g., 9.1.0)
-bundle exec rake create_release[9.1.0]
+bundle exec rake "create_release[9.1.0]"
 
 # For a beta release (note: use period, not dash)
-bundle exec rake create_release[9.2.0.beta.1]  # Creates npm package 9.2.0-beta.1
+bundle exec rake "create_release[9.2.0.beta.1]"  # Creates npm package 9.2.0-beta.1
+
+# For a release candidate
+bundle exec rake "create_release[9.6.0.rc.0]"
+
+# Auto-calculate next prerelease and confirm before publishing
+bundle exec rake "create_prerelease[9.6.0]"      # defaults to rc -> 9.6.0.rc.0 or 9.6.0.rc.1, etc.
+bundle exec rake "create_prerelease[9.6.0,rc]"   # -> 9.6.0.rc.0 or 9.6.0.rc.1, etc.
+bundle exec rake "create_prerelease[9.6.0,beta]" # -> 9.6.0.beta.0 or 9.6.0.beta.1, etc.
 
 # For a patch version bump (auto-increments)
-bundle exec rake create_release
+bundle exec rake create_release  # prompts to confirm computed patch version
 
 # Dry run to test without publishing
-bundle exec rake create_release[9.1.0,true]
+bundle exec rake "create_release[9.1.0,true]"
+
+# Override version policy checks (monotonic + changelog/bump consistency)
+RELEASE_VERSION_POLICY_OVERRIDE=true bundle exec rake "create_release[9.1.0]"
+bundle exec rake "create_release[9.1.0,false,true]"
 ```
 
+Dry runs use a temporary git worktree so version bumps and installs do not modify your current checkout.
+
+`create_release` and `create_prerelease` validate release-version policy before publishing:
+- Target version must be greater than the latest tagged release.
+- If the versioned target changelog section exists (`## [vX.Y.Z...]`; not `UNRELEASED`), it maps to expected bump type:
+  - Breaking changes => major bump
+  - Added/New Features/Features/Enhancements => minor bump
+  - Fixed/Fixes/Bug Fixes/Security/Improved/Deprecated => patch bump
+  - Other headings => no inferred bump level (consistency check is skipped)
+
+Use override only when needed:
+- `RELEASE_VERSION_POLICY_OVERRIDE=true`
+- Or task arg override (`create_release[..., ..., true]`, `create_prerelease[..., ..., ..., true]`)
+
 ### 3. What the Release Task Does
 
 The `create_release` task automatically:
 
-1. **Pulls latest changes** from the repository
-2. **Bumps version numbers** in:
+1. **Validates release prerequisites**:
+   - Verifies npm authentication
+2. **Pulls latest changes** from the repository
+3. **Bumps version numbers** in:
    - `lib/shakapacker/version.rb` (Ruby gem version)
    - `package.json` (npm package version - converted from Ruby format)
-3. **Publishes to npm:**
+4. **Publishes to npm:**
    - Prompts for npm OTP (2FA code)
    - Creates git tag
    - Pushes to GitHub
-4. **Publishes to RubyGems:**
+5. **Publishes to RubyGems:**
    - Prompts for RubyGems OTP (2FA code)
-5. **Updates spec/dummy lockfiles:**
+6. **Updates spec/dummy lockfiles:**
    - Runs `bundle install` to update `Gemfile.lock`
    - Runs `npm install` to update `package-lock.json` (yarn.lock may also be updated for multi-package-manager compatibility testing)
-6. **Commits and pushes lockfile changes** automatically
+7. **Commits and pushes lockfile changes** automatically
+
+### 4. Sync GitHub Release (Optional, After Publish)
+
+If you want GitHub Releases, do that as a separate step after publishing.
+Requires GitHub CLI (`gh`) with write access to this repository:
+
+Legacy note: `SKIP_GITHUB_RELEASE=true` is no longer used by release tasks. GitHub release creation is now an explicit, separate step via `sync_github_release`.
+
+1. Run `bundle exec rake update_changelog`
+2. Update `CHANGELOG.md` with the published version section
+   - For prerelease entries, use npm semver header format with dashes, for example `## [v9.6.0-rc.1]`
+3. Commit `CHANGELOG.md`
+4. Run:
+
+```bash
+# Stable
+bundle exec rake "sync_github_release[9.6.0]"
+
+# Prerelease
+bundle exec rake "sync_github_release[9.6.0.rc.1]"
+```
+
+`sync_github_release` reads release notes from the matching `CHANGELOG.md` section and creates/updates the GitHub release for the corresponding tag.
 
-### 4. Version Format
+### 5. Version Format
 
 **Important:** Use Ruby gem version format (no dashes):
 
@@ -83,28 +135,35 @@ The task automatically converts Ruby gem format to npm semver format:
 
 ```bash
 # Regular release
-bundle exec rake create_release[9.1.0]  # Gem: 9.1.0, npm: 9.1.0
+bundle exec rake "create_release[9.1.0]"  # Gem: 9.1.0, npm: 9.1.0
 
 # Beta release
-bundle exec rake create_release[9.2.0.beta.1]  # Gem: 9.2.0.beta.1, npm: 9.2.0-beta.1
+bundle exec rake "create_release[9.2.0.beta.1]"  # Gem: 9.2.0.beta.1, npm: 9.2.0-beta.1
 
 # Release candidate
-bundle exec rake create_release[10.0.0.rc.1]  # Gem: 10.0.0.rc.1, npm: 10.0.0-rc.1
+bundle exec rake "create_release[10.0.0.rc.1]"  # Gem: 10.0.0.rc.1, npm: 10.0.0-rc.1
+
+# Auto-next prerelease (recommended)
+bundle exec rake "create_prerelease[10.0.0,rc]"  # picks rc.0 then rc.1, etc., with confirmation
 ```
 
-### 5. During the Release
+The `create_prerelease` task defaults to `rc` if prerelease type is omitted. Use `beta` explicitly when needed.
+
+### 6. During the Release
 
 1. When prompted for **npm OTP**, enter your 2FA code from your authenticator app
 2. Accept defaults for release-it options
 3. When prompted for **RubyGems OTP**, enter your 2FA code
-4. The script will automatically commit and push lockfile updates
+4. If using patch auto-bump (`create_release` with no version), confirm the computed patch version when prompted
+5. If using `create_prerelease`, confirm the computed next prerelease version when prompted
+6. The script will automatically commit and push lockfile updates
 
-### 6. After Release
+### 7. After Release
 
 1. Verify the release on:
    - [npm](https://www.npmjs.com/package/shakapacker)
    - [RubyGems](https://rubygems.org/gems/shakapacker)
-   - [GitHub releases](https://github.com/shakacode/shakapacker/releases)
+   - [GitHub releases](https://github.com/shakacode/shakapacker/releases) if you ran `sync_github_release`
 
 2. Check that the lockfile commit was pushed:
 
@@ -141,6 +200,26 @@ If publishing fails partway through:
 3. If RubyGems failed: Fix the issue and manually run `gem release`
 4. Then manually update and commit spec/dummy lockfiles
 
+### GitHub Release Sync Fails
+
+If package publishing succeeds but `sync_github_release` fails:
+
+1. Fix GitHub auth (`gh auth login`) or permissions
+2. Ensure `CHANGELOG.md` has matching header `## [vX.Y.Z...]` (npm format for prereleases)
+3. Rerun only:
+
+   ```bash
+   bundle exec rake "sync_github_release[<gem_version>]"
+   ```
+
+### Legacy `SKIP_GITHUB_RELEASE` Usage
+
+If your CI or local runbook still sets `SKIP_GITHUB_RELEASE=true`:
+
+1. `create_release` and `create_prerelease` now always skip GitHub release creation by design
+2. Remove `SKIP_GITHUB_RELEASE` from scripts to avoid confusion
+3. Run `sync_github_release` explicitly when you want to create or update a GitHub release
+
 ### Wrong Version Format
 
 If you accidentally use npm format (with dashes):

data/eslint.config.js

@@ -233,6 +233,7 @@ module.exports = [
     // Remaining utils files that need type safety improvements
     // These use dynamic requires and helper functions that return `any`
     files: [
+      "package/utils/bundlerUtils.ts",
       "package/utils/inliningCss.ts",
       "package/utils/errorCodes.ts",
       "package/utils/errorHelpers.ts",

data/lib/install/binstubs.rb

@@ -1,6 +1,10 @@
-force_option = ENV["FORCE"] ? { force: true } : {}
+require "shakapacker/install/env"
+
+# template.rb sets @conflict_option first during normal install flow.
+# ||= keeps binstubs runnable standalone (e.g., rake shakapacker:binstubs).
+@conflict_option ||= Shakapacker::Install::Env.conflict_option
 
 say "Copying binstubs"
-directory "#{__dir__}/bin", "bin", force_option
+directory "#{__dir__}/bin", "bin", @conflict_option
 
 chmod "bin", 0755 & ~File.umask, verbose: false

data/lib/install/config/shakapacker.yml

@@ -161,8 +161,10 @@ development:
     allowed_hosts: "auto"
     # Shows progress and colorizes output of bin/shakapacker[-dev-server]
     pretty: true
-    headers:
-      "Access-Control-Allow-Origin": "*"
+    # Uncomment to enable CORS (e.g., when webpack-dev-server runs on a different
+    # port than your Rails server and the browser blocks cross-origin asset requests):
+    # headers:
+    #   "Access-Control-Allow-Origin": "*"
     static:
       watch:
         ignored: "**/node_modules/**"

data/lib/install/template.rb

@@ -1,13 +1,14 @@
 require "shakapacker/utils/misc"
 require "shakapacker/utils/manager"
 require "shakapacker/utils/version_syntax_converter"
+require "shakapacker/install/env"
 require "package_json"
 require "yaml"
 require "json"
 
 # Install Shakapacker
 
-force_option = ENV["FORCE"] ? { force: true } : {}
+@conflict_option = Shakapacker::Install::Env.conflict_option
 
 # Initialize variables for use throughout the template
 # Using instance variable to avoid method definition issues in Rails templates
@@ -17,33 +18,41 @@ install_dir = File.expand_path(File.dirname(__FILE__))
 # Installation strategy:
 # - USE_BABEL_PACKAGES installs both babel AND swc for compatibility
 # - Otherwise install only the specified transpiler
-if ENV["USE_BABEL_PACKAGES"] == "true" || ENV["USE_BABEL_PACKAGES"] == "1"
+if Shakapacker::Install::Env.truthy_env?("USE_BABEL_PACKAGES")
   @transpiler_to_install = "babel"
+  @install_swc_compat_packages = true
   say "📦 Installing Babel packages (USE_BABEL_PACKAGES is set)", :yellow
   say "✨ Also installing SWC packages for default config compatibility", :green
 elsif ENV["JAVASCRIPT_TRANSPILER"]
   @transpiler_to_install = ENV["JAVASCRIPT_TRANSPILER"]
+  @install_swc_compat_packages = false
   say "📦 Installing #{@transpiler_to_install} packages", :blue
 else
   # Default to swc (matches the default in shakapacker.yml)
   @transpiler_to_install = "swc"
+  @install_swc_compat_packages = false
   say "✨ Installing SWC packages (20x faster than Babel)", :green
 end
 
 # Copy config file
-copy_file "#{install_dir}/config/shakapacker.yml", "config/shakapacker.yml", force_option
-
-# Update config if USE_BABEL_PACKAGES is set to ensure babel is used at runtime
-if @transpiler_to_install == "babel" && !ENV["JAVASCRIPT_TRANSPILER"]
-  # When USE_BABEL_PACKAGES is set, update the config to use babel
-  gsub_file "config/shakapacker.yml", "javascript_transpiler: 'swc'", "javascript_transpiler: 'babel'"
-  say "   📝 Updated config/shakapacker.yml to use Babel transpiler", :green
+shakapacker_config_preexisting = Rails.root.join("config/shakapacker.yml").exist?
+copy_file "#{install_dir}/config/shakapacker.yml", "config/shakapacker.yml", @conflict_option
+
+# Update config to match the selected transpiler
+# Skip modification only when SKIP mode preserved a pre-existing user file
+if Shakapacker::Install::Env.update_transpiler_config?(
+  transpiler_to_install: @transpiler_to_install,
+  conflict_option: @conflict_option,
+  config_preexisting: shakapacker_config_preexisting
+)
+  gsub_file "config/shakapacker.yml", 'javascript_transpiler: "swc"', "javascript_transpiler: \"#{@transpiler_to_install}\""
+  say "   📝 Updated config/shakapacker.yml to use #{@transpiler_to_install} transpiler", :green
 end
 
 # Detect TypeScript usage
 # Auto-detect from tsconfig.json or explicit via SHAKAPACKER_USE_TYPESCRIPT env var
 @use_typescript = File.exist?(Rails.root.join("tsconfig.json")) ||
-  ENV["SHAKAPACKER_USE_TYPESCRIPT"] == "true"
+  Shakapacker::Install::Env.truthy_env?("SHAKAPACKER_USE_TYPESCRIPT")
 assets_bundler = ENV["SHAKAPACKER_ASSETS_BUNDLER"] || "webpack"
 config_extension = @use_typescript ? "ts" : "js"
 
@@ -53,7 +62,7 @@ source_config = "#{install_dir}/config/#{assets_bundler}/#{config_file}"
 dest_config = "config/#{assets_bundler}/#{config_file}"
 
 empty_directory "config/#{assets_bundler}"
-copy_file source_config, dest_config, force_option
+copy_file source_config, dest_config, @conflict_option
 
 if @use_typescript
   say "   ✨ Using TypeScript config for enhanced type safety", :green
@@ -216,29 +225,28 @@ Dir.chdir(Rails.root) do
 
   # Inline fetch_peer_dependencies and fetch_common_dependencies
   peers = PackageJson.read(install_dir).fetch(ENV["SHAKAPACKER_ASSETS_BUNDLER"] || "webpack")
-  common_deps = ENV["SKIP_COMMON_LOADERS"] ? {} : PackageJson.read(install_dir).fetch("common")
+  common_deps = Shakapacker::Install::Env.truthy_env?("SKIP_COMMON_LOADERS") ? {} : PackageJson.read(install_dir).fetch("common")
   peers = peers.merge(common_deps)
 
   # Add transpiler-specific dependencies based on detected/configured transpiler
   # Inline the logic here since methods can't be called before they're defined in Rails templates
 
   # Install transpiler-specific dependencies
-  # When USE_BABEL_PACKAGES is set, install both babel AND swc
-  # This ensures backward compatibility while supporting the default config
   if @transpiler_to_install == "babel"
     # Install babel packages
     babel_deps = PackageJson.read(install_dir).fetch("babel")
     peers = peers.merge(babel_deps)
 
-    # Also install SWC since that's what the default config uses
-    # This ensures the runtime works regardless of config
-    swc_deps = PackageJson.read(install_dir).fetch("swc")
-    peers = peers.merge(swc_deps)
+    # Also install SWC only when USE_BABEL_PACKAGES requested compatibility mode.
+    if @install_swc_compat_packages
+      swc_deps = PackageJson.read(install_dir).fetch("swc")
+      peers = peers.merge(swc_deps)
 
-    say "ℹ️  Installing both Babel and SWC packages for compatibility:", :blue
-    say "   - Babel packages are installed as requested via USE_BABEL_PACKAGES", :blue
-    say "   - SWC packages are also installed to ensure the default config works", :blue
-    say "   - Your actual transpiler will be determined by your shakapacker.yml configuration", :blue
+      say "ℹ️  Installing both Babel and SWC packages for compatibility:", :blue
+      say "   - Babel packages are installed as requested via USE_BABEL_PACKAGES", :blue
+      say "   - SWC packages are also installed to ensure the default config works", :blue
+      say "   - Your actual transpiler will be determined by your shakapacker.yml configuration", :blue
+    end
   elsif @transpiler_to_install == "swc"
     swc_deps = PackageJson.read(install_dir).fetch("swc")
     peers = peers.merge(swc_deps)

data/lib/shakapacker/env.rb

@@ -1,4 +1,6 @@
 class Shakapacker::Env
+  FALLBACK_ENV = "production".freeze
+
   delegate :config_path, :logger, to: :@instance
 
   def self.inquire(instance)
@@ -11,7 +13,7 @@ class Shakapacker::Env
 
   def inquire
     fallback_env_warning if config_path.exist? && !current
-    current || Shakapacker::DEFAULT_ENV.inquiry
+    current || FALLBACK_ENV.inquiry
   end
 
   private
@@ -20,7 +22,7 @@ class Shakapacker::Env
     end
 
     def fallback_env_warning
-      logger.info "RAILS_ENV=#{Rails.env} environment is not defined in #{config_path}, falling back to #{Shakapacker::DEFAULT_ENV} environment"
+      logger.info "RAILS_ENV=#{Rails.env} environment is not defined in #{config_path}, falling back to #{FALLBACK_ENV} environment"
     end
 
     def available_environments