DEV Community: Maikelev

Integrate AI Models with Genkit and Node.js

Maikelev — Fri, 20 Jun 2025 03:54:47 +0000

In this tutorial, we'll use Gemini's gemini-2.5-flash model to implement two key functionalities.

Bidirectional Translation: Translate text between English and Spanish (and vice versa).
Text Improvement: Refine and optimize the quality of a given text.

Check the supported models from Genkit to explore other AI models you can integrate into your projects.

What is Genkit?

Google's open-source framework for integrating AI into your projects, acting as an AI wrapper with extended functionalities.
Genkit.dev

Note: Before we start with the code, it's crucial to understand that Genkit operates exclusively in server environments (such as Node.js, Cloud Functions, etc.). Currently, there are no SDKs or methods for its direct client-side implementation.

1) Create the project

We'll start by setting up our project's basic structure and installing the necessary dependencies:

mkdir ia-translate
cd ia-translate
npm init -y
npm install genkit @genkit-ai/googleai dotenv

2) Install additional dependencies

npm install cors express zod

# Install development dependencies (for TypeScript)
npm install --save-dev types/cors types/express types/express-serve-static-core types/node typescript

3) Get the Gemini API Key

Go to Google AI Studio: aistudio.google.com
Create API Key: On the left sidebar, look for "Get API Key"
Copy and Paste this key into the .env file in the backend/ directory

Remember to keep your API key secure and never commit it to version control.

4) Project Structure

To organize the code, our project will follow the structure below. This reflects the separation between the backend (with Genkit) and the frontend (the user interface).

ia-translate/
├── backend/
│   ├── app.ts               # Express server: defines routes and exposes Genkit flows
│   └── translateFlow.ts     # Here we define the Genkit flows (e.g., `translateTextFlow`)
│   ├── .env.example             # Template for sensitive environment variables (e.g., GEMINI_API_KEY)
│   ├── .env                     # **Create this file.** Contains the actual environment variables (DO NOT commit to Git)
│   ├── package.json
│   └── tsconfig.json            # TypeScript configuration for the backend
├── frontend/
│   ├── index.html
│   ├── styles.css
│   └── translatorIA.js          # Client-side JavaScript logic to interact with the backend
├── .gitignore
└── README.md

5) Genkit Initialization and Model Configuration

Inside the backend/ folder, create a new file named translateFlow.ts. In this file, we will configure and initialize Genkit, specifying the Gemini AI model (gemini-2.5-flash) we will use and connecting it to your API Key.

backend/translateFlow.ts:

import { googleAI, gemini15Flash } from "@genkit-ai/googleai"
import { genkit, z } from "genkit"
import dotenv from "dotenv"

// --- Zod Schemas for Structured Output ---
// These schemas define the expected structure of the AI model's response.
// Genkit uses these to guide the model's output and to parse/validate it.
const optionSchema = z.object({
  option: z.string(),
  explanation: z.string(),
})

const improveSchema = z.object({
  resultList: z.array(optionSchema),
})

const translateSchema = z.object({
  resultText: z.string(),
})

dotenv.config()

const ai = genkit({
  plugins: [googleAI({ apiKey: process.env.GEMINI_API_KEY })],
  model: googleAI.model("gemini-2.5-flash"),
})

