facebook/docusaurus · error · Error

You can't use siteConfig.webpack.jsLoader and siteConfig.fut

Error message

You can't use siteConfig.webpack.jsLoader and siteConfig.future.faster.swcJsLoader at the same time.
To avoid any configuration ambiguity, you must make an explicit choice:
- If you want to use Docusaurus Faster and SWC (recommended), remove siteConfig.webpack.jsLoader
- If you want to use a custom JS loader, use siteConfig.future.faster.swcJsLoader: false

What it means

Thrown by createJsLoaderFactory() in @docusaurus/bundler when the site enables both siteConfig.future.faster.swcJsLoader AND a custom siteConfig.webpack.jsLoader. The two are mutually exclusive because Docusaurus cannot decide which JS pipeline to use, so it refuses to pick silently and asks the user to make an explicit choice.

Source

Thrown at packages/docusaurus-bundler/src/loaders/jsLoader.ts:67

// Confusing: function that creates a function that creates actual js loaders
// This is done on purpose because the js loader factory is a public API
// It is injected in configureWebpack plugin lifecycle for plugin authors
export async function createJsLoaderFactory({
  siteConfig,
}: {
  siteConfig: {
    webpack?: DocusaurusConfig['webpack'];
    future: {
      faster: DocusaurusConfig['future']['faster'];
    };
  };
}): Promise<ConfigureWebpackUtils['getJSLoader']> {
  const currentBundler = await getCurrentBundler({siteConfig});
  const isSWCLoader = siteConfig.future.faster.swcJsLoader;
  if (isSWCLoader) {
    if (siteConfig.webpack?.jsLoader) {
      throw new Error(
        `You can't use siteConfig.webpack.jsLoader and siteConfig.future.faster.swcJsLoader at the same time.
To avoid any configuration ambiguity, you must make an explicit choice:
- If you want to use Docusaurus Faster and SWC (recommended), remove siteConfig.webpack.jsLoader
- If you want to use a custom JS loader, use siteConfig.future.faster.swcJsLoader: false`,
      );
    }
    return currentBundler.name === 'rspack'
      ? createRspackSwcJsLoaderFactory()
      : createSwcJsLoaderFactory();
  }

  const jsLoader = siteConfig.webpack?.jsLoader ?? 'babel';
  if (jsLoader instanceof Function) {
    return ({isServer}) => jsLoader(isServer);
  }
  if (jsLoader === 'babel') {
    return BabelJsLoaderFactory;
  }

View on GitHub (pinned to 3f483e80e3)

Solutions

1. If you want Faster + SWC (recommended): remove the siteConfig.webpack.jsLoader entry.
2. If you want to keep your custom JS loader: set siteConfig.future.faster.swcJsLoader = false (or leave the faster block off).

Example fix

// before
webpack: { jsLoader: (isServer) => ({ loader: 'babel-loader', options }) },
future: { faster: { swcJsLoader: true } }
// after (use SWC via Faster)
// webpack: { jsLoader: ... }   <-- removed
future: { faster: { swcJsLoader: true } }

function assertNoLoaderConflict(cfg: {webpack?: {jsLoader?: unknown}; future?: {faster?: {swcJsLoader?: boolean}}}) {
  if (cfg.future?.faster?.swcJsLoader && cfg.webpack?.jsLoader !== undefined) {
    throw new Error('Remove siteConfig.webpack.jsLoader when future.faster.swcJsLoader is true.');
  }
}

When it happens

Trigger: In docusaurus.config, setting future.faster.swcJsLoader = true while also providing a custom webpack: { jsLoader: ... } function or value; copying a config that had a custom jsLoader and then flipping the faster.swcJsLoader flag on.

Common situations: Adopting Docusaurus Faster on a site that previously had a custom Babel/SWC jsLoader; enabling faster.swcJsLoader during a migration but forgetting to delete the old custom loader.

Related errors

• HTML minification failed (SWC)
• To enable Docusaurus Faster options, your site must add the
• HTML minification failed (Terser)
• Unexpected "reportingSeverity" value: ${reportingSeverity}.
• ${JSON.stringify(redirect)} => Validation error: ${error.mes

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/81c35df77ee911c7. Report an issue: GitHub.