DEV Community: Željko Šević

Infrastructure as Code (IaC) with AWS CDK (EC2 Example)

Željko Šević — Wed, 10 Jun 2026 22:01:31 +0000

Infrastructure as Code (IaC) is a DevOps approach where infrastructure is defined and managed using code instead of manual setup. This makes environments reproducible, version-controlled, and easy to scale.

In this guide, you'll provision an AWS EC2 instance using the AWS Cloud Development Kit (CDK). CDK lets you define infrastructure in TypeScript (or other languages), synthesize CloudFormation templates, and deploy stacks through the CDK CLI.

Requirements

Before starting, install:

Node.js version 26
AWS CDK CLI (npm i -g aws-cdk)
AWS CLI

AWS Credentials Setup

Go to IAM → Security credentials in AWS
Create access keys
Configure locally:

aws configure

This stores credentials in:

~/.aws/credentials
~/.aws/config

CDK requires CloudFormation permissions (and bootstrap-related IAM/S3 access). An IAM user scoped only for Terraform EC2 is often insufficient - attach broader permissions or use a dedicated CDK user.

Project Structure

A simple CDK TypeScript setup:

.
├── bin/
│   └── app.ts
├── lib/
│   └── ec2-stack.ts
├── cdk.json
├── package.json
└── tsconfig.json

Install dependencies:

npm i

App Entry

The CDK app wires stacks together in bin/app.ts:

#!/usr/bin/env node
import * as cdk from 'aws-cdk-lib';
import { Ec2Stack } from '../lib/ec2-stack';

const app = new cdk.App();

new Ec2Stack(app, 'Ec2Stack', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION ?? 'eu-north-1',
  },
  instanceName: app.node.tryGetContext('instanceName') ?? 'MyEC2Name',
});

Set the target account and region once per shell session:

export CDK_DEFAULT_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
export CDK_DEFAULT_REGION=eu-north-1

On Windows PowerShell:

$env:CDK_DEFAULT_ACCOUNT = aws sts get-caller-identity --query Account --output text
$env:CDK_DEFAULT_REGION = "eu-north-1"

Stack and EC2 Instance

Define the stack in lib/ec2-stack.ts:

import * as cdk from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import { Construct } from 'constructs';

export interface Ec2StackProps extends cdk.StackProps {
  instanceName?: string;
}

export class Ec2Stack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: Ec2StackProps) {
    super(scope, id, props);

    const instanceName = props?.instanceName ?? 'MyEC2Name';

    const instance = new ec2.Instance(this, 'AppServer', {
      vpc: ec2.Vpc.fromLookup(this, 'DefaultVpc', { isDefault: true }),
      instanceType: ec2.InstanceType.of(
        ec2.InstanceClass.T3,
        ec2.InstanceSize.MICRO,
      ),
      machineImage: ec2.MachineImage.latestAmazonLinux2023(),
      instanceName,
    });

    new cdk.CfnOutput(this, 'InstanceId', {
      value: instance.instanceId,
      description: 'EC2 instance ID',
    });

    new cdk.CfnOutput(this, 'InstancePublicIp', {
      value: instance.instancePublicIp,
      description: 'Public IP address',
    });
  }
}

CDK resolves the default VPC during synthesis. Amazon Linux 2023 is selected automatically for the current region.

Configuration

CDK settings live in cdk.json:

{
  "app": "npx ts-node --prefer-ts-exts bin/app.ts",
  "context": {
    "instanceName": "MyEC2Name"
  }
}

Change instanceName in context to override the default tag without editing stack code.

CDK Workflow

Bootstrap the environment (once per account/region):

cdk bootstrap

Preview the CloudFormation template:

cdk synth

Compare deployed stack with local changes:

cdk diff

Deploy the stack:

cdk deploy

Destroy infrastructure:

cdk destroy

Important Notes

State management

CDK deploys through CloudFormation. Stack state lives in AWS, not in a local file like Terraform's terraform.tfstate.

Bootstrap stack

The first cdk bootstrap creates an S3 bucket and IAM roles CDK uses for deployments. Keep the bootstrap stack in place while you use CDK in that account/region.

Idempotency

Running cdk deploy again updates the stack in place when possible instead of recreating resources unnecessarily.

Version control

Treat CDK code like application code. Commit cdk.json and lockfiles; do not commit cdk.out/ or node_modules/.

Demo

CDK project files for this post live in the cdk-aws-ec2 folder. Get access via code demos.

AI image generation with OpenAI API

Željko Šević — Tue, 09 Jun 2026 22:30:27 +0000

OpenAI exposes image generation through the Image API (POST /images/generations). The official openai npm package wraps it as client.images.generate. This post walks through the main request parameters and how to save generated images from Node.js.

The examples use gpt-image-2, OpenAI's latest GPT Image model. GPT Image models always return base64-encoded image data in data[].b64_json. Use output_format for the on-disk file type and put artistic direction in the prompt.

For text generation with the same package, see the Chat Completions API and Responses API posts. Image generation is also available through Responses API tools, but this post focuses on the dedicated Image API endpoint.

The running scenario: generate marketing hero images for a fictional todo app.

Prerequisites

OpenAI account
Generated API key
Enabled billing
Node.js version 26
openai package installed (npm i openai)

Client setup

Create a client with your API key (read from the environment in production).

import OpenAI from 'openai';

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

The same SDK can target other hosts that implement a compatible API by setting baseURL and apiKey:

const client = new OpenAI({
  apiKey: process.env.LLM_API_KEY,
  baseURL: 'https://your-gateway.example/v1',
});

Azure OpenAI uses AzureOpenAI instead. Confirm your provider supports the Image API and the model you pass to model.

Basic integration

Call client.images.generate with model and prompt. The examples use gpt-image-2, older snapshots include gpt-image-1.5, gpt-image-1, and gpt-image-1-mini. Pin a snapshot (for example gpt-image-2-2026-04-21) when you need stable behavior across deploys.

The prompt describes what to generate. GPT Image models accept up to about 32,000 characters. Be specific about subject, layout, colors, and style.

GPT Image models always return base64 in data[].b64_json. Decode it and write the file yourself.

import { writeFile } from 'node:fs/promises';

const prompt = `
Minimal flat illustration for a productivity app landing page.
Show a todo dashboard with a checklist, calendar widget, and soft pastel palette.
No text labels on screen elements.
`.trim();

const result = await client.images.generate({
  model: 'gpt-image-2',
  prompt,
});

await writeFile('hero.png', Buffer.from(result.data[0].b64_json, 'base64'));

n

Use n to generate multiple images in one request (default 1, maximum 10). Loop over result.data to save each image.

import { writeFile } from 'node:fs/promises';

const result = await client.images.generate({
  model: 'gpt-image-2',
  prompt:
    'Minimal flat illustration of a todo app dashboard, variant layout, soft pastel colors',
  n: 2,
});

for (const [index, item] of result.data.entries()) {
  await writeFile(
    `hero-${index}.png`,
    Buffer.from(item.b64_json, 'base64'),
  );
}

Size

Control dimensions with size. Common presets are 1024x1024 (square), 1536x1024 (landscape), and 1024x1536 (portrait). auto lets the model pick based on the prompt.

gpt-image-2 also accepts custom WIDTHxHEIGHT strings when width and height are multiples of 16, the aspect ratio is between 1:3 and 3:1, and total pixels stay within the documented limits.

const result = await client.images.generate({
  model: 'gpt-image-2',
  prompt:
    'Minimal flat illustration of a todo app dashboard, portrait orientation, soft pastel colors',
  size: '1024x1536',
});

Quality

Set rendering quality with quality. Use low for fast drafts and iterations, then medium or high for final assets. Default is auto.

const draft = await client.images.generate({
  model: 'gpt-image-2',
  prompt:
    'Minimal flat illustration of a todo app dashboard, soft pastel colors',
  quality: 'low',
});

const final = await client.images.generate({
  model: 'gpt-image-2',
  prompt:
    'Minimal flat illustration of a todo app dashboard, soft pastel colors, polished details',
  quality: 'high',
  size: '1024x1536',
});

Output format

GPT Image models return base64 in the JSON response. Use output_format to control the encoded file type: png (default), jpeg, or webp.

import { writeFile } from 'node:fs/promises';