export const translateText = ai.defineFlow(
  {
    name: "translateText", // Unique name for this Genkit flow
    // inputSchema: Defines the expected structure of the input data for this flow.
    inputSchema: z.object({
      text: z.string().min(1, "Text is required"),
      language: z.enum(["English", "Spanish"]),
      action: z.enum(["translate", "improve"]),
    }),
    /* 
      The flow's outputSchema is implicitly handled by the return types
      and the ai.generate output schema, allowing flexible return based on action.
    */
  },
  async (input) => {
    const { text, language, action } = input
    const isImprove = action === "improve"

    const prompt = isImprove
      ? `Please improve this ${language} text:\n\n${text}\n\nReturn a list with 2 options to improve the text.`
      : `Translate this to ${language}:\n\n${text}\n\nReturn ONLY the translated text. DO NOT include any additional text, explanations, or suggestions.`

    // Uses Genkit's `generate` function to call the configured AI model.
    const result = await ai.generate({
      prompt: prompt,
      config: {
        // Model configuration: lower temperature for more consistent/less creative output.
        temperature: isImprove ? 0.3 : 0.2,
      },
      /* 
        output: { schema: ... }: CRUCIAL for structured output.
        Instructs Genkit to expect and attempt to parse the AI's response
        according to the specified Zod schema (improveSchema or translateSchema).
      */
      output: { schema: isImprove ? improveSchema : translateSchema },
    })

    const parsedOutput = result.output
    if (!parsedOutput) {
      throw new Error("No result received from translation flow")
    }

    if (isImprove) {
      if (
        "resultList" in parsedOutput &&
        Array.isArray(parsedOutput.resultList)
      ) {
        return parsedOutput // Returns the object `{ resultList: [...] }` if valid
      }
      throw new Error(
        "Output for improve action did not match expected schema.",
      )
    } else {
      if (
        "resultText" in parsedOutput &&
        typeof parsedOutput.resultText === "string"
      ) {
        return parsedOutput // Returns the object `{ resultText: "..." }` if valid
      }
      throw new Error(
        "Output for translate action did not match expected schema.",
      )
    }
  },
)

6) Executing the Flow (Express Server)

Now, let's create the app.ts file directly in the backend/ folder. This file will serve as the entry point for our Node.js server. It will use Express to define an API route (/api/translate) that will receive requests from the frontend and pass them to our Genkit flow (translateText).

backend/app.ts:

import express from "express"
import cors from "cors"
import { translateText } from "./translateFlow.ts"

// Define an interface for the expected structure of the request body
interface TranslateRequest {
  text: string
  language: "English" | "Spanish"
  action: "translate" | "improve"
}

const app = express()
const PORT = process.env.PORT || 3001

app.use(express.json())
app.use(express.urlencoded({ extended: true }))
app.use(
  cors({
    origin: "http://localhost:3000", // Configure CORS to allow requests only from http://localhost:3000 (your frontend)
  }),
)

const translateHandler = (req: express.Request, res: express.Response) => {
  const { text, language, action } = req.body as TranslateRequest

  if (!text || !language || !action) {
    res.status(400).json({
      error: "Missing required fields: text, language, and action are required",
    })
    return
  }

  if (!text.trim()) {
    res.status(400).json({
      error: "Text cannot be empty",
    })
    return
  }

  translateText({ text, language, action })
    .then((result: any) => {
      if (!result) {
        throw new Error("No result received from translation flow")
      }

      res.status(200).json(result)
    })
    .catch((error: any) => {
      console.error("Error in /api/translate endpoint:", error) // Log the error to the console
      res
        .status(500)
        .json({ error: "Failed to process request", details: error.message })
    })
}

app.post("/api/translateText", translateHandler)

app.get("/", (_, res: express.Response) => {
  res.send("Genkit Translation API is running!")
})

app.listen(PORT, () => {
  console.log(`Server listening at http://localhost:${PORT}`) // Log the server URL to the console
  console.log(`Access the API at http://localhost:${PORT}/api/translate`) // Provide API endpoint access info
})

7) Compilation and Execution

If you are using TypeScript (as in this project), you first need to compile your code. Make sure you have TypeScript installed globally:

npm install -g typescript

To leverage Genkit's Dev UI (Developer User Interface), install its command-line interface (CLI) globally:

npm install -g genkit-cli

When you run genkit start, it not only starts your server but also brings up a local web interface (usually at http://localhost:4000/flows) that allows you to interactively inspect and debug your Genkit flows.
Genkit Developer UI

Project Scripts

To simplify execution, let's add the following scripts to the package.json file within the "scripts" object:

"scripts": {
   "build": "tsc",
    "dev": "npx ts-node app.ts",
    "start": "genkit start -- npx ts-node app.ts"
  }

8) Frontend Application

