Recipe Book0.6.0

1.1Get started

Introduction

What Recipe Book is, what @recipe-book/core and @recipe-book/react each do, require, and weigh, and how to use core without React.

§ 1.13 min readView as Markdown

Recipe Book is a TypeScript toolkit for recipe sites. You write recipes as plain data, and Recipe Book validates them, converts quantities between metric and US units, and renders them with React components that ship no CSS.

Packages

Package @recipe-book/core @recipe-book/react
What it does Parses and validates recipes, converts units, and reads and writes schema.org JSON-LD. Renders recipes with React components that ship no CSS.
Requires Node 22+ or a supported browser Node 22+ or a supported browser, and React 18 (18.2 or later) or React 19 (any 19.x)
Browser support Chrome and Edge 80+, Firefox 78+, Safari 13.1+, iOS Safari 13.4+. Built as ES2020. Same as core
Bundle size (min+gzip) Under 23.10 kB Under 21.18 kB, without the parser
Module formats ESM and CommonJS, with types for each ESM and CommonJS, with types for each
Dependencies None @recipe-book/core, plus react as a peer

The sizes are budgets: CI fails any change that grows a package past its budget. Core’s covers everything but its schema.org functions and label packs. React’s covers every part and hook, with the core code they use, but not the parser or React itself. A page that renders a recipe parsed on the server ships only that. One that parses in the browser also ships parseRecipe, which is under 9.65 kB on its own; see Why parse on the server. Both packages tree-shake, so a page that imports less ships less, except for @recipe-book/react in Next.js’s App Router: it’s one client module, so a page whose Server Components render any part, or a <Recipe.Provider>, ships every part the app uses.

A React app installs only @recipe-book/react, which includes core, so it imports @recipe-book/core as @recipe-book/react/core, @recipe-book/core/schema-org as @recipe-book/react/core/schema-org, and @recipe-book/core/labels as @recipe-book/react/core/labels. Its packs for the parts, which add most of the text of their controls, come from @recipe-book/react/labels.

With TypeScript, strictNullChecks must be on, or if (!result.success) doesn’t narrow a parseRecipe result and reading result.error fails with TS2339. strict includes it, and TypeScript 6.0 and later turn strict on by default. Use version 5.4 or newer, because on 5.0–5.3, emitting declarations (declaration: true) for your own exports whose inferred types come from Recipe Book, such as a parseRecipe result, can fail with TS2742. <Recipe.Image> also needs, on React 18, @types/react 18.2.8 or newer. With older versions, TypeScript doesn’t accept it as a component.

Both packages are MIT-licensed and share one version number, currently 0.6.0, and these docs also cover changes not yet released. The @recipe-book/core changelog and the @recipe-book/react changelog list what changed in each release, and each ships as CHANGELOG.md in its package: @recipe-book/core on npm and @recipe-book/react on npm.

Use core without React

Core doesn’t use React, so it works in scripts, on servers, in React Server Components, and with Vue, Svelte, Angular, or any other framework. It uses no Node-only or browser-only APIs, so it also runs in Bun, Deno, and edge runtimes such as Cloudflare Workers and Vercel’s Edge Runtime. The components are React-only, so with another framework, render the recipe in your own markup: resolve it for the reader’s servings and measurement system with resolveRecipe, as Scale a recipe shows, and format its quantities and times as Display quantities shows. A parsed recipe is plain data, so you can parse it on the server and pass it to the client.

Install core on its own:

Package manager
Terminal
npm i @recipe-book/core
Terminal
pnpm add @recipe-book/core
Terminal
yarn add @recipe-book/core
Terminal
bun add @recipe-book/core

Then start from the node-script example, a TypeScript script that Node 22.18 or a later 22.x, or 23.6 or later, runs with no build step.

Next steps

To render a recipe in your React app with one package and two files, follow the Quickstart.

To show a recipe at another number of servings or in the reader’s measurement system, see Scale a recipe and the Resolving reference.

To show quantities, ingredient lines, temperatures, and times as text, see Display quantities and the Formatting reference.

To import a recipe from another site’s page, see Import recipes and the schema.org JSON-LD reference.

To render a recipe with React, see Render a recipe in React and the React reference.

Contents