const result = await client.images.generate({
  model: 'gpt-image-2',
  prompt:
    'Minimal flat illustration of a todo app dashboard, soft pastel colors',
  output_format: 'jpeg',
});

await writeFile('hero.jpg', Buffer.from(result.data[0].b64_json, 'base64'));

Compression

When output_format is jpeg or webp, set output_compression from 0 to 100 to trade file size for quality. JPEG is often faster than PNG when latency matters.

const result = await client.images.generate({
  model: 'gpt-image-2',
  prompt:
    'Minimal flat illustration of a todo app dashboard, soft pastel colors',
  output_format: 'webp',
  output_compression: 50,
});

Background

Use background: 'transparent' with png or webp on models that support it when you need a cutout asset. gpt-image-2 does not support transparent backgrounds; use gpt-image-1.5 or an earlier GPT Image model for that workflow, or bake the background into the prompt.

const result = await client.images.generate({
  model: 'gpt-image-1.5',
  prompt: 'Flat icon of a checkmark, no background, centered',
  output_format: 'png',
  background: 'transparent',
});

Production notes

Cost scales with quality and size. See OpenAI pricing before generating at scale.
Moderation - use moderation: 'auto' (default) or 'low' on GPT Image models when you need less restrictive filtering.
Errors - handle image_generation_user_error (for example moderation_blocked) by changing the prompt or inputs; do not blindly retry.
Latency - complex prompts can take up to about two minutes.
Storage - decode and persist files yourself. GPT Image responses are base64 in JSON.

Demo

Runnable scripts for each section live in the openai-image-generation-demo folder. Get access via code demos.

Building AI agents with Vercel AI SDK

Željko Šević — Tue, 09 Jun 2026 08:35:36 +0000

The Vercel AI SDK treats agents as tool-calling loops: the model generates text or invokes tools, the SDK runs those tools, and the loop continues until the model answers or a stop condition fires.

This post builds a support triage agent that looks up customers and invoices, searches an internal knowledge base, and either opens a ticket or escalates to a human. It builds on the LLM integration with Vercel AI SDK post and focuses on multiple tools, stopWhen, and stepCountIs.

For external tools exposed over MCP instead of SDK-native tool() handlers, see the MCP server with Node.js post.

Prerequisites

OpenAI account
Generated API key
Enabled billing
Node.js version 26
ai, @ai-sdk/openai, and zod installed (npm i ai @ai-sdk/openai zod)
Client setup from the Vercel AI SDK integration post

Mental model - steps and the tool loop

A step is one model generation. In that step the model either:

returns text (the loop ends), or
returns tool calls (the SDK executes them and starts another step with the results)

Typical flow for the support triage agent: user question → model calls lookup tools (getCustomer, getInvoice, searchKnowledgeBase) → model creates a ticket or escalates → final answer. stopWhen can end the loop before or after the write tools run.

stepCountIs(5) means "stop after 5 steps" (five model generations), not five individual tool calls. A single step can include multiple parallel tool calls.

When you pass tools without stopWhen, the SDK defaults to stepCountIs(20) as a safety cap.

Support triage scenario

Example prompt:

Customer cus_1042 says they were charged twice for invoice inv_8891. What should we do?

A realistic chain:

getCustomer - plan tier, open ticket count
getInvoice - amount, status, payment IDs
searchKnowledgeBase - duplicate-charge and refund policy
createSupportTicket or escalateToHuman - write action or sentinel stop

The demo uses in-memory fixtures (customers, invoices, knowledge-base articles) so scripts run without a database.

Defining multiple tools

import { tool } from 'ai';
import { z } from 'zod';

const getCustomer = tool({
  description: 'Look up a customer account by ID',
  inputSchema: z.object({
    customerId: z.string().describe('Customer ID, e.g. cus_1042'),
  }),
  execute: async ({ customerId }) => {
    const customer = customers.find((item) => item.id === customerId);
    if (!customer) {
      return { found: false, customerId, error: 'Customer not found' };
    }
    return { found: true, customer };
  },
});

const getInvoice = tool({
  description: 'Look up an invoice by ID, including payment IDs and status',
  inputSchema: z.object({
    invoiceId: z.string().describe('Invoice ID, e.g. inv_8891'),
  }),
  execute: async ({ invoiceId }) => {
    const invoice = invoices.find((item) => item.id === invoiceId);
    if (!invoice) {
      return { found: false, invoiceId, error: 'Invoice not found' };
    }
    return { found: true, invoice };
  },
});

const searchKnowledgeBase = tool({
  description: 'Search internal support articles by keyword',
  inputSchema: z.object({
    query: z.string().describe('Search terms, e.g. duplicate charge refund'),
  }),
  execute: async ({ query }) => {
    // keyword match against mocked articles
    return { query, articles: matches };
  },
});

Add write tools for outcomes:

const createSupportTicket = tool({
  description: 'Create a support ticket after gathering customer and policy context',
  inputSchema: z.object({
    customerId: z.string(),
    subject: z.string().min(3),
    priority: z.enum(['low', 'medium', 'high']),
    summary: z.string().min(10),
  }),
  execute: async (input) => {
    const ticket = createTicket(input);
    return { created: true, ticket };
  },
});

const escalateToHuman = tool({
  description: 'Escalate when policy requires manual review',
  inputSchema: z.object({
    customerId: z.string(),
    reason: z.string().min(10),
    urgency: z.enum(['normal', 'high']),
  }),
  execute: async (input) => ({
    escalated: true,
    queue: input.urgency === 'high' ? 'billing-urgent' : 'billing-standard',
    ...input,
  }),
});

Return structured objects from execute. The SDK serializes them as tool results for the next step. Return explicit errors (for example { found: false, error: '...' }) so the model can recover instead of throwing.

Multi-step triage with `generateText`

Pass all tools and a system prompt with triage rules:

import { generateText, stepCountIs } from 'ai';

const { text, steps } = await generateText({
  model: openai('gpt-5.5'),
  system: `You are a billing support triage agent.
- Look up customer and invoice before recommending refunds.
- Search the knowledge base for policy guidance.
- Create a ticket when you can resolve within policy.
- Call escalateToHuman when manual review is required.`,
  tools: {
    getCustomer,
    getInvoice,
    searchKnowledgeBase,
    createSupportTicket,
    escalateToHuman,
  },
  stopWhen: stepCountIs(8),
  prompt:
    'Customer cus_1042 says they were charged twice for invoice inv_8891. What should we do?',
});

console.log('steps:', steps.length);
console.log(text);

Use a model that supports tool calling (same requirement as web search in the Vercel AI SDK post).

`stopWhen` - when the loop stops

stopWhen defines stopping conditions for the tool loop. Conditions are evaluated only when the last step contains tool results.

A single condition stops when that condition returns true
An array stops when any condition returns true (OR logic)
Without stopWhen, the SDK applies stepCountIs(20)

The loop also ends naturally when the model returns text without further tool calls.

`stepCountIs` - cap the number of steps

stepCountIs(n) stops once steps.length reaches n. Use it on every production agent to prevent runaway loops and unbounded API cost.

Use case	Suggested cap
Single tool, then answer	2 (tool step + text step)
Chat with occasional tool use	3-5
Task agents (triage, research)	8-15
Long autonomous workflows	15-20 (with monitoring)

Tight vs relaxed cap on the same prompt:

import { generateText, stepCountIs } from 'ai';

// Stops after 3 steps even if the model still wants more context
const capped = await generateText({
  model: openai('gpt-5.5'),
  tools: supportTools,
  stopWhen: stepCountIs(3),
  prompt: '...',
});

// Allows a fuller investigation chain
const relaxed = await generateText({
  model: openai('gpt-5.5'),
  tools: supportTools,
  stopWhen: stepCountIs(8),
  prompt: '...',
});

Combining `hasToolCall` with `stepCountIs`

hasToolCall('toolName') stops when the model invokes a specific tool in the latest step. Pair it with stepCountIs for a hard cap plus a sentinel tool:

import { generateText, stepCountIs, hasToolCall } from 'ai';