Next, let's build a simple frontend using plain HTML, CSS, and JavaScript. This will be our way of interacting with the API we built using Genkit. To easily serve these static files during development, we'll use lite-server.

I've already created the full frontend project, and you'll find the complete repository link at the end of this tutorial.

To get started, navigate to your frontend folder in the terminal and run:

npm install
npm run dev

This will launch the frontend project in your browser at http://localhost:3000.

Below is the key part of our main JavaScript file, focusing on how we interact with the Genkit API:

frontend/translatorIA.js:

document.addEventListener("DOMContentLoaded", () => {
  // Function to make the API call to our backend.
  async function translateTextApiCall({ text, language, action }) {
    try {
      const response = await fetch(state.backendUrl, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ text, language, action }),
      })
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`)
      }

      // This 'data' object will match the Zod schemas returned by the Genkit flow.
      const data = await response.json()
      return data
    } catch (error) {
      console.error("API call error:", error)
      throw new Error("Could not connect to the server or process the request.")
    }
  }

  async function handleAction(action) {
    const text = originalText.value.trim()
    if (!text) return
    translatedText.innerHTML =
      '<span class="loading-spinner">Traduciendo...</span>' // Show loading spinner

    try {
      const resultObject = await translateTextApiCall({
        text,
        language: state.selectedLanguage,
        action,
      })

      // Check if the result indicates an 'improve' action or contains a resultList
      // as defined by our Genkit flow's output schemas.
      if (action === "improve" || resultObject.resultList?.length > 0) {
        renderImproveResult(resultObject)
      } else {
        setText(translatedText, resultObject.resultText)
      }
    } catch (error) {
      setText(
        translatedText,
        error.message || "Error: Unable to process the request.",
      )
    }
  }
})

Demo

Here's a quick demonstration of the translator in action:

You can check out the complete project on GitHub to see it in action.

That's it, everyone! This demonstrates an easy way to wrap and use AI models in your applications with Node.js and Genkit. There's much more you can create and integrate, and I'll cover more advanced topics in future posts.

References:

📘 Genkit Documentation
✍️ Editing assistance with IA (Gemini)

Discriminated Unions in TypeScript

Maikelev — Fri, 13 Jun 2025 02:35:52 +0000

We'll explore three ways to create a discriminated union in TypeScript and the benefits it brings to our code.

What is a discriminated union?

Discriminated unions are a technique in TypeScript for creating a union of types that share a common property (the discriminator), whose literal value allows TypeScript to know exactly which type to use.

In this tutorial, the discriminator will be the type property, although it can have any name as long as it's the same in all the types.

The discriminator property must be a literal type, such as a string literal, number literal, or boolean literal.

Let's say we have these two interfaces:

interface Person {
  type: "Person"
  roles: ("engineer" | "technician" | "supervisor")[]
}

interface Robot {
  type: "Robot"
  task: "packaging" | "transport" | "maintenance"
}

I. Intersection with common fields

type Entity = { name: string } & (Person | Robot)

This is useful when the interfaces come from elsewhere (for example, generated automatically or imported from another system) and you can't modify them, but you want to work with common properties. It also applies if the common property doesn't have a direct logical relationship with the specific types.

This option may not be very clear at first glance, and the IDE might not provide much assistance when working with it.

II. Using a base interface

interface BaseEntity {
  name: string
}

interface Person extends BaseEntity {
  type: "Person"
  roles: ("engineer" | "technician" | "supervisor")[]
}

interface Robot extends BaseEntity {
  type: "Robot"
  task: "packaging" | "transport" | "maintenance"
}

type Entity = Person | Robot

TypeScript provides better autocomplete when using extends, and the IDE offers a better development experience.

III. Extensible record (map or dictionary)

type EntityMap = {
  Person: Person
  Robot: Robot
}

type Entity = EntityMap[keyof EntityMap]

Example of usage

const handlers: { [K in keyof EntityMap]: (entity: EntityMap[K]) => void } = {
  Person: (e) => console.log(e.roles),
  Robot: (e) => console.log(e.task),
}

Here, the type and its corresponding function are automatically linked, and TypeScript will show an error if you forget to handle a case.

You can also create computed types based on the keys:

type EntityTypes = keyof EntityMap // 'Person' | 'Robot'
type EntityOf<T extends EntityTypes> = EntityMap[T]

This approach is useful when you want to associate metadata with each type. For example, having an object that maps type → render function or associating a type with specific configuration.

Contextual Typing with Discriminated Unions

TypeScript can accurately infer the subtype (Person or Robot) during the literal array construction because:

The objects have a literal type ('Person' or 'Robot').
The properties exactly match one of the subtypes.
The context (Array) helps TypeScript resolve the inference.

This is called contextual typing with discriminated unions.

const entityList: Array<Entity> = [
  {
    type: "Person",
    name: "Person 1",
    roles: ["engineer", "technician"],
    // (property) Person.roles: ("engineer" | "technician" | "supervisor")[]
  },
  {
    type: "Person",
    name: "Person 2",
    roles: ["technician"],
  },
  {
    type: "Robot",
    name: "Robot 1",
    task: "transport",
    // (property) Robot.task: "packaging" | "transport" | "maintenance"
  },
]

What Happens Outside the Literal Context?

Outside the immediate literal context, type inference is lost.

TypeScript doesn't know which subtype (Person or Robot) you're working with, because entity is of the base type Entity (it only knows about name and type).

entityList.forEach((entity) => {
  entity.roles // ❌ Error: Property 'roles' does not exist on type 'Entity'.

  if (entity.type === "Person") {
    entity.roles // ✅ Now it works thanks to discriminated unions.
  }
})

Narrowing

We can also use narrowing techniques, such as runtime checks (conditions).

TypeScript narrows the type of a variable within a condition by using the value of the discriminator (type).

TypeScript automatically uses the type property to infer which subtype you're working with, providing complete type safety without needing to use type assertions.

function handleEntity(entity: Entity) {
  switch (entity.type) {
    case "Person":
      console.log(entity.roles)
      break
    case "Robot":
      console.log(entity.task)
      break
  }
}

Exhaustiveness Checking

Another important use case is ensuring that the compiler warns us if we forget to handle one of the variants in a discriminated union. For example, if we later add a new entity like Alien:

interface Alien extends BaseEntity {
  type: "Alien"
  planet: string
}

To solve this, TypeScript can help us ensure that all possible cases are handled using exhaustiveness checking.

Here are two ways to do this:

I. Enable strictNullChecks and enforce a return type
If we enable strictNullChecks in the compiler options and define an explicit return type (e.g., string), TypeScript will throw an error if a branch does not return a value:

{
  "compilerOptions": {
    "strictNullChecks": true
  }
}

function handleEntity(entity: Entity): string {
  // ❌ Error: Argument of type 'Alien' is not assignable to parameter of type 'never'.
  switch (entity.type) {
    case "Person":
      console.log(entity.roles)
      break
    case "Robot":
      console.log(entity.task)
      break
  }
}

This forces us to either handle all possible cases or provide a fallback.

II. Using never for Exhaustiveness Checking

Another, more explicit, way is to use the never type, which the compiler uses to ensure that no cases are left unhandled.

function assertNever(x: never): never {
  throw new Error("Unexpected object: " + x)
}

With this approach, the compiler checks that after handling all known cases, nothing remains. If a case is forgotten, TypeScript throws an error because the type won't be never.

function handleEntity(entity: Entity): string {
  switch (entity.type) {
    case "Person":
      console.log(entity.roles)
      break
    case "Robot":
      console.log(entity.task)
      break
    default:
      return assertNever(entity)
    // ❌ ERROR: Argument of type 'Alien' is not assignable to parameter of type 'never'.
  }
}

This approach requires an extra helper function but makes it much clearer when a case is missing, as the error will include the name of the missing type.

Conclusion

For simple use cases, a base interface works well. When you need more flexibility, like associating handlers or metadata with each type, consider using a mapped type.