shakapacker 9.7.0 → 10.0.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 518eb8673a021c5e18507ebc14ba593128288ddb9f735390581bd998d1f33715
-  data.tar.gz: 3c2c532321d8c79e4374fbbe0854319d6ebd89df33557e21a4ce6e4ec322cc7c
+  metadata.gz: 88f81e8b1935f9898330405c06f7e71366d53b5c43a9223931055a741697e76a
+  data.tar.gz: f4358d5be4114b34aa01668c07b2ed5d0e032dfac18174c4e052afdd39885091
 SHA512:
-  metadata.gz: 26414fbf14fe2d835262ee5a6d2b46a9e50c76eee0391a0d859b60ee60f8899a87fa0e8c9d39aa651a8eadecb37639cd9684e775dd2004a55f83bb1f8aa4647e
-  data.tar.gz: 13f248afecdaa3ef579a20f7abf7ed592db788c2e5aa6b119a4940429b1e3c6f0bae263b985abe78e6ed0217116c6eeb9483c252f3a38bddd33e1c6e4533cc2c
+  metadata.gz: e774c9cce94707f55922d2bb65d3ce9aa1f773937a315373cde05e6c01ad4531e1815e2a1b276dc80c07ff670604db0de58e5cf14b67b7130cf27ac3135cb619
+  data.tar.gz: 3cf440898e5ef0a949835aead30e370c4bbd5d648e57233b763bc8a768edfca7572fbcbf954d1823c80321e1220e8d086114400296d3b345c59fd48cf2092245

data/.claude/commands/address-review.md