const { text, steps } = await generateText({
  model: openai('gpt-5.5'),
  system: TRIAGE_INSTRUCTIONS,
  tools: supportTools,
  stopWhen: [stepCountIs(10), hasToolCall('escalateToHuman')],
  prompt:
    'Customer cus_2201 on the starter plan reports a duplicate $190 charge on invoice inv_9104.',
});

escalateToHuman works well as a sentinel: the loop stops as soon as the model decides the case needs a human, without waiting for a final text-only step.

Inspecting `steps` and usage

The steps array on the result contains per-step tool calls, tool results, finish reason, and usage. Use it for debugging and cost tracking:

const { text, steps, totalUsage } = await generateText({
  model: openai('gpt-5.5'),
  tools: supportTools,
  stopWhen: stepCountIs(8),
  prompt: '...',
});

for (const [index, step] of steps.entries()) {
  console.log(`step ${index + 1}`);
  console.log('  toolCalls:', step.toolCalls?.map((c) => c.toolName));
  console.log('  usage:', step.usage);
}

console.log('totalUsage:', totalUsage);

With streamText, pass onStepFinish to log each step as it completes.

`ToolLoopAgent` - reusable agent definition

ToolLoopAgent wraps the same loop for reuse across scripts and API routes. It accepts the same settings as generateText (tools, stopWhen, instructions).

import { ToolLoopAgent, stepCountIs } from 'ai';

const supportTriageAgent = new ToolLoopAgent({
  model: openai('gpt-5.5'),
  instructions: TRIAGE_INSTRUCTIONS,
  tools: supportTools,
  stopWhen: stepCountIs(8),
});

const result = await supportTriageAgent.generate({
  prompt:
    'Customer cus_1042 says they were charged twice for invoice inv_8891. What should we do?',
  onStepFinish: async ({ stepNumber, usage, toolCalls }) => {
    console.log(`step ${stepNumber + 1}`, {
      tokens: usage.totalTokens,
      tools: toolCalls?.map((call) => call.toolName),
    });
  },
});

console.log(result.text);

Use .stream() for streaming. For Next.js chat UIs, see createAgentUIStreamResponse in the AI SDK agents docs.

Streaming with tools

streamText supports the same tools and stopWhen settings:

import { streamText, stepCountIs } from 'ai';

const result = streamText({
  model: openai('gpt-5.5'),
  system: TRIAGE_INSTRUCTIONS,
  tools: supportTools,
  stopWhen: stepCountIs(8),
  prompt: 'Customer cus_1042 says they were charged twice for invoice inv_8891.',
  onStepFinish: async ({ stepNumber, toolCalls }) => {
    console.error(`step ${stepNumber + 1}:`, toolCalls?.map((c) => c.toolName));
  },
});

for await (const part of result.textStream) {
  process.stdout.write(part);
}

Text streams incrementally. Tool calls run between text segments as the loop progresses.

Production notes

Always set stopWhen - do not rely on the default stepCountIs(20) in production without monitoring
Cost - each step is another model call; log steps or onStepFinish usage
Tool errors - return structured errors from execute instead of throwing when the model should retry or escalate
Instructions - keep policy rules in system / instructions, not only in the user prompt
Same patterns elsewhere - PR review (listPRs → getChecks → submitReview) or job-fit scoring use the same loop mechanics with different tools

Demo

Runnable scripts for each section live in the vercel-ai-sdk-agents-demo folder. Get access via code demos.

LLM integration with OpenRouter

Željko Šević — Mon, 08 Jun 2026 15:52:46 +0000

OpenRouter is a unified API gateway to hundreds of language models from providers such as OpenAI, Anthropic, Google, and Meta. You use one API key and one billing surface, and swap models by changing a provider/model slug. OpenRouter exposes a Chat Completions-compatible HTTP API.

This post shows three Node.js integration paths: the official @openrouter/sdk, the openai package with baseURL, and the Vercel AI SDK with @openrouter/ai-sdk-provider.

For deeper patterns on each stack, see the Chat Completions API, OpenAI Responses API (OpenAI direct only), and Vercel AI SDK posts.

Prerequisites

OpenRouter account
API key
Credits or billing enabled as needed
Node.js version 26
Install packages for the path you use:
- @openrouter/sdk (npm i @openrouter/sdk)
- openai (npm i openai)
- ai and @openrouter/ai-sdk-provider (npm i ai @openrouter/ai-sdk-provider)

Configuration

Read credentials from the environment in production.

Variable	Purpose
`OPENROUTER_API_KEY`	Bearer token from OpenRouter settings
`OPENROUTER_MODEL`	Default model slug, for example `openai/gpt-5.5`
`OPENROUTER_SITE_URL`	Optional site URL sent as `HTTP-Referer` for rankings on openrouter.ai
`OPENROUTER_SITE_TITLE`	Optional app name sent as `X-OpenRouter-Title`

Model IDs use the provider/model format, for example openai/gpt-5.5, anthropic/claude-opus-4.8, or google/gemini-3.1-flash-lite. Browse the full catalog at openrouter.ai/models.

The examples below use openai/gpt-5.5, matching the model in the other LLM posts in this series. Override it with OPENROUTER_MODEL when you want a different model.

`@openrouter/sdk`

OpenRouter's official TypeScript SDK is type-safe and generated from the OpenAPI spec.

Client setup

import { OpenRouter } from '@openrouter/sdk';

const client = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  httpReferer: process.env.OPENROUTER_SITE_URL,
  appTitle: process.env.OPENROUTER_SITE_TITLE,
});

Basic integration

const response = await client.chat.send({
  chatRequest: {
    model: process.env.OPENROUTER_MODEL ?? 'openai/gpt-5.5',
    messages: [
      { role: 'user', content: 'Write a one-sentence bedtime story about a unicorn.' },
    ],
  },
});

console.log(response.choices[0].message.content);

System prompt

Add a system message before the user turn to set tone, format, and role.

const response = await client.chat.send({
  chatRequest: {
    model: process.env.OPENROUTER_MODEL ?? 'openai/gpt-5.5',
    messages: [
      { role: 'system', content: 'Reply in one short sentence. Use plain language.' },
      { role: 'user', content: 'Explain what an LLM is.' },
    ],
  },
});

console.log(response.choices[0].message.content);

Streaming

Set stream: true and read incremental text from choices[0].delta.content.

const stream = await client.chat.send({
  chatRequest: {
    model: process.env.OPENROUTER_MODEL ?? 'openai/gpt-5.5',
    messages: [{ role: 'user', content: 'List three colors.' }],
    stream: true,
  },
});

process.stdout.write('[stream] ');
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) {
    process.stdout.write(delta);
  }
}
process.stdout.write('\n');

Model switching

Change only the model string to route the same code to a different provider.

const models = ['openai/gpt-5.5', 'google/gemini-3.1-flash-lite'];

for (const model of models) {
  const response = await client.chat.send({
    chatRequest: {
      model,
      messages: [{ role: 'user', content: 'Reply with exactly one word: ok.' }],
    },
  });

  console.log(model, '->', response.choices[0].message.content);
}

`openai` package

If you already use the OpenAI SDK, point it at OpenRouter with baseURL. The request shape matches the Chat Completions API.

Client setup

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENROUTER_API_KEY,
  baseURL: 'https://openrouter.ai/api/v1',
  defaultHeaders: {
    'HTTP-Referer': process.env.OPENROUTER_SITE_URL,
    'X-OpenRouter-Title': process.env.OPENROUTER_SITE_TITLE,
  },
});

Basic integration

const completion = await client.chat.completions.create({
  model: process.env.OPENROUTER_MODEL ?? 'openai/gpt-5.5',
  messages: [
    { role: 'user', content: 'Write a one-sentence bedtime story about a unicorn.' },
  ],
});

console.log(completion.choices[0].message.content);

System prompt

const completion = await client.chat.completions.create({
  model: process.env.OPENROUTER_MODEL ?? 'openai/gpt-5.5',
  messages: [
    { role: 'system', content: 'Reply in one short sentence. Use plain language.' },
    { role: 'user', content: 'Explain what an LLM is.' },
  ],
});

console.log(completion.choices[0].message.content);

Streaming

const stream = await client.chat.completions.create({
  model: process.env.OPENROUTER_MODEL ?? 'openai/gpt-5.5',
  messages: [{ role: 'user', content: 'List three colors.' }],
  stream: true,
});

