Express tutorial

In this tutorial, you’ll build Bargain Chef, a standalone Genkit backend on Express that exposes a recipe-generating flow over HTTP. It uses two AI patterns Genkit simplifies: streaming structured output and tool calling.

What you’ll build

For each request, your server prompts Gemini to draft a recipe, and the model calls a tool to look up mock grocery sale prices so it can prefer on-sale ingredients. The server streams the recipe back field-by-field as it’s generated, so clients see progress before the full recipe is ready.

You can find the finished code on GitHub.

Prerequisites

• Node.js v20 or later
• npm
• Familiarity with Express and TypeScript

Set up the application

Create the project

Create a new Express project:

npm

mkdir my-genkit-express
cd my-genkit-express
npm init -y
npm pkg set type=module
npx tsc --init
mkdir -p src/genkit
touch src/index.ts src/genkit/bargainChefFlow.ts

pnpm

mkdir my-genkit-express
cd my-genkit-express
pnpm init -y
npm pkg set type=module
pnpm dlx tsc --init
mkdir -p src/genkit
touch src/index.ts src/genkit/bargainChefFlow.ts

yarn

mkdir my-genkit-express
cd my-genkit-express
yarn create -y
npm pkg set type=module
yarn dlx tsc --init
mkdir -p src/genkit
touch src/index.ts src/genkit/bargainChefFlow.ts

bun

mkdir my-genkit-express
cd my-genkit-express
bun create -y
npm pkg set type=module
bunx tsc --init
mkdir -p src/genkit
touch src/index.ts src/genkit/bargainChefFlow.ts

Install packages

npm

npm install express cors genkit @genkit-ai/google-genai @genkit-ai/express
npm install -D typescript tsx @types/node @types/express @types/cors genkit-cli

pnpm

pnpm add express cors genkit @genkit-ai/google-genai @genkit-ai/express
pnpm add -D typescript tsx @types/node @types/express @types/cors genkit-cli

yarn

yarn add express cors genkit @genkit-ai/google-genai @genkit-ai/express
yarn add -D typescript tsx @types/node @types/express @types/cors genkit-cli

bun

bun add express cors genkit @genkit-ai/google-genai @genkit-ai/express
bun add -d typescript tsx @types/node @types/express @types/cors genkit-cli

These packages include:

• express: The Express web framework.
• cors: Express CORS middleware. Lets browser frontends served from a different origin (such as a Vite or Next.js dev server) call the Genkit endpoint.
• genkit: Core Genkit SDK.
• @genkit-ai/google-genai: Plugin that connects Genkit to Google’s Gemini models.
• @genkit-ai/express: Provides Express server integration for Genkit flows.
• genkit-cli: CLI tool that enables Genkit testing and observability.

Configure a model API key

This tutorial uses the Gemini API from Google AI Studio.

Get a Gemini API Key

Set the GEMINI_API_KEY environment variable to your key:

export GEMINI_API_KEY=<your API key>

Prefer a different model?

This tutorial uses Gemini, but Genkit also supports Anthropic (Claude), OpenAI, and many other model providers.

Create the backend

The backend handles requests from your clients. For each request, it prompts Gemini to draft a recipe, lets the model call a tool to look up today’s grocery sale prices, and streams the partial recipe back as it’s generated.

The whole pipeline is a single Genkit flow. A flow is a special Genkit function with built-in observability, type safety, and tooling integration.

You’ll build the backend in four parts:

1. Initialize Genkit and register Gemini as the model provider.
2. Define a tool the model can call to fetch sale prices.
3. Describe the recipe shape with Zod so Genkit can validate the final output and stream partial recipe chunks.
4. Define the flow that ties everything together.

Create src/genkit/bargainChefFlow.ts:

src/genkit/bargainChefFlow.ts

import { googleAI } from '@genkit-ai/google-genai';
import { genkit, z } from 'genkit';

const ai = genkit({
  plugins: [googleAI()],
});

