shakapacker 9.3.0 → 9.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e94cd0b57c81506b9cab0fb54cc6a876276c3f3331686cf921fa4485442ab99
-  data.tar.gz: 292b0623b5241014524f9227ed2a1009752de53e8db610344567f761c7b8b4bc
+  metadata.gz: 827667fa6e3a24bab59f3d9c2ef8404755b0deed67e1fce8ec62ada24e9b1a51
+  data.tar.gz: 06e18cd459b5e343601524ef2a1275ed0a86e6f842f63ef49d22e94fd7468ff2
 SHA512:
-  metadata.gz: 6dd27e8501b86f06fbefd6f71a2a3ceb9c975dd28f140251ab03cf6bd972b631db35666e9c05bdf434bf2ac13c1568f57bd73a7841efb38befb541f2d0cfaeb1
-  data.tar.gz: 623358b9543ddcad7586a68e03aba4848151d4490a298c39320a395cb4aa450783a91f4c21d53b491868600d57e054f3f52bcb72eb244f25ebc0e8cb20ff1738
+  metadata.gz: ccc98e916ba625cc386091668bad5737376f0d031758ce44124f8c3a45f463e8e9dbdc2e42c302387b3f1f074a075524e9856e01295cd73ea1efa7ebf3f40469
+  data.tar.gz: 5b256253fb6abd10007f861c6fc16a2a2500db40ca2a454cd75f8aeb89f83a13669394524cffb3cfffac6b490aa9a57f498358d3c57c0836d069072d208713eb

data/.claude/commands/update-changelog.md