process.stdout.write('[stream] ');
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) {
    process.stdout.write(delta);
  }
}
process.stdout.write('\n');

For JSON schema output, Markdown-to-HTML, and few-shot prompting, reuse the patterns from the Chat Completions post with the OpenRouter client and model slug above.

Vercel AI SDK

The @openrouter/ai-sdk-provider package exposes OpenRouter models to generateText, streamText, and related helpers from the ai package. See the OpenRouter Vercel AI SDK guide for the full integration reference.

Client setup

import { createOpenRouter } from '@openrouter/ai-sdk-provider';

const openrouter = createOpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  appUrl: process.env.OPENROUTER_SITE_URL,
  appName: process.env.OPENROUTER_SITE_TITLE,
});

The returned provider is callable. Pass a model slug directly: openrouter('openai/gpt-5.5').

Basic integration

import { generateText } from 'ai';

const { text } = await generateText({
  model: openrouter(process.env.OPENROUTER_MODEL ?? 'openai/gpt-5.5'),
  prompt: 'Write a one-sentence bedtime story about a unicorn.',
});

console.log(text);

System prompt

const { text } = await generateText({
  model: openrouter(process.env.OPENROUTER_MODEL ?? 'openai/gpt-5.5'),
  system: 'Reply in one short sentence. Use plain language.',
  prompt: 'Explain what an LLM is.',
});

console.log(text);

Streaming

import { streamText } from 'ai';

const result = streamText({
  model: openrouter(process.env.OPENROUTER_MODEL ?? 'openai/gpt-5.5'),
  prompt: 'List three colors.',
});

process.stdout.write('[stream] ');
for await (const part of result.textStream) {
  process.stdout.write(part);
}
process.stdout.write('\n');

For structured output, embeddings, and web search, see the Vercel AI SDK post. Those patterns apply when you call OpenAI directly; OpenRouter coverage depends on the model and endpoint.

Demo

Runnable scripts for each integration path live in the openrouter-demo folder. Get access via code demos.

LLM integration with Vercel AI SDK

Željko Šević — Sun, 07 Jun 2026 22:11:46 +0000

Large language models (LLMs) understand and generate text from prompts. The Vercel AI SDK is a provider-agnostic layer over LLM APIs - core functions are generateText, streamText, and embed. This post uses the OpenAI provider and mirrors the patterns from the OpenAI Responses API post.

For the lower-level openai npm package, see the Chat Completions API and Responses API posts.

Prerequisites

OpenAI account
Generated API key
Enabled billing
Node.js version 26
ai, @ai-sdk/openai, and zod installed (npm i ai @ai-sdk/openai zod)
For Markdown output: marked, dompurify, and jsdom (npm i marked dompurify jsdom)

Client setup

Create an OpenAI provider with your API key (read from the environment in production).

import { createOpenAI } from '@ai-sdk/openai';

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });

The same provider can target other hosts that implement a compatible API by setting baseURL and apiKey:

const openai = createOpenAI({
  apiKey: process.env.LLM_API_KEY,
  baseURL: 'https://your-gateway.example/v1',
});

Many third-party gateways support Chat Completions only. The examples below use openai(model) (Responses API path). If your provider does not support it, switch to openai.chat(model) and skip the web search example.

Basic integration

Pass a string as prompt and read text from the result.

import { generateText } from 'ai';
import { createOpenAI } from '@ai-sdk/openai';

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });

const { text } = await generateText({
  model: openai('gpt-5.5'),
  prompt: 'Write a one-sentence bedtime story about a unicorn.',
});

console.log(text);

System prompt

Use the system parameter for stable behavior (tone, format, role). It takes precedence over casual wording in the user message.

const { text } = await generateText({
  model: openai('gpt-5.5'),
  system: 'Reply in one short sentence. Use plain language.',
  prompt: 'Explain what an LLM is.',
});

console.log(text);

Few-shot prompting

Pass prior turns in a messages array with user and assistant roles, then the new user message. Keep task rules in system.

const { text } = await generateText({
  model: openai('gpt-5.5'),
  system:
    'Classify sentiment as exactly one word: positive, negative, or neutral.',
  messages: [
    { role: 'user', content: 'I love this!' },
    { role: 'assistant', content: 'positive' },
    { role: 'user', content: 'This is awful.' },
    { role: 'assistant', content: 'negative' },
    { role: 'user', content: 'It is fine I guess.' },
  ],
});

console.log(text);

Streaming

Use streamText and iterate over textStream for incremental text.

import { streamText } from 'ai';

const result = streamText({
  model: openai('gpt-5.5'),
  prompt: 'List three colors.',
});

for await (const part of result.textStream) {
  process.stdout.write(part);
}

Structured output with JSON schema

Constrain the model to JSON matching your schema via Output.object() and a Zod schema. The SDK validates the result.

import { generateText, Output } from 'ai';
import { z } from 'zod';

const { output } = await generateText({
  model: openai('gpt-5.5'),
  prompt: 'The film Inception was directed by Christopher Nolan.',
  output: Output.object({
    schema: z.object({
      title: z.string(),
      director: z.string(),
    }),
    schemaName: 'movie_summary',
  }),
});

console.log(output.title, output.director);

Markdown output to HTML

Ask for Markdown in system, then convert text to HTML and sanitize before rendering (for example with innerHTML in the browser or when storing HTML).

import { marked } from 'marked';
import { JSDOM } from 'jsdom';
import DOMPurify from 'dompurify';

const purify = DOMPurify(new JSDOM('').window);

const { text } = await generateText({
  model: openai('gpt-5.5'),
  system: 'Reply in Markdown only. Use a heading and a short bullet list.',
  prompt: 'Explain what an LLM is in three bullet points.',
});

const markdown = text;
const html = marked.parse(markdown);
const safeHtml = purify.sanitize(html);

Always run DOMPurify.sanitize on model-generated HTML. The model can emit unsafe markup. Sanitization strips scripts and other dangerous content.

Web search tool

Enable the built-in web search tool when the answer should use current information from the web.

const result = await generateText({
  model: openai('gpt-5.5'),
  tools: { web_search: openai.tools.webSearch() },
  prompt: 'What was a major tech headline this week? Cite sources briefly.',
});

console.log(result.text);

Web search adds latency and tool usage cost. Use a model that supports tools.

Embeddings

Embeddings are numeric vectors that represent the semantic meaning of text. Use them for semantic search, clustering, and RAG.

Pass a single string to embed and read the vector from embedding.

import { embed } from 'ai';

const { embedding } = await embed({
  model: openai.embedding('text-embedding-3-small'),
  value: 'How do I connect pgvector to PostgreSQL?',
});

console.log(embedding.length);

Pass multiple strings in a values array with embedMany. Results are in the same order as the input.

import { embedMany } from 'ai';

const chunks = [
  'pgvector adds vector similarity search to PostgreSQL.',
  'LangChain helps split long documents into retrieval-friendly chunks.',
  'RAG retrieves context first, then asks an LLM to answer.',
];

const { embeddings } = await embedMany({
  model: openai.embedding('text-embedding-3-small'),
  values: chunks,
});

console.log(embeddings.length); // 3

For a full RAG flow with pgvector, see the RAG with OpenAI embeddings post.

Demo

Runnable scripts for each section live in the vercel-ai-sdk-demo folder. Get access via code demos.

Building an MCP server with Node.js

Željko Šević — Sun, 07 Jun 2026 11:25:30 +0000

The Model Context Protocol (MCP) is an open standard for connecting AI hosts (Claude, ChatGPT, Cursor, VS Code, and others) to external context and actions through a structured protocol instead of ad-hoc plugins.

The host runs an MCP client. Your application is the MCP server, exposing tools (actions the model can invoke), resources (read-only data), and optionally prompts (reusable message templates). Communication uses JSON-RPC over a transport such as stdio or HTTP.

This post shows how to build a small todo MCP server with Node.js using the official @modelcontextprotocol/sdk package and Zod schemas.

After the client connects, the server completes an initialization handshake (initialize → initialized). The host discovers capabilities via tools/list, resources/list, and prompts/list, then calls tools or reads resources at runtime.

Prerequisites

Node.js version 26
npm i @modelcontextprotocol/sdk zod
Optional for client testing: Claude Desktop and/or ChatGPT (Connectors / Apps)

