From 295795e0ce28efdd02be21464508c9674e336cfa Mon Sep 17 00:00:00 2001
From: Gareth Jones <Jones258@Gmail.com>
Date: Wed, 22 May 2024 20:19:32 +1200
Subject: [PATCH] docs: explain that you have to use a `babel.config.js` for
 Yarn PnP (#484)

* 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
---
 CHANGELOG.md                     |  4 ++++
 README.md                        |  2 ++
 docs/customizing_babel_config.md | 36 ++++++++++++++++++++++++++++----
 3 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6e943516..092a8e70 100644
--- 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
index 895bc88d..bd45c662 100644
--- 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
index f45d7e13..ea52aab1 100644
--- 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
 }