facebook/docusaurus · error · Error

To enable Docusaurus Faster options, your site must add the

Error message

To enable Docusaurus Faster options, your site must add the ${logger.name('@docusaurus/faster')} package as a dependency.

What it means

Thrown by ensureFaster() in @docusaurus/bundler when a Docusaurus Faster feature is requested (Rspack, SWC loader, SWC/HTML/CSS minimizers) but the dynamic import('@docusaurus/faster') fails. @docusaurus/faster is an optional peer dependency: it must be installed by the site to use any future.faster option, and this guard turns the cryptic MODULE_NOT_FOUND into an actionable message.

Source

Thrown at packages/docusaurus-bundler/src/importFaster.ts:25

import logger from '@docusaurus/logger';
import type {
  MinimizerOptions as JsMinimizerOptions,
  CustomOptions,
} from 'terser-webpack-plugin';
import type {MinimizerOptions as CssMinimizerOptions} from 'css-minimizer-webpack-plugin';

export type FasterModule = Awaited<typeof import('@docusaurus/faster')>;

async function importFaster(): Promise<FasterModule> {
  return import('@docusaurus/faster');
}

async function ensureFaster(): Promise<FasterModule> {
  try {
    return await importFaster();
  } catch (error) {
    throw new Error(
      `To enable Docusaurus Faster options, your site must add the ${logger.name(
        '@docusaurus/faster',
      )} package as a dependency.`,
      {cause: error},
    );
  }
}

export async function importRspack(): Promise<FasterModule['rspack']> {
  const faster = await ensureFaster();
  return faster.rspack;
}

export async function importSwcLoader(): Promise<string> {
  const faster = await ensureFaster();
  return faster.swcLoader;
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Install the package with your manager: npm install @docusaurus/faster (or yarn/pnpm/bun add).
2. Confirm it resolves: ls node_modules/@docusaurus/faster and check package.json dependencies contains it.
3. For pnpm, ensure no shamefully-hoist=false block hides it; add it explicitly to the workspace package that builds the site.
4. If you did not mean to use Faster, remove the future.faster flags from docusaurus.config.

Example fix

// before (docusaurus.config.ts)
future: { faster: { swcJsLoader: true } }
// after (shell)
npm install @docusaurus/faster

import {existsSync} from 'node:fs';
import {createRequire} from 'node:module';
const require = createRequire(import.meta.url);
function fasterIsInstalled(): boolean {
  try { require.resolve('@docusaurus/faster'); return true; }
  catch { return false; }
}
// before enabling future.faster, assert fasterIsInstalled()

const hasFaster = (): boolean => {
  try { require.resolve('@docusaurus/faster'); return true; } catch { return false; }
};

When it happens

Trigger: Setting future.faster.swcJsLoader = true, future.faster.rspack = true, or htmlMinifier/swc minimizer options without having run npm install @docusaurus/faster; the package is in devDependencies but the install was skipped; a monorepo hoisting issue where the package is not resolvable from the bundler.

Common situations: Following a guide that enables Faster options without the install step; copying a docusaurus.config from another project that had @docusaurus/faster but forgetting its dependency; upgrading Docusaurus to a version that split faster into its own package; pnpm strict-hoisting hiding the package.

Related errors

• You can't use siteConfig.webpack.jsLoader and siteConfig.fut
• HTML minification failed (SWC)
• HTML minification failed (Terser)
• Docusaurus built-in SVG rule couldn't be found. The SVGR plu
• Failed to retrieve git history for "${file}" because git is

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