From f6b345562c80390f7e1d146d3387abc80c3f2e2d Mon Sep 17 00:00:00 2001
From: Sam <sam@developersam.com>
Date: Sun, 7 Jun 2020 16:44:05 -0400
Subject: [PATCH 1/4] feat(v2): Allow configuring babel via
 docusaurus.config.js

---
 packages/docusaurus-types/src/index.d.ts      |  1 +
 packages/docusaurus/src/babel/base.ts         | 62 +++++++++++++++++++
 .../docusaurus/src/babel/client-preset.ts     |  3 +
 .../docusaurus/src/babel/server-preset.ts     |  3 +
 packages/docusaurus/src/server/config.ts      |  1 +
 packages/docusaurus/src/webpack/base.ts       | 16 +++--
 packages/docusaurus/src/webpack/utils.ts      | 55 +---------------
 website/docs/docusaurus.config.js.md          | 24 +++++++
 8 files changed, 108 insertions(+), 57 deletions(-)
 create mode 100644 packages/docusaurus/src/babel/base.ts
 create mode 100644 packages/docusaurus/src/babel/client-preset.ts
 create mode 100644 packages/docusaurus/src/babel/server-preset.ts

diff --git a/packages/docusaurus-types/src/index.d.ts b/packages/docusaurus-types/src/index.d.ts
index a8fffdc4f8ac..113bf3d49392 100644
--- a/packages/docusaurus-types/src/index.d.ts
+++ b/packages/docusaurus-types/src/index.d.ts
@@ -27,6 +27,7 @@ export interface DocusaurusConfig {
   customFields?: {
     [key: string]: any;
   };
+  configureBabel?: (isServer: boolean) => any;
   scripts?: (
     | string
     | {
diff --git a/packages/docusaurus/src/babel/base.ts b/packages/docusaurus/src/babel/base.ts
new file mode 100644
index 000000000000..e33ea7862221
--- /dev/null
+++ b/packages/docusaurus/src/babel/base.ts
@@ -0,0 +1,62 @@
+import path from 'path';
+import {TransformOptions} from '@babel/core';
+
+export function babelPresets(isServer: boolean): TransformOptions {
+  const absoluteRuntimePath = path.dirname(
+    require.resolve(`@babel/runtime/package.json`),
+  );
+  return {
+    // All optional newlines and whitespace will be omitted when generating code in compact mode
+    compact: true,
+    presets: [
+      isServer
+        ? [
+            require.resolve('@babel/preset-env'),
+            {
+              targets: {
+                node: 'current',
+              },
+            },
+          ]
+        : [
+            require.resolve('@babel/preset-env'),
+            {
+              useBuiltIns: 'usage',
+              loose: true,
+              corejs: '2',
+              // Do not transform modules to CJS
+              modules: false,
+              // Exclude transforms that make all code slower
+              exclude: ['transform-typeof-symbol'],
+            },
+          ],
+      require.resolve('@babel/preset-react'),
+      require.resolve('@babel/preset-typescript'),
+    ],
+    plugins: [
+      // Polyfills the runtime needed for async/await, generators, and friends
+      // https://babeljs.io/docs/en/babel-plugin-transform-runtime
+      [
+        require.resolve('@babel/plugin-transform-runtime'),
+        {
+          corejs: false,
+          helpers: true,
+          // By default, it assumes @babel/runtime@7.0.0. Since we use >7.0.0, better to
+          // explicitly specify the version so that it can reuse the helper better
+          // See https://github.com/babel/babel/issues/10261
+          version: require('@babel/runtime/package.json').version,
+          regenerator: true,
+          useESModules: true,
+          // Undocumented option that lets us encapsulate our runtime, ensuring
+          // the correct version is used
+          // https://github.com/babel/babel/blob/090c364a90fe73d36a30707fc612ce037bdbbb24/packages/babel-plugin-transform-runtime/src/index.js#L35-L42
+          absoluteRuntime: absoluteRuntimePath,
+        },
+      ],
+      // Adds syntax support for import()
+      isServer
+        ? require.resolve('babel-plugin-dynamic-import-node')
+        : require.resolve('@babel/plugin-syntax-dynamic-import'),
+    ],
+  };
+}
diff --git a/packages/docusaurus/src/babel/client-preset.ts b/packages/docusaurus/src/babel/client-preset.ts
new file mode 100644
index 000000000000..a5e994137af5
--- /dev/null
+++ b/packages/docusaurus/src/babel/client-preset.ts
@@ -0,0 +1,3 @@
+import {babelPresets} from './base';
+
+module.exports = () => babelPresets(false);
diff --git a/packages/docusaurus/src/babel/server-preset.ts b/packages/docusaurus/src/babel/server-preset.ts
new file mode 100644
index 000000000000..268d0e4cffcb
--- /dev/null
+++ b/packages/docusaurus/src/babel/server-preset.ts
@@ -0,0 +1,3 @@
+import {babelPresets} from './base';
+
+module.exports = () => babelPresets(true);
diff --git a/packages/docusaurus/src/server/config.ts b/packages/docusaurus/src/server/config.ts
index 1284f8ac3a46..26ea42eeb731 100644
--- a/packages/docusaurus/src/server/config.ts
+++ b/packages/docusaurus/src/server/config.ts
@@ -26,6 +26,7 @@ const OPTIONAL_FIELDS = [
   'scripts',
   'stylesheets',
   'tagline',
+  'configureBabel',
 ];
 
 const DEFAULT_CONFIG: {
diff --git a/packages/docusaurus/src/webpack/base.ts b/packages/docusaurus/src/webpack/base.ts
index 6526b501113d..330fce2322a3 100644
--- a/packages/docusaurus/src/webpack/base.ts
+++ b/packages/docusaurus/src/webpack/base.ts
@@ -37,7 +37,14 @@ export function createBaseConfig(
   isServer: boolean,
   minify: boolean,
 ): Configuration {
-  const {outDir, siteDir, baseUrl, generatedFilesDir, routesPaths} = props;
+  const {
+    outDir,
+    siteDir,
+    baseUrl,
+    generatedFilesDir,
+    routesPaths,
+    siteConfig: {configureBabel},
+  } = props;
 
   const totalPages = routesPaths.length;
   const isProd = process.env.NODE_ENV === 'production';
@@ -155,9 +162,10 @@ export function createBaseConfig(
         {
           test: /\.(j|t)sx?$/,
           exclude: excludeJS,
-          use: [getCacheLoader(isServer), getBabelLoader(isServer)].filter(
-            Boolean,
-          ) as Loader[],
+          use: [
+            getCacheLoader(isServer),
+            getBabelLoader(isServer, configureBabel?.(isServer)),
+          ].filter(Boolean) as Loader[],
         },
         {
           test: CSS_REGEX,
diff --git a/packages/docusaurus/src/webpack/utils.ts b/packages/docusaurus/src/webpack/utils.ts
index 2fda739cf192..ecd1bb6e7b3d 100644
--- a/packages/docusaurus/src/webpack/utils.ts
+++ b/packages/docusaurus/src/webpack/utils.ts
@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import path from 'path';
 import MiniCssExtractPlugin from 'mini-css-extract-plugin';
 import env from 'std-env';
 import merge from 'webpack-merge';
@@ -86,66 +85,16 @@ export function getCacheLoader(
 }
 
 export function getBabelLoader(isServer: boolean, babelOptions?: {}): Loader {
-  const absoluteRuntimePath = path.dirname(
-    require.resolve(`@babel/runtime/package.json`),
-  );
   return {
     loader: require.resolve('babel-loader'),
     options: Object.assign(
       {
         babelrc: false,
         configFile: false,
-        // All optional newlines and whitespace will be omitted when generating code in compact mode
-        compact: true,
         presets: [
           isServer
-            ? [
-                require.resolve('@babel/preset-env'),
-                {
-                  targets: {
-                    node: 'current',
-                  },
-                },
-              ]
-            : [
-                require.resolve('@babel/preset-env'),
-                {
-                  useBuiltIns: 'usage',
-                  loose: true,
-                  corejs: '2',
-                  // Do not transform modules to CJS
-                  modules: false,
-                  // Exclude transforms that make all code slower
-                  exclude: ['transform-typeof-symbol'],
-                },
-              ],
-          require.resolve('@babel/preset-react'),
-          require.resolve('@babel/preset-typescript'),
-        ],
-        plugins: [
-          // Polyfills the runtime needed for async/await, generators, and friends
-          // https://babeljs.io/docs/en/babel-plugin-transform-runtime
-          [
-            require.resolve('@babel/plugin-transform-runtime'),
-            {
-              corejs: false,
-              helpers: true,
-              // By default, it assumes @babel/runtime@7.0.0. Since we use >7.0.0, better to
-              // explicitly specify the version so that it can reuse the helper better
-              // See https://github.com/babel/babel/issues/10261
-              version: require('@babel/runtime/package.json').version,
-              regenerator: true,
-              useESModules: true,
-              // Undocumented option that lets us encapsulate our runtime, ensuring
-              // the correct version is used
-              // https://github.com/babel/babel/blob/090c364a90fe73d36a30707fc612ce037bdbbb24/packages/babel-plugin-transform-runtime/src/index.js#L35-L42
-              absoluteRuntime: absoluteRuntimePath,
-            },
-          ],
-          // Adds syntax support for import()
-          isServer
-            ? require.resolve('babel-plugin-dynamic-import-node')
-            : require.resolve('@babel/plugin-syntax-dynamic-import'),
+            ? require.resolve('../babel/server-preset')
+            : require.resolve('../babel/client-preset'),
         ],
       },
       babelOptions,
diff --git a/website/docs/docusaurus.config.js.md b/website/docs/docusaurus.config.js.md
index b114bb759cba..3ed2992a2501 100644
--- a/website/docs/docusaurus.config.js.md
+++ b/website/docs/docusaurus.config.js.md
@@ -287,3 +287,27 @@ module.exports = {
   ],
 };
 ```
+
+### `configureBabel`
+
+The function to customize Babel configuration.
+
+- Type `(isServer: boolean) => Object`
+
+Example:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  // Added suppport for Flow.
+  configureBabel: (isServer) => ({
+    presets: [
+      '@babel/preset-flow',
+      // The following lines are necessary,
+      // unless you want to configure Babel from scratch.
+      isServer
+        ? require.resolve('@docusaurus/core/lib/babel/server-preset')
+        : require.resolve('@docusaurus/core/lib/babel/client-preset'),
+    ],
+  }),
+};
+```

From d872c17aefdce8e5b0b4113142c5615c69e33fc8 Mon Sep 17 00:00:00 2001
From: Sam <sam@developersam.com>
Date: Tue, 9 Jun 2020 22:34:19 -0400
Subject: [PATCH 2/4] Use api.caller feature from babel to avoid expose
 isServer to users

---
 .../templates/bootstrap/babel.config.js       |  3 +++
 .../templates/classic/babel.config.js         |  3 +++
 .../templates/facebook/babel.config.js        | 12 +++++++++
 packages/docusaurus-types/src/index.d.ts      |  1 -
 .../docusaurus/src/babel/client-preset.ts     |  3 ---
 .../src/babel/{base.ts => preset.ts}          | 11 ++++++--
 .../docusaurus/src/babel/server-preset.ts     |  3 ---
 packages/docusaurus/src/constants.ts          |  1 +
 packages/docusaurus/src/webpack/base.ts       | 22 +++++++++-------
 packages/docusaurus/src/webpack/utils.ts      | 26 +++++++++----------
 website/babel.config.js                       | 12 +++++++++
 website/docs/configuration.md                 | 22 +++++++++++++---
 website/docs/docusaurus.config.js.md          | 24 -----------------
 13 files changed, 84 insertions(+), 59 deletions(-)
 create mode 100644 packages/docusaurus-init/templates/bootstrap/babel.config.js
 create mode 100644 packages/docusaurus-init/templates/classic/babel.config.js
 create mode 100644 packages/docusaurus-init/templates/facebook/babel.config.js
 delete mode 100644 packages/docusaurus/src/babel/client-preset.ts
 rename packages/docusaurus/src/babel/{base.ts => preset.ts} (87%)
 delete mode 100644 packages/docusaurus/src/babel/server-preset.ts
 create mode 100644 website/babel.config.js

diff --git a/packages/docusaurus-init/templates/bootstrap/babel.config.js b/packages/docusaurus-init/templates/bootstrap/babel.config.js
new file mode 100644
index 000000000000..e00595dae7d6
--- /dev/null
+++ b/packages/docusaurus-init/templates/bootstrap/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/packages/docusaurus-init/templates/classic/babel.config.js b/packages/docusaurus-init/templates/classic/babel.config.js
new file mode 100644
index 000000000000..e00595dae7d6
--- /dev/null
+++ b/packages/docusaurus-init/templates/classic/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/packages/docusaurus-init/templates/facebook/babel.config.js b/packages/docusaurus-init/templates/facebook/babel.config.js
new file mode 100644
index 000000000000..81604ce8ec2e
--- /dev/null
+++ b/packages/docusaurus-init/templates/facebook/babel.config.js
@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/packages/docusaurus-types/src/index.d.ts b/packages/docusaurus-types/src/index.d.ts
index 113bf3d49392..a8fffdc4f8ac 100644
--- a/packages/docusaurus-types/src/index.d.ts
+++ b/packages/docusaurus-types/src/index.d.ts
@@ -27,7 +27,6 @@ export interface DocusaurusConfig {
   customFields?: {
     [key: string]: any;
   };
-  configureBabel?: (isServer: boolean) => any;
   scripts?: (
     | string
     | {
diff --git a/packages/docusaurus/src/babel/client-preset.ts b/packages/docusaurus/src/babel/client-preset.ts
deleted file mode 100644
index a5e994137af5..000000000000
--- a/packages/docusaurus/src/babel/client-preset.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-import {babelPresets} from './base';
-
-module.exports = () => babelPresets(false);
diff --git a/packages/docusaurus/src/babel/base.ts b/packages/docusaurus/src/babel/preset.ts
similarity index 87%
rename from packages/docusaurus/src/babel/base.ts
rename to packages/docusaurus/src/babel/preset.ts
index e33ea7862221..535145ee6874 100644
--- a/packages/docusaurus/src/babel/base.ts
+++ b/packages/docusaurus/src/babel/preset.ts
@@ -1,7 +1,7 @@
 import path from 'path';
-import {TransformOptions} from '@babel/core';
+import {ConfigAPI, TransformOptions} from '@babel/core';
 
-export function babelPresets(isServer: boolean): TransformOptions {
+function getTransformOptions(isServer: boolean): TransformOptions {
   const absoluteRuntimePath = path.dirname(
     require.resolve(`@babel/runtime/package.json`),
   );
@@ -60,3 +60,10 @@ export function babelPresets(isServer: boolean): TransformOptions {
     ],
   };
 }
+
+function babelPresets(api: ConfigAPI): TransformOptions {
+  const caller = api.caller((caller) => caller?.name);
+  return getTransformOptions(caller === 'server');
+}
+
+export = babelPresets;
diff --git a/packages/docusaurus/src/babel/server-preset.ts b/packages/docusaurus/src/babel/server-preset.ts
deleted file mode 100644
index 268d0e4cffcb..000000000000
--- a/packages/docusaurus/src/babel/server-preset.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-import {babelPresets} from './base';
-
-module.exports = () => babelPresets(true);
diff --git a/packages/docusaurus/src/constants.ts b/packages/docusaurus/src/constants.ts
index 0333577d9586..30ae952f8f66 100644
--- a/packages/docusaurus/src/constants.ts
+++ b/packages/docusaurus/src/constants.ts
@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+export const BABEL_CONFIG_FILE_NAME = 'babel.config.js';
 export const BUILD_DIR_NAME = 'build';
 export const CONFIG_FILE_NAME = 'docusaurus.config.js';
 export const GENERATED_FILES_DIR_NAME = '.docusaurus';
diff --git a/packages/docusaurus/src/webpack/base.ts b/packages/docusaurus/src/webpack/base.ts
index 330fce2322a3..dd0ef75fd9a3 100644
--- a/packages/docusaurus/src/webpack/base.ts
+++ b/packages/docusaurus/src/webpack/base.ts
@@ -15,6 +15,7 @@ import {Configuration, Loader} from 'webpack';
 
 import {Props} from '@docusaurus/types';
 import {getBabelLoader, getCacheLoader, getStyleLoaders} from './utils';
+import {BABEL_CONFIG_FILE_NAME} from '../constants';
 
 const CSS_REGEX = /\.css$/;
 const CSS_MODULE_REGEX = /\.module\.css$/;
@@ -37,18 +38,21 @@ export function createBaseConfig(
   isServer: boolean,
   minify: boolean,
 ): Configuration {
-  const {
-    outDir,
-    siteDir,
-    baseUrl,
-    generatedFilesDir,
-    routesPaths,
-    siteConfig: {configureBabel},
-  } = props;
+  const {outDir, siteDir, baseUrl, generatedFilesDir, routesPaths} = props;
 
   const totalPages = routesPaths.length;
   const isProd = process.env.NODE_ENV === 'production';
 
+  let customBabelConfiguration;
+  try {
+    customBabelConfiguration = require(path.join(
+      siteDir,
+      BABEL_CONFIG_FILE_NAME,
+    ));
+  } catch {
+    customBabelConfiguration = undefined;
+  }
+
   return {
     mode: isProd ? 'production' : 'development',
     output: {
@@ -164,7 +168,7 @@ export function createBaseConfig(
           exclude: excludeJS,
           use: [
             getCacheLoader(isServer),
-            getBabelLoader(isServer, configureBabel?.(isServer)),
+            getBabelLoader(isServer, customBabelConfiguration),
           ].filter(Boolean) as Loader[],
         },
         {
diff --git a/packages/docusaurus/src/webpack/utils.ts b/packages/docusaurus/src/webpack/utils.ts
index ecd1bb6e7b3d..752e0975aa6f 100644
--- a/packages/docusaurus/src/webpack/utils.ts
+++ b/packages/docusaurus/src/webpack/utils.ts
@@ -9,6 +9,7 @@ import MiniCssExtractPlugin from 'mini-css-extract-plugin';
 import env from 'std-env';
 import merge from 'webpack-merge';
 import {Configuration, Loader} from 'webpack';
+import {TransformOptions} from '@babel/core';
 
 import {version as cacheLoaderVersion} from 'cache-loader/package.json';
 
@@ -84,21 +85,20 @@ export function getCacheLoader(
   };
 }
 
-export function getBabelLoader(isServer: boolean, babelOptions?: {}): Loader {
+export function getBabelLoader(
+  isServer: boolean,
+  babelOptions?: TransformOptions,
+): Loader {
+  const babelOptionsWithDocusaurusPreset = babelOptions ?? {
+    presets: [require.resolve('../babel/preset')],
+  };
   return {
     loader: require.resolve('babel-loader'),
-    options: Object.assign(
-      {
-        babelrc: false,
-        configFile: false,
-        presets: [
-          isServer
-            ? require.resolve('../babel/server-preset')
-            : require.resolve('../babel/client-preset'),
-        ],
-      },
-      babelOptions,
-    ),
+    options: Object.assign(babelOptionsWithDocusaurusPreset, {
+      babelrc: false,
+      configFile: false,
+      caller: {name: isServer ? 'server' : 'client'},
+    }),
   };
 }
 
diff --git a/website/babel.config.js b/website/babel.config.js
new file mode 100644
index 000000000000..81604ce8ec2e
--- /dev/null
+++ b/website/babel.config.js
@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/website/docs/configuration.md b/website/docs/configuration.md
index 5555732d214f..19d3164031b4 100644
--- a/website/docs/configuration.md
+++ b/website/docs/configuration.md
@@ -15,10 +15,12 @@ However, it can be helpful if you have a high-level understanding of how the con
 
 The high-level overview of Docusaurus configuration can be categorized into:
 
-- [Site metadata](#site-metadata)
-- [Deployment configurations](#deployment-configurations)
-- [Theme, plugin, and preset configurations](#theme-plugin-and-preset-configurations)
-- [Custom configurations](#custom-configurations)
+- [What goes into a `docusaurus.config.js`?](#what-goes-into-a-docusaurusconfigjs)
+  - [Site metadata](#site-metadata)
+  - [Deployment configurations](#deployment-configurations)
+  - [Theme, plugin, and preset configurations](#theme-plugin-and-preset-configurations)
+  - [Custom configurations](#custom-configurations)
+- [Customizing Babel Configuration](#customizing-babel-configuration)
 
 For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](docusaurus.config.js.md).
 
@@ -149,3 +151,15 @@ const Hello = () => {
 If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in `docusaurus.config.js`.
 
 :::
+
+## Customizing Babel Configuration
+
+For new Docusaurus projects, we automatically generated a `babel.config.js` in project root.
+
+```js title="babel.config.js"
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
+```
+
+Most of the times, this configuration will work just fine. If you want to customize it, you can directly edit this file to customize babel configuration. For your changes to take effect, you need to restart Docusaurus devserver.
diff --git a/website/docs/docusaurus.config.js.md b/website/docs/docusaurus.config.js.md
index 3ed2992a2501..b114bb759cba 100644
--- a/website/docs/docusaurus.config.js.md
+++ b/website/docs/docusaurus.config.js.md
@@ -287,27 +287,3 @@ module.exports = {
   ],
 };
 ```
-
-### `configureBabel`
-
-The function to customize Babel configuration.
-
-- Type `(isServer: boolean) => Object`
-
-Example:
-
-```js title="docusaurus.config.js"
-module.exports = {
-  // Added suppport for Flow.
-  configureBabel: (isServer) => ({
-    presets: [
-      '@babel/preset-flow',
-      // The following lines are necessary,
-      // unless you want to configure Babel from scratch.
-      isServer
-        ? require.resolve('@docusaurus/core/lib/babel/server-preset')
-        : require.resolve('@docusaurus/core/lib/babel/client-preset'),
-    ],
-  }),
-};
-```

From 614f0f931157a25cd90a0e9bfeab3cc8d126fd59 Mon Sep 17 00:00:00 2001
From: Sam <sam@developersam.com>
Date: Wed, 10 Jun 2020 18:46:44 -0400
Subject: [PATCH 3/4] Remove unused optional config key

---
 packages/docusaurus/src/server/config.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/docusaurus/src/server/config.ts b/packages/docusaurus/src/server/config.ts
index 26ea42eeb731..1284f8ac3a46 100644
--- a/packages/docusaurus/src/server/config.ts
+++ b/packages/docusaurus/src/server/config.ts
@@ -26,7 +26,6 @@ const OPTIONAL_FIELDS = [
   'scripts',
   'stylesheets',
   'tagline',
-  'configureBabel',
 ];
 
 const DEFAULT_CONFIG: {

From aba33b4fd9d5ee4102cfce8b1f87005b9f958bf2 Mon Sep 17 00:00:00 2001
From: Sam <sam@developersam.com>
Date: Wed, 10 Jun 2020 18:58:26 -0400
Subject: [PATCH 4/4] Make babel loader resolve and require config file

---
 packages/docusaurus/src/webpack/base.ts  | 20 ++++++++---------
 packages/docusaurus/src/webpack/utils.ts | 28 ++++++++++++++++--------
 2 files changed, 29 insertions(+), 19 deletions(-)

diff --git a/packages/docusaurus/src/webpack/base.ts b/packages/docusaurus/src/webpack/base.ts
index dd0ef75fd9a3..37ab479b5e2e 100644
--- a/packages/docusaurus/src/webpack/base.ts
+++ b/packages/docusaurus/src/webpack/base.ts
@@ -43,15 +43,10 @@ export function createBaseConfig(
   const totalPages = routesPaths.length;
   const isProd = process.env.NODE_ENV === 'production';
 
-  let customBabelConfiguration;
-  try {
-    customBabelConfiguration = require(path.join(
-      siteDir,
-      BABEL_CONFIG_FILE_NAME,
-    ));
-  } catch {
-    customBabelConfiguration = undefined;
-  }
+  const customBabelConfigurationPath = path.join(
+    siteDir,
+    BABEL_CONFIG_FILE_NAME,
+  );
 
   return {
     mode: isProd ? 'production' : 'development',
@@ -168,7 +163,12 @@ export function createBaseConfig(
           exclude: excludeJS,
           use: [
             getCacheLoader(isServer),
-            getBabelLoader(isServer, customBabelConfiguration),
+            getBabelLoader(
+              isServer,
+              fs.existsSync(customBabelConfigurationPath)
+                ? customBabelConfigurationPath
+                : undefined,
+            ),
           ].filter(Boolean) as Loader[],
         },
         {
diff --git a/packages/docusaurus/src/webpack/utils.ts b/packages/docusaurus/src/webpack/utils.ts
index 752e0975aa6f..111e40998009 100644
--- a/packages/docusaurus/src/webpack/utils.ts
+++ b/packages/docusaurus/src/webpack/utils.ts
@@ -87,18 +87,28 @@ export function getCacheLoader(
 
 export function getBabelLoader(
   isServer: boolean,
-  babelOptions?: TransformOptions,
+  babelOptions?: TransformOptions | string,
 ): Loader {
-  const babelOptionsWithDocusaurusPreset = babelOptions ?? {
-    presets: [require.resolve('../babel/preset')],
-  };
-  return {
-    loader: require.resolve('babel-loader'),
-    options: Object.assign(babelOptionsWithDocusaurusPreset, {
+  let options: TransformOptions;
+  if (typeof babelOptions === 'string') {
+    options = {
       babelrc: false,
-      configFile: false,
+      configFile: babelOptions,
       caller: {name: isServer ? 'server' : 'client'},
-    }),
+    };
+  } else {
+    options = Object.assign(
+      babelOptions ?? {presets: [require.resolve('../babel/preset')]},
+      {
+        babelrc: false,
+        configFile: false,
+        caller: {name: isServer ? 'server' : 'client'},
+      },
+    );
+  }
+  return {
+    loader: require.resolve('babel-loader'),
+    options,
   };
 }