5.7Errors
missing_
A part or a hook such as useRecipe() ran outside the component it belongs in, like <Recipe.Root>, or two copies of @recipe-book/react loaded.
A part from @recipe-book/react, such as <Recipe.Image>, or a hook such as useRecipe() ran outside the component it belongs in. Parts and hooks read the state of the nearest component that the table names, such as <Recipe.Root>. The checkbox parts need a <Recipe.Checklist> around their ingredient or step too.
RecipeBookError: useRecipe() must be called inside <Recipe.Root>. To use recipe state without a Root, call useRecipeState().
See https://recipe-book.siraj.page/errors/missing_parent/| Thrown by | Message |
|---|---|
<Recipe.Image> |
<Recipe.Image> must be rendered inside <Recipe.Root>. |
<Recipe.Ingredients> |
<Recipe.Ingredients> must be rendered inside <Recipe.Root>. |
<Recipe.IngredientList> |
<Recipe.IngredientList> must be rendered inside <Recipe.Root>. |
<Recipe.Ingredient> |
<Recipe.Ingredient> must be rendered inside <Recipe.Root>. |
<Recipe.IngredientQuantity> |
<Recipe.IngredientQuantity> must be rendered inside <Recipe.Ingredient>. |
<Recipe.IngredientName> |
<Recipe.IngredientName> must be rendered inside <Recipe.Ingredient>. |
<Recipe.IngredientNote> |
<Recipe.IngredientNote> must be rendered inside <Recipe.Ingredient>. |
<Recipe.IngredientOptional> |
<Recipe.IngredientOptional> must be rendered inside <Recipe.Ingredient>. |
<Recipe.Steps> |
<Recipe.Steps> must be rendered inside <Recipe.Root>. |
<Recipe.StepList> |
<Recipe.StepList> must be rendered inside <Recipe.Root>. |
<Recipe.Step> |
<Recipe.Step> must be rendered inside <Recipe.Root>. |
<Recipe.StepName> |
<Recipe.StepName> must be rendered inside <Recipe.Step>. |
<Recipe.StepText> |
<Recipe.StepText> must be rendered inside <Recipe.Step>. |
<Recipe.ConvertedStepText> |
<Recipe.ConvertedStepText> must be rendered inside <Recipe.Step>. |
<Recipe.Times> |
<Recipe.Times> must be rendered inside <Recipe.Root>. |
<Recipe.Equipment> |
<Recipe.Equipment> must be rendered inside <Recipe.Root>. |
<Recipe.Notes> |
<Recipe.Notes> must be rendered inside <Recipe.Root>. |
<Recipe.Nutrition> |
<Recipe.Nutrition> must be rendered inside <Recipe.Root>. |
<Recipe.SystemToggle> |
<Recipe.SystemToggle> must be rendered inside <Recipe.Root>. |
<Recipe.SystemOption> |
<Recipe.SystemOption> must be rendered inside <Recipe.SystemToggle>. |
<Recipe.ServingsSelect> |
<Recipe.ServingsSelect> must be rendered inside <Recipe.Root>. |
<Recipe.ServingsInput> |
<Recipe.ServingsInput> must be rendered inside <Recipe.Root>. |
<Recipe.ServingsText> |
<Recipe.ServingsText> must be rendered inside <Recipe.Root>. |
<Recipe.YieldText> |
<Recipe.YieldText> must be rendered inside <Recipe.Root>. |
<Recipe.JsonLd> |
<Recipe.JsonLd> must be rendered inside <Recipe.Root>. |
<Recipe.Checklist> |
<Recipe.Checklist> must be rendered inside <Recipe.Root>. |
<Recipe.IngredientCheckbox> |
<Recipe.IngredientCheckbox> must be rendered inside <Recipe.Ingredient>. |
<Recipe.StepCheckbox> |
<Recipe.StepCheckbox> must be rendered inside <Recipe.Step>. |
<Recipe.CookMode> |
<Recipe.CookMode> must be rendered inside <Recipe.Root>. |
useRecipe() |
useRecipe() must be called inside <Recipe.Root>. To use recipe state without a Root, call useRecipeState(). |
useFormatIngredient() |
useFormatIngredient() must be called inside <Recipe.Root>. To format ingredients without a Root, call formatIngredient() from @recipe-book/react/core. |
useChecklist() |
useChecklist() must be called inside <Recipe.Checklist>. To keep ticks without a Checklist, call useChecklistState(). |
It throws while React renders, so React shows the nearest error boundary instead of the component.
A checkbox part inside its ingredient or step, but outside a <Recipe.Checklist>, throws <Recipe.IngredientCheckbox> must be rendered inside <Recipe.Checklist>. or <Recipe.StepCheckbox> must be rendered inside <Recipe.Checklist>.
Wrap the component in <Recipe.Root>
A component that calls useRecipe() must render inside a Root, even when it’s far from the parts. Here, ServingsBadge is in a header next to the Root, not inside it, so useRecipe() throws:
'use client'
import { formatServings, type ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'
function ServingsBadge() {
const { scaledServings } = Recipe.useRecipe()
return scaledServings ? (
<span>{`Serves ${formatServings(scaledServings)}`}</span>
) : null
}
export function RecipePage({ recipe }: { recipe: ParsedRecipe }) {
return (
<>
<header>
<ServingsBadge />
</header>
<Recipe.Root recipe={recipe}>
<Recipe.Image />
</Recipe.Root>
</>
)
}Move <Recipe.Root> up so it wraps both. It renders no element of its own, so the HTML keeps its structure:
'use client'
import { formatServings, type ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'
function ServingsBadge() {
const { scaledServings } = Recipe.useRecipe()
return scaledServings ? (
<span>{`Serves ${formatServings(scaledServings)}`}</span>
) : null
}
export function RecipePage({ recipe }: { recipe: ParsedRecipe }) {
return (
<Recipe.Root recipe={recipe}>
<header>
<ServingsBadge />
</header>
<Recipe.Image />
</Recipe.Root>
)
}For the sample recipe, which has 4 servings, RecipePage renders this HTML, and on React 19 a server render also adds a preload <link> for the image to the page:
<header><span>Serves 4</span></header><img src="/pancakes.svg" alt="Buttermilk pancakes" data-recipe-image=""/>Use useRecipeState()
When a component can’t go inside a Root, such as a summary in a list of recipes, pass it the recipe and call useRecipeState():
'use client'
import { formatServings, type ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'
export function ServingsBadge({ recipe }: { recipe: ParsedRecipe }) {
const { scaledServings } = Recipe.useRecipeState({ recipe })
return scaledServings ? (
<span>{`Serves ${formatServings(scaledServings)}`}</span>
) : null
}For a recipe with 4 servings, ServingsBadge renders <span>Serves 4</span>, and for 6–8 servings, <span>Serves 6–8</span>. For a recipe with only a yield, or neither count, it renders nothing. Its state is its own: changing its servings doesn’t change a Root’s, and parts can’t read it.
Load one copy of @recipe-book/react
A part inside a Root also throws when the app loads two copies of @recipe-book/react, such as two versions in node_modules, or the ESM and CommonJS builds of one version. Each copy has its own Root state, so a part from one copy can’t find a Root from the other. List the copies:
npm ls @recipe-book/reactWith pnpm, run pnpm why @recipe-book/react. When either lists more than one version, update the packages that depend on @recipe-book/react so they share one version. When they list one version, look for a dependency that loads @recipe-book/react with require() while your components import it. Two copies also cause these problems, without an error or a warning:
- A
<Recipe.Provider>from one copy doesn’t reach a Root from the other, so the Root doesn’t use the provider’slabels,locale, anddefaultSystem. - In development, Roots from different copies don’t compare their
idPrefix, so two that render the same step IDs don’t warn.
A dependency’s require() loads the same copy as your components’ import in these setups, because both packages give require() the same build as import there:
- Node.js 22.12 and later, including Vitest and the Next.js Pages Router’s server render, which leave dependencies to Node.js
- Vite, webpack, Rollup, esbuild, and Next.js with webpack or Turbopack, in the code they bundle
On Node.js 22.12 to 22.14, when Node.js runs your ES modules itself and they import the dependency before the package it requires, the dependency’s require() throws ERR_REQUIRE_CYCLE_MODULE instead. On Node.js 22.15 and 22.16, it returns the package before the package has run, so its classes and constants, such as RecipeBookError and most parts, are undefined until your import of the package runs. A dependency that reads one when it loads, such as with const { Ingredients } = require('@recipe-book/react'), keeps undefined, and React throws Element type is invalid when it renders it. Vitest and the Pages Router’s server render still load one copy. Import the package first, or upgrade to Node.js 22.17 or later, which loads one copy with every export set in either order.
On Node.js 22.12.x, your app’s own CommonJS code that requires either package prints Node.js’s one-time ExperimentalWarning about loading an ES module with require(). A dependency’s require() doesn’t, and Node.js 22.13 and later print none.
Four setups still load two copies, because their require() loads the CommonJS build:
- Jest when it runs ES modules natively, with
--experimental-vm-modules, before Jest 30.5 or Node.js 24.9. From Jest 30.5 on Node.js 24.9 and later, the dependency’srequire()resolves to the ES module build and throws Jest’sCannot require() ES Module … in a cycleerror instead. Jest loads one copy when Babel compiles your imports torequire(). - Node.js 22.0 to 22.11, which can’t
require()an ES module, in the code it loads without a bundler, such as the Next.js Pages Router’s server render. The packages support Node.js 22 and later. - Bun, in the code it runs, including code that
bun buildbundles with--target=bunor--target=node. - Wrangler, in the Cloudflare Workers it bundles.
On Node.js 22.0 to 22.11, upgrade to 22.17 or later. If you can’t, or you run Bun or Wrangler, use an ESM build of the dependency, which imports your app’s copy. On Node.js 22.0 to 22.11, a module customization hook that resolves your app’s imports of both packages to their .cjs builds works too, because the dependency’s require() loads those builds there. Remove the hook when you upgrade: from 22.12, that require() loads the ES module build, so the hook loads two copies. In the Next.js Pages Router, set bundlePagesRouterDependencies: true in next.config, so that webpack or Turbopack bundles the server render’s dependencies and loads one copy. On Next.js 14, set experimental.bundlePagesExternals: true instead, which only webpack reads: next dev --turbo exits with an error that asks you to remove it.
When Jest runs ES modules natively, alias @recipe-book/react to its CommonJS build with moduleNameMapper, such as '^@recipe-book/react$': '<rootDir>/node_modules/@recipe-book/react/dist/index.cjs'. An alias to dist/index.js fails before Jest 30.4 or Node.js 24.9, where Jest’s require() can’t load the ES module build, and from Jest 30.5 on Node.js 24.9 and later, where it throws the cycle error. On Jest 30.4 with Node.js 24.9 and later, it throws a Cannot require() ES Module … synchronously error when your code imports @recipe-book/react before the dependency, because that import is still loading the ES module build. When it imports the dependency first, the alias loads one copy of @recipe-book/react, but the dependency’s require() of @recipe-book/core still loads core’s CommonJS build, so the app loads two copies of @recipe-book/core. Alias each other entry your code imports to its .cjs build too, such as '^@recipe-book/react/core$' to dist/core.cjs, and '^@recipe-book/core$' to core’s dist/index.cjs. Otherwise those imports load core’s ES module build while the dependency’s require() loads its CommonJS build, and the app still loads two copies of @recipe-book/core. From Jest 30.5 on Node.js 24.9 and later, React’s CommonJS build throws the cycle error instead when it requires @recipe-book/core. Parts work with two copies of core, and a recipe parsed by one copy renders in a Root from the other. But instanceof RecipeBookError returns false for errors from the other copy, so use isRecipeBookError, and each copy keeps its own caches.