feat(v2): Allow configuring babel via babel.config.js (#2903)

* feat(v2): Allow configuring babel via docusaurus.config.js

* Use api.caller feature from babel to avoid expose isServer to users

* Remove unused optional config key

* Make babel loader resolve and require config file

packages/docusaurus-init/templates/bootstrap/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

packages/docusaurus-init/templates/classic/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

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')],
+};

packages/docusaurus/src/babel/preset.ts

@@ -0,0 +1,69 @@
+import path from 'path';
+import {ConfigAPI, TransformOptions} from '@babel/core';
+
+function getTransformOptions(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'),
+    ],
+  };
+}
+
+function babelPresets(api: ConfigAPI): TransformOptions {
+  const caller = api.caller((caller) => caller?.name);
+  return getTransformOptions(caller === 'server');
+}
+
+export = babelPresets;

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';

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$/;
@@ -42,6 +43,11 @@ export function createBaseConfig(
   const totalPages = routesPaths.length;
   const isProd = process.env.NODE_ENV === 'production';
 
+  const customBabelConfigurationPath = path.join(
+    siteDir,
+    BABEL_CONFIG_FILE_NAME,
+  );
+
   return {
     mode: isProd ? 'production' : 'development',
     output: {
@@ -155,9 +161,15 @@ export function createBaseConfig(
         {
           test: /\.(j|t)sx?$/,
           exclude: excludeJS,
-          use: [getCacheLoader(isServer), getBabelLoader(isServer)].filter(
-            Boolean,
-          ) as Loader[],
+          use: [
+            getCacheLoader(isServer),
+            getBabelLoader(
+              isServer,
+              fs.existsSync(customBabelConfigurationPath)
+                ? customBabelConfigurationPath
+                : undefined,
+            ),
+          ].filter(Boolean) as Loader[],
         },
         {
           test: CSS_REGEX,

packages/docusaurus/src/webpack/utils.ts

@@ -5,11 +5,11 @@
  * 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';
 import {Configuration, Loader} from 'webpack';
+import {TransformOptions} from '@babel/core';
 
 import {version as cacheLoaderVersion} from 'cache-loader/package.json';
 
@@ -85,71 +85,30 @@ 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(
+export function getBabelLoader(
+  isServer: boolean,
+  babelOptions?: TransformOptions | string,
+): Loader {
+  let options: TransformOptions;
+  if (typeof babelOptions === 'string') {
+    options = {
+      babelrc: false,
+      configFile: babelOptions,
+      caller: {name: isServer ? 'server' : 'client'},
+    };
+  } else {
+    options = Object.assign(
+      babelOptions ?? {presets: [require.resolve('../babel/preset')]},
       {
         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'),
-        ],
+        caller: {name: isServer ? 'server' : 'client'},
       },
-      babelOptions,
-    ),
+    );
+  }
+  return {
+    loader: require.resolve('babel-loader'),
+    options,
   };
 }
 

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')],
+};

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.