From c6641484f2da66dff5d421b6b6832e2548cd3ef6 Mon Sep 17 00:00:00 2001
From: Rob Hogan <rob@expo.dev>
Date: Tue, 1 Sep 2026 07:29:44 +0100
Subject: [PATCH] Docs: Fix stale `unstable_conditionNames` defaults

## Summary

`unstable_conditionNames` hasn't defaulted to `['require']` since #1447 made Metro assert `import`/`require` per call site, released in Metro 0.82.0. `default` plus one of `import`/`require` is always in the condition set:

https://github.com/react/metro/blob/v0.87.0/packages/metro-resolver/src/utils/matchSubpathFromExportsLike.js#L37-L44

and the configured default is empty:

https://github.com/react/metro/blob/v0.87.0/packages/metro-config/src/defaults/index.js#L50

`@react-native/metro-config` dropped its static assertion in https://github.com/react/react-native/pull/49780, shipped in React Native 0.79.0, and now sets `['react-native']`:

https://github.com/react/react-native/blob/v0.87.1/packages/metro-config/src/index.flow.js#L59

This being wrong might've led people to assume `'import'` should be added alongside, which asserts the ESM branch of every package's `exports` regardless of the call site, and leads to issues such as #1150.

Also updates the worked example under `unstable_conditionsByPlatform`, and fixes its anchor link (`#unstable-conditionnames` -> `#unstable_conditionnames-experimental`).

Changelog: [Internal]

## Test plan

Docs-only. Values checked against source (above).
---
 docs/Configuration.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/Configuration.md b/docs/Configuration.md
index 3e0e7bc538..282b6682c2 100644
--- a/docs/Configuration.md
+++ b/docs/Configuration.md
@@ -408,13 +408,15 @@ This setting will take effect when [`unstable_enablePackageExports`](#unstable_e
 
 The set of [condition names](https://nodejs.org/docs/latest-v18.x/api/packages.html#conditional-exports) to assert globally when interpreting the [`"exports"` field](https://nodejs.org/docs/latest-v18.x/api/packages.html#exports) in package.json.
 
-Conditions may be any string value and are resolved in the order specified by each package. Node.js documents a number of [community conditions](https://nodejs.org/docs/latest-v18.x/api/packages.html#community-conditions-definitions) which are commonly used by package authors. The `default` condition is always matched.
+Conditions may be any string value and are resolved in the order specified by each package. Node.js documents a number of [community conditions](https://nodejs.org/docs/latest-v18.x/api/packages.html#community-conditions-definitions) which are commonly used by package authors.
 
-Defaults to `['require']`.
+Metro always asserts `default`, plus `import` or `require` according to the syntax of each import - an `import` statement asserts `import`, a `require()` call asserts `require`. Neither needs to be listed here, and listing one would assert it for every import regardless of syntax.
+
+Defaults to `[]`.
 
 :::note
 
-When using React Native, `unstable_conditionNames` defaults to `['require', 'react-native']`.
+When using React Native, `unstable_conditionNames` defaults to `['react-native']`.
 
 :::
 
@@ -430,7 +432,7 @@ This setting will take effect when [`unstable_enablePackageExports`](#unstable_e
 
 The set of additional [condition names](https://nodejs.org/docs/latest-v18.x/api/packages.html#conditional-exports) to dynamically assert by platform (see [`platforms`](#platforms)) when interpreting the [`"exports"` field](https://nodejs.org/docs/latest-v18.x/api/packages.html#exports) in package.json.
 
-Matched conditions are merged with [`unstable_conditionNames`](#unstable-conditionnames) before resolution. With the defaults for both options, the conditions `new Set(['require', 'browser'])` will be asserted when requesting a `web` bundle, and `new Set(['require'])` otherwise. Again, these are resolved in the order specified by each package.
+Matched conditions are merged with [`unstable_conditionNames`](#unstable_conditionnames-experimental) before resolution. Under React Native's defaults for both options, a `require()` call site asserts `new Set(['default', 'require', 'react-native', 'browser'])` when requesting a `web` bundle, and `new Set(['default', 'require', 'react-native'])` otherwise. Again, these are resolved in the order specified by each package.
 
 Defaults to `‌{ web: ['browser'] }`.