const getIngredientsOnSale = ai.defineTool(
  {
    name: 'getIngredientsOnSale',
    description:
      'Returns the ingredients on sale at the local grocery store, with prices. The sale set differs between weekdays and weekends.',
    inputSchema: z.object({
      dayType: z
        .enum(['weekday', 'weekend'])
        .describe('Whether to fetch weekday or weekend sale prices.'),
    }),
    outputSchema: z.array(
      z.object({
        name: z.string(),
        price: z.string(),
      }),
    ),
  },
  async ({ dayType }) => {
    // Mock data: in a real app, query a pricing database.
    return dayType === 'weekend'
      ? [
          { name: 'chicken breast', price: '$2.99/lb' },
          { name: 'pasta', price: '$0.79' },
          { name: 'canned tomatoes', price: '$0.99' },
          { name: 'garlic', price: '$0.50 / head' },
          { name: 'olive oil', price: '$6.99' },
        ]
      : [
          { name: 'eggs', price: '$3.49 / dozen' },
          { name: 'spinach', price: '$1.99' },
          { name: 'parmesan', price: '$4.99' },
          { name: 'lemons', price: '$0.50 each' },
          { name: 'rice', price: '$2.49' },
          { name: 'butter', price: '$3.99' },
        ];
  },
);

const RecipeSchema = z.object({
  title: z.string(),
  description: z.string(),
  servings: z.number(),
  ingredients: z.array(
    z.object({
      name: z.string(),
      quantity: z.string(),
      onSale: z.boolean(),
    }),
  ),
  steps: z.array(z.string()),
});

export const bargainChefFlow = ai.defineFlow(
  {
    name: 'bargainChefFlow',
    inputSchema: z.object({
      craving: z
        .string()
        .describe('What the user feels like eating right now.'),
    }),
    outputSchema: RecipeSchema,
    streamSchema: RecipeSchema.partial(),
  },
  async ({ craving }, { sendChunk }) => {
    const today = new Date().toLocaleDateString('en-US', { weekday: 'long' });

    const { stream, response } = ai.generateStream({
      model: googleAI.model('gemini-flash-latest', {
        temperature: 0.7,
        thinkingConfig: { thinkingLevel: 'MINIMAL' },
      }),
      prompt: `Today is ${today}. The user is craving: ${craving}.

Call the getIngredientsOnSale tool with the dayType that matches today. Saturday and Sunday are weekends; all other days are weekdays. Then propose ONE recipe that takes advantage of those deals. For each ingredient, set onSale=true if it appears in the tool's response, false otherwise.`,
      tools: [getIngredientsOnSale],
      output: { schema: RecipeSchema },
    });

    for await (const chunk of stream) {
      if (chunk.output) sendChunk(chunk.output);
    }

    const { output } = await response;
    if (!output) throw new Error('Failed to generate recipe');
    return output;
  },
);

A few details are worth noting before you wire up the server route:

• Final output and streamed chunks: outputSchema is the complete recipe the flow returns at the end. streamSchema is the same shape with every field optional (RecipeSchema.partial()), because early chunks might only include the title or description.
• The getIngredientsOnSale tool: The model decides when to call it based on the prompt, and the typed inputSchema forces the model to pass dayType: 'weekday' or 'weekend'. In a real app, the tool would query a pricing database, inventory system, or third-party API.
• sendChunk: Each call forwards the latest partial recipe to the client so it can fill in field by field. After the stream completes, the flow awaits response so the HTTP request still resolves with a validated recipe.

Add the server route

Wire up the Genkit flow as an Express route. Create src/index.ts:

src/index.ts

import express from 'express';
import cors from 'cors';
import { expressHandler } from '@genkit-ai/express';
import { bargainChefFlow } from './genkit/bargainChefFlow.js';

const app = express();

app.use(cors());
app.use(express.json());
app.post('/bargainChefFlow', expressHandler(bargainChefFlow));