@@ -0,0 +1,224 @@
+# Update Changelog
+
+You are helping to add an entry to the CHANGELOG.md file for the Shakapacker project.
+
+## Critical Requirements
+
+1. **User-visible changes only**: Only add changelog entries for user-visible changes:
+   - New features
+   - Bug fixes
+   - Breaking changes
+   - Deprecations
+   - Performance improvements
+   - Security fixes
+   - Changes to public APIs or configuration options
+
+2. **Do NOT add entries for**:
+   - Linting fixes
+   - Code formatting
+   - Internal refactoring
+   - Test updates
+   - Documentation fixes (unless they fix incorrect docs about behavior)
+   - CI/CD changes
+
+## Formatting Requirements
+
+### Entry Format
+
+Each changelog entry MUST follow this exact format:
+
+```markdown
+- **Bold description of change**. [PR #123](https://github.com/shakacode/shakapacker/pull/123) by [username](https://github.com/username). Optional additional context or details.
+```
+
+**Important formatting rules**:
+
+- Start with a dash and space: `- `
+- Use **bold** for the main description
+- End the bold description with a period before the link
+- Always link to the PR: `[PR #123](https://github.com/shakacode/shakapacker/pull/123)` - **Note: Shakapacker uses `#` in PR links, unlike React on Rails**
+- Always link to the author: `by [username](https://github.com/username)`
+- End with a period after the author link
+- Additional details can be added after the main entry, using proper indentation for multi-line entries
+
+### Breaking Changes Format
+
+For breaking changes, use this format:
+
+```markdown
+- **Breaking**: Description of the breaking change. See [Migration Guide](docs/vX_upgrade.md) for migration instructions. [PR #123](https://github.com/shakacode/shakapacker/pull/123) by [username](https://github.com/username).
+```
+
+### Category Organization
+
+Entries should be organized under these section headings. The project uses both standard and custom headings:
+
+**Standard headings** (from keepachangelog.com) - use these for most changes:
+
+- `### Added` - New features
+- `### Changed` - Changes to existing functionality
+- `### Deprecated` - Deprecation notices
+- `### Removed` - Removed features
+- `### Fixed` - Bug fixes
+- `### Security` - Security-related changes
+- `### Improved` - Improvements to existing features
+
+**Custom headings** (project-specific) - use sparingly when standard headings don't fit:
+
+- `### ⚠️ Breaking Changes` - Breaking changes only (Shakapacker uses emoji in heading)
+- `### API Improvements` - API changes and improvements
+- `### Developer Experience` - Developer workflow improvements
+- `### Performance` - Performance improvements
+
+**Prefer standard headings.** Only use custom headings when the change needs more specific categorization.
+
+**Only include section headings that have entries.**
+
+### Version Management
+
+After adding entries, use the rake task to manage version headers:
+
+```bash
+bundle exec rake update_changelog
+```
+
+This will:
+
+- Add headers for the new version
+- Update version diff links at the bottom of the file
+
+### Version Links
+
+After adding an entry to the `## [Unreleased]` section, ensure the version diff links at the bottom of the file are correct.
+
+The format at the bottom should be:
+
+```markdown
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.3.0...main
+[v9.3.0]: https://github.com/shakacode/shakapacker/compare/v9.2.0...v9.3.0
+```
+
+When a new version is released:
+
+1. Change `[Unreleased]` heading to `## [vX.Y.Z] - Month Day, Year`
+2. Add a new `## [Unreleased]` section at the top
+3. Update the `[Unreleased]` link to compare from the new version
+4. Add a new version link for the released version
+
+## Process
+
+### For Regular Changelog Updates
+
+1. **Determine the correct version tag to compare against**:
+   - First, check the tag dates: `git log --tags --simplify-by-decoration --pretty="format:%ai %d" | head -10`
+   - Find the latest version tag and its date
+   - Compare main branch date to the tag date
+   - If the tag is NEWER than main, it means main needs to be updated to include the tag's commits
+   - **CRITICAL**: Always use `git log TAG..BRANCH` to find commits that are in the tag but not in the branch, as the tag may be ahead
+
+2. **Check commits and version boundaries**:
+   - Run `git log --oneline LAST_TAG..main` to see commits since the last release
+   - Also check `git log --oneline main..LAST_TAG` to see if the tag is ahead of main
+   - If the tag is ahead, entries in "Unreleased" section may actually belong to that tagged version
+   - Identify which commits contain user-visible changes
+   - Extract PR numbers and author information from commit messages
+   - **Never ask the user for PR details** - get them from the git history
+
+3. **Validate** that changes are user-visible (per the criteria above). If not user-visible, skip those commits.
+
+4. **Read the current CHANGELOG.md** to understand the existing structure and formatting.
+
+5. **Determine where entries should go**:
+   - If the latest version tag is NEWER than main branch, move entries from "Unreleased" to that version section
+   - If main is ahead of the latest tag, add new entries to "Unreleased"
+   - Always verify the version date in CHANGELOG.md matches the actual tag date
+
+6. **Add or move entries** to the appropriate section under appropriate category headings.
+   - **CRITICAL**: When moving entries from "Unreleased" to a version section, merge them with existing entries under the same category heading
+   - **NEVER create duplicate section headings** (e.g., don't create two "### Fixed" sections)
+   - If the version section already has a category heading (e.g., "### Fixed"), add the moved entries to that existing section
+   - Maintain the category order as defined above
+
+7. **Verify formatting**:
+   - Bold description with period
+   - Proper PR link
+   - Proper author link
+   - Consistent with existing entries
+   - File ends with a newline character
+
+8. **Run linting** after making changes:
+
+   ```bash
+   yarn lint
+   ```
+
+9. **Show the user** the added or moved entries and explain what was done.
+
+### For Beta to Non-Beta Version Release
+
+When releasing from beta to a stable version (e.g., v9.1.0-beta.3 → v9.1.0):
+
+1. **Remove all beta version labels** from the changelog:
+   - Change `## [v9.1.0-beta.1]`, `## [v9.1.0-beta.2]`, etc. to a single `## [v9.1.0]` section
+   - Combine all beta entries into the stable release section
+
+2. **Consolidate duplicate entries**:
+   - If bug fixes or changes were made to features introduced in earlier betas, keep only the final state
+   - Remove redundant changelog entries for fixes to beta features
+   - Keep the most recent/accurate description of each change
+
+3. **Update version diff links** at the bottom to point to the stable version
+
+### For New Beta Version Release
+
+When creating a new beta version, ask the user which approach to take:
+
+**Option 1: Process changes since last beta**
+
+- Only add entries for commits since the previous beta version
+- Maintains detailed history of what changed in each beta
+
+**Option 2: Collapse all prior betas into current beta**
+
+- Combine all beta changelog entries into the new beta version
+- Removes previous beta version sections
+- Cleaner changelog with less version noise
+
+After the user chooses, proceed with that approach.
+
+## Examples
+
+Run this command to see real formatting examples from the codebase:
+
+```bash
+grep -A 3 "^### " CHANGELOG.md | head -30
+```
+
+### Good Entry Example
+
+```markdown
+- **Enhanced error handling for better security and debugging**. [PR #786](https://github.com/shakacode/shakapacker/pull/786) by [justin808](https://github.com/justin808).
+  - Path validation now properly reports permission errors instead of silently handling them
+  - Module loading errors now include original error context for easier troubleshooting
+  - Improved security by only catching ENOENT errors in path resolution, rethrowing permission and access errors
+```
+
+### Entry with Sub-bullets Example
+
+```markdown
+- **HTTP 103 Early Hints support** for faster asset loading. [PR #722](https://github.com/shakacode/shakapacker/pull/722) by [justin808](https://github.com/justin808). Automatically sends early hints when `early_hints: enabled: true` in `shakapacker.yml`. Works with `append_javascript_pack_tag`/`append_stylesheet_pack_tag`, supports per-controller/action configuration, and includes helpers like `configure_pack_early_hints` and `skip_send_pack_early_hints`. Requires Rails 5.2+ and HTTP/2-capable server. See [Early Hints Guide](docs/early_hints.md).
+```
+
+### Breaking Change Example
+
+```markdown
+- **Breaking: SWC default configuration now uses `loose: false`**. [PR #658](https://github.com/shakacode/shakapacker/pull/658) by [justin808](https://github.com/justin808). See [v9 Upgrade Guide - SWC Loose Mode](./docs/v9_upgrade.md#swc-loose-mode-breaking-change-v910) for migration details.
+```
+
+## Additional Notes
+
+- Keep descriptions concise but informative
+- Focus on the "what" and "why", not the "how"
+- Use past tense for the description
+- Be consistent with existing formatting in the changelog
+- Always ensure the file ends with a trailing newline

data/.github/actionlint-matcher.json

@@ -0,0 +1,17 @@
+{
+  "problemMatcher": [
+    {
+      "owner": "actionlint",
+      "pattern": [
+        {
+          "regexp": "^(?:\\x1b\\[\\d+m)?(.+?)(?:\\x1b\\[\\d+m)*:(?:\\x1b\\[\\d+m)*(\\d+)(?:\\x1b\\[\\d+m)*:(?:\\x1b\\[\\d+m)*(\\d+)(?:\\x1b\\[\\d+m)*: (?:\\x1b\\[\\d+m)*(.+?)(?:\\x1b\\[\\d+m)* \\[(.+?)\\]$",
+          "file": 1,
+          "line": 2,
+          "column": 3,
+          "message": 4,
+          "code": 5
+        }
+      ]
+    }
+  ]
+}

data/.github/workflows/dummy.yml

@@ -5,6 +5,15 @@ on:
     branches:
       - "main"
   pull_request:
+    paths:
+      - "spec/dummy/**"
+      - "lib/**"
+      - "**.rb"
+      - "**.js"
+      - "**.ts"
+      - "package.json"
+      - ".github/workflows/dummy.yml"
+  workflow_dispatch:
 
 concurrency:
   # Pushing new changes to a branch will cancel any in-progress CI runs

data/.github/workflows/generator.yml

@@ -5,6 +5,19 @@ on:
     branches:
       - "main"
   pull_request:
+    paths:
+      - "lib/install/**"
+      - "lib/generators/**"
+      - "spec/generator_specs/**"
+      - "**.rb"
+      - "**.gemspec"
+      - "Gemfile"
+      - "gemfiles/**"
+      - "package.json"
+      - "**.js"
+      - "**.ts"
+      - ".github/workflows/generator.yml"
+  workflow_dispatch:
 
 concurrency:
   # Pushing new changes to a branch will cancel any in-progress CI runs

data/.github/workflows/node.yml

@@ -5,6 +5,19 @@ on:
     branches:
       - "main"
   pull_request:
+    paths:
+      - "**.js"
+      - "**.ts"
+      - "package.json"
+      - "yarn.lock"
+      - "eslint.config.js"
+      - ".prettierrc"
+      - ".prettierignore"
+      - "knip.json"
+      - "tsconfig.json"
+      - "jest.config.js"
+      - ".github/workflows/node.yml"
+  workflow_dispatch:
 
 concurrency:
   # Pushing new changes to a branch will cancel any in-progress CI runs
@@ -58,6 +71,76 @@ jobs:
 
       - name: TypeScript type check
         run: yarn type-check
+
+      # We only download and run Actionlint if there is any difference in GitHub Action workflows
+      # https://github.com/rhysd/actionlint/blob/main/docs/usage.md#on-github-actions
+      # Note: Only runs on pull_request events, not push events (where github.event.pull_request is null)
+      - name: Check GitHub Action changes
+        if: github.event_name == 'pull_request'
+        id: check-workflows
+        run: |
+          git fetch origin ${{ github.event.pull_request.base.sha }}
+          if git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.sha }} | grep -q '^.github/workflows'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            response=$(curl -sf https://api.github.com/repos/rhysd/actionlint/releases/latest)
+            if [ $? -eq 0 ]; then
+              actionlint_version=$(echo "$response" | jq -r .tag_name)
+              if [ -z "$actionlint_version" ]; then
+                echo "Failed to parse Actionlint version"
+                exit 1
+              fi
+              echo "actionlint_version=\"$actionlint_version\"" >> "$GITHUB_OUTPUT"
+            fi
+          fi
+      - name: Setup Actionlint
+        if: github.event_name == 'pull_request' && steps.check-workflows.outputs.changed == 'true'
+        uses: actions/cache@v4
+        id: cache-actionlint
+        with:
+          path: ./actionlint
+          key: ${{ runner.os }}-actionlint-${{ steps.check-workflows.outputs.actionlint_version }}
+      - name: Download Actionlint
+        if: github.event_name == 'pull_request' && steps.check-workflows.outputs.changed == 'true' && steps.cache-actionlint.outputs.cache-hit != 'true'
+        run: bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
+      - name: Lint GitHub Actions
+        if: github.event_name == 'pull_request' && steps.check-workflows.outputs.changed == 'true'
+        run: |
+          echo "::add-matcher::.github/actionlint-matcher.json"
+          SHELLCHECK_OPTS="-S warning" ./actionlint -color
+        shell: bash
+
+  type-check-dts-without-webpack:
+    name: Verify .d.ts files work without webpack
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+
+      - name: Create test directory and copy .d.ts files
+        run: |
+          mkdir -p /tmp/test-types
+          cp package/*.d.ts /tmp/test-types/
+          # types.ts is imported by index.d.ts; copy if it exists
+          cp package/types.ts /tmp/test-types/ 2>/dev/null || true
+
+      - name: Install TypeScript in test directory
+        run: |
+          cd /tmp/test-types
+          npm init -y
+          npm install typescript @types/node
+
+      - name: Verify hand-written .d.ts files type-check without webpack
+        run: |
+          cd /tmp/test-types
+          npx tsc --noEmit \
+            --skipLibCheck \
+            --moduleResolution node \
+            *.d.ts
   test:
     name: Testing
     strategy:

data/.github/workflows/ruby.yml

@@ -5,6 +5,17 @@ on:
     branches:
       - "main"
   pull_request:
+    paths:
+      - "**.rb"
+      - "**.gemspec"
+      - "Gemfile"
+      - "Rakefile"
+      - "gemfiles/**"
+      - ".rubocop.yml"
+      - "package.json"
+      - "**.ts"
+      - ".github/workflows/ruby.yml"
+  workflow_dispatch:
 
 concurrency:
   # Pushing new changes to a branch will cancel any in-progress CI runs

data/.github/workflows/test-bundlers.yml

@@ -2,8 +2,18 @@ name: Test Both Bundlers
 
 on:
   pull_request:
+    paths:
+      - "spec/dummy/**"
+      - "lib/**"
+      - "**.rb"
+      - "**.js"
+      - "**.ts"
+      - "package.json"
+      - "yarn.lock"
+      - ".github/workflows/test-bundlers.yml"
   push:
     branches: [master, main]
+  workflow_dispatch:
 
 jobs:
   test-webpack:

data/CHANGELOG.md

@@ -9,8 +9,20 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Extended manifest merging for multiple client configurations to all environments. [PR #800](https://github.com/shakacode/shakapacker/pull/800) by [Judahmeek](https://github.com/Judahmeek).
+
 Changes since the last non-beta release.
 
+### Added
+
+- **Support for `css_modules_export_mode` configuration option**. [PR #817](https://github.com/shakacode/shakapacker/pull/817) by [justin808](https://github.com/justin808). Adds `css_modules_export_mode` setting in `shakapacker.yml` to control CSS Modules export style. Set to `"named"` (default, v9+ behavior with true named exports) or `"default"` (v8 behavior with default export object). Allows teams to opt into v8-style exports for easier migration from v8 or when using TypeScript with strict type checking.
+- **`Configuration#data` public API method** with enhanced documentation and safety. [PR #820](https://github.com/shakacode/shakapacker/pull/820) by [justin808](https://github.com/justin808). The `Configuration#data` method is now part of the public Ruby API, providing stable access to raw configuration data. Returns a frozen hash with symbolized keys to prevent accidental mutations. Includes comprehensive test coverage and detailed RDoc documentation.
+- **Support for `javascript_transpiler: 'none'`** for completely custom webpack configurations. [PR #799](https://github.com/shakacode/shakapacker/pull/799) by [justin808](https://github.com/justin808). Allows users with custom webpack configs to skip Shakapacker's transpiler setup and validation by setting `javascript_transpiler: 'none'` in `shakapacker.yml`. Useful when managing transpilation entirely outside of Shakapacker's defaults.
+
+## [v9.3.0] - November 2, 2025
+
 ### Fixed
 
 - **Enhanced error handling for better security and debugging**. [PR #786](https://github.com/shakacode/shakapacker/pull/786) by [justin808](https://github.com/justin808).
@@ -29,8 +41,9 @@ Changes since the last non-beta release.
   - Eliminates confusing warning about `useContentHash: false` not being allowed in production
   - Development environment now explicitly sets `useContentHash: false` for faster builds
   - Production no longer needs explicit override since it inherits the correct default
-
-## [v9.3.0] - October 28, 2025
+- Fixed Rails constant error when using custom environments like staging. [PR #681](https://github.com/shakacode/shakapacker/pull/681) by [justin808](https://github.com/justin808). `RAILS_ENV=staging` no longer causes "uninitialized constant Shakapacker::Instance::Rails" error. Shakapacker now works in non-Rails contexts.
+- Fixed TypeScript type definitions to export proper types instead of `any`. [PR #684](https://github.com/shakacode/shakapacker/pull/684) by [justin808](https://github.com/justin808). Previously `package/index.d.ts` was exporting all types as `any`, breaking IDE autocomplete. Now properly exports typed interfaces.
+- Fixed integrity config handling and sass-loader version check. [PR #688](https://github.com/shakacode/shakapacker/pull/688) by [justin808](https://github.com/justin808). Properly handles subresource integrity configuration and correctly detects sass-loader version for conditional logic.
 
 ### Added
 
@@ -62,12 +75,6 @@ Changes since the last non-beta release.
 - **Improved error messages** to suggest `assets_bundler_config_path`. [PR #712](https://github.com/shakacode/shakapacker/pull/712) by [justin808](https://github.com/justin808). More helpful error messages when bundler config is not found, suggesting use of `assets_bundler_config_path` for custom locations.
 - **Improved doctor command output** clarity and accuracy. [PR #682](https://github.com/shakacode/shakapacker/pull/682) by [justin808](https://github.com/justin808). Better formatting and organization of diagnostic information with more actionable recommendations.
 
-### Fixed
-
-- Fixed Rails constant error when using custom environments like staging. [PR #681](https://github.com/shakacode/shakapacker/pull/681) by [justin808](https://github.com/justin808). `RAILS_ENV=staging` no longer causes "uninitialized constant Shakapacker::Instance::Rails" error. Shakapacker now works in non-Rails contexts.
-- Fixed TypeScript type definitions to export proper types instead of `any`. [PR #684](https://github.com/shakacode/shakapacker/pull/684) by [justin808](https://github.com/justin808). Previously `package/index.d.ts` was exporting all types as `any`, breaking IDE autocomplete. Now properly exports typed interfaces.
-- Fixed integrity config handling and sass-loader version check. [PR #688](https://github.com/shakacode/shakapacker/pull/688) by [justin808](https://github.com/justin808). Properly handles subresource integrity configuration and correctly detects sass-loader version for conditional logic.
-
 ## [v9.2.0] - October 9, 2025
 
 ### Added

data/CLAUDE.md

@@ -29,16 +29,12 @@
 
 ## Changelog
 
-- **Update CHANGELOG.md for user-visible changes only**
-- User-visible changes include: new features, bug fixes, breaking changes, deprecations, performance improvements
-- **Do NOT add changelog entries for**: linting fixes, code formatting, internal refactoring, test updates, documentation fixes
-- Non-user-visible changes don't need changelog entries even if they modify code
-- **Format requirements**:
-  - Always link to the PR: `[PR #123](https://github.com/shakacode/shakapacker/pull/123)`
-  - Always link to the author: `by [username](https://github.com/username)`
-  - Keep formatting consistent with existing entries
-  - When releasing a version, update the version diff links at the bottom of CHANGELOG.md
-  - **For breaking changes**: Use bold formatting and link to migration documentation (e.g., `**Breaking**: Description. See [Migration Guide](docs/vX_upgrade.md)`)
+- **Update CHANGELOG.md for user-visible changes only** (features, bug fixes, breaking changes, deprecations, performance improvements)
+- **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
+- **Examples**: Run `grep -A 3 "^### " CHANGELOG.md | head -30` to see real formatting examples
 
 ## Shakapacker-Specific
 

data/CONTRIBUTING.md

@@ -103,11 +103,36 @@ Shakapacker uses optional peer dependencies (via `peerDependenciesMeta`) for max
 - **No installation warnings** - Package managers won't warn about missing optional dependencies
 - **Version constraints still apply** - When a package is installed, version compatibility is enforced
 
+### TypeScript Declaration Files and Optional Dependencies
+
+When importing types from optional peer dependencies, we use `@ts-expect-error` directives:
+
+```typescript
+// @ts-expect-error: webpack is an optional peer dependency (using type-only import)
+import type { Configuration } from "webpack"
+```
+
+**Important behavior:**
+
+- **In development** (webpack installed): TypeScript doesn't error, but `@ts-expect-error` expects one → TypeScript compilation will fail
+- **In production** (webpack not installed): TypeScript errors on import, `@ts-expect-error` suppresses it → TypeScript compilation succeeds
+
+This is counterintuitive but correct. Our CI validates both scenarios to ensure the behavior works as expected.
+
+**Example scenario:**
+
+If webpack were changed from optional to required in `package.json`:
+
+- Development builds would fail with: `error TS2578: Unused '@ts-expect-error' directive`
+- This surfaces the dependency change immediately, preventing accidental breakage
+- The build failure prompts developers to remove the `@ts-expect-error` directive
+
 ### When modifying dependencies:
 
 1. Add new peer dependencies to both `peerDependencies` and `peerDependenciesMeta` (marking as optional)
 2. Keep version ranges synchronized between `devDependencies` and `peerDependencies`
 3. Test with multiple package managers: `npm`, `yarn`, and `pnpm`
+4. If adding type-only imports from optional dependencies, use the `@ts-expect-error` pattern shown above
 
 ### Testing peer dependency changes:
 
@@ -223,6 +248,8 @@ The project uses Yarn in CI workflows for the following reasons:
 - `.github/workflows/ruby.yml` - Ruby test suite across Ruby/Rails versions
 - `.github/workflows/node.yml` - Node.js test suite across Node versions
 - `.github/workflows/generator.yml` - Generator installation tests
+- `.github/workflows/dummy.yml` - Dummy app integration tests
+- `.github/workflows/eslint-validation.yml` - ESLint configuration validation
 
 All workflows use:
 
@@ -239,6 +266,36 @@ And install dependencies with:
 yarn install
 ```
 
+### CI Optimization: Path Filtering
+
+To reduce CI costs and execution time, workflows use **path filtering** to run only when relevant files change:
+
+- **Ruby workflow** - Only runs when Ruby files, gemspecs, Gemfile, or RuboCop config changes
+- **Node workflow** - Only runs when JS/TS files, package.json, or Node config changes
+- **Generator specs** - Only runs when generator-related files change
+- **Dummy specs** - Only runs when dummy app or lib files change
+- **Test bundlers** - Only runs when code affecting bundler integration changes
+
+This means documentation-only PRs (e.g., only changing `README.md`) will skip all test workflows entirely.
+
+**Important:** The full test suite always runs on pushes to the `main` branch to ensure the main branch is always thoroughly tested.
+
+### Manual Workflow Execution
+
+All workflows can be triggered manually via the GitHub Actions UI using the "Run workflow" button. This is useful for:
+
+- Re-running tests after a temporary CI failure
+- Testing workflows on specific branches without creating a PR
+- Running full test suites on PRs that would normally skip certain workflows
+
+### Conditional Linting
+
+The Node workflow includes conditional execution of actionlint (GitHub Actions linter):
+
+- Only downloads and runs when `.github/workflows/*` files change
+- Saves time by skipping on most PRs
+- Includes caching for faster execution when needed
+
 ### Testing with Other Package Managers
 
 While CI uses Yarn, the gem supports all major package managers (npm, yarn, pnpm, bun). Generator specs test against all package managers to ensure compatibility.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shakapacker (9.3.0)
+    shakapacker (9.3.1)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)