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/src/babel/preset.ts b/packages/docusaurus/src/babel/preset.ts new file mode 100644 index 000000000000..535145ee6874 --- /dev/null +++ b/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; 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 6526b501113d..37ab479b5e2e 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$/; @@ -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, diff --git a/packages/docusaurus/src/webpack/utils.ts b/packages/docusaurus/src/webpack/utils.ts index 2fda739cf192..111e40998009 100644 --- a/packages/docusaurus/src/webpack/utils.ts +++ b/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, }; } 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.