Update docs for shakapacker (#71)

README.md

@@ -18,6 +18,7 @@ You can configure your bundler options in the `build` script in `package.json` o
 
 If you're already using [`webpacker`](https://github.com/rails/webpacker) and you're wondering if you should migrate to `jsbundling-rails`, have a look at [the high-level comparison](./docs/comparison_with_webpacker.md). If you're looking to migrate from webpacker, see the [migration guide](https://github.com/rails/jsbundling-rails/blob/main/docs/switch_from_webpacker.md).
 
+If you want to use webpack features like [code splitting](https://webpack.js.org/guides/code-splitting/) and [hot module reloading](https://webpack.js.org/concepts/hot-module-replacement/), consider using the official fork of `webpacker`, [`shakapacker`](https://github.com/shakacode/shakapacker).
 
 ## Installation
 

docs/comparison_with_webpacker.md

@@ -1,23 +1,23 @@
-# Comparison with `webpacker`
+# Comparison with `webpacker` (`shakapacker`)
 
-If you're already using [`webpacker`](https://github.com/rails/webpacker), you may be wondering how it compares to `jsbundling-rails` and whether you should migrate or stick with `webpacker`. Here are some considerations:
+If you're already using [`webpacker`](https://github.com/rails/webpacker), you may be wondering how it compares to `jsbundling-rails` and whether you should migrate or migrate to `shakapacker` the official fork of `webpacker`. Note, the `shakapacker` fork still uses `webpacker` name within the project. So the below discussion applies to v6+ of `webpacker`/`shakapacker` vs `jsbundling-rails`.
 
-- `jsbundling-rails` is a much more lightweight integration.
-  `webpacker` is more involved and opinionated.
-- `jsbundling-rails` can be used with multiple bundlers (currently `esbuild`, `rollup`, and `webpack` are supported out of the box, but anything that can put a bundle into `app/assets/builds` could be configured to work with it).
-  `webpacker` is built specifically to integrate with `webpack`.
+Here are some considerations between the two:
+
+- `jsbundling-rails` is a lighter integration. `webpacker` _can be_ more involved and opinionated. The difference is whether or not you use only the view helpers of `shakapacker` or include the webpack configuration setup.
+- `jsbundling-rails` can be used with multiple bundlers (currently `esbuild`, `rollup`, and `webpack` are supported out of the box, but anything that can put a bundle into `app/assets/builds` could be configured to work with it). `webpacker` is built specifically to integrate with `webpack`. That allows `webpacker` to provide support for HMR and bundle splitting. 
 - `jsbundling-rails` doesn't tie you to specific versions of the JavaScript packages you use for bundling, transpiling, etc.
-  `webpacker` releases are tied to a specific major version of `webpack`, `babel`, etc.
-   This means you cannot freely upgrade those packages - you have to wait for a new `webpacker` major release that supports the newer versions, and upgrading to that new `webpacker`  release requires upgrading to all of those new JavaScript package versions at once.
+  `webpacker` releases are also not tied to a specific major version of `webpack`, `babel`, etc. as these are handled because webpacker specifies these as _peer dependencies_.
 - `jsbundling-rails` uses the standard configuration format for your bundler of choice.
-  `webpacker` has its own configuration layer on top of `webpack`'s configuration, which requires you to do some translation when following guides/documentation written directly for `webpack`.
+  `webpacker` has an optional configuration layer on top of `webpack`'s configuration. You don't have to use it. The only requirement of webpacker is that your webpack configuration must produce a manifest.
 - `jsbundling-rails` works with the standard [`actionview` asset helpers](https://api.rubyonrails.org/classes/ActionView/Helpers/AssetUrlHelper.html).
-  `webpacker` provides its own tag helpers that you need to use.
-- `webpacker` can be used as a complete replacement for [`sprockets`](https://github.com/rails/sprockets), and in that setup you can stop loading the `sprockets/railtie` in your application.
-  `jsbundling-rails` (as well as [`css-bundling-rails`](https://github.com/rails/cssbundling-rails)) works in conjunction with `sprockets`.
-- `webpacker` supports using a dev server for hot reloading.
-  `jsbundling-rails` hands off static files to `sprockets`, so hot reloading is not supported (i.e. to load any JavaScript changes, you'll need to do a local-state-clearing full page refresh).
+  `webpacker` provides view helpers with an almost identical API.
+- `webpacker` can be used as a complete replacement for [`sprockets`](https://github.com/rails/sprockets), and in that setup you can stop loading the `sprockets/railtie` in your application. What you produce in the webpack ecosystem is what is sent to the browser.
+  `jsbundling-rails` (as well as [`css-bundling-rails`](https://github.com/rails/cssbundling-rails)) works in conjunction with `sprockets`. Because of this, you need to be sure not to double fingerprint your assets in both `webpack` and `sprockets`. You might also have issues with source maps due to double fingerprinting of output files.
+- `webpacker` supports using the `webpack-dev-server` for hot reloading. HMR enables you to see your changes in the browser almost immediately as you make them, usually without the need to refresh the page or lose your application state. 
+  `jsbundling-rails` hands over static files to `sprockets`, so hot reloading is not supported. To load any JavaScript changes, you'll need to do a local-state-clearing full page refresh.
 - `webpacker` delegates asset processing entirely to the external nodejs tooling.
   `jsbundling-rails` still relies on `sprockets` to output the final `public` assets and create the associated manifest.
-  When `webpack` has full control over the end result, it can integrate additional features like automatic code splitting of statically `import`ed shared dependencies, and `webpacker` can load each entry point's dependent chunks for you.
-  With `jsbundling-rails`, you'll be able to manually split out lazy loaded chunks by using dynamic `import()`s.
+  `webpacker`'s complete control over the resulting webpack output files allow it to integrate additional features like automatic [code splitting](https://webpack.js.org/guides/code-splitting/).  Webpack provides advanced optimization to split your statically `import`ed shared dependencies. The `webpacker` view helper will automatically specify each entry point's dependent chunks for you in the resulting HTML.
+  With `jsbundling-rails`, you'll be able to manually split out lazy-loaded chunks by using dynamic `import()`s. However, the manual approach would be challenging to maintain on a large project.
+  Why is this important? Code splitting allows the browser to download only the JavasScript and CSS needed for a page, improving performance and SEO.

docs/switch_from_webpacker.md

@@ -1,6 +1,13 @@
 # Switch from Webpacker 5 to jsbundling-rails with webpack
 
-This guide provides step-by-step instructions to migration from [`Webpacker 5`](https://github.com/rails/webpacker/tree/5-x-stable) to `jsbundling-rails` with [`webpack 4`](https://v4.webpack.js.org/concepts/). For upgrading to Webpacker 6 instead, follow [this guide](https://github.com/rails/webpacker/blob/master/docs/v6_upgrade.md) or for comparison between Webpacker and jsbundling-rails, [see this](./comparison_with_webpacker.md).
+This guide provides step-by-step instructions to migration from [`Webpacker 5`](https://github.com/rails/webpacker/tree/5-x-stable) to `jsbundling-rails` with [`webpack 4`](https://v4.webpack.js.org/concepts/). For upgrading to Webpacker/Shakapacker v6 instead, follow [this guide](https://github.com/shakacode/shakapacker/blob/master/docs/v6_upgrade.md) or for comparison between Webpacker and jsbundling-rails, [see this](./docs/comparison_with_webpacker.md).
+
+Note, you will no longer have the following features of `webpacker` if you migrate to `jsbundling-rails`:
+
+1. [HMR](https://webpack.js.org/concepts/hot-module-replacement/)
+2. [Code splitting](https://webpack.js.org/guides/code-splitting/)
+
+If you rely on these features or you have a complicated webpack setup, consider using [`shakpacker`](https://github.com/shakacode/shakapacker).
 
 ## 1. Setup jsbundling-rails
 
@@ -25,7 +32,7 @@ The installation script will:
 - Create `./webpack.config.js`
 - Add the build script to `package.json`
 
-### Optional: Move your webpack configuration
+### Move your webpack configuration
 
 If you would like to minimize the diff between Webpacker and jsbundling-rails:
 
@@ -46,7 +53,7 @@ If you would like to minimize the diff between Webpacker and jsbundling-rails:
 
 ## 2. Remove Webpacker
 
-1. Delete the following files
+1. Delete the following files, ensuring that you've migrated any customizations you've done in them: 
 
 - `./bin/webpack`
 - `./bin/webpack-dev-server`