Resolve Babel 8 migration follow-ups (#1212)

## Summary

Resolves the remaining Babel 8 migration follow-ups from PR #1187:

- converts missing `@babel/core` package metadata lookups into
Shakapacker-style install guidance instead of a raw module-resolution
stack trace
- documents the Babel 8 target-default change so apps can preserve the
old Babel 7 all-browser output policy when needed
- makes React runtime selection explicit in the Babel customization docs
so upgrades do not silently inherit Babel 8's `automatic` runtime
default

Closes #1194.

## Validation

- `node node_modules/jest/bin/jest.js test/package/rules/babel.test.js
--runInBand`
- `node node_modules/eslint/bin/eslint.js package/rules/babel.ts
test/package/rules/babel.test.js`
- `node node_modules/prettier/bin/prettier.cjs --check
package/rules/babel.ts test/package/rules/babel.test.js
docs/customizing_babel_config.md`
- `node node_modules/typescript/bin/tsc --noEmit`
- `git diff --check origin/main...HEAD`

## Notes

`CHANGELOG.md` already has the PR #1187 Babel 8 support entry in the
v10.2.0 section on current `main`, so this follow-up does not add
duplicate changelog coverage.

Author: justin808

docs/customizing_babel_config.md

@@ -65,6 +65,9 @@ module.exports = function (api) {
       [
         "@babel/preset-react",
         {
+          // Babel 7 defaults to "classic"; Babel 8 defaults to "automatic".
+          // Choose the runtime intentionally when upgrading.
+          runtime: "classic",
           development: isDevelopmentEnv || isTestEnv
         }
       ]
@@ -97,10 +100,22 @@ npm install --save-dev @babel/core@^8 @babel/plugin-transform-runtime@^8 @babel/
 ```
 
 Babel 8 requires Node `^22.18.0 || >=24.11.0` while running the build. It also
-removed some Babel 7 configuration options. The Shakapacker preset omits those
-removed options when Babel 8 is running, but app-level custom Babel config should
-also avoid Babel 7-only options such as `useBuiltIns` on `@babel/preset-react`
-or `helpers` on `@babel/plugin-transform-runtime`.
+removed some Babel 7 configuration options and changed several defaults. The
+Shakapacker preset omits options removed by Babel 8 when Babel 8 is running, but
+app-level custom Babel config should also avoid Babel 7-only options such as
+`useBuiltIns` on `@babel/preset-react`, `useBuiltIns` or `corejs` on
+`@babel/preset-env`, or `helpers` on `@babel/plugin-transform-runtime`.
+
+If your app does not have a Browserslist or top-level Babel `targets` setting,
+Babel 8's no-target fallback is different from Babel 7's historical all-browser
+fallback. Add an explicit top-level `targets` value before upgrading when you
+need to preserve the old output policy.
+
+If you use `@babel/preset-react` or `@babel/plugin-transform-react-jsx`, choose
+the React runtime explicitly. Babel 7 defaulted to `runtime: "classic"` while
+Babel 8 defaults to `runtime: "automatic"`. Keep `runtime: "classic"` to
+preserve the previous transform behavior, or switch to `runtime: "automatic"`
+intentionally after confirming your React/SSR setup supports it.
 
 Shakapacker validates the loader/core pairing when `javascript_transpiler:
 "babel"` is active. If your app installs Babel 8, install `babel-loader` 10 or

package/rules/babel.ts

@@ -1,11 +1,30 @@
 const { loaderMatches, packageMajorVersion } = require("../utils/helpers")
+const { isModuleNotFoundError } = require("../utils/errorHelpers")
 const { javascript_transpiler: javascriptTranspiler } = require("../config")
 const { isProduction } = require("../env")
 const jscommon = require("./jscommon")
 
+const babelCoreMajorVersion = (): number => {
+  try {
+    return packageMajorVersion("@babel/core")
+  } catch (error: unknown) {
+    if (!isModuleNotFoundError(error)) {
+      throw error
+    }
+
+    throw new Error(
+      "Your Shakapacker config specified using Babel, but @babel/core package is not installed.\n" +
+        "\nTo fix this issue, run one of the following commands:\n" +
+        "  npm install --save-dev @babel/core\n" +
+        "  yarn add --dev @babel/core\n" +
+        "\nOr change your 'javascript_transpiler' setting in shakapacker.yml to use a different loader."
+    )
+  }
+}
+
 const validateBabelLoaderCompatibility = (): void => {
   if (
-    packageMajorVersion("@babel/core") >= 8 &&
+    babelCoreMajorVersion() >= 8 &&
     packageMajorVersion("babel-loader") < 10
   ) {
     throw new Error(

spec/dummy/Gemfile.lock

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

test/package/rules/babel.test.js

@@ -48,6 +48,35 @@ const loadBabelRuleWithPackageMajors = (packageMajors) => {
   return require("../../../package/rules/babel")
 }
 
+const loadBabelRuleWithMissingBabelCore = () => {
+  jest.resetModules()
+  jest.doMock("../../../package/config", () => ({
+    javascript_transpiler: "babel"
+  }))
+  jest.doMock("../../../package/env", () => ({
+    isProduction: false
+  }))
+  jest.doMock("../../../package/rules/jscommon", () => ({}))
+  jest.doMock("../../../package/utils/errorHelpers", () => ({
+    isModuleNotFoundError: (error) => error?.code === "MODULE_NOT_FOUND"
+  }))
+  jest.doMock("../../../package/utils/helpers", () => ({
+    loaderMatches: (_configLoader, _loaderToCheck, ruleFactory) =>
+      ruleFactory(),
+    packageMajorVersion: (packageName) => {
+      if (packageName === "@babel/core") {
+        const error = new Error("Cannot find module '@babel/core/package.json'")
+        error.code = "MODULE_NOT_FOUND"
+        throw error
+      }
+
+      return 10
+    }
+  }))
+
+  return require("../../../package/rules/babel")
+}
+
 // Skip tests if babel config is not available (not the active transpiler)
 if (!babelConfig) {
   // eslint-disable-next-line jest/no-disabled-tests
@@ -141,6 +170,12 @@ describe("babel loader compatibility", () => {
       }).use[0].loader
     ).toContain("babel-loader")
   })
+
+  test("raises an actionable error when @babel/core is missing", () => {
+    expect(() => loadBabelRuleWithMissingBabelCore()).toThrow(
+      /@babel\/core package is not installed/
+    )
+  })
 })
 
 describe("babel preset", () => {