The stable v1 SDK is @modelcontextprotocol/sdk. A v2 split (@modelcontextprotocol/server, @modelcontextprotocol/client) is in pre-release - this post uses v1, which matches current production tooling.

MCP capabilities - tools, resources, prompts

Capability	Purpose	Demo example
Tools	Model-invoked actions with typed inputs	`add_todo`, `list_todos`, `mark_todo_done`
Resources	Read-only context the host can fetch	`todo://all` JSON snapshot
Prompts (optional)	Named templates with arguments	`summarize-open-todos`

Tools are the main integration surface - the model calls them via tools/call. Resources are fetched with resources/read and should stay read-only. Prompts return pre-built messages via prompts/get.

Tool inputs need a schema so clients know parameters. With the TypeScript SDK, pass Zod fields in inputSchema:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const server = new McpServer({ name: 'todo-mcp-server', version: '1.0.0' });

server.registerTool(
  'add_todo',
  {
    description: 'Add a new todo item',
    inputSchema: { title: z.string().min(1) },
  },
  async ({ title }) => ({
    content: [{ type: 'text', text: JSON.stringify({ title, done: false }) }],
  })
);

server.registerResource(
  'all-todos',
  'todo://all',
  {
    title: 'All todos',
    mimeType: 'application/json',
  },
  async (uri) => ({
    contents: [
      {
        uri: uri.href,
        mimeType: 'application/json',
        text: JSON.stringify([{ id: 1, title: 'Learn MCP', done: false }]),
      },
    ],
  })
);

server.registerPrompt(
  'summarize-open-todos',
  {
    title: 'Summarize open todos',
    description: 'Ask the model to summarize open todos',
  },
  () => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: 'Summarize my open todos and suggest a priority order.',
        },
      },
    ],
  })
);

Building the server

Use a factory so the same server definition works with multiple transports:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const todos = [
  { id: 1, title: 'Learn MCP basics', done: false },
  { id: 2, title: 'Ship demo server', done: false },
];
let nextId = 3;

export function createMcpServer() {
  const server = new McpServer({ name: 'todo-mcp-server', version: '1.0.0' });

  server.registerTool(
    'add_todo',
    {
      description: 'Add a new todo item',
      inputSchema: { title: z.string().min(1) },
    },
    async ({ title }) => {
      const todo = { id: nextId++, title, done: false };
      todos.push(todo);
      return { content: [{ type: 'text', text: JSON.stringify(todo, null, 2) }] };
    }
  );

  server.registerTool('list_todos', { description: 'List all todo items' }, async () => ({
    content: [{ type: 'text', text: JSON.stringify(todos, null, 2) }],
  }));

  server.registerTool(
    'mark_todo_done',
    {
      description: 'Mark a todo item as done by id',
      inputSchema: { id: z.number().int().positive() },
    },
    async ({ id }) => {
      const todo = todos.find((item) => item.id === id);
      if (!todo) {
        return { content: [{ type: 'text', text: `Todo ${id} not found` }], isError: true };
      }
      todo.done = true;
      return { content: [{ type: 'text', text: JSON.stringify(todo, null, 2) }] };
    }
  );

  // register resource and prompt here (see snippets above)

  return server;
}

Tool handlers return { content: [...] }. Set isError: true when a tool fails so the host can surface the error. Resource handlers return { contents: [...] }. Prompt handlers return { messages: [...] }.

The demo uses an in-memory store so you can run it without API keys or a database.

Transports - stdio vs SSE / Streamable HTTP

MCP separates protocol (JSON-RPC messages) from transport (how bytes move between client and server).

Stdio (StdioServerTransport)

The client spawns your server as a child process. JSON-RPC goes over stdin/stdout.

Use when: Claude Desktop, Cursor, VS Code, Claude Code, local CLI agents
Pros: simplest setup, no ports or firewall rules, no OAuth
Cons: one client per process; cloud hosts cannot spawn your local binary

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { createMcpServer } from './create-server.js';

const server = createMcpServer();
await server.connect(new StdioServerTransport());

Write logs to stderr only - stdout is the protocol channel.

Remote HTTP - SSE (legacy) vs Streamable HTTP (current)

Early MCP remote servers used HTTP + SSE: POST for client→server requests, Server-Sent Events for server→client streaming. That transport is deprecated.

New servers should use Streamable HTTP (StreamableHTTPServerTransport). It supports POST request/response, optional SSE for notifications, and session management. The v2 SDK removes server-side SSE entirely; client-side SSE remains for legacy servers.

Scenario	Transport
Claude Desktop, local dev	stdio
Cursor / VS Code project MCP	stdio
ChatGPT Apps / Connectors	Streamable HTTP over public HTTPS
Legacy SSE-only clients	SSE client transport still exists; prefer Streamable HTTP for new servers

Streamable HTTP entry (stateless):

import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { createMcpServer } from './create-server.js';

const app = createMcpExpressApp();
const PORT = Number(process.env.PORT) || 3000;

app.post('/mcp', async (req, res) => {
  const server = createMcpServer();
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });

  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);

  res.on('close', () => {
    transport.close();
    server.close();
  });
});

app.listen(PORT, () => {
  console.error(`MCP server listening on http://127.0.0.1:${PORT}/mcp`);
});

createMcpExpressApp() enables DNS rebinding protection when binding to localhost - recommended for local HTTP servers.

Deploy Streamable HTTP behind HTTPS before exposing it to cloud clients. ChatGPT Connectors also require OAuth 2.1 for production use.

Connecting MCP clients

Claude Desktop (stdio - primary demo path)

Config file on Windows: %APPDATA%\Claude\claude_desktop_config.json. Open it via Settings → Developer → Edit Config.

{
  "mcpServers": {
    "todo-mcp": {
      "command": "node",
      "args": ["C:/path/to/demos/mcp-server-nodejs-demo/src/stdio.js"]
    }
  }
}

Restart Claude Desktop after saving. Claude shows a tool approval UI before executing write operations.

Claude Desktop (remote HTTP)

claude_desktop_config.json validates stdio servers only - do not put a bare url field there expecting it to work. For a public HTTPS MCP server, use Settings → Connectors → Add custom connector. For local HTTP during development, bridge with mcp-remote as a stdio-launched proxy.

ChatGPT (Connectors / Apps)

ChatGPT has no local MCP config file. Register servers in Settings → Apps (or Connectors) with a name, description, and MCP server URL.

Requirements:

Public HTTPS endpoint (Streamable HTTP)
OAuth 2.1 for production connectors
Stdio-only servers need an HTTP wrapper or tunnel before ChatGPT can reach them

ChatGPT shows confirmation modals before write/modify tool calls.

Cursor

Cursor uses .cursor/mcp.json with the same stdio shape as Claude Desktop (command + args).

What else matters

Security - validate tool inputs, scope tools narrowly, and never expose secrets in resources.
Logging - stderr only for stdio servers; avoid console.log on stdout.
Testing - use @modelcontextprotocol/sdk client helpers with StdioClientTransport for smoke tests.
Spec evolution - prefer Streamable HTTP over legacy SSE; watch the v2 SDK split when upgrading.

Demo

Runnable scripts for this post live in the mcp-server-nodejs-demo folder in the private demos repository. Get access via code demos.

Supabase basics with Node.js

Željko Šević — Sat, 06 Jun 2026 13:21:03 +0000

Supabase is an open-source backend platform built around managed PostgreSQL. You get a database, auto-generated REST APIs (via PostgREST), Auth, file Storage, Realtime subscriptions, and Edge Functions - with a dashboard and SQL editor on top.

Compared to running Postgres yourself, Supabase adds hosted infra, API layers, and product features without you wiring them up. Compared to an ORM-only stack, you often talk to Postgres through the Supabase client or SQL, with RLS (row level security) enforcing access at the database layer.

Prerequisites

Supabase account (free tier is enough for learning)
Node.js version 26
@supabase/supabase-js installed (npm i @supabase/supabase-js)

Create a project and database

In the Supabase dashboard, choose New project, pick a region, and set the database password.
Wait until the project is ready.
Open SQL Editor and run the schema below.

The Table Editor is fine for quick experiments; SQL Editor keeps schema reproducible in git and reviews.