@@ -16,7 +16,9 @@ If this command fails, ensure `gh` CLI is installed and authenticated (`gh auth
 
 ## Step 2: Parse User Input
 
-Extract the PR number and optional review/comment ID from the user's message:
+The user's input is: $ARGUMENTS
+
+Extract the PR number and optional review/comment ID from the input above:
 
 **Supported formats:**
 
@@ -42,21 +44,40 @@ gh api repos/${REPO}/issues/comments/{COMMENT_ID} | jq '{body: .body, user: .use
 **If a specific review ID is provided (`#pullrequestreview-...`):**
 
 ```bash
-gh api repos/${REPO}/pulls/{PR_NUMBER}/reviews/{REVIEW_ID}/comments | jq '[.[] | {id: .id, path: .path, body: .body, line: .line, start_line: .start_line, user: .user.login}]'
+# Review body (often contains summary feedback)
+gh api repos/${REPO}/pulls/{PR_NUMBER}/reviews/{REVIEW_ID} | jq '{id: .id, body: .body, state: .state, user: .user.login, html_url: .html_url}'
+
+# Inline comments for this review
+gh api --paginate repos/${REPO}/pulls/{PR_NUMBER}/reviews/{REVIEW_ID}/comments | jq -s '[.[].[] | {id: .id, node_id: .node_id, path: .path, body: .body, line: .line, start_line: .start_line, user: .user.login, in_reply_to_id: .in_reply_to_id}]'
 ```
 
-**If only PR number is provided (fetch all PR review comments):**
+Include the review body as a general comment when it contains actionable feedback. When the review body contains actionable feedback, note that it cannot be replied to via the `/replies` endpoint — responses to review summary bodies must be posted as general PR comments (see Step 7).
+
+**If only PR number is provided (fetch all PR comments):**
 
 ```bash
-gh api repos/${REPO}/pulls/{PR_NUMBER}/comments | jq '[.[] | {id: .id, path: .path, body: .body, line: .line, start_line: .start_line, user: .user.login, in_reply_to_id: .in_reply_to_id}]'
+# Inline code review comments
+gh api --paginate repos/${REPO}/pulls/{PR_NUMBER}/comments | jq -s '[.[].[] | {id: .id, node_id: .node_id, type: "review", path: .path, body: .body, line: .line, start_line: .start_line, user: .user.login, in_reply_to_id: .in_reply_to_id}]'
+
+# General PR discussion comments (not tied to specific lines)
+gh api --paginate repos/${REPO}/issues/{PR_NUMBER}/comments | jq -s '[.[].[] | {id: .id, node_id: .node_id, type: "issue", body: .body, user: .user.login, html_url: .html_url}]'
+```
+
+**For all paths that fetch review comments (both specific review and full PR), fetch review thread metadata and attach `thread_id` by matching each review comment's `node_id`:**
+
+```bash
+OWNER=${REPO%/*}
+NAME=${REPO#*/}
+gh api graphql --paginate -f owner="${OWNER}" -f name="${NAME}" -F pr={PR_NUMBER} -f query='query($owner:String!, $name:String!, $pr:Int!, $endCursor:String) { repository(owner:$owner, name:$name) { pullRequest(number:$pr) { reviewThreads(first:100, after:$endCursor) { nodes { id isResolved comments(first:100) { nodes { id databaseId } } } pageInfo { hasNextPage endCursor } } } } }' | jq -s '[.[].data.repository.pullRequest.reviewThreads.nodes[] | {thread_id: .id, is_resolved: .isResolved, comments: [.comments.nodes[] | {node_id: .id, id: .databaseId}]}]'
 ```
 
 **Filtering comments:**
 
+- Skip comments belonging to already-resolved threads (match via `thread_id` and `is_resolved` from the GraphQL response)
 - Skip comments where `in_reply_to_id` is set (these are replies, not top-level comments)
 - Do not skip bot-generated comments by default. Many actionable review comments in this repository come from bots.
 - Deduplicate repeated bot comments and skip bot status posts, summaries, and acknowledgments that do not require a code or documentation change
-- Treat as actionable by default only: correctness bugs, regressions, missing tests, and clear inconsistencies with adjacent code
+- Treat as actionable by default only: correctness bugs, regressions, security issues, missing tests, and clear inconsistencies with adjacent code
 - Treat as non-actionable by default: style nits, speculative suggestions, changelog wording, duplicate bot comments, and "could consider" feedback unless the user explicitly asks for polish work
 - Focus on actionable feedback, not acknowledgments or thank-you messages
 
@@ -83,31 +104,33 @@ Triage rules:
 
 ## Step 5: Create Todo List
 
-Create a todo list with TodoWrite containing **only the `MUST-FIX` items**:
+Create a task list with TodoWrite containing **only the `MUST-FIX` items**:
 
-- One todo per must-fix comment or deduplicated issue
-- For file-specific comments: `"{file}:{line} - {comment_summary} (@{username})"` (content)
-- For general comments: Parse the comment body and extract the must-fix action
-- Format activeForm: `"Addressing {brief description}"`
-- All todos should start with status: `"pending"`
+- One task per must-fix comment or deduplicated issue
+- Subject: `"{file}:{line} - {comment_summary} (@{username})"`
+- For general comments: Parse the comment body and extract the must-fix action as the subject
+- Description: Include the full review comment text and any relevant context
+- All tasks should start with status: `"pending"`
 
 ## Step 6: Present Triage to User
 
 Present the triage to the user - **DO NOT automatically start addressing items**:
 
+- Use a single sequential numbering across all categories (1, 2, 3, ...) so every item has a unique number the user can reference. Do not restart numbering at 1 for each category.
 - `MUST-FIX ({count})`: list the todos created
 - `DISCUSS ({count})`: list items needing user choice, with a short reason
 - `SKIPPED ({count})`: list skipped comments with a short reason, including duplicates and factually incorrect suggestions
 - Wait for the user to tell you which items to address
 - Always offer an explicit optional follow-up to post rationale replies on selected `SKIPPED` or declined `DISCUSS` items
 - Never post those rationale replies unless the user explicitly selects which items to reply to
-- Ask two things when relevant:
+- Ask two things when there are `SKIPPED` or declined `DISCUSS` items:
   - Which items to address in code/tests/docs
   - Which skipped/declined items (if any) should receive a rationale reply
 
 ## Step 7: Address Items, Reply, and Resolve
 
-When addressing items, after completing each selected todo item, reply to the original review comment explaining how it was addressed.
+When addressing items, after completing each selected item (whether `MUST-FIX` or `DISCUSS`), reply to the original review comment explaining how it was addressed.
+If the user selects `DISCUSS` items to address, treat them the same as `MUST-FIX`: make the code change, reply, and resolve the thread.
 If the user selects skipped/declined items for rationale replies, post those replies too.
 
 **For issue comments (general PR comments):**
@@ -122,14 +145,16 @@ gh api repos/${REPO}/issues/{PR_NUMBER}/comments -X POST -f body="<response>"
 gh api repos/${REPO}/pulls/{PR_NUMBER}/comments/{COMMENT_ID}/replies -X POST -f body="<response>"
 ```
 
-**For standalone review comments (not in a thread):**
+Use the `/replies` endpoint for all existing review comments, including standalone top-level comments.
+
+**For review summary bodies (from `/pulls/{PR_NUMBER}/reviews/{REVIEW_ID}`):**
+
+Review summary bodies do not have a `comment_id` and cannot be replied to via the `/replies` endpoint. Instead, post a general PR comment referencing the review:
 
 ```bash
-gh api repos/${REPO}/pulls/{PR_NUMBER}/comments -X POST -f body="<response>" -f commit_id="<COMMIT_SHA>" -f path="<FILE_PATH>" -f line=<LINE_NUMBER> -f side="RIGHT"
+gh api repos/${REPO}/issues/{PR_NUMBER}/comments -X POST -f body="<response>"
 ```
 
-Note: `side` is required when using `line`. Use `"RIGHT"` for the PR commit side (most common) or `"LEFT"` for the base commit side.
-
 The response should briefly explain:
 
 - What was changed
@@ -184,6 +209,8 @@ Which items would you like me to address? (e.g., "1", "1,2", or "all must-fix")
 Optional: I can also post rationale replies for skipped/declined items (e.g., "reply 3,5" or "reply all skipped").
 ```
 
+Note: Only show the "Optional: rationale replies" line when there are `SKIPPED` or declined `DISCUSS` items. Omit it when every item is `MUST-FIX`.
+
 # Important Notes
 
 - Automatically detect the repository using `gh repo view` for the current working directory
@@ -204,3 +231,4 @@ Optional: I can also post rationale replies for skipped/declined items (e.g., "r
 
 - Rate limiting: GitHub API has rate limits; if you hit them, wait a few minutes
 - Private repos: Requires appropriate `gh` authentication scope
+- GraphQL inner pagination: The `comments(first:100)` inside each review thread is hardcoded. Threads with >100 comments (rare) will have older comments truncated. The outer `reviewThreads` pagination is handled by `--paginate`.

data/.claude/commands/verify.md

@@ -0,0 +1,12 @@
+---
+description: Run the standard project verification loop before pushing.
+---
+
+Run the following checks in order and stop on first failure:
+
+1. `bundle exec rubocop`
+2. `yarn lint`
+3. `bundle exec rspec`
+4. `yarn test --runInBand` (serial mode for reliable pre-push verification)
+
+If all checks pass, summarize command outcomes and total runtime.

data/.claude/rules/coding-style.md

@@ -0,0 +1,7 @@
+# Coding Style Rules
+
+1. Always end files with a trailing newline.
+2. Always use `bundle exec` when running Ruby commands.
+3. Follow existing code conventions in the file you are editing.
+4. Keep changes focused and minimal; avoid unrelated diffs.
+5. Do not add unnecessary comments unless requested.

data/.claude/rules/git-workflow.md

@@ -0,0 +1,6 @@
+# Git Workflow Rules
+
+1. Create feature branches for all changes.
+2. Never push directly to `main`.
+3. Keep PRs small and focused.
+4. Open a PR immediately after pushing branch changes.

data/.claude/rules/open-source.md

@@ -0,0 +1,7 @@
+# Open Source Maintainability Rules
+
+1. Prefer removing complexity over adding new configuration.
+2. Treat every new option as long-term maintenance surface.
+3. Favor secure defaults over convenience defaults.
+4. Keep feature PRs focused; do not refactor adjacent code in the same PR.
+5. For niche needs, prefer existing extension points over new global options.

data/.claude/rules/testing.md

@@ -0,0 +1,9 @@
+# Testing Rules
+
+1. Run corresponding specs/tests when changing source files.
+2. Run `bundle exec rubocop` before committing Ruby changes.
+3. Run `yarn lint` before committing JavaScript changes.
+4. Prefer explicit RSpec spy assertions (`have_received`) over indirect counters.
+5. Validate both webpack and rspack paths when changing core Shakapacker behavior.
+6. Run `bundle exec rspec` (full suite) before pushing.
+7. Run `yarn test --runInBand` (JS tests) before pushing.

data/.github/workflows/dummy.yml

@@ -30,7 +30,7 @@ jobs:
           persist-credentials: false
       - uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "20.x"
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: "3.2"
@@ -40,7 +40,6 @@ jobs:
           bundle install
           yarn install --frozen-lockfile --production=false
           npm install -g yalc
-          cd spec/dummy && npm install
 
       - name: Build TypeScript
         run: yarn build

data/.github/workflows/node.yml

@@ -139,7 +139,8 @@ jobs:
           cd /tmp/test-types
           npx tsc --noEmit \
             --skipLibCheck \
-            --moduleResolution node \
+            --moduleResolution bundler \
+            --types node \
             *.d.ts
   test:
     name: Testing

data/.github/workflows/trigger-docs-site.yml

@@ -0,0 +1,24 @@
+name: Trigger docs site rebuild
+
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**"]
+
+jobs:
+  notify-docs-site:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ secrets.DOCS_DISPATCH_APP_ID }}
+          private-key: ${{ secrets.DOCS_DISPATCH_APP_KEY }}
+          owner: shakacode
+          repositories: shakapacker.com
+
+      - uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          repository: shakacode/shakapacker.com
+          event-type: docs-updated

