facebook/react · critical · Error

This module must be shimmed by a specific renderer.

Error message

This module must be shimmed by a specific renderer.

What it means

packages/react-reconciler/src/ReactFiberConfig.js is a deliberate trap: react-reconciler never ships with a real host config. Rollup aliases and Jest moduleNameMapper are supposed to replace this module with a renderer's host config (e.g. react-dom's ReactDOMHostConfig). If module resolution ever loads this stub, it throws immediately at import time so a broken build config fails loudly instead of silently.

Source

Thrown at packages/react-reconciler/src/ReactFiberConfig.js:20

 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 *
 * @flow
 */

/* eslint-disable react-internal/prod-error-codes */

// We expect that our Rollup, Jest, and Flow configurations
// always shim this module with the corresponding host config
// (either provided by a renderer, or a generic shim for npm).
//
// We should never resolve to this file, but it exists to make
// sure that if we *do* accidentally break the configuration,
// the failure isn't silent.

throw new Error('This module must be shimmed by a specific renderer.');

View on GitHub (pinned to eafeac097b)

Solutions

1. Consume the published npm build of react-reconciler (it ships with a bundled config) instead of source.
2. For Jest, add moduleNameMapper entries mapping 'react-reconciler' (and the config path) to your host config file, mirroring React's own jest.config.js.
3. For bundlers, add the equivalent resolve.alias so ReactFiberConfig resolves to your host config.

Example fix

// before: jest.config.js with no mapping -> tests crash with 'must be shimmed'
module.exports = {testEnvironment: 'node'};

// after: map reconciler config to your host config
module.exports = {
  testEnvironment: 'node',
  moduleNameMapper: {
    '^react-reconciler$': '<rootDir>/src/ReactFiberReconciler.js',
    'ReactFiberConfig': '<rootDir>/hostconfig/myHostConfig.js',
  },
};

// Assert the trap module never resolves in your build/test setup
const assert = require('assert');
const path = require('path');
const resolved = require.resolve('react-reconciler');
assert(!resolved.includes(path.join('src', 'ReactFiberConfig.js')),
  'ReactFiberConfig trap resolved — fix your moduleNameMapper/aliases');

When it happens

Trigger: Importing react-reconciler source directly in Jest, webpack, or any bundler without the alias mapping 'ReactFiberConfig' to a host config; a fork or monorepo where the jest moduleNameMapper / rollup alias entries were dropped or path-mismatched.

Common situations: Contributing to React or building a custom renderer fork and the test/bundle config lost the shim aliases; tooling (ts-jest, esbuild) that ignores moduleNameMapper; deep imports that bypass the configured entry points.

Related errors

• This module must be shimmed by a specific renderer.
• 320
• 492
• React is running in production mode, but dead code eliminati
• Section offsets must be ordered and non-overlapping.

AI-assisted analysis of facebook/react@eafeac097b (2026-08-21). Data as JSON: /api/errors/5667c80306239141. Report an issue: GitHub.