Recipe Book0.6.0

1.2Get started

Quickstart

Install Recipe Book, parse a recipe, and render it in your React app with <Recipe.Root> and the parts.

§ 1.23 min readView as Markdown

Install one package and add two files to render a recipe in your React app, with a servings select that rescales its ingredients and a toggle that converts them between metric and US units.

  1. Install the package:

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

    With TypeScript, strictNullChecks must be on, or if (!result.success) in step 3 doesn’t narrow the result and 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 can fail with TS2742.

    An app without React installs @recipe-book/core instead, as Use core without React describes. If a React app also installs @recipe-book/core, keep it on the same version as @recipe-book/react, or the app gets a second copy of core.

  2. Save the sample recipe input as recipe.ts:

    recipe.ts
    import type { RecipeInput } from '@recipe-book/react/core'
    
    export const pancakes = {
      name: 'Buttermilk pancakes',
      servings: 4,
      times: { prep: 10, cook: 15 },
      ingredients: [
        { name: 'all-purpose flour', quantity: '1 ½ cups', equivalents: ['190 g'] },
        { name: 'sugar', quantity: '2 tbsp', equivalents: ['25 g'] },
        { name: 'baking powder', quantity: '2 tsp' },
        { name: 'buttermilk', quantity: '1 ¼ cups' },
        { name: 'egg', plural: 'eggs', quantity: 2 },
        {
          name: 'butter',
          quantity: '3 tbsp',
          note: 'melted',
          equivalents: ['42 g'],
        },
        { name: 'maple syrup', note: 'to serve' },
      ],
      steps: [
        'Whisk the dry ingredients in a large bowl.',
        'Whisk the buttermilk, eggs, and butter, then fold into the dry ingredients.',
        'Cook ¼-cup portions on a buttered griddle, 2–3 minutes per side.',
      ],
    } satisfies RecipeInput
  3. Parse the recipe and render it:

    pancakes.tsx
    import { parseRecipe } from '@recipe-book/react/core'
    import * as Recipe from '@recipe-book/react'
    import { pancakes } from './recipe'
    
    const result = parseRecipe(pancakes)
    if (!result.success) throw result.error
    const recipe = result.data
    
    export function Pancakes() {
      return (
        <Recipe.Root recipe={recipe}>
          <h1>{recipe.name}</h1>
          <Recipe.ServingsSelect />
          <Recipe.SystemToggle />
          <h2>Ingredients</h2>
          <Recipe.Ingredients />
          <h2>Steps</h2>
          <Recipe.Steps />
        </Recipe.Root>
      )
    }

Render <Pancakes /> on any page of your app, including a Next.js Server Component. It shows the recipe at 4 servings in US units, as written. Choose 8 servings, and the flour changes from 1 ½ cups to 3 cups. Then click Metric, and it changes to 380 g.

parseRecipe checks the recipe input and returns the parsed recipe as result.data. <Recipe.Root> holds the recipe’s servings and measurement system, and the parts inside it read and set them: <Recipe.ServingsSelect>, <Recipe.SystemToggle>, <Recipe.Ingredients>, and <Recipe.Steps>. The parts ship no CSS.

The sample’s steps have no temperatures, so the toggle leaves them as written. In a recipe whose steps have temperatures, it converts them too, as <Recipe.StepText> describes.

Runnable examples

Each project in examples/ uses the same sample recipe:

  • nextjs-app-router: a Next.js App Router page that parses the recipe in a Server Component and renders it with the parts, including its image through Next.js’s Image, and its schema.org JSON-LD with <Recipe.JsonLd>
  • vite-spa: a Vite single-page app that parses the recipe input in the browser, passes result.data to <Recipe.Root>, and styles the parts with plain CSS
  • node-script: a Node script that parses the recipe and prints its ingredients, with no React and no build step
  • seo-json-ld: an Astro page that renders the recipe at build time, writes its schema.org JSON-LD with <Recipe.JsonLd>, and ships no client-side JavaScript
  • react-router-ssr: a React Router app in framework mode that parses the recipe in a route’s loader on the server, renders it with the parts and its schema.org JSON-LD with <Recipe.JsonLd>, and hydrates the page in the browser
  • astro-island: an Astro page that parses the recipe at build time, renders its image and its schema.org JSON-LD with no client-side JavaScript, and hydrates a React island with the servings and units controls, the ingredients, and the steps

To run vite-spa, node-script, or seo-json-ld in your browser, choose Open in StackBlitz under it. To run any example on your machine, use Node.js 22.23.4 or later. Copy the example’s folder, delete the dependencies whose version is workspace:* from its package.json, and install @recipe-book/react with npm, or @recipe-book/core for node-script. Then run npm run dev, or node src/index.ts for node-script.

Next steps

  • Render a recipe in React to keep the parser on the server, write components that read the recipe’s state, and parse in the browser
  • Style a recipe to style the parts with className, style, and the data attributes they render
  • Author recipes to write your own recipe input
Contents