app.listen(8080, () => {
  console.log('Express server listening on http://localhost:8080');
});

expressHandler adapts your Genkit flow to an Express request handler. It parses the JSON request body, invokes the flow, and (when the client opts in with an Accept: text/event-stream header) streams chunks back as server-sent events. app.use(cors()) enables CORS for all origins, so any browser frontend (a Vite dev server, a separately-deployed Next.js app, etc.) can call this endpoint during development. Before deploying, restrict it to the origins you actually serve (for example, cors({ origin: 'https://your-app.com' })).

Check the project layout

Verify that your project layout matches the structure below:

• package.json
• tsconfig.json
• Directorysrc

  • Directorygenkit

    • bargainChefFlow.ts
  • index.ts

Optional: install the Genkit agent skills

If you’re coding with an AI assistant, install the Genkit Agent Skills so it has structured guidance on Genkit APIs, patterns, and common errors:

npx skills add genkit-ai/skills

See Develop with AI for tool-specific installation instructions.

Run the app

Start the Express server:

npm

npx tsx --watch src/index.ts

pnpm

pnpm dlx tsx --watch src/index.ts

yarn

yarn dlx tsx --watch src/index.ts

bun

bunx tsx --watch src/index.ts

You’ll see Express server listening on http://localhost:8080 in the terminal. The server is now ready to accept requests at POST /bargainChefFlow.

Test and inspect the app

You can test the endpoint directly with curl, and you can use the Developer UI to inspect both manual runs and requests from any client.

Send a request with curl

With the server running, use the -N flag and an Accept: text/event-stream header to consume the streamed response:

curl -N -X POST http://localhost:8080/bargainChefFlow \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"data":{"craving":"something warm with chicken"}}'

The { "data": ... } wrapper is required: Genkit’s HTTP handler reads the flow input from the request body’s data field.

The response arrives as a series of data: events. Each event contains the partial recipe accumulated so far, with fields such as title, ingredients, and steps filling in as the model generates them. The final event contains the complete, validated recipe.

Use the Developer UI

The Developer UI is Genkit’s local console for testing flows and inspecting execution traces. It runs alongside your backend code, gives you a visual runner for any flow in your project, and records every tool call and model invocation so you can iterate on prompts and debug tool behavior.

1. Start the Developer UI from your project root:

   npm

   npx genkit start -- tsx --watch src/index.ts

   pnpm

   pnpm dlx genkit start -- tsx --watch src/index.ts

   yarn

   yarn dlx genkit start -- tsx --watch src/index.ts

   bun

   bunx genkit start -- tsx --watch src/index.ts

   This launches the Developer UI at http://localhost:4000 by default.

   Add a script

   To make starting the Developer UI easier, add the above command to your project’s scripts such as in the package.json.

2. Select bargainChefFlow from the list of flows.

3. Enter sample input:

   { "craving": "something warm with chicken" }

4. Click Run.

   You’ll see the generated recipe, with a trace that builds in real time so you can follow the flow’s progress through each tool call and model invocation.

Inspect traces from connected clients

While the Developer UI is running, any flow invocation triggered from a connected client (such as a web app, mobile app, or another service) appears in the Traces tab alongside flows you run manually.

What you built

You now have a standalone Genkit backend on Express that streams structured output from Gemini over HTTP, calls a tool during generation to ground the model’s response in mock sale-price data, validates input and output against schemas, and surfaces every step in a local trace UI.

Next steps

• Creating flows: Compose multi-step flows, branch on input, and chain model calls.
• Generating content: Swap Gemini for another provider, tune sampling parameters, and work with multimodal input.
• Connect an app framework: Add a full-stack UI that calls your flow.
• Connect a web frontend: Wire a standalone web client up to this backend.
• Deploy your app: Ship to Cloud Run, Vercel, Firebase, or your own infrastructure.
• Developer tools: Dig deeper into the Developer UI, tracing, and evaluation.