Get started with Genkit JS

This guide shows you how to get started with Genkit in a Node.js app and test it in the Developer UI.

Prerequisites

Before you begin, make sure your environment meets these requirements:

• Node.js v20 or later
• npm

This guide assumes you’re already familiar with building Node.js applications.

Set up your project

Create a new Node.js project and configure TypeScript:

mkdir my-genkit-app
cd my-genkit-app
npm init -y

# Set up your source directory
mkdir src
touch src/index.ts

# Install and configure TypeScript
npm install -D typescript tsx
npx tsc --init

This sets up your project structure and a TypeScript entry point at src/index.ts.

Install Genkit packages

First, install the Genkit CLI globally. This gives you access to local developer tools, including the Developer UI:

npm install -g genkit-cli

Then, add the following packages to your project:

npm install genkit @genkit-ai/googleai

• genkit provides Genkit core capabilities.
• @genkit-ai/googleai provides access to the Google AI Gemini models.

Configure your model API key

Genkit can work with multiple model providers. This guide uses the Gemini API, which offers a generous free tier and doesn’t require a credit card to get started.

To use it, you’ll need an API key from Google AI Studio:

Get a Gemini API Key

Once you have a key, set the GEMINI_API_KEY environment variable:

export GEMINI_API_KEY=<your API key>

Note

Genkit also supports models from Vertex AI, Anthropic, OpenAI, Cohere, Ollama, and more. See supported models for details.

Create your first flow

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

Update src/index.ts with the following:

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

// Initialize Genkit with the Google AI plugin
const ai = genkit({
  plugins: [googleAI()],
  model: googleAI.model('gemini-2.5-flash', {
    temperature: 0.8
  }),
});

// Define input schema
const RecipeInputSchema = z.object({
  ingredient: z.string().describe('Main ingredient or cuisine type'),
  dietaryRestrictions: z.string().optional().describe('Any dietary restrictions'),
});

// Define output schema
const RecipeSchema = z.object({
  title: z.string(),
  description: z.string(),
  prepTime: z.string(),
  cookTime: z.string(),
  servings: z.number(),
  ingredients: z.array(z.string()),
  instructions: z.array(z.string()),
  tips: z.array(z.string()).optional(),
});

// Define a recipe generator flow
export const recipeGeneratorFlow = ai.defineFlow(
  {
    name: 'recipeGeneratorFlow',
    inputSchema: RecipeInputSchema,
    outputSchema: RecipeSchema,
  },
  async (input) => {
    // Create a prompt based on the input
    const prompt = `Create a recipe with the following requirements:
      Main ingredient: ${input.ingredient}
      Dietary restrictions: ${input.dietaryRestrictions || 'none'}`;

    // Generate structured recipe data using the same schema
    const { output } = await ai.generate({
      prompt,
      output: { schema: RecipeSchema },
    });

    if (!output) throw new Error('Failed to generate recipe');

    return output;
  }
);

// Run the flow
async function main() {
  const recipe = await recipeGeneratorFlow({
    ingredient: 'avocado',
    dietaryRestrictions: 'vegetarian'
  });

  console.log(recipe);
}

main().catch(console.error);

This code sample:

• Defines reusable input and output schemas with Zod
• Configures the gemini-2.5-flash model with temperature settings
• Defines a Genkit flow to generate a structured recipe based on your input
• Runs the flow with a sample input and prints the result

Why use flows?

• Type-safe inputs and outputs
• Integrates with the Developer UI
• Easy deployment as APIs
• Built-in tracing and observability

Test in the Developer UI

The Developer UI is a local tool for testing and inspecting Genkit components, like flows, with a visual interface.

Start the Developer UI

Run the following command from your project root:

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

This starts your app and launches the Developer UI at http://localhost:4000 by default.

Note

The command after -- should run the file that defines or imports your Genkit components. You can use tsx, node, or other commands based on your setup. Learn more in developer tools.

Optional: Add an npm script

To make starting the Developer UI easier, add the following to your package.json scripts:

"scripts": {
  "genkit:ui": "genkit start -- npx tsx --watch src/index.ts"
}

Then run it with:

npm run genkit:ui

Run and inspect the flow

In the Developer UI:

1. Select the recipeGeneratorFlow from the list of flows
2. Enter sample input:

   {
     "ingredient": "avocado",
     "dietaryRestrictions": "vegetarian"
   }

3. Click Run

You’ll see the generated recipe as structured output, along with a visual trace of the AI generation process for debugging and optimization.

Next steps

Now that you’ve created and tested your first flow, explore more features to build powerful AI-driven applications:

• Developer tools: Set up your local workflow with the Genkit CLI and Dev UI.
• Generating content: Use Genkit’s unified generation API to work with multimodal and structured output across supported models.
• Defining flows: Learn about streaming flows, schema customization, deployment options, and more.
• Prompt management: Define flexible prompt templates using .prompt files or code.
• App integration: See a full-stack Genkit app example built with flows and the Gemini API.