shakapacker 7.3.0.beta.1 → 8.0.0.rc.2

data/README.md

@@ -1,8 +1,9 @@
-# Shakapacker (v7)
+# Shakapacker (v8)
 
 _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._
 
 * ⚠️ See the [6-stable](https://github.com/shakacode/shakapacker/tree/6-stable) branch for Shakapacker v6.x code and documentation. :warning:
+* See [V8 Upgrade](./docs/v8_upgrade.md) for upgrading from the v7 release.
 * See [V7 Upgrade](./docs/v7_upgrade.md) for upgrading from the v6 release.
 * See [V6 Upgrade](./docs/v6_upgrade.md) for upgrading from v5 or prior v6 releases.
 
@@ -51,8 +52,6 @@ Read the [full review here](https://clutch.co/profile/shakacode#reviews?sort_by=
     - [Optional support](#optional-support)
   - [Installation](#installation)
     - [Rails v6+](#rails-v6)
-    - [Using alternative package managers](#using-alternative-package-managers)
-    - [Note for Yarn v2 usage](#note-for-yarn-v2-usage)
   - [Concepts](#concepts)
   - [Usage](#usage)
     - [Configuration and Code](#configuration-and-code)
@@ -98,16 +97,16 @@ Read the [full review here](https://clutch.co/profile/shakacode#reviews?sort_by=
 
 ## Prerequisites
 
-- Ruby 2.6+
+- Ruby 2.7+
 - Rails 5.2+
-- Node.js 12.13.0+ || 14+
-- Yarn
+- Node.js 14+
 
 ## Features
 - Rails view helpers that fully support Webpack output, including HMR and code splitting.
 - Convenient but not required webpack configuration. The only requirement is that your webpack configuration creates a manifest.
 - HMR with the `shakapacker-dev-server`, such as for hot-reloading React!
 - Automatic code splitting using multiple entry points to optimize JavaScript downloads.
+- Support for [NPM](https://www.npmjs.com/package/npm), Yarn ([classic](https://classic.yarnpkg.com/lang/en/) and [berry](https://yarnpkg.com/getting-started)), [PNPM](https://pnpm.io/), and [Bun](https://bun.sh/)
 - [Webpack v5+](https://webpack.js.org/)
 - ES6 with [babel](https://babeljs.io/), [SWC](https://swc.rs/), or [Esbuild](https://github.com/privatenumber/esbuild-loader)
 - Asset compression, source-maps, and minification
@@ -147,40 +146,45 @@ Then run the following to install Shakapacker:
 
 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.
 
-When `package.json` and/or `yarn.lock` changes, such as when pulling down changes to your local environment in team settings, be sure to keep your NPM packages up-to-date:
+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`.
 
-```bash
-yarn
-```
-
-Note, in v6+, most JS packages are peer dependencies. Thus, the installer will add the packages:
-
-```bash
-yarn add @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.
-
-### Using alternative package managers
+If `packageManager` is not set when running `shakapacker:install`, Shakapacker will set it based on the lockfile and the result of calling `--version` on the inferred manager; if no lockfile is present, then `npm` be used unless you choose to explicitly set the `PACKAGE_JSON_FALLBACK_MANAGER` to your preferred package manager.
 
-There is experimental support for using package managers besides Yarn classic for managing JavaScript dependencies using the [`package_json`](https://github.com/G-Rath/package_json) gem.
-
-This can be enabled by setting the environment variable `SHAKAPACKER_USE_PACKAGE_JSON_GEM` to `true`; Shakapacker will then use the `package_json` gem which in turn will look for the [`packageManager`](https://nodejs.org/api/packages.html#packagemanager) property in the `package.json` or otherwise the `PACKAGE_JSON_FALLBACK_MANAGER` environment variable to determine which manager to use, defaulting to `npm` if neither are found.
+> **Note**
+>
+> The `packageManager` property is only used to determine the package manager to use, based primarily on its name.
+> The version (if present) is only used to determine if Yarn Classic or Yarn Berry should be used, but is otherwise
+> _not_ checked, nor is [`corepack`](https://nodejs.org/api/corepack.html) used to ensure that the package manager is installed.
+>
+> It is up to the developer to ensure that the desired package manager is actually install at the right version, which can be done
+> using `corepack` or by other means.
 
 See [here](https://github.com/G-Rath/package_json#specifying-a-package-manager) for a list of the supported package managers and more information; note that `package_json` does not handle ensuring the manager is installed.
 
-> **Note**
-> 
-> The rest of the documentation assumes that `package_json` is not being used, and so always references `yarn` - you should instead use the package manager of your choice for these commands.  
+> [NOTE]
+>
+> The rest of the documentation will only reference `npm` when providing commands such as to install optional packages except in cases where
+> 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 for Yarn v2 usage
+Note, in v6+, most JS packages are peer dependencies. Thus, the installer will add the packages:
 
-If you are using Yarn v2 (berry), please note that PnP modules are not supported unless you're using `SHAKAPACKER_USE_PACKAGE_JSON_GEM`.
+- `@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`
 
-To use Shakapacker with Yarn v2, make sure you set `nodeLinker: node-modules` in your `.yarnrc.yml` file as per the [Yarn docs](https://yarnpkg.com/getting-started/migration#step-by-step) to opt out of Plug'n'Play behavior.
+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.
 
 ## Concepts
 
@@ -578,8 +582,11 @@ console.log(JSON.stringify(webpackConfig, undefined, 2))
 You may want to modify the rules in the default configuration. For instance, if you are using a custom svg loader, you may want to remove `.svg` from the default file loader rules. You can search and filter the default rules like so:
 
 ```js
-const svgRule = config.module.rules.find(rule => rule.test.test('.svg'));
-svgRule.test = svgRule.test.filter(t => !t.test('.svg'))
+const fileRule = config.module.rules.find(rule => rule.test.test('.svg'));
+// removing svg from asset file rule's test RegExp
+fileRule.test = /\.(bmp|gif|jpe?g|png|tiff|ico|avif|webp|eot|otf|ttf|woff|woff2)$/
+// changing the rule type from 'asset/resource' to 'asset'. See https://webpack.js.org/guides/asset-modules/
+fileRule.type = 'asset'
 ```
 
 ### Babel configuration
@@ -621,13 +628,13 @@ See also [Customizing Babel Config](./docs/customizing_babel_config.md) for an e
 #### TypeScript
 
 ```bash
-yarn add typescript @babel/preset-typescript
+npm install typescript @babel/preset-typescript
 ```
 
 Babel won’t perform any type-checking on TypeScript code. To optionally use type-checking run:
 
 ```bash
-yarn add fork-ts-checker-webpack-plugin
+npm install fork-ts-checker-webpack-plugin
 ```
 
 Add tsconfig.json
@@ -668,7 +675,7 @@ module.exports = generateWebpackConfig({
 To enable CSS support in your application, add the following packages:
 
 ```bash
-yarn add css-loader style-loader mini-css-extract-plugin css-minimizer-webpack-plugin
+npm install css-loader style-loader mini-css-extract-plugin css-minimizer-webpack-plugin
 ```
 
 Optionally, add the `CSS` extension to webpack config for easy resolution.
@@ -692,36 +699,55 @@ then add the relevant pre-processors:
 #### Postcss
 
 ```bash
-yarn add postcss postcss-loader
+npm install postcss postcss-loader
 ```
 
 Optionally add these two plugins if they are required in your `postcss.config.js`:
 ```bash
-yarn add postcss-preset-env postcss-flexbugs-fixes
+npm install postcss-preset-env postcss-flexbugs-fixes
 ```
 
 #### Sass
 
 ```bash
-yarn add sass sass-loader
+npm install sass-loader
+```
+
+You will also need to install [Dart Sass](https://github.com/sass/dart-sass), [Node Sass](https://github.com/sass/node-sass) or [Sass Embedded](https://github.com/sass/embedded-host-node) to pick the implementation to use. sass-loader will automatically pick an implementation based on installed packages.
+
+Please refer to [sass-loader documentation](https://www.npmjs.com/package/sass-loader) and individual packages repos for more information on all the options.
+
+##### Dart Sass
+```bash
+npm install sass
+```
+
+##### Node Sass
+```bash
+npm install node-sass
+```
+
+##### Sass Embedded
+```bash
+npm install sass-embedded
 ```
 
 #### Less
 
 ```bash
-yarn add less less-loader
+npm install less less-loader
 ```
 
 #### Stylus
 
 ```bash
-yarn add stylus stylus-loader
+npm install stylus stylus-loader
 ```
 
 #### CoffeeScript
 
 ```bash
-yarn add coffeescript coffee-loader
+npm install coffeescript coffee-loader
 ```
 
 #### Other frameworks
@@ -821,16 +847,24 @@ bundle update shakapacker
 # overwrite your changes to the default install files and revert any unwanted changes from the install
 rails shakapacker:install
 
-# yarn 1 instructions
+# using npm
+npm install shakapacker@latest
+npm install webpack-dev-server@latest
+
+# using yarn classic
 yarn upgrade shakapacker --latest
 yarn upgrade webpack-dev-server --latest
 
-# yarn 2 instructions
+# using yarn berry
 yarn up shakapacker@latest
 yarn up webpack-dev-server@latest
 
+# using pnpm
+pnpm up shakapacker@latest
+pnpm up webpack-dev-server@latest
+
 # Or to install the latest release (including pre-releases)
-yarn add shakapacker@next
+npm install shakapacker@next
 ```
 
 Also, consult the [CHANGELOG](./CHANGELOG.md) for additional upgrade links.
@@ -880,7 +914,9 @@ import 'stylesheets/main'
 import 'images/rails.png'
 ```
 
-Assets put in these folders will have their directory stripped just like with the `source_path`. For example:
+Assets put in these folders will also have their path stripped just like with the `source_path`.
+
+Example:
 
 A file in `app/assets/images/image.svg` with `additional_paths: ['app/assets']` will result in `static/images/image.svg`
 
@@ -895,7 +931,24 @@ Shakapacker hooks up a new `shakapacker:compile` task to `assets:precompile`, wh
 
 This behavior is optional & can be disabled by either setting a `SHAKAPACKER_PRECOMPILE` environment variable to `false`, `no`, `n`, or `f`, or by setting a `shakapacker_precompile` key in your `shakapacker.yml` to `false`. ([source code](./lib/shakapacker/configuration.rb#L34))
 
-When compiling assets for production on a remote server, such as a continuous integration environment, it's recommended to use `yarn install --frozen-lockfile` to install NPM packages on the remote host to ensure that the installed packages match the `yarn.lock` file.
+When compiling assets for production on a remote server, such as a continuous integration environment, it's recommended to ensure the exact versions specified in your lockfile are installed:
+
+```
+# using npm
+npm ci
+
+# using yarn classic
+yarn install --frozen-lockfile
+
+# using yarn berry
+yarn install --immutable
+
+# using pnpm
+pnpm install --frozen-lockfile
+
+# using bun
+bun install --frozen-lockfile
+```
 
 If you are using a CDN setup, Shakapacker does NOT use the `ASSET_HOST` environment variable to prefix URLs for assets during bundle compilation. You must use the `SHAKAPACKER_ASSET_HOST` environment variable instead (`WEBPACKER_ASSET_HOST` if you're using any version of Webpacker or Shakapacker before Shakapacker v7).
 

data/Rakefile

@@ -14,12 +14,6 @@ namespace :run_spec do
     sh("bundle exec rspec spec/shakapacker/*_spec.rb")
   end
 
-  desc "Run backward compatibility specs"
-  task :gem_bc do
-    puts "Running Shakapacker gem specs for backward compatibility"
-    sh("bundle exec rspec spec/backward_compatibility_specs/*_spec.rb")
-  end
-
   desc "Run specs in the dummy app"
   task :dummy do
     puts "Running dummy app specs"
@@ -41,7 +35,7 @@ namespace :run_spec do
   end
 
   desc "Run all specs"
-  task all_specs: %i[gem gem_bc dummy generator] do
+  task all_specs: %i[gem dummy generator] do
     puts "Completed all RSpec tests"
   end
 end

data/docs/customizing_babel_config.md

@@ -20,8 +20,8 @@ This example shows how you can create an object and apply _additional_ presets a
 To use this example file,
 
 ```
-yarn add react react-dom @babel/preset-react
-yarn add --dev @pmmmwh/react-refresh-webpack-plugin react-refresh
+npm install react react-dom @babel/preset-react
+npm install --dev @pmmmwh/react-refresh-webpack-plugin react-refresh
 ```
 
 ```js

data/docs/deployment.md

@@ -24,7 +24,7 @@ We're essentially doing the following here:
 * Adding the Heroku NodeJS and Ruby buildpacks for your app. This allows the `npm` or `yarn` executables to properly function when compiling your app - as well as Ruby.
 * Pushing your code to Heroku and kicking off the deployment
 
-Your production build process is responsible for running `yarn install` before `rake assets:precompile`. For example, if you are on Heroku, the `heroku/nodejs` buildpack must run **prior** to the `heroku/ruby` buildpack for precompilation to run successfully.
+Your production build process is responsible for installing your JavaScript dependencies before `rake assets:precompile`. For example, if you are on Heroku, the `heroku/nodejs` buildpack must run **prior** to the `heroku/ruby` buildpack for precompilation to run successfully.
 
 ## Nginx
 
@@ -100,18 +100,25 @@ Make sure you have your public output path (default `public/packs`), the shakapa
 append :linked_dirs, "log", "tmp/pids", "tmp/cache", "tmp/sockets", "tmp/shakapacker", "public/packs", ".bundle", "node_modules"
 ```
 
-If you have `node_modules` added to `:linked_dirs` you'll need to run yarn install before `deploy:assets:precompile`, so you can add this code snippet at the bottom deploy.rb
+If you have `node_modules` added to `:linked_dirs` you'll need to install your JavaScript dependencies before `deploy:assets:precompile`; you can use `package_json` to do this generically:
 
 ```ruby
-before "deploy:assets:precompile", "deploy:yarn_install"
+before "deploy:assets:precompile", "deploy:js_install"
 namespace :deploy do
-  desc "Run rake yarn install"
-  task :yarn_install do
+  desc "Run rake js install"
+  task :js_install do
+    require "package_json"
+    
+    # this will use the package manager specified via `packageManager`, or otherwise fallback to `npm`
+    native_js_install_command = PackageJson.read.manager.native_install_command(frozen: true).join(" ")
+    
     on roles(:web) do
       within release_path do
-        execute("cd #{release_path} && yarn install --silent --no-progress --no-audit --no-optional")
+        execute("cd #{release_path} && #{native_js_install_command}")
       end
     end
   end
 end
 ```
+
+You can also replace the use of `package_json` with the underlying native install command for your preferred package manager.

data/docs/react.md

@@ -2,12 +2,6 @@
 
 These steps describe creating a Rails/React app, using Shakapacker as the bundler.
 
-Before starting, ensure that you have Yarn installed, for example:
-
-```shell
-npm i -g yarn
-```
-
 ## Easy Setup
 If you'd like easy integration of React with Ruby on Rails, see [React on Rails](https://github.com/shakacode/react_on_rails).
 
@@ -24,8 +18,8 @@ Create a new Rails app as per the [installation instructions in the README](http
 Add React, as well as the necessary libraries to enable CSS support in your application:
 
 ```shell
-yarn add react react-dom @babel/preset-react
-yarn add css-loader style-loader mini-css-extract-plugin css-minimizer-webpack-plugin
+npm install react react-dom @babel/preset-react
+npm install css-loader style-loader mini-css-extract-plugin css-minimizer-webpack-plugin
 ```
 
 Update the Babel configuration in the `package.json` file:
@@ -52,7 +46,7 @@ In `config/shakapacker.yml` set `hmr` is set to `true`.
 Install the [react-refresh](https://www.npmjs.com/package/react-refresh) package, as well as [@pmmmwh/react-refresh-webpack-plugin](https://www.npmjs.com/package/@pmmmwh/react-refresh-webpack-plugin):
 
 ```shell
-yarn add --dev react-refresh @pmmmwh/react-refresh-webpack-plugin
+npm install --dev react-refresh @pmmmwh/react-refresh-webpack-plugin
 ```
 
 Alter `config/webpack/webpack.config.js` like so:
@@ -142,8 +136,8 @@ cd myapp
 bundle add shakapacker --strict
 ./bin/bundle install
 ./bin/rails shakapacker:install
-yarn add react react-dom @babel/preset-react
-yarn add css-loader style-loader mini-css-extract-plugin css-minimizer-webpack-plugin
+npm install react react-dom @babel/preset-react
+npm install css-loader style-loader mini-css-extract-plugin css-minimizer-webpack-plugin
 ```
 
 2. Generate a controller
@@ -192,7 +186,7 @@ hmr: true
 8. Install the [react-refresh](https://www.npmjs.com/package/react-refresh) package, as well as [@pmmmwh/react-refresh-webpack-plugin](https://www.npmjs.com/package/@pmmmwh/react-refresh-webpack-plugin):
 
 ```shell
-yarn add --dev react-refresh @pmmmwh/react-refresh-webpack-plugin
+npm install --dev react-refresh @pmmmwh/react-refresh-webpack-plugin
 ```
 
 9. Alter `config/webpack/webpack.config.js` like so:
@@ -226,7 +220,7 @@ module.exports = webpackConfig;
 - },
 ```
 
-11. Create a `babel.config.js` file in the project root and add the following [sample code](https://github.com/shakacode/shakapacker/blob/master/docs/customizing_babel_config.md#react-configuration):
+11. Create a `babel.config.js` file in the project root and add the following [sample code](https://github.com/shakacode/shakapacker/blob/main/docs/customizing_babel_config.md#react-configuration):
 ```js
 module.exports = function (api) {
   const defaultConfigFunc = require('shakapacker/package/babel/preset.js')

data/docs/troubleshooting.md

@@ -18,9 +18,9 @@
 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`
 
 ## Incorrect peer dependencies
-The latest version of Shakapacker uses peer dependencies to make upgrading easier. However, there's a catch.
-
-If you fail to update peer dependencies, you'll see an easy-to-overlook warning from `yarn install`. 
+Shakapacker uses peer dependencies to make it easier to manage what versions are being used for your app, which is especially
+useful for patching security vulnerabilities. However, not all package managers will actually enforce these versions - notably,
+Yarn will omit a warning rather than erroring if you forget to update a peer dependency:
 
 ```
 warning " > shakapacker@6.1.1" has incorrect peer dependency "compression-webpack-plugin@^9.0.0".
@@ -31,7 +31,7 @@ This omission resulted in an error in the browser:
 Failed to load resource: net::ERR_CONTENT_DECODING_FAILED
 ```
 
-The error was caused by an old version of the peer dependency webpack-compression-plugin.
+The error was caused by an old version of the peer dependency `webpack-compression-plugin`.
 
 So, be sure to investigate warnings from `yarn install`!
 

data/docs/using_esbuild_loader.md

@@ -24,7 +24,7 @@ To use esbuild as your transpiler today. You need to do two things:
 1. Make sure you've installed `esbuild` and `esbuild-loader` packages.
 
 ```
-yarn add esbuild esbuild-loader
+npm install esbuild esbuild-loader
 ```
 
 2. Add or change `shakapacker_loader` value in your default `shakapacker.yml` config to `esbuild`

data/docs/using_swc_loader.md

@@ -19,7 +19,7 @@ In order to use SWC as your compiler today. You need to do two things:
 1. Make sure you've installed `@swc/core` and `swc-loader` packages.
 
 ```
-yarn add @swc/core swc-loader
+npm install @swc/core swc-loader
 ```
 
 2. Add or change `webpack_loader` value in your default `shakapacker.yml` config to `swc`

data/docs/v6_upgrade.md

@@ -140,7 +140,7 @@ _If you're on webpacker v5, follow [how to upgrade to webpacker v6.0.0.rc.6 from
    ```
    See customization example the [Customizing Babel Config](./customizing_babel_config.md) for React configuration.
 
-1. `extensions` was removed from the `webpacker.yml` file. Move custom extensions to your configuration by merging an object like this. For more details, see docs for [Webpack Configuration](https://github.com/shakacode/shakapacker/blob/master/README.md#webpack-configuration)
+1. `extensions` was removed from the `webpacker.yml` file. Move custom extensions to your configuration by merging an object like this. For more details, see docs for [Webpack Configuration](https://github.com/shakacode/shakapacker/blob/main/README.md#webpack-configuration)
 
    ```js
    {

data/docs/v8_upgrade.md

@@ -0,0 +1,148 @@
+# Upgrading from Shakapacker v7 to v8
+
+The majority of the breaking changes in v8 were about dropping deprecated
+functions and features, along with switching to be agnostic about what package
+manager is used to manage JavaScript dependencies.
+
+Support for Ruby 2.6 and Node v12 has also been dropped since they're very old
+at this point.
+
+## The `packageManager` property in `package.json` is used to determine the package manager
+
+The biggest functional change in v8, `shakapacker` is now able to work with any
+of the major JavaScript package managers thanks to the
+[`package_json`](https://github.com/shakacode/package_json) gem which uses the
+[`packageManager`](https://nodejs.org/api/packages.html#packagemanager) property
+in the `package.json`.
+
+In alignment with the behaviour of Node and `corepack`, in the absence of the
+`packageManager` property `npm` will be used as the package manager so as part
+of upgrading you will want to ensure that is set to `yarn@<version>` if you want
+to continue using Yarn.
+
+An error will be raised in the presences of a lockfile other than
+`package-lock.json` if this property is not set with the recommended value to
+use, but it important the property is set to ensure all tooling uses the right
+package manager.
+
+The `check_yarn` rake task has also been renamed to `check_manager` to reflect
+this change.
+
+Check out the [installation section](../README.md#installation) of the readme
+for more details.
+
+## Usages of `webpacker` must now be `shakapacker`
+
+The `webpacker` spelling was deprecated in v7 and has now been completely
+removed in v8 - this includes constants, environment variables, and rake tasks.
+
+If you are still using references to `webpacker`, see the
+[v7 Upgrade Guide](../docs/v7_upgrade.md) for how to migrate.
+
+## JavaScript dependencies are no longer installed automatically as part of `assets:precompile`
+
+You will now need to ensure your dependencies are installed before compiling
+assets.
+
+Some platforms like Heroku will install dependencies automatically but if you're
+using a tool like `capistrano` to deploy to servers you can enhance the
+`assets:precompile` command like so:
+
+```ruby
+namespace :assets do
+  desc "Ensures that dependencies required to compile assets are installed"
+  task install_dependencies: :environment do
+    # npm v6+
+    raise if File.exist?("package.json") && !(system "npm ci")
+
+    # yarn v1.x (classic)
+    raise if File.exist?("package.json") && !(system "yarn install --immutable")
+
+    # yarn v2+ (berry)
+    raise if File.exist?("package.json") && !(system "yarn install --frozen-lockfile")
+
+    # bun v1+
+    raise if File.exist?("package.json") && !(system "bun install --frozen-lockfile")
+
+    # pnpm v6+
+    raise if File.exist?("package.json") && !(system "pnpm install --frozen-lockfile")
+  end
+end
+
+Rake::Task["assets:precompile"].enhance ["assets:install_dependencies"]
+```
+
+This allows more flexibility than what `shakapacker` could provide - for
+example, you might only want to do an immutable install if you're in CI.
+
+## `ensure_consistent_versioning` is now enabled by default
+
+This has `shakapacker` check that the versions of the installed Ruby gem and
+JavaScript package are compatible; this should only be impactful for codebases
+that are not using lockfiles.
+
+## Usages of `globalMutableWebpackConfig` must be replaced with `generateWebpackConfig()`
+
+The function will return the same object with less risk:
+
+```js
+// before
+const { globalMutableWebpackConfig, merge } = require('shakapacker');
+
+const customConfig = {
+  module: {
+    rules: [
+      {
+        test: require.resolve('jquery'),
+        loader: 'expose-loader',
+        options: { exposes: ['$', 'jQuery'] }
+      }
+    ]
+  }
+};
+
+module.exports = merge(globalMutableWebpackConfig, customConfig);
+```
+
+```js
+// after
+const { generateWebpackConfig } = require('shakapacker');
+
+const customConfig = {
+  module: {
+    rules: [
+      {
+        test: require.resolve('jquery'),
+        loader: 'expose-loader',
+        options: { exposes: ['$', 'jQuery'] }
+      }
+    ]
+  }
+};
+
+// you can also pass your config directly to the generator function to have it merged in!
+module.exports = merge(generateWebpackConfig(), customConfig);
+```
+
+## `additional_paths` are now stripped just like with `source_path`
+
+This means going forward asset paths should be same regardless of their source:
+
+```erb
+<%# before %>
+<%= image_pack_tag('marketing/images/people_looking_happy.png') %>
+
+<%# after %>
+<%= image_pack_tag('image/people_looking_happy.png') %>
+```
+
+## Misc. removals
+
+In addition to the above, v8 has also removed a number of miscellaneous
+functions that no one is probably using anyway but technically could have been
+including:
+
+- `isArray` js utility function (just use `Array.isArray` directly)
+- `relative_url_root` config getter (it was never used)
+- `verify_file_existance` method (use `verify_file_existence` instead)
+- `https` option for `webpack-dev-server` (use `server: 'https'` instead)

data/gemfiles/Gemfile-rails.7.1.x

@@ -0,0 +1,12 @@
+source "https://rubygems.org"
+
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
+gemspec path: "../"
+
+gem "rails", '~>7.1.0'
+gem "arel", github: "rails/arel"
+gem "rake", ">= 11.1"
+gem "rack-proxy", require: false
+gem "rspec-rails", "~> 6.0.0"
+gem "byebug"

data/jest.config.js

@@ -0,0 +1,4 @@
+module.exports = {
+  roots: ["<rootDir>/test"],
+  testPathIgnorePatterns: ["/__fixtures__/", "/__utils__/"]
+}

data/lib/install/config/shakapacker.yml

@@ -39,8 +39,8 @@ default: &default
   # Select loader to use, available options are 'babel' (default), 'swc' or 'esbuild'
   webpack_loader: 'babel'
 
-  # Set to true to enable check for matching versions of shakapacker gem and NPM package - will raise an error if there is a mismatch or wildcard versioning is used
-  ensure_consistent_versioning: false
+  # Raises an error if there is a mismatch in the shakapacker gem and npm package being used
+  ensure_consistent_versioning: true
 
   # Select whether the compiler will use SHA digest ('digest' option) or most most recent modified timestamp ('mtime') to determine freshness
   compiler_strategy: digest