data/.gitignore

@@ -26,6 +26,9 @@ yalc.lock
 # Config exporter output directory
 shakapacker-config-exports/
 
+# Webpack build output
+public/packs/
+
 # TypeScript generated files
 package/**/*.d.ts
 package/**/*.d.ts.map

data/CHANGELOG.md

@@ -9,6 +9,27 @@
 
 ## [Unreleased]
 
+## [v10.0.0-rc.0] - April 1, 2026
+
+### Added
+
+- **Added `bin/shakapacker-watch` binstub for clean Ctrl-C shutdown in Procfile-based workflows**. [PR #1026](https://github.com/shakacode/shakapacker/pull/1026) by [justin808](https://github.com/justin808). The new wrapper script traps INT/TERM signals and forwards TERM to the underlying `bin/shakapacker --watch` process, preventing Ruby interrupt backtraces when stopping `bin/dev`. Use `bin/shakapacker-watch --watch` in Procfiles instead of `bin/shakapacker --watch`.
+- **Allowed `webpack-cli` v7 (`^7.0.0`) in peer dependencies**. [PR #1021](https://github.com/shakacode/shakapacker/pull/1021) by [justin808](https://github.com/justin808). Fixes [#1020](https://github.com/shakacode/shakapacker/issues/1020). Note: `webpack-cli` v7 requires Node.js >= 20.9.0.
+
+### ⚠️ Breaking Changes
+
+- **Breaking: bumped the minimum `webpack` version to `^5.101.0`**. [PR #1021](https://github.com/shakacode/shakapacker/pull/1021) by [justin808](https://github.com/justin808). The previous minimum was `^5.76.0`.
+- **Breaking: required `webpack-dev-server` `^5.2.2` and dropped support for v4**. [PR #1021](https://github.com/shakacode/shakapacker/pull/1021) by [justin808](https://github.com/justin808). The removed v4 range was `^4.15.2`.
+
+### Changed
+
+- **Changed `shakapacker:install` to default `webpack-cli` installs to the latest v6 range**. [PR #1021](https://github.com/shakacode/shakapacker/pull/1021) by [justin808](https://github.com/justin808). This keeps installs compatible with Node.js `20.0-20.8`; v7 remains supported via peer dependencies for Node.js >= 20.9.0.
+- **Changed dev server config handling to warn on deprecated middleware hooks and ignore them for webpack-dev-server v5**. [PR #1021](https://github.com/shakacode/shakapacker/pull/1021) by [justin808](https://github.com/justin808). Use `setup_middlewares` instead of `on_before_setup_middleware` and `on_after_setup_middleware`.
+
+### Fixed
+
+- **Ensured `shakapacker:install` installs the latest `compression-webpack-plugin`**. [PR #1035](https://github.com/shakacode/shakapacker/pull/1035) by [G-Rath](https://github.com/G-Rath).
+
 ## [v9.7.0] - March 15, 2026
 
 ### Added
@@ -887,7 +908,8 @@ 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.7.0...main
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v10.0.0-rc.0...main
+[v10.0.0-rc.0]: https://github.com/shakacode/shakapacker/compare/v9.7.0...v10.0.0-rc.0
 [v9.7.0]: https://github.com/shakacode/shakapacker/compare/v9.6.1...v9.7.0
 [v9.6.1]: https://github.com/shakacode/shakapacker/compare/v9.6.0...v9.6.1
 [v9.6.0]: https://github.com/shakacode/shakapacker/compare/v9.5.0...v9.6.0

data/CLAUDE.md

@@ -1,5 +1,16 @@
 # Shakapacker Project Guidelines
 
+## Rules Directory
+
+Concise always-on reminders live in `.claude/rules/`:
+
+- `.claude/rules/coding-style.md`
+- `.claude/rules/testing.md`
+- `.claude/rules/git-workflow.md`
+- `.claude/rules/open-source.md`
+
+See the sections below for full detail and examples.
+
 ## Critical Requirements
 
 - **ALWAYS end all files with a trailing newline character.** This is required by the project's linting rules.
@@ -11,7 +22,7 @@
 
 - Run corresponding RSpec tests when changing source files
 - For example, when changing `lib/shakapacker/foo.rb`, run `spec/shakapacker/foo_spec.rb`
-- Run the full test suite with `bundle exec rspec` before pushing
+- Run the full test suite with `bundle exec rake test` before pushing
 - **Use explicit RSpec spy assertions** - prefer `have_received`/`not_to have_received` over indirect counter patterns
   - Good: `expect(Open3).to have_received(:capture3).with(anything, hook_command, anything)`
   - Good: `expect(Open3).not_to have_received(:capture3).with(anything, hook_command, anything)`
@@ -37,7 +48,7 @@
 - **Do NOT add entries for**: linting, formatting, refactoring, tests, or documentation fixes
 - **Format**: `[PR #123](https://github.com/shakacode/shakapacker/pull/123) by [username](https://github.com/username)` (Shakapacker uses `#` in PR links)
 - **Use `/update-changelog` command** for guided changelog updates with automatic formatting
-- **Version management**: Run `bundle exec rake update_changelog` after releases to update version headers
+- **Version management**: Use the `/update-changelog` command to stamp version headers during release prep
 - **Examples**: Run `grep -A 3 "^### " CHANGELOG.md | head -30` to see real formatting examples
 
 ## Open Source Maintainability

data/CONTRIBUTING.md

@@ -8,7 +8,7 @@ Thank you for your interest in contributing to Shakapacker! We welcome all contr
 - [Submitting Pull Requests](#submitting-pull-requests)
 - [Setting Up a Development Environment](#setting-up-a-development-environment)
 - [Making sure your changes pass all tests](#making-sure-your-changes-pass-all-tests)
-- [Testing the generator](#testing-the-generator)
+- [Testing the installer](#46-testing-the-installer)
 
 ## Reporting Issues
 
@@ -44,8 +44,8 @@ This project includes configuration for git hooks via `husky` and `lint-staged`,
 To enable pre-commit hooks locally:
 
 ```bash
-npx husky install
-npx husky add .husky/pre-commit "npx lint-staged"
+yarn install
+npx husky
 ```
 
 ---
@@ -178,7 +178,8 @@ yarn lint --cache
    ```
    bundle install
    yarn install
-   yarn prepare:husky  # Set up pre-commit hooks for linting
+   # Optional: enable local pre-commit hooks
+   npx husky
    ```
 
 ## Understanding Optional Peer Dependencies

data/README.md

@@ -4,6 +4,8 @@
 
 _🚀 Shakapacker 9 supports [Rspack](https://rspack.rs/)! 10x faster than webpack!_
 
+_📖 **Full documentation at [shakapacker.com](https://shakapacker.com)**_
+
 ---
 
 _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._
@@ -19,7 +21,7 @@ _Official, actively maintained successor to [rails/webpacker](https://github.com
 [![Rubocop](https://github.com/shakacode/shakapacker/workflows/Rubocop/badge.svg)](https://github.com/shakacode/shakapacker/actions)
 [![JS lint](https://github.com/shakacode/shakapacker/workflows/JS%20lint/badge.svg)](https://github.com/shakacode/shakapacker/actions)
 
-[![node.js](https://img.shields.io/badge/node-%3E%3D%2012.0.0-brightgreen.svg)](https://www.npmjs.com/package/shakapacker)
+[![node.js](https://img.shields.io/badge/node-%3E%3D%2020-brightgreen.svg)](https://www.npmjs.com/package/shakapacker)
 [![Gem](https://img.shields.io/gem/v/shakapacker.svg)](https://rubygems.org/gems/shakapacker)
 [![npm version](https://badge.fury.io/js/shakapacker.svg)](https://badge.fury.io/js/shakapacker)
 
@@ -57,6 +59,20 @@ Here's a testimonial of how ShakaCode can help from [Florian Gößler](https://g
 
 Read the [full review here](https://clutch.co/profile/shakacode#reviews?sort_by=date_DESC#review-2118154).
 
+Here's a testimonial from Jon Rajavuori of [Academia.edu](https://www.academia.edu/) about migrating frontend builds from Webpack to [rspack](https://rspack.rs/) with ShakaCode's help, shared in March 2026:
+
+> We've been running [rspack](https://rspack.rs/) most of the week now for frontend builds! It's a performance-focused drop-in replacement for Webpack that apparently works as advertised. The impact has been between a **2-4x build speed increase** depending on the environment and conditions.
+>
+> The typical case of first startup with a warm cache has gone from roughly 1m with Webpack down to about **20s** — close to the amount of time other dev components take to startup.
+>
+> As for production **incremental** builds, they now take around 10s when only a few lines in one bundle have changed!
+>
+> Additional stats from follow-up conversation with Jon:
+>
+> - Cold-cache startup: **4m30s → 3m30s** (~22% faster; 2-4x gains apply to warm-cache and incremental builds)
+> - Production incremental builds: **~10 seconds**
+> - HMR rebuild time: unchanged at ~8s (bottleneck is orchestration, not compilation)
+
 ---
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
@@ -78,7 +94,7 @@ Read the [full review here](https://clutch.co/profile/shakacode#reviews?sort_by=
     - [View Helper: `image_pack_tag`](#view-helper-image_pack_tag)
     - [View Helper: `favicon_pack_tag`](#view-helper-favicon_pack_tag)
     - [View Helper: `preload_pack_asset`](#view-helper-preload_pack_asset)
-    - [View Helper: `send_pack_early_hints`](#view-helper-send_pack_early_hints)
+    - [HTTP 103 Early Hints](#http-103-early-hints)
   - [Images in Stylesheets](#images-in-stylesheets)
   - [Server-Side Rendering (SSR)](#server-side-rendering-ssr)
   - [Development](#development)
@@ -117,7 +133,7 @@ Read the [full review here](https://clutch.co/profile/shakacode#reviews?sort_by=
 
 - Ruby 2.7+
 - Rails 5.2+
-- Node.js 14+
+- Node.js 20+
 
 ## Features
 
@@ -191,24 +207,16 @@ If you wish to use [Yarn PnP](https://yarnpkg.com/features/pnp) you will need to
 > a particular package manager requires a very different command; otherwise it should be safe to just replace `npm` with the name of your
 > preferred package manager when running the command
 
-Note, in v6+, most JS packages are peer dependencies. Thus, the installer will add the packages:
-
-- `@babel/core`
-- `@babel/plugin-transform-runtime`
-- `@babel/preset-env`
-- `@babel/runtime`
-- `babel-loader`
-- `compression-webpack-plugin`
-- `terser-webpack-plugin`
-- `webpack`
-- `webpack-assets-manifest`
-- `webpack-cli`
-- `webpack-merge`
-- `webpack-sources`
-- `webpack-dev-server`
-
-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.
+Note, in v6+, most JS packages are peer dependencies. During `shakapacker:install`, Shakapacker
+adds the subset required for your chosen bundler/transpiler setup rather than forcing every
+supported package into every app.
+
+See:
+
+- [Optional Peer Dependencies](./docs/optional-peer-dependencies.md) for how optional peers work
+- [Shakapacker's Peer Dependencies](./docs/peer-dependencies.md) for the current supported version ranges
+
+This keeps installation flexible while still making the supported dependency ranges explicit.
 
 ### Optional Peer Dependencies
 
@@ -238,14 +246,16 @@ Depending on your setup, you'll need different subsets of the optional peer depe
     "babel-loader": "^8.2.4",
     "compression-webpack-plugin": "^9.0.0",
     "terser-webpack-plugin": "^5.3.1",
-    "webpack": "^5.76.0",
+    "webpack": "^5.101.0",
     "webpack-assets-manifest": "^5.0.6",
-    "webpack-cli": "^5.0.0",
-    "webpack-dev-server": "^5.0.0"
+    "webpack-cli": "^6.0.0",
+    "webpack-dev-server": "^5.2.2"
   }
 }
 ```
 
+> **Note:** `webpack-cli` v7 is also supported but requires Node.js >= 20.9.0. If you're on Node >= 20.9.0, you can use `"webpack-cli": "^7.0.0"` instead. See [peer-dependencies.md](./docs/peer-dependencies.md) for the full supported range.
+
 **For Webpack + SWC (faster alternative):**
 
 ```json
@@ -256,10 +266,10 @@ Depending on your setup, you'll need different subsets of the optional peer depe
     "swc-loader": "^0.2.0",
     "compression-webpack-plugin": "^9.0.0",
     "terser-webpack-plugin": "^5.3.1",
-    "webpack": "^5.76.0",
+    "webpack": "^5.101.0",
     "webpack-assets-manifest": "^5.0.6",
-    "webpack-cli": "^5.0.0",
-    "webpack-dev-server": "^5.0.0"
+    "webpack-cli": "^6.0.0",
+    "webpack-dev-server": "^5.2.2"
   }
 }
 ```
@@ -607,7 +617,7 @@ Note, if you are using server-side rendering of JavaScript with dynamic code-spl
 
 ### Development
 
-Shakapacker ships with two binstubs: `./bin/shakapacker` and `./bin/shakapacker-dev-server`. Both are thin wrappers around the standard `webpack.js` and `webpack-dev-server.js` executables to ensure that the right configuration files and environmental variables are loaded based on your environment.
+Shakapacker ships with three binstubs: `./bin/shakapacker`, `./bin/shakapacker-dev-server`, and `./bin/shakapacker-watch`. The first two are thin wrappers around the standard `webpack.js` and `webpack-dev-server.js` executables to ensure that the right configuration files and environmental variables are loaded based on your environment. `./bin/shakapacker-watch` is a shell wrapper around `./bin/shakapacker` that traps INT/TERM signals for clean shutdown — use it in Procfile-based workflows (e.g., `foreman`, `bin/dev`) to avoid Ruby interrupt backtraces when pressing Ctrl-C.
 
 _Note: older Shakapacker installations had set a missing NODE_ENV in the binstubs. Please remove this for versions 6.5.2 and newer._
 
@@ -642,7 +652,10 @@ If you want to use live code reloading, or you have enough JavaScript that on-de
 # webpack dev server
 ./bin/shakapacker-dev-server
 
-# watcher
+# watcher (use in Procfiles for clean Ctrl-C shutdown)
+./bin/shakapacker-watch --watch --progress
+
+# watcher (standalone, without signal handling)
 ./bin/shakapacker --watch --progress
 
 # standalone build
@@ -962,15 +975,22 @@ See also [Customizing Babel Config](./docs/customizing_babel_config.md) for an e
 **📚 TypeScript Support:** See the **[TypeScript Documentation](./docs/typescript.md)** for type-safe configuration.
 
 ```bash
-npm install typescript @babel/preset-typescript
+npm install --save-dev typescript
+
+# If you explicitly use `javascript_transpiler: babel`
+npm install --save-dev @babel/preset-typescript
 ```
 
-Babel won't perform any type-checking on TypeScript code. To optionally use type-checking run:
+Shakapacker does not type-check TypeScript during builds. For webpack projects, you can optionally
+add type-checking during builds with:
 
 ```bash
-npm install fork-ts-checker-webpack-plugin
+npm install --save-dev fork-ts-checker-webpack-plugin
 ```
 
+You can also run `tsc --noEmit` separately in CI or local development if you prefer not to wire
+type-checking into the bundler.
+
 Add tsconfig.json
 
 ```json