docs: explain that you have to use a babel.config.js for Yarn PnP (shakacode#484)

G-Rath · web-flow · commit 295795e0ce28 · 2024-05-22T09:19:32.000+01:00
* docs: provide a basic skeleton example on customizing the babel config

* docs: mention that you have to switch to `babel.config.js` for Yarn PnP

* docs: add changelog entry

* docs: add language to code fence
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,10 @@ _next_ branch is for v8 changes
 ## [Unreleased]
 Changes since the last non-beta release.
 
+### Fixed
+
+- Improve documentation for using Yarn PnP [PR 484](https://github.com/shakacode/shakapacker/pull/484) by [G-Rath](https://github.com/g-rath).
+
 ## [v8.0.0] - May 17, 2024
 
 See the [v8 Upgrade Guide](https://github.com/shakacode/shakapacker/blob/main/docs/v8_upgrade.md).
diff --git a/README.md b/README.md
@@ -167,6 +167,8 @@ If `packageManager` is not set when running `shakapacker:install`, Shakapacker w
 
 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.
 
+If you wish to use [Yarn PnP](https://yarnpkg.com/features/pnp) you will need to configure Babel using a `babel.config.js` file rather than via `package.json` - see [customizing Babel Config](./docs/customizing_babel_config.md) for examples on how to do this.
+
 > [NOTE]
 >
 > The rest of the documentation will only reference `npm` when providing commands such as to install optional packages except in cases where
diff --git a/docs/customizing_babel_config.md b/docs/customizing_babel_config.md
@@ -14,16 +14,44 @@ The default configuration of babel is done by using `package.json` to use the fi
 ```
 
 ## Customizing the Babel Config
-This example shows how you can create an object and apply _additional_ presets and plugins on top of the default.
 
-### React Configuration
-To use this example file,
+### Basic Configuration
+
+This is a very basic skeleton that you can use that includes the Shakapacker preset, and makes it easy to add new plugins and presents:
+
+```js
+// babel.config.js
+module.exports = function (api) {
+  const defaultConfigFunc = require('shakapacker/package/babel/preset.js')
+  const resultConfig = defaultConfigFunc(api)
+
+  const changesOnDefault = {
+    presets: [
+      // put custom presets here
+    ].filter(Boolean),
+    plugins: [
+      // put custom plugins here
+    ].filter(Boolean),
+  }
 
+  resultConfig.presets = [...resultConfig.presets, ...changesOnDefault.presets]
+  resultConfig.plugins = [...resultConfig.plugins, ...changesOnDefault.plugins]
+
+  return resultConfig
+}
 ```
+
+### React Configuration
+
+This shows how you can add to the above skeleton to support React - to use this, install the following dependencies:
+
+```bash
 npm install react react-dom @babel/preset-react
 npm install --dev @pmmmwh/react-refresh-webpack-plugin react-refresh
 ```
 
+And then update the configuration:
+
 ```js
 // babel.config.js
 module.exports = function (api) {
@@ -54,7 +82,7 @@ module.exports = function (api) {
   }
 
   resultConfig.presets = [...resultConfig.presets, ...changesOnDefault.presets]
-  resultConfig.plugins = [...resultConfig.plugins, ...changesOnDefault.plugins ]
+  resultConfig.plugins = [...resultConfig.plugins, ...changesOnDefault.plugins]
 
   return resultConfig
 }

Original file line number	Diff line number	Diff line change
@@ -167,6 +167,8 @@ If `packageManager` is not set when running `shakapacker:install`, Shakapacker w
`167`	`167`
`168`	`168`	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.
`169`	`169`
	`170`	+If you wish to use [Yarn PnP](https://yarnpkg.com/features/pnp) you will need to configure Babel using a `babel.config.js` file rather than via `package.json` - see [customizing Babel Config](./docs/customizing_babel_config.md) for examples on how to do this.
	`171`	`+`
`170`	`172`	`> [NOTE]`
`171`	`173`	`>`
`172`	`174`	> The rest of the documentation will only reference `npm` when providing commands such as to install optional packages except in cases where