create table if not exists public.todos (
  id bigint generated always as identity primary key,
  title text not null,
  done boolean not null default false,
  created_at timestamptz not null default now()
);

create or replace function public.list_open_todos()
returns setof public.todos
language sql
security definer
set search_path = public
as $$
  select * from public.todos where done = false order by id;
$$;

create or replace function public.mark_todo_done(todo_id bigint)
returns setof public.todos
language sql
security definer
set search_path = public
as $$
  update public.todos set done = true where id = todo_id returning *;
$$;

grant execute on function public.list_open_todos() to service_role;
grant execute on function public.mark_todo_done(bigint) to service_role;

This schema skips RLS setup because this post uses the secret key from Node.js, which bypasses RLS. For browser or mobile clients, use the publishable key instead - it obeys Row Level Security when you enable it on tables.

list_open_todos is a Postgres function exposed as an RPC endpoint.

Postgres functions default to security invoker: they run with the caller's permissions, so RLS applies as that role. security definer runs the function as its owner (often a privileged database role), not as the caller.

API keys and connection

On the project Overview tab you will find:

Project URL (https://<ref>.supabase.co) - for SUPABASE_URL
Publishable key (sb_publishable_..., legacy anon) - for browsers and mobile apps where RLS should limit access; this post does not use it

For Node.js backends, use a secret key from Project Settings → API Keys:

Secret key(s) (sb_secret_...) - full data access, bypasses RLS; trusted servers only, never in client bundles or public repos. Replaces the legacy service_role key.
Reveal or create a secret key in the dashboard (legacy projects: Legacy anon, service_role API keys tab → service_role).

The Supabase JS client talks to PostgREST and can query tables (from) and call registered functions (rpc) only after they exist. It does not run DDL (create table, create function, grant, and similar), so apply the schema in the SQL Editor (or via Supabase CLI migrations in larger projects).

Store values in environment variables:

SUPABASE_URL=https://<ref>.supabase.co
SUPABASE_SECRET_KEY=your-secret-key

Client setup

Create a client with the project URL and secret key. Read values from the environment in real apps; never commit the secret key.

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_SECRET_KEY
);

Every table you create in the public schema is available as supabase.from('<table>'). Custom SQL functions are called with supabase.rpc('<function_name>').

Insert data

Insert one or more rows and return the created records with .select().

const { data, error } = await supabase
  .from('todos')
  .insert([
    { title: 'Learn Supabase client', done: false },
    { title: 'Run RPC example', done: false },
    { title: 'Ship demo', done: true },
  ])
  .select();

if (error) {
  throw new Error(error.message);
}

console.log(data);

Read, update, and delete

Select with filters and ordering:

const { data, error } = await supabase
  .from('todos')
  .select('*')
  .eq('done', false)
  .order('id');

Update matching rows:

const { data, error } = await supabase
  .from('todos')
  .update({ done: true })
  .eq('id', 1)
  .select();

Delete matching rows:

const { error } = await supabase
  .from('todos')
  .delete()
  .eq('id', 1);

Chain .eq(), .in(), .limit(), and other filter helpers the same way across operations.

RPC

Call a database function by name. Our list_open_todos() returns open todos without repeating filter logic in the app.

const { data, error } = await supabase.rpc('list_open_todos');

if (error) {
  throw new Error(error.message);
}

console.log(data);

Functions with parameters map to a second argument:

await supabase.rpc('mark_todo_done', { todo_id: 42 });

Define parameters in SQL (todo_id bigint) and grant execute to service_role when calling RPC from a secret-key backend.

What else matters

Row Level Security (RLS) - When enabled on a table, Postgres denies access until policies allow it. The publishable key is subject to RLS; the secret key is not. Add policies per role (anon, authenticated) and operation when you turn RLS on.
Auth - Supabase Auth stores users in auth.users. After sign-in, the client JWT includes the authenticated role so policies can use auth.uid() for per-user rows.
Migrations - Avoid changing production only via the dashboard. Track SQL in versioned migration files and apply with the Supabase CLI (supabase db push, linked projects) so environments stay aligned.
Generated types - Run supabase gen types typescript --project-id <ref> to emit TypeScript types from your schema for a type-safe client.
Storage - S3-compatible buckets for files (images, PDFs) with bucket policies analogous to RLS.
Realtime - Subscribe to insert/update/delete on tables or channels for live UI updates.
Edge Functions - Deno functions for webhooks, light API logic, or tasks that should not live in the database.
Local dev - supabase init and supabase start spin up local Postgres and services; useful for offline work, while cloud projects are fastest for a first tutorial.

Demo

Runnable scripts for this post live in the supabase-basics-demo folder in the private demos repository. Get access via code demos.

RAG with OpenAI Embeddings, pgvector and LangChain

Željko Šević — Tue, 02 Jun 2026 22:25:21 +0000

Retrieval-Augmented Generation (RAG) is a practical pattern: store knowledge as embeddings, retrieve the most relevant chunks with semantic search, then generate an answer grounded in that context.

This guide shows a simple end-to-end flow with OpenAI embeddings, PostgreSQL + pgvector, and LangChain chunking.

Prerequisites

OpenAI account
Generated API key
Enabled billing
Node.js version 26
PostgreSQL with pgvector extension enabled
npm packages: openai, langchain, pg, pgvector

What are embeddings?

Embeddings are numeric vectors that represent the semantic meaning of text. Similar text should produce vectors that are close in vector space.

In practice:

Convert document chunks to vectors and store them in pgvector
Convert a user question to a vector
Run a nearest-neighbor search to find the most relevant chunks

OpenAI client setup

import OpenAI from 'openai';

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

Embedding one input element

Use a single string when embedding a user query.

const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'How do I connect pgvector to PostgreSQL?',
});

const queryEmbedding = response.data[0].embedding;
console.log(queryEmbedding.length);

Embedding multiple input elements

Use an array to embed multiple chunks in one API call.

const chunks = [
  'pgvector adds vector similarity search to PostgreSQL.',
  'LangChain helps split long documents into retrieval-friendly chunks.',
  'RAG retrieves context first, then asks an LLM to answer.',
];

const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: chunks,
});

const rows = response.data.map((item, index) => ({
  text: chunks[index],
  embedding: item.embedding,
}));

console.log(rows.length); // 3

Chunking documents with LangChain

Chunking makes retrieval more precise. Instead of embedding one large document, split it into smaller overlapping parts.
Start with chunkSize: 800 and chunkOverlap: 120, then adjust based on your document style and answer quality.

import { RecursiveCharacterTextSplitter } from 'langchain/text_splitter';

const splitter = new RecursiveCharacterTextSplitter({
  chunkSize: 800,
  chunkOverlap: 120,
});

const docs = await splitter.createDocuments([
  `RAG combines retrieval and generation. Store chunks as vectors and fetch similar chunks at query time.`,
]);

console.log(docs.map((doc) => doc.pageContent));

Store embeddings in pgvector

Create a table with a vector column. text-embedding-3-small outputs 1536 dimensions.

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE IF NOT EXISTS rag_chunks (
  id BIGSERIAL PRIMARY KEY,
  content TEXT NOT NULL,
  embedding VECTOR(1536) NOT NULL,
  source TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Insert chunk vectors from Node.js:

import pg from 'pg';
import pgvector from 'pgvector/pg';

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
await pgvector.registerTypes(pool);

await pool.query(
  `INSERT INTO rag_chunks (content, embedding, source)
   VALUES ($1, $2, $3)`,
  ['Chunk content', pgvector.toSql(queryEmbedding), 'notes.md']
);

Semantic search in pgvector

Embed the user question, then retrieve nearest chunks using cosine distance.
Lower distance means a closer semantic match.
top-k means how many nearest chunks you return (in this query, k=4 with LIMIT 4).
You can also use a simple threshold (for example 0.4) to discard weak matches.
As a starting point, many setups work well in the 0.35 to 0.45 range for cosine distance, then tune with real questions from your domain.

const searchResult = await pool.query(
  `SELECT id, content, source, embedding <=> $1::vector AS distance
   FROM rag_chunks
   ORDER BY embedding <=> $1::vector
   LIMIT 4`,
  [pgvector.toSql(queryEmbedding)]
);

const contextChunks = searchResult.rows.map((row) => row.content);

Threshold filtering example:

const DISTANCE_THRESHOLD = 0.4;
const filteredChunks = searchResult.rows
  .filter((row) => Number(row.distance) <= DISTANCE_THRESHOLD)
  .map((row) => row.content);

If no chunks pass the threshold, skip answer generation and return a fallback message:

if (filteredChunks.length === 0) {
  console.log('I do not have enough context to answer this.');
  process.exit(0);
}

Generate answer from retrieved context

Use retrieved chunks as grounded context for the final model call.

const context = contextChunks.join('\n\n---\n\n');

const answer = await client.responses.create({
  model: 'gpt-5.5',
  instructions:
    'Answer only from the provided context. If context is insufficient, respond with: I do not have enough context to answer this.',
  input: `Context:\n${context}\n\nQuestion: How does pgvector semantic search work?`,
});

console.log(answer.output_text);

Demo

Runnable scripts for this post live in the rag-openai-embeddings-pgvector-demo folder in the private demos repository. Get access via code demos.

Integration with Hugging Face Inference API

Željko Šević — Tue, 02 Jun 2026 00:14:00 +0000

Hugging Face hosts thousands of open models for NLP, vision, and other tasks. The Inference API (via Inference Providers) lets you call those models over HTTP. The @huggingface/inference package from huggingface.js is the Node.js client.

Prerequisites

Hugging Face account
Access token with permission to call Inference (create a token of type Read or Fine-grained with inference access)
Node.js version 26
@huggingface/inference installed (npm i @huggingface/inference)

Some models (especially image generation) are routed through Inference Providers. Enable providers and billing in account settings when a model requires it.

Client setup

Pass your token to InferenceClient. Read it from the environment in production.

import { InferenceClient } from '@huggingface/inference';

const client = new InferenceClient(process.env.HF_TOKEN);

Summarization

Shrink longer text into a short summary. Pick a model trained for summarization and respect its max input length.

const result = await client.summarization({
  model: 'facebook/bart-large-cnn',
  inputs: `The tower is 324 metres (1,063 ft) tall, about the same height as an 81-storey building, and the tallest structure in Paris. Its base is square, measuring 125 metres (410 ft) on each side. During its construction, the Eiffel Tower surpassed the Washington Monument to become the tallest man-made structure in the world, a title it held for 41 years until the Chrysler Building in New York City was finished in 1930. It was initially criticized by some artists and intellectuals, but it became a global cultural icon of France and one of the most recognizable structures in the world.`,
  parameters: {
    max_length: 80,
  },
});

console.log(result.summary_text);

Text classification

Assign labels with confidence scores. Common use case: sentiment analysis on short text.

const labels = await client.textClassification({
  model: 'distilbert-base-uncased-finetuned-sst-2-english',
  inputs: 'I really enjoyed this workshop.',
});

for (const { label, score } of labels) {
  console.log(label, score.toFixed(4));
}

Text to image

Generate an image from a text prompt. The client returns a Blob; write it to disk or serve it from your app.

import { writeFileSync } from 'node:fs';

const image = await client.textToImage({
  provider: 'hf-inference',
  model: 'black-forest-labs/FLUX.1-schnell',
  inputs: 'A watercolor painting of a fox in an autumn forest',
  parameters: {
    num_inference_steps: 4,
  },
});

const buffer = Buffer.from(await image.arrayBuffer());
writeFileSync('output.png', buffer);

With provider: 'hf-inference', use a model from the hf-inference catalog for that task (for example black-forest-labs/FLUX.1-schnell). Older Hub repos such as stabilityai/stable-diffusion-2-1 may no longer exist or lack provider mapping.

Image models are often slower and may incur provider usage charges.

Demo

Runnable scripts for each task live in the huggingface-inference-api-demo folder. Get access via code demos.

LLM integration with OpenAI Responses API

Željko Šević — Mon, 01 Jun 2026 15:50:26 +0000

Large language models (LLMs) understand and generate text from prompts. OpenAI exposes models through the Responses API. The official openai npm package is the practical way to call it from Node.js. This post covers common patterns beyond a single prompt string.

Prerequisites

OpenAI account
Generated API key
Enabled billing
Node.js version 26
openai package installed (npm i openai)
For Markdown output: marked, dompurify, and jsdom (npm i marked dompurify jsdom)

Client setup

Create a client with your API key (read from the environment in production).

import OpenAI from 'openai';

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

The same SDK can target other hosts that implement a compatible API by setting baseURL and apiKey:

const client = new OpenAI({
  apiKey: process.env.LLM_API_KEY,
  baseURL: 'https://your-gateway.example/v1',
});

Azure OpenAI uses AzureOpenAI instead. Many third-party gateways support Chat Completions only; the examples below use client.responses.*, so confirm your provider supports the Responses API (especially for tools like web search).

Basic integration

Pass a string as input and read output_text from the response.

const response = await client.responses.create({
  model: 'gpt-5.5',
  input: 'Write a one-sentence bedtime story about a unicorn.',
});

console.log(response.output_text);

System prompt

Use top-level instructions for stable behavior (tone, format, role). They take precedence over casual wording in the user message.

const response = await client.responses.create({
  model: 'gpt-5.5',
  instructions: 'Reply in one short sentence. Use plain language.',
  input: 'Explain what an LLM is.',
});

console.log(response.output_text);

Few-shot prompting

Pass prior turns as an input array with user and assistant roles, then the new user message. Keep task rules in instructions.

const response = await client.responses.create({
  model: 'gpt-5.5',
  instructions:
    'Classify sentiment as exactly one word: positive, negative, or neutral.',
  input: [
    { role: 'user', content: 'I love this!' },
    { role: 'assistant', content: 'positive' },
    { role: 'user', content: 'This is awful.' },
    { role: 'assistant', content: 'negative' },
    { role: 'user', content: 'It is fine I guess.' },
  ],
});

console.log(response.output_text);

Streaming

Set stream: true and handle response.output_text.delta events for incremental text.

const stream = await client.responses.create({
  model: 'gpt-5.5',
  input: 'List three colors.',
  stream: true,
});

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}

Structured output with JSON schema

Constrain the model to JSON matching your schema via text.format. With strict: true, the output should match the schema.

const response = await client.responses.create({
  model: 'gpt-5.5',
  input: 'The film Inception was directed by Christopher Nolan.',
  text: {
    format: {
      type: 'json_schema',
      name: 'movie_summary',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          title: { type: 'string' },
          director: { type: 'string' },
        },
        required: ['title', 'director'],
        additionalProperties: false,
      },
    },
  },
});

const data = JSON.parse(response.output_text);
console.log(data.title, data.director);

For typed parsing with Zod, you can use client.responses.parse() instead of JSON.parse.

Markdown output to HTML

Ask for Markdown in instructions, then convert output_text to HTML and sanitize before rendering (for example with innerHTML in the browser or when storing HTML).

import { marked } from 'marked';
import { JSDOM } from 'jsdom';
import DOMPurify from 'dompurify';

const purify = DOMPurify(new JSDOM('').window);

const response = await client.responses.create({
  model: 'gpt-5.5',
  instructions: 'Reply in Markdown only. Use a heading and a short bullet list.',
  input: 'Explain what an LLM is in three bullet points.',
});

const markdown = response.output_text;
const html = marked.parse(markdown);
const safeHtml = purify.sanitize(html);

Always run DOMPurify.sanitize on model-generated HTML. The model can emit unsafe markup; sanitization strips scripts and other dangerous content.

Web search tool

Enable the built-in web search tool when the answer should use current information from the web.

const response = await client.responses.create({
  model: 'gpt-5.5',
  tools: [{ type: 'web_search' }],
  include: ['web_search_call.action.sources'],
  input: 'What was a major tech headline this week? Cite sources briefly.',
});

console.log(response.output_text);

Web search adds latency and tool usage cost. Use a model that supports tools.

Browser automation with Playwright

Željko Šević — Sun, 17 May 2026 13:54:58 +0000

Playwright is a headless browser library for automating browser tasks. Here's the list of some of the features:

Turn off headless mode

  import { chromium } from 'playwright';

  const browser = await chromium.launch({
    headless: false
    // ...
  });

Resize the viewport to the window size

  const context = await browser.newContext({
    viewport: null
  });
  const page = await context.newPage();

Emulate screen how it's shown to the user via the emulateMedia method

  await page.emulateMedia({ media: 'screen' });

Save the page as a PDF file with a specified path, format, scale factor, and page range

  await page.pdf({
    path: 'path.pdf',
    format: 'A3',
    scale: 1,
    pageRanges: '1-2',
    printBackground: true
  });

Use preexisting user's credentials to skip logging in to some websites. The user data directory is a parent of the Profile Path value from the chrome://version page. Use launchPersistentContext instead of launch + newContext.

  import { chromium } from 'playwright';

  const context = await chromium.launchPersistentContext(
    'C:\\Users\\<USERNAME>\\AppData\\Local\\Google\\Chrome\\User Data',
    { headless: false }
  );
  const page = context.pages()[0] ?? (await context.newPage());

Use Chrome instance instead of Chromium via the channel option. Close Chrome before running the script if the profile is in use.

  import { chromium } from 'playwright';

  const browser = await chromium.launch({
    channel: 'chrome'
    // ...
  });

Switch to the selected tab

  await page.bringToFront();

Get value based on evaluation in the browser page

  const shouldPaginate = await page.evaluate(
    ([param1, param2]) => {
      // ...
    },
    [param1, param2]
  );

Get HTML content from the specific element

  const html = await page.locator('.field--text').evaluate(
    (element) => element.outerHTML
  );

Wait for a specific selector to be loaded. You can also provide a timeout in milliseconds

  await page.waitForSelector('.success', { timeout: 5000 });

Manipulate with a specific element and click on some of the elements

  await page.locator('#header').evaluate(async (headerElement) => {
    // ...
    headerElement
      .querySelectorAll('svg')
      .item(13)
      .parentNode.click();
  });

Extend execution timeout for slow evaluate callbacks

  page.setDefaultTimeout(0);
  // or per action:
  await page.locator('#header').evaluate(async (headerElement) => {
    // ...
  }, { timeout: 0 });

Manipulate with multiple elements

  await page.locator('.some-class').evaluateAll(async (elements) => {
    // ...
  });

Wait for navigation (e.g., form submitting) to be done

  await page.waitForLoadState('networkidle', { timeout: 0 });

Or wait for navigation triggered by a click:

  await Promise.all([
    page.waitForNavigation({ waitUntil: 'networkidle', timeout: 0 }),
    page.click('button[type="submit"]')
  ]);

Trigger hover event on some of the elements

  await page.locator('#header').hover();

Or dispatch a custom event in the page:

  await page.locator('#header').evaluate((headerElement) => {
    const hoverEvent = new MouseEvent('mouseover', {
      view: window,
      bubbles: true,
      cancelable: true
    });

    headerElement.dispatchEvent(hoverEvent);
  });

Expose a function in the browser and use it in evaluate / evaluateAll callbacks (e.g., simulate typing using the window.type function)

  await page.exposeFunction('type', async (selector, text, options) => {
    await page.locator(selector).type(text, options);
  });

  await page.locator('.some-class').evaluateAll(async (elements) => {
    // ...
    await window.type(selector, text, { delay: 0 });
  });

Press the Enter button after typing the input field value

  await page.locator(selector).fill(text);
  await page.locator(selector).press('Enter');

Open a file chooser and select file for upload

  const fileChooserPromise = page.waitForEvent('filechooser');
  await page.locator(selector).click();
  const fileChooser = await fileChooserPromise;

  const filePath = `C:/Users/<USERNAME>/Downloads/test.jpeg`; // use "/" instead of "\" in file path
  await fileChooser.setFiles(filePath);

Remove the value from the input field before typing the new one

  await page.locator(selector).fill(text);

Or select all and replace:

  await page.locator(selector).click({ clickCount: 3 });
  await page.locator(selector).type(text, options);

Pass a variable into evaluate / evaluateAll callbacks via extra arguments

  await page.locator('#element').evaluate(
    async (element, customVariable) => {
      // ...
    },
    customVariable
  );

Mock response for the specific request

  await page.route(REDIRECTION_URL, async (route) => {
    await route.fulfill({
      contentType: 'text/html',
      status: 304,
      body: '<body></body>'
    });
  });

Intercept page redirections (via route) and open them in new tabs rather than following them in the same tab

  await page.route(REDIRECTION_URL, async (route) => {
    const url = route.request().url();

    await route.fulfill({
      contentType: 'text/html',
      status: 304,
      body: '<body></body>'
    });

    const newPage = await context.newPage();
    await newPage.goto(url, { waitUntil: 'domcontentloaded', timeout: 0 });
    // ...
    await newPage.close();
  });

Intercept page response

  page.on('response', async (response) => {
    if (response.url() === RESPONSE_URL) {
      if (response.status() === 200) {
        // ...
      }
      // ...
    }
  });

Demo

Runnable tests for each API pattern live in the browser-automation-playwright-demo folder. Get access via code demos.

Deploying Node.js apps to Railway

Željko Šević — Fri, 15 May 2026 23:47:35 +0000

Railway is probably one of the fastest ways to get a Node.js API live.

GitHub Integration

Connect your GitHub repository to Railway.

Railway can automatically deploy every push from your repository.

In the Source section, enable:

Wait for CI

This is useful if you already use GitHub Actions for:

tests
linting
type checking

Railway will wait for the GitHub Actions workflow to pass before deploying.

Provisioning Databases and Services

Railway allows provisioning managed services directly from the dashboard:

PostgreSQL
Redis
other services

Environment Variables

After provisioning services, configure environment variables like:

DATABASE_URL=${{Postgres.DATABASE_URL}}
REDIS_URL=${{Redis.REDIS_URL}}
JWT_SECRET=your_secret

This automatically connects your application to Railway-managed services.

Public API Access

Go to:

Networking → Public Networking

Generate a public domain for your API.

Horizontal Scaling

In the Scale section, increase the number of replicas.

This allows running multiple instances of your application for handling more traffic.

Logs and Observability

Application logs can be found directly in the side menu.

Railway also provides an Observability section where you can monitor:

error logs
CPU metrics
memory usage
billing usage

Redeploying Changes

After changing:

environment variables
databases/services
networking configuration

redeploy the application so changes are applied correctly.

Railway removes a lot of deployment complexity while still giving enough flexibility for real production applications.

DEV Community: Željko Šević

Infrastructure as Code (IaC) with AWS CDK (EC2 Example)

Requirements

AWS Credentials Setup

Project Structure

App Entry

Stack and EC2 Instance

Configuration

CDK Workflow

Important Notes

Demo

AI image generation with OpenAI API

Prerequisites

Client setup

Basic integration

n

Size

Quality

Output format

Compression

Background

Production notes

Demo

Building AI agents with Vercel AI SDK

Prerequisites

Mental model - steps and the tool loop

Support triage scenario

Defining multiple tools

Multi-step triage with generateText

stopWhen - when the loop stops

stepCountIs - cap the number of steps

Combining hasToolCall with stepCountIs

Inspecting steps and usage

ToolLoopAgent - reusable agent definition

Streaming with tools

Production notes

Demo

LLM integration with OpenRouter

Prerequisites

Configuration

@openrouter/sdk

Client setup

Basic integration

System prompt

Streaming

Model switching

openai package

Client setup

Basic integration

System prompt

Streaming

Vercel AI SDK

Client setup

Basic integration

System prompt

Streaming

Demo

LLM integration with Vercel AI SDK

Prerequisites

Client setup

Basic integration

System prompt

Few-shot prompting

Streaming

Structured output with JSON schema

Markdown output to HTML

Web search tool

Embeddings

Demo

Building an MCP server with Node.js

Prerequisites

MCP capabilities - tools, resources, prompts

Building the server

Transports - stdio vs SSE / Streamable HTTP

Connecting MCP clients

What else matters

Demo

Supabase basics with Node.js

Prerequisites

Create a project and database

Multi-step triage with `generateText`

`stopWhen` - when the loop stops

`stepCountIs` - cap the number of steps

Combining `hasToolCall` with `stepCountIs`

Inspecting `steps` and usage

`ToolLoopAgent` - reusable agent definition

`@openrouter/sdk`

`openai` package