DEV Community: Željko Šević

Git hooks with Husky

Željko Šević — Sun, 12 Jul 2026 14:03:49 +0000

Git hooks run scripts around local Git events (pre-commit, commit-msg, pre-push, and others). They are a good place for fast checks - lint, format, and lightweight validation - before bad changes leave your machine. Hooks are not a substitute for CI; treat them as an early filter.

Husky wires those hooks through Git's core.hooksPath. Hook files live in .husky/ as plain shell scripts, and a prepare script installs them after npm install so every clone gets the same setup.

This post covers Husky v9 setup, common hooks, lint-staged, skipping hooks in CI, pitfalls, and a runnable demo that blocks messy commits.

Prerequisites

Node.js version 26
A Git repository (git init if you are starting fresh)
npm i -D husky
Optional but recommended: npm i -D lint-staged plus ESLint and Prettier

Setup

Install Husky and initialize it:

npm i -D husky
npx husky init

husky init creates .husky/pre-commit and adds a prepare script to package.json:

{
  "scripts": {
    "prepare": "husky"
  }
}

prepare runs after local npm install, so teammates get hooks without a separate setup step. Replace the default pre-commit body with the checks you want.

Mental model

Piece	Role
`prepare` / `husky`	Points Git at `.husky/` via `core.hooksPath`
`.husky/<hook>`	Shell script Git runs for that event
`lint-staged`	Runs tools only on staged files (typical `pre-commit` target)
CI	Still runs full lint/test; hooks are local only

Husky does not invent a new hook system - it configures native Git hooks and keeps the scripts in the repo.

Pre-commit with lint-staged

Running eslint . or prettier --write on the whole tree from pre-commit gets slow. lint-staged limits work to staged files.

npm i -D lint-staged eslint prettier

// package.json
{
  "lint-staged": {
    "*.{js,ts}": ["eslint --fix", "prettier --write"]
  }
}

# .husky/pre-commit
npx lint-staged

On git commit, Git runs .husky/pre-commit → lint-staged → ESLint/Prettier on matching staged paths. Auto-fixed files are restaged. If a check exits non-zero, the commit is aborted.

Keep pre-commit fast and file-local. Put slow or whole-repo work in pre-push or CI.

Other useful hooks

commit-msg - validate the message file Git passes as $1:

# .husky/commit-msg
message=$(cat "$1")

if echo "$message" | grep -qE '^(WIP|wip)($|[^a-zA-Z])'; then
  echo "WIP commits are blocked by the commit-msg hook"
  exit 1
fi

pre-push - run a quicker subset of CI before a push:

# .husky/pre-push
npm test

Create a hook by adding an executable script under .husky/ with the Git hook name. Prefer POSIX shell for Windows compatibility.

Skipping hooks

Skip once with Git's no-verify flag:

git commit -m "emergency fix" -n

Disable Husky for a command or environment:

HUSKY=0 git commit -m "skip hooks"

Set HUSKY=0 (or HUSKY: 0 in CI env) on CI/Docker so installs do not try to configure local hooks. If production installs omit devDependencies, use a safe prepare script so missing husky does not fail the install:

{
  "scripts": {
    "prepare": "husky || true"
  }
}

Pitfalls

Hooks are local - they do not run on the remote; CI still matters.
--no-verify / HUSKY=0 - anyone can bypass hooks; do not rely on them for security.
GUI + Node version managers - GUI clients often lack the shell PATH where nvm/fnm put Node. Source your version manager from ~/.config/husky/init.sh.
Nested package vs Git root - Husky will not install into a parent ../ by default. In a monorepo, install Husky at the repo root (or adjust prepare as in the Husky how-to).
Slow pre-commit - full test suites belong in pre-push or CI; keep commit hooks on staged files.

When to use what

Approach	Good for
Husky + lint-staged	Fast lint/format on staged files before commit
Husky `commit-msg`	Lightweight message conventions locally
Husky `pre-push`	Short tests before sharing a branch
CI only	Full lint, build, and test on every change

Pair Husky with ESLint and Prettier for the usual Node.js quality gate on commit.

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation

Cron jobs and schedulers with BullMQ

Željko Šević — Sun, 05 Jul 2026 09:35:36 +0000

In-process cron (node-cron, @nestjs/schedule, OS crontab) runs inside one Node process. That is fine for a single instance, but it does not survive restarts gracefully, deduplicate across replicas, or share infrastructure with your other background jobs.

BullMQ stores queues and schedulers in Redis. Job Schedulers (BullMQ 5.16+) are the recommended way to enqueue recurring work on a cron pattern or fixed interval. The same workers that process one-off jobs also process scheduled ones, with retries, backoff, and concurrency you already get from BullMQ.

This post covers Job Schedulers in plain Node.js, operations and pitfalls, a NestJS setup with @nestjs/bullmq, and a runnable demo with a fast cron heartbeat and a daily cleanup cron.

Prerequisites

Node.js version 26
Redis at redis://localhost:6379 (included in the demo docker-compose.yml, or use Postgres and Redis containers with Docker Compose)
npm i bullmq

For the NestJS section: npm i @nestjs/bullmq bullmq

BullMQ 2.0+ does not require a separate QueueScheduler instance. Use the Job Scheduler API (upsertJobScheduler), not the deprecated repeat option on queue.add().

Mental model

Piece	Role
Queue	Holds jobs waiting to run
Worker	Executes jobs
Job Scheduler	Factory that enqueues jobs on a schedule
Scheduled job	A job instance produced by a scheduler

A scheduler id is stable across deploys. Calling upsertJobScheduler with the same id updates the schedule in place instead of creating duplicates.

Queue and worker

Share one Redis connection config between the queue and the worker:

import { Queue, Worker } from 'bullmq';

const connection = { host: 'localhost', port: 6379 };

const queue = new Queue('reports', { connection });

const worker = new Worker(
  'reports',
  async (job) => {
    console.log(`[${job.name}]`, new Date().toISOString(), job.data);
  },
  { connection },
);

worker.on('failed', (job, error) => {
  console.error(job?.name, error.message);
});

Start the worker before or shortly after registering schedulers. If no worker is running, jobs accumulate in Redis until one picks them up.

Cron schedulers

BullMQ uses a 6-field cron expression (optional seconds). A fast pattern for demos and heartbeats:

await queue.upsertJobScheduler(
  'report-heartbeat',
  { pattern: '*/10 * * * * *' },
  {
    name: 'heartbeat',
    data: { source: 'scheduler' },
    opts: {
      attempts: 3,
      backoff: { type: 'exponential', delay: 1000 },
      removeOnComplete: 50,
    },
  },
);

Daily cleanup at 03:15 in a specific timezone:

await queue.upsertJobScheduler(
  'daily-cleanup',
  { pattern: '0 15 3 * * *', tz: 'Europe/Berlin' },
  {
    name: 'cleanup',
    data: { scope: 'stale-sessions' },
    opts: { attempts: 3 },
  },
);

Set tz when the job must fire at a local wall-clock time. For millisecond intervals instead of cron, use every (mutually exclusive with pattern).

Other useful repeat options:

Option	Purpose
`limit`	Maximum number of iterations
`immediately`	Run once now, then follow the schedule
`startDate` / `endDate`	Bound the scheduler to a time window

Register schedulers on startup

Keep scheduler registration in a dedicated bootstrap script or onModuleInit hook so deploys upsert the same ids:

// scheduler.js
import { Queue } from 'bullmq';

const connection = { host: 'localhost', port: 6379 };
const queue = new Queue('reports', { connection });

await queue.upsertJobScheduler(
  'report-heartbeat',
  { pattern: '*/10 * * * * *' },
  { name: 'heartbeat', data: { source: 'scheduler' } },
);

await queue.upsertJobScheduler(
  'daily-cleanup',
  { pattern: '0 15 3 * * *', tz: 'Europe/Berlin' },
  { name: 'cleanup', data: { scope: 'stale-sessions' } },
);

const schedulers = await queue.getJobSchedulers();
console.log(
  'Active schedulers:',
  schedulers.map((item) => ({ key: item.key, pattern: item.pattern })),
);

await queue.close();

To remove a scheduler:

await queue.removeJobScheduler('daily-cleanup');

Shut down cleanly on SIGINT / SIGTERM: await worker.close() and await queue.close().

NestJS with `@nestjs/bullmq`

NestJS wraps BullMQ queues and workers as providers. Register Redis once, register the queue, inject it into a service that upserts schedulers on startup, and process jobs in a @Processor class.

// app.module.ts
import { Module } from '@nestjs/common';
import { BullModule } from '@nestjs/bullmq';
import { ReportsProcessor } from './reports.processor';
import { ReportsSchedulerService } from './reports-scheduler.service';

@Module({
  imports: [
    BullModule.forRoot({
      connection: { host: 'localhost', port: 6379 },
    }),
    BullModule.registerQueue({ name: 'reports' }),
  ],
  providers: [ReportsProcessor, ReportsSchedulerService],
})
export class AppModule {}

// reports-scheduler.service.ts
import { Injectable, OnModuleInit } from '@nestjs/common';
import { InjectQueue } from '@nestjs/bullmq';
import { Queue } from 'bullmq';

@Injectable()
export class ReportsSchedulerService implements OnModuleInit {
  constructor(@InjectQueue('reports') private readonly reportsQueue: Queue) {}

  async onModuleInit() {
    await this.reportsQueue.upsertJobScheduler(
      'report-heartbeat',
      { pattern: '*/10 * * * * *' },
      { name: 'heartbeat', data: { source: 'nestjs' } },
    );

    await this.reportsQueue.upsertJobScheduler(
      'daily-cleanup',
      { pattern: '0 15 3 * * *', tz: 'Europe/Berlin' },
      { name: 'cleanup', data: { scope: 'stale-sessions' } },
    );
  }
}

// reports.processor.ts
import { Processor, WorkerHost } from '@nestjs/bullmq';
import { Job } from 'bullmq';

@Processor('reports')
export class ReportsProcessor extends WorkerHost {
  async process(job: Job): Promise<void> {
    console.log(`[${job.name}]`, new Date().toISOString(), job.data);
  }
}

ReportsSchedulerService runs when the Nest app boots, so schedulers are upserted on every deploy. ReportsProcessor is the worker; Nest registers it automatically unless you set manualRegistration on BullModule.forRoot.

@nestjs/schedule (@Cron()) is still a good fit for trivial timers inside one instance. Prefer BullMQ schedulers when you already use Redis queues, run multiple replicas, or need the same retry and observability model as the rest of your background jobs.

Pitfalls

Worker must be running - schedulers enqueue jobs; something must consume them.
Busy queues slip - BullMQ creates the next scheduled job when the previous one starts processing. Under load, ticks can be less frequent than every or the cron interval suggests.
pattern vs every - mutually exclusive; pick one per scheduler.
Timezone - omit tz and cron runs in the server default zone; set it explicitly for "9 AM local" jobs.
Legacy repeat on add() - deprecated from BullMQ 5.16; use upsertJobScheduler for new code.

When to use what

Approach	Good for
`@nestjs/schedule` / `node-cron`	Single instance, simple in-process timers
BullMQ Job Schedulers	Multi-instance apps, shared Redis, retries with async jobs
External cron + HTTP	Fire-and-forget HTTP triggers without queue semantics

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation

Integration with Lever public jobs API

Željko Šević — Sat, 04 Jul 2026 17:43:06 +0000

Lever is an ATS with a public Postings API for read-only access to published job listings. No API key is required - you only need the company's Lever site slug.

This post covers fetching postings with pagination, optional filters, and EU vs US API hosts. For other ATS public feeds, see the Ashby, Greenhouse, and Workable posts.

Lever's authenticated Data API (https://api.lever.co/v1/...) manages candidates and pipeline data and is separate from the public postings feed.

Prerequisites

Node.js version 26
A company's Lever site slug (see below)
No API key required for the Postings API

Find the site slug

Lever-hosted career pages use https://jobs.lever.co/{site_slug}/. The first path segment after jobs.lever.co is the slug passed to the API.

Examples: unlimit → https://jobs.lever.co/unlimit/, API https://api.lever.co/v0/postings/unlimit.

Some accounts are hosted in the EU region and answer on https://api.eu.lever.co/v0/postings/{site_slug} instead.

API overview

Item	Value
US base	`https://api.lever.co/v0/postings/{site_slug}`
EU base	`https://api.eu.lever.co/v0/postings/{site_slug}`
Auth	None
Format	JSON array (`mode=json`)

Common query parameters:

Parameter	Description
`mode=json`	Return JSON instead of HTML
`skip`, `limit`	Pagination (`limit` defaults to 100)
`team`, `department`, `location`, `commitment`	Filters; repeat a key for multiple values
`group`	Group results by `location`, `team`, or `commitment`

Each posting includes id, text (title), hostedUrl, applyUrl, categories (team, department, location), workplaceType, country, and plain-text description fields.

Basic integration

Fetch one page of postings:

const siteSlug = process.env.LEVER_SITE_SLUG ?? 'unlimit';
const url = new URL(`https://api.lever.co/v0/postings/${encodeURIComponent(siteSlug)}`);
url.searchParams.set('mode', 'json');
url.searchParams.set('limit', '100');

const response = await fetch(url);

if (!response.ok) {
  throw new Error(`Lever API ${response.status}: ${response.statusText}`);
}

const postings = await response.json();

for (const posting of postings) {
  console.log(posting.text, '-', posting.categories?.location, '-', posting.hostedUrl);
}

Paginate until a page returns fewer rows than your limit:

const PAGE_SIZE = 100;

async function fetchAllLeverPostings(siteSlug, baseUrl = 'https://api.lever.co/v0/postings') {
  const all = [];
  let skip = 0;

  for (;;) {
    const url = new URL(`${baseUrl}/${encodeURIComponent(siteSlug)}`);
    url.searchParams.set('mode', 'json');
    url.searchParams.set('skip', String(skip));
    url.searchParams.set('limit', String(PAGE_SIZE));

    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`Lever API ${response.status}`);
    }

    const page = await response.json();
    if (!Array.isArray(page) || page.length === 0) break;

    all.push(...page);
    if (page.length < PAGE_SIZE) break;
    skip += PAGE_SIZE;
  }

  return all;
}

If the US host returns 404, retry against the EU host:

const EU_BASE = 'https://api.eu.lever.co/v0/postings';
const US_BASE = 'https://api.lever.co/v0/postings';

async function fetchPostingsWithRegionFallback(siteSlug) {
  try {
    return await fetchAllLeverPostings(siteSlug, US_BASE);
  } catch (error) {
    if (String(error.message).includes('404')) {
      return fetchAllLeverPostings(siteSlug, EU_BASE);
    }
    throw error;
  }
}

Filter at the source

Request only roles in a team or location:

url.searchParams.append('team', 'Engineering');
url.searchParams.append('location', 'Berlin');
url.searchParams.append('location', 'Remote');

Fetch a single posting:

const detailUrl = `https://api.lever.co/v0/postings/${siteSlug}/${postingId}?mode=json`;

Normalize to a stable shape

function buildDescription(posting) {
  const parts = [
    posting.descriptionPlain,
    posting.openingPlain,
    posting.descriptionBodyPlain,
    posting.additionalPlain,
  ].filter(Boolean);

  for (const list of posting.lists ?? []) {
    if (list.text && list.content) {
      parts.push(`${list.text}\n${list.content.replace(/<[^>]+>/g, ' ')}`);
    }
  }

  return parts.join('\n\n');
}

function normalizeLeverPosting(posting, companyName) {
  const primary = posting.categories?.location?.trim() ?? '';
  const extras = (posting.categories?.allLocations ?? []).filter(
    (loc) => loc.trim().toLowerCase() !== primary.toLowerCase(),
  );
  const location = [primary, ...extras].filter(Boolean).join(' | ') || 'Unknown';
  const isRemote =
    posting.workplaceType?.toLowerCase() === 'remote' ||
    /remote/i.test(location);

  return {
    id: posting.id ?? `${posting.text}:${posting.createdAt}`,
    title: posting.text.trim(),
    company: companyName,
    location,
    country: posting.country ?? null,
    isRemote,
    url: posting.hostedUrl || posting.applyUrl,
    postedAt: posting.createdAt ? new Date(posting.createdAt) : null,
    team: posting.categories?.team ?? null,
    commitment: posting.categories?.commitment ?? null,
    description: buildDescription(posting),
  };
}

Only published postings appear in this API. Confidential or internal-only roles are never returned.

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation

Integration with Workable public jobs API

Željko Šević — Fri, 03 Jul 2026 11:15:07 +0000

Workable is an ATS with a public careers layer you can read without authentication. The widget-style JSON endpoint powers Workable-hosted career sites and embeddable job widgets.

This post shows how to list published jobs for one Workable account, request full descriptions, and normalize location and remote fields. For other ATS public feeds, see the Ashby, Greenhouse, and Lever posts.

Workable's authenticated REST API v3 (https://{subdomain}.workable.com/spi/v3/) requires a bearer token and is meant for HR integrations, not public job aggregation.

Prerequisites

Node.js version 26
A company's Workable account slug (see below)
No API key required for the public widget endpoint

Find the account slug

Workable career pages use URLs like https://apply.workable.com/{account_slug}/ or legacy https://{account_slug}.workable.com/. The slug is the account identifier in API paths.

Examples: huggingface for Hugging Face, flosum for Flosum.

API overview

Item	Value
Jobs (with details)	`GET https://www.workable.com/api/accounts/{slug}?details=true`
Locations	`GET .../accounts/{slug}/locations`
Departments	`GET .../accounts/{slug}/departments`
Auth	None
Format	JSON

Node fetch may follow a redirect to https://apply.workable.com/api/v1/widget/accounts/{slug}?details=true; both URLs return the same payload.

Set details=true to include description and full_description on each job. Without it you get summary fields only.

Common fields on each job in jobs[]:

Field	Description
`title`	Job title
`url`, `shortlink`	Apply links
`location`, `locations`	Structured location objects
`experience`	Seniority label (for example `Mid-Senior level`)
`published_on`, `created_at`	Timestamps
`state`	On public feeds this is often a region name, not listing status - prefer `published_on` to detect live roles

Basic integration

const accountSlug = process.env.WORKABLE_ACCOUNT_SLUG ?? 'huggingface';
const url = new URL(
  `https://www.workable.com/api/accounts/${encodeURIComponent(accountSlug)}`,
);
url.searchParams.set('details', 'true');

const response = await fetch(url);

if (!response.ok) {
  throw new Error(`Workable API ${response.status}: ${response.statusText}`);
}

const data = await response.json();

for (const job of data.jobs ?? []) {
  console.log(job.title, '-', job.location?.location_str, '-', job.url);
}

Keep only published listings:

function isPublished(job) {
  if (job.published_on?.trim()) return true;
  return !job.state || job.state === 'published';
}

const publicJobs = (data.jobs ?? []).filter(
  (job) => job.title && (job.url || job.shortlink) && isPublished(job),
);

Locations and remote detection

Prefer location.location_str when present. Otherwise build a label from structured fields:

function stringifyLocation(entry) {
  const city = entry.city?.trim();
  const region = entry.state_code?.trim() || entry.region?.trim();
  const country = entry.country_name?.trim() || entry.country?.trim();

  if (city && region && country) return `${city}, ${region}, ${country}`;
  if (city && country) return `${city}, ${country}`;
  return country || city || '';
}

function resolveLocation(job) {
  const primary = job.location?.location_str?.trim();
  if (primary) return primary;

  const parts = (job.locations ?? [])
    .map(stringifyLocation)
    .filter(Boolean);

  return parts.join(' / ') || 'Unknown';
}

function isRemoteJob(job, locationLabel) {
  const structured =
    Boolean(job.location?.telecommuting) ||
    job.location?.workplace_type?.toLowerCase() === 'remote' ||
    (job.locations ?? []).some(
      (loc) =>
        Boolean(loc.telecommuting) ||
        loc.workplace_type?.toLowerCase() === 'remote',
    );

  return structured || /remote/i.test(locationLabel);
}

Normalize to a stable shape

function normalizeWorkableJob(job, companyName) {
  const location = resolveLocation(job);
  const description = `${job.description ?? ''} ${job.full_description ?? ''}`.trim();

  return {
    id: job.id ?? job.shortcode,
    title: job.title.trim(),
    company: companyName,
    location,
    isRemote: isRemoteJob(job, location),
    url: job.url || job.shortlink,
    postedAt: job.created_at
      ? new Date(job.created_at)
      : job.published_on
        ? new Date(job.published_on)
        : null,
    experience: job.experience ?? null,
    description,
  };
}

Optional companion calls enrich filters:

const [locationsRes, departmentsRes] = await Promise.all([
  fetch(`https://www.workable.com/api/accounts/${accountSlug}/locations`),
  fetch(`https://www.workable.com/api/accounts/${accountSlug}/departments`),
]);

const { locations } = await locationsRes.json();
const { departments } = await departmentsRes.json();

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation

Integration with Greenhouse public jobs API

Željko Šević — Thu, 02 Jul 2026 21:20:49 +0000

Greenhouse is a widely used ATS. Its public Job Board API returns published jobs, departments, and offices as JSON - no authentication for read access.

This post covers listing jobs for one company, loading descriptions, and handling location metadata. For other ATS public feeds, see the Ashby, Workable, and Lever posts.

Greenhouse also ships a private Harvest API for full recruiting workflows (candidates, pipelines, offers). That API requires credentials and is out of scope here.

Prerequisites

Node.js version 26
A company's Greenhouse board token (see below)
No API key required for GET job listings

Find the board token

Greenhouse career pages live at https://boards.greenhouse.io/{board_token}. The path segment after /boards/ is the token.

Examples: stripe → https://boards.greenhouse.io/stripe, API base https://boards-api.greenhouse.io/v1/boards/stripe/jobs.

API overview

Item	Value
List jobs	`GET https://boards-api.greenhouse.io/v1/boards/{board_token}/jobs`
Single job	`GET .../jobs/{job_id}`
Auth (read)	None
Auth (apply)	HTTP Basic with Job Board API key - only for `POST .../jobs/{id}` applications

Useful query parameters on the list endpoint:

Parameter	Effect
`content=true`	Include HTML job descriptions in the list response
`department_id`, `office_id`	Filter by department or office

Each job typically includes id, title, location.name, absolute_url, updated_at, departments, offices, and optionally content and metadata (custom fields the employer exposed to the job board).

Basic integration

List published jobs with descriptions:

const boardToken = process.env.GREENHOUSE_BOARD_TOKEN ?? 'stripe';
const url = new URL(
  `https://boards-api.greenhouse.io/v1/boards/${encodeURIComponent(boardToken)}/jobs`,
);
url.searchParams.set('content', 'true');

const response = await fetch(url);

if (!response.ok) {
  throw new Error(`Greenhouse API ${response.status}: ${response.statusText}`);
}

const data = await response.json();

for (const job of data.jobs ?? []) {
  console.log(job.title, '-', job.location?.name, '-', job.absolute_url);
}

Fetch one job by id when you need the full posting or application questions:

async function getGreenhouseJob(boardToken, jobId) {
  const url = `https://boards-api.greenhouse.io/v1/boards/${encodeURIComponent(boardToken)}/jobs/${jobId}?questions=true`;
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Greenhouse API ${response.status}`);
  }
  return response.json();
}

Location and metadata

Some boards store only work mode in location.name (Remote, Hybrid; In-Office) while the city and country live in a custom metadata field such as Job Posting Location:

const JOB_POSTING_LOCATION = 'Job Posting Location';

function extractPostingLocation(metadata) {
  const item = metadata?.find((m) => m.name?.trim() === JOB_POSTING_LOCATION);
  if (!item?.value) return null;
  if (Array.isArray(item.value)) {
    return item.value.map(String).join(', ');
  }
  return String(item.value).trim() || null;
}

function resolveLocation(job) {
  const primary = job.location?.name?.trim() ?? '';
  const fromMetadata = extractPostingLocation(job.metadata);
  if (fromMetadata && (!primary || /^(remote|hybrid|on-?site|in-?office)$/i.test(primary))) {
    return fromMetadata;
  }
  return primary || fromMetadata || 'Unknown';
}

Detect remote roles from location text:

function isRemoteJob(job) {
  const text = `${job.location?.name ?? ''} ${resolveLocation(job)}`.toLowerCase();
  return text.includes('remote') || text.includes('anywhere');
}

Normalize to a stable shape

function normalizeGreenhouseJob(job, companyName) {
  const location = resolveLocation(job);

  return {
    id: String(job.id),
    title: job.title.trim(),
    company: companyName,
    location,
    isRemote: isRemoteJob(job),
    url: job.absolute_url,
    postedAt: job.updated_at ? new Date(job.updated_at) : null,
    description: job.content ?? '',
    departments: (job.departments ?? []).map((d) => d.name).filter(Boolean),
  };
}

Cache responses when polling. Greenhouse does not publish hard rate limits for the job board API, but aggressive hammering can get blocked - poll on a schedule (for example every few hours) rather than on every page view.

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation

Integration with Ashby public jobs API

Željko Šević — Wed, 01 Jul 2026 20:40:58 +0000

Ashby is an applicant tracking system (ATS) used by many startups and scale-ups. Ashby exposes a lightweight, unauthenticated Job Postings API so you can list published openings on a custom careers page or aggregate jobs into a job board.

This post shows how to fetch public job listings from Ashby with Node.js, normalize the response, and filter to listed roles only. For other ATS public feeds, see the Greenhouse, Workable, and Lever posts.

Prerequisites

Node.js version 26
A company's Ashby job board name (see below)
No API key required for the public posting API

Find the job board name

Open the company's Ashby-hosted careers page. The URL looks like https://jobs.ashbyhq.com/{JOB_BOARD_NAME}. The last path segment is the identifier you pass to the API.

Examples: notion for Notion (https://jobs.ashbyhq.com/notion), ashby for Ashby itself.

Ashby also offers authenticated endpoints (for example jobPosting.list) for customers who need filters or private data. The public API documented here is read-only and scoped to one job board at a time.

API overview

Item	Value
Base URL	`https://api.ashbyhq.com/posting-api/job-board/{JOB_BOARD_NAME}`
Auth	None for read access
Format	JSON
Optional query	`includeCompensation=true` adds salary bands when the employer exposes them

Common fields on each job in jobs[]:

Field	Description
`title`	Job title
`location`	Primary location label
`secondaryLocations`	Additional offices or regions
`isRemote`, `workplaceType`	Remote / hybrid / on-site hints
`isListed`	When `false`, the role is unlisted and should not appear on a public board
`jobUrl`, `applyUrl`	Hosted Ashby pages
`descriptionPlain`	Plain-text description (when provided)
`publishedAt`	Publish timestamp

Basic integration

Fetch all published jobs for one board:

const boardName = process.env.ASHBY_BOARD_NAME ?? 'notion';
const url = new URL(
  `https://api.ashbyhq.com/posting-api/job-board/${encodeURIComponent(boardName)}`,
);
url.searchParams.set('includeCompensation', 'true');

const response = await fetch(url);

if (!response.ok) {
  throw new Error(`Ashby API ${response.status}: ${response.statusText}`);
}

const data = await response.json();
const jobs = data.jobs ?? [];

for (const job of jobs) {
  console.log(job.title, '-', job.location, '-', job.jobUrl);
}

Filter to roles that are safe to show publicly and have a link:

const publicJobs = jobs.filter(
  (job) => (job.isListed ?? true) && job.title && (job.jobUrl || job.applyUrl),
);

Normalize to a stable shape

Different ATS products use different field names. Map Ashby jobs into a schema your app owns:

function normalizeAshbyJob(job, companyName) {
  const locations = [job.location, ...(job.secondaryLocations ?? []).map((s) => s.location)]
    .map((value) => value?.trim())
    .filter(Boolean);

  const isRemote =
    Boolean(job.isRemote) ||
    job.workplaceType?.toLowerCase() === 'remote' ||
    locations.some((loc) => /remote/i.test(loc));

  return {
    id: job.id ?? `${job.title}:${job.publishedAt}`,
    title: job.title.trim(),
    company: companyName,
    location: locations.join(' | ') || 'Unknown',
    isRemote,
    url: job.jobUrl || job.applyUrl,
    postedAt: job.publishedAt ? new Date(job.publishedAt) : null,
    description: job.descriptionPlain ?? '',
    compensation: job.compensation ?? null,
  };
}

When the primary location is generic (Remote, Hybrid) but postal data includes a country, append the country so filters still work:

function enrichLocation(location, country) {
  const label = location?.trim();
  const c = country?.trim();
  if (!label || !c) return label ?? '';
  if (/^(remote|hybrid|on-?site)$/i.test(label) && !label.toLowerCase().includes(c.toLowerCase())) {
    return `${label}, ${c}`;
  }
  return label;
}

Ashby may return "European Union" in address.postalAddress.addressCountry; treat that as a region hint, not a country code.

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation

Request context in Node.js with AsyncLocalStorage

Željko Šević — Sun, 28 Jun 2026 20:32:25 +0000

In Express and NestJS apps you often need a requestId, userId, or trace fields deep in services and loggers without threading a context object through every function. A module-level global breaks under concurrent requests; passing ctx through every layer is noisy.

AsyncLocalStorage (built into node:async_hooks) gives each async execution chain its own store. Concurrent requests stay isolated, and await, timers, and Promise chains inside a request inherit the same context automatically.

This post covers the API, an Express middleware pattern, a NestJS interceptor with parameter decorators, and common pitfalls.

What AsyncLocalStorage is

AsyncLocalStorage has been stable since Node.js 16.4. No npm package is required.

Approach	Concurrent requests	Propagates through `await`
Global variable	Breaks	Yes
Pass `ctx` argument	Safe	Manual at every layer
AsyncLocalStorage	Safe	Automatic

Prerequisites

Node.js version 26
npm i express

Core API

import { AsyncLocalStorage } from 'node:async_hooks';

const als = new AsyncLocalStorage();

// Start a context for this async chain
als.run({ requestId: 'abc' }, () => {
  doWork();
});

// Read the current store anywhere in the chain
const store = als.getStore();

als.run(store, callback) - preferred entry point; call once per request in middleware.
als.getStore() - returns the store for the current async chain, or undefined outside run().
als.enterWith(store) - sets context for the current execution resource; useful in some framework hooks, but run() is the default pattern for Express middleware.

Express middleware pattern

Create a store per request in middleware, then read it from loggers and services without passing arguments.

// context.js
import { AsyncLocalStorage } from 'node:async_hooks';

export const requestContext = new AsyncLocalStorage();

export function getRequestId() {
  return requestContext.getStore()?.requestId;
}

// logger.js
import { getRequestId } from './context.js';

export function log(level, message, extra = {}) {
  console.log(
    JSON.stringify({
      level,
      requestId: getRequestId(),
      message,
      ...extra,
    })
  );
}

// middleware.js
import { randomUUID } from 'node:crypto';
import { requestContext } from './context.js';

export function requestContextMiddleware(req, res, next) {
  const store = {
    requestId: req.headers['x-request-id'] ?? randomUUID(),
  };
  res.setHeader('x-request-id', store.requestId);
  requestContext.run(store, () => next());
}

Wire middleware before routes. A handler can await a simulated database call and log without receiving requestId:

// routes.js
import { log } from './logger.js';

function delay(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function findUserById(id) {
  await delay(100);
  log('info', 'Loaded user from database', { userId: id });
  return { id, name: `User ${id}` };
}

export async function getUser(req, res) {
  const user = await findUserById(req.params.id);
  res.json(user);
}

// app.js
import express from 'express';
import { requestContextMiddleware } from './middleware.js';
import { getUser } from './routes.js';
import { getRequestId } from './context.js';

const app = express();

app.use(requestContextMiddleware);
app.get('/users/:id', getUser);

app.listen(3000, () => {
  console.log('Listening on http://localhost:3000');
});

Send concurrent requests with different x-request-id headers. Logs interleave on stdout, but each line carries the correct requestId for its request.

NestJS interceptor and decorator

The flow is the same as Express - an interceptor replaces middleware. For production apps, nestjs-cls wraps AsyncLocalStorage with typed stores and plugins; the snippets below use the built-in API directly.

Prerequisites add-on: npm i @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata rxjs

Shared store:

// request-context.storage.ts
import { AsyncLocalStorage } from 'node:async_hooks';

export type RequestContextStore = { requestId: string };

export const requestContext = new AsyncLocalStorage<RequestContextStore>();

Wrap each request in als.run() with a global interceptor. Subscribe inside run() so context propagates through async route handlers:

// request-context.interceptor.ts
import {
  CallHandler,
  ExecutionContext,
  Injectable,
  NestInterceptor,
} from '@nestjs/common';
import { randomUUID } from 'node:crypto';
import { Observable } from 'rxjs';
import { requestContext, RequestContextStore } from './request-context.storage';

@Injectable()
export class RequestContextInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
    const req = context.switchToHttp().getRequest();
    const store: RequestContextStore = {
      requestId: (req.headers['x-request-id'] as string) ?? randomUUID(),
    };
    const res = context.switchToHttp().getResponse();
    res.setHeader('x-request-id', store.requestId);

    return new Observable((subscriber) => {
      requestContext.run(store, () => {
        next.handle().subscribe(subscriber);
      });
    });
  }
}

Parameter decorators read from the store in controllers:

// request-context.decorator.ts
import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import { requestContext, RequestContextStore } from './request-context.storage';

export const RequestContext = createParamDecorator(
  (_data: unknown, _ctx: ExecutionContext): RequestContextStore | undefined =>
    requestContext.getStore(),
);

export const RequestId = createParamDecorator(
  (): string | undefined => requestContext.getStore()?.requestId,
);

Register the interceptor globally and use @RequestId() in a controller. Services can call requestContext.getStore() directly (for example from an injectable logger):

// app.module.ts
import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { RequestContextInterceptor } from './request-context/request-context.interceptor';
import { UsersModule } from './users/users.module';

@Module({
  imports: [UsersModule],
  providers: [{ provide: APP_INTERCEPTOR, useClass: RequestContextInterceptor }],
})
export class AppModule {}

// users.controller.ts
@Get(':id')
async getUser(@Param('id') id: string, @RequestId() requestId: string) {
  const user = await this.usersService.findById(id);
  return { requestId, user };
}

@Transactional() from typeorm-transactional uses the same ALS propagation idea for database transactions. See TypeORM examples with NestJS for a real-world decorator built on top of request-scoped context.

Why it works

Node ties the store to the async resource created when als.run() executes. Any async work started inside that callback - including await, setTimeout, and nested Promise chains - runs in the same context. Each concurrent request calls als.run() with its own store, so getStore() always returns the value for the current chain.

Common pitfalls

Call als.run() at the request boundary (middleware), not inside a shared singleton constructor.
getStore() returns undefined outside run() - guard with optional chaining or a default.
Callbacks scheduled before run() or from another request will not see your store.
Worker threads and cluster workers each have separate AsyncLocalStorage instances.

Related use cases

Structured logging - attach requestId to every log line (this post).
Distributed tracing - OpenTelemetry uses AsyncLocalStorage internally; see Tracing Node.js Microservices with OpenTelemetry.
Database transactions - typeorm-transactional propagates transactions across repositories via ALS; see TypeORM examples with NestJS.

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation

Nginx local setup

Željko Šević — Sat, 20 Jun 2026 20:46:54 +0000

Nginx is a reverse proxy and web server. On a local machine it can sit on port 80 and route traffic to apps running on other ports - a frontend on :3000, an API on :4000, or a Docker Compose stack with published ports.

This post covers install, config layout, reverse proxying, path-based routes, static files, and service commands on a local dev machine. It does not cover HTTPS, production hardening, or multi-domain TLS.

On Windows, use WSL2 with Ubuntu. On macOS or Linux, the same apt or brew install steps apply.

Prerequisites

WSL2 with Ubuntu (Windows) or a Linux/macOS shell
At least one app listening on a local port (for example :3000)
sudo access to install packages and edit /etc/nginx

Mental model

server - a virtual host block (listen, server_name) that handles requests for a hostname.
location - a path prefix inside a server (/, /api/) matched against the request URI.
proxy_pass - forwards the request to another HTTP server (your Node app, Compose service, etc.).
root - serves files from a directory on disk (built SPA, static HTML).

On Debian and Ubuntu, site configs live in /etc/nginx/sites-available/ and are enabled with symlinks in /etc/nginx/sites-enabled/. The main file /etc/nginx/nginx.conf includes those enabled sites.

Install

sudo apt update
sudo apt install nginx

Start Nginx and verify the default page:

sudo systemctl start nginx
curl -I http://localhost

You should get an HTTP 200 or 301 response.

Config layout

Path	Purpose
`/etc/nginx/nginx.conf`	Main config; includes enabled sites
`/etc/nginx/sites-available/`	Site config files (one file per app or domain)
`/etc/nginx/sites-enabled/`	Symlinks to enabled sites
`/var/log/nginx/access.log`	Request log
`/var/log/nginx/error.log`	Errors and config issues

Create a new site file:

sudo nano /etc/nginx/sites-available/local-dev

Enable it and disable the default site if it conflicts on port 80:

sudo ln -s /etc/nginx/sites-available/local-dev /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx

Always run nginx -t before reloading. A syntax error blocks reload and leaves the old config in place.

Proxy one service

Forward all traffic to an app on port 3000:

server {
    listen 80;
    server_name localhost;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

The Upgrade and Connection headers allow WebSocket connections through the proxy (useful for Vite, Next.js dev server, etc.).

Use an upstream block when several backend servers share the same target name; for a single local app, proxy_pass with a URL is enough.

Path-based routes

Route /api/ to a backend on port 4000 and everything else to a frontend on port 3000:

server {
    listen 80;
    server_name localhost;

    location /api/ {
        proxy_pass http://127.0.0.1:4000/;
        proxy_set_header Host $host;
    }

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
    }
}

Trailing slash in proxy_pass - proxy_pass http://127.0.0.1:4000/; (note the slash after the port) strips the matched /api/ prefix before forwarding. A request to /api/health reaches the backend as /health. Without the trailing slash, the backend receives /api/health.

Longer prefixes should use more specific location blocks. Nginx picks the best match for the request URI.

Static files

Serve a built frontend from disk instead of proxying:

server {
    listen 80;
    server_name localhost;
    root /var/www/my-app;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

try_files falls back to index.html for client-side routes in SPAs.

Commands

Command	Purpose
`sudo systemctl start nginx`	Start Nginx
`sudo systemctl stop nginx`	Stop Nginx
`sudo systemctl restart nginx`	Full restart (drops active connections)
`sudo systemctl reload nginx`	Reload config without dropping connections
`sudo systemctl status nginx`	Check service state
`sudo nginx -t`	Validate config syntax
`sudo nginx -s reload`	Reload without systemd
`curl -I http://localhost`	Smoke test from the shell

Safe edit workflow: edit config → sudo nginx -t → sudo systemctl reload nginx.

Use reload after config changes when the syntax test passes. Use restart when Nginx fails to start or after package upgrades.

Local networking on Windows + WSL

Nginx runs inside WSL. 127.0.0.1 inside WSL refers to the Linux VM, not processes on the Windows host.

App runs inside WSL or Docker Compose - use http://127.0.0.1:<port> in proxy_pass when the port is published to the WSL host (Compose ports: mapping works).
App runs on Windows only - use the Windows host IP from WSL:

  grep nameserver /etc/resolv.conf | awk '{ print $2 }'

Put that IP in proxy_pass instead of 127.0.0.1, or run the app inside WSL/Compose so localhost routing stays simple.

From a Windows browser, http://localhost reaches Nginx in WSL when it listens on port 80.

Troubleshooting

Port 80 already in use - check what holds the port: sudo ss -tlnp | grep :80. Stop the conflicting service or change Nginx listen to another port (for example 8080).
502 Bad Gateway - the upstream app is not running or the proxy_pass URL is wrong. Confirm the app responds: curl http://127.0.0.1:3000.
Config test fails - read the path and line from sudo nginx -t output; fix the file and test again before reload.
Unexpected routing - check /var/log/nginx/error.log and /var/log/nginx/access.log.

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation

Docker Compose overview

Željko Šević — Fri, 19 Jun 2026 22:55:36 +0000

Docker Compose runs multi-container applications from a single YAML file. One command can start an API, a database, a message broker, and supporting tools for local development - without installing each service on the host machine.

This post covers Compose concepts and commands. For ready-made stacks, see the service-specific posts linked at the end (Postgres/Redis, RabbitMQ, MongoDB, Kafka, DynamoDB/SQS).

Prerequisites

Docker Engine installed
Compose V2 - use docker compose (with a space). Current Docker Desktop includes it; no separate Compose install is required.

Mental model

Project - the folder that contains docker-compose.yml. The project name defaults to the directory name and prefixes container names.
Services - named containers defined in the file (api, redis, postgres). Each service maps to one image or build context.
Network - Compose creates a default network so services resolve each other by name. From the api container, Redis is reachable at redis:6379, not localhost:6379.
Volumes - named or bind mounts for data that survives docker compose down (unless you pass -v).

Minimal compose file

A two-service stack: a Node API and Redis. No top-level version: key - it is deprecated in the current Compose specification.

services:
  api:
    build: .
    ports:
      - 3000:3000
    environment:
      REDIS_URL: redis://redis:6379
    depends_on:
      - redis

  redis:
    image: redis:alpine
    volumes:
      - redis-data:/data

volumes:
  redis-data:

Run docker compose up --build from the directory that contains this file.

Core concepts

Ports - map host ports to container ports as host:container:

ports:
  - 3000:3000

Environment - inline variables or an env file:

environment:
  REDIS_URL: redis://redis:6379

env_file:
  - .env

Volumes - named volumes are managed by Docker (good for database data). Bind mounts map a host path into the container (good for live code reload during development):

volumes:
  - redis-data:/data        # named
  - ./src:/app/src:ro       # bind mount

Networks - services on the default network can reach each other by service name. Custom networks isolate groups of services (see the Postgres and Redis post for a multi-network example).

depends_on - controls startup order. It does not wait for the dependency to be ready; add a healthcheck or retry logic in the app when you need readiness.

restart - policies like on-failure:3 or unless-stopped keep containers running after crashes or host reboots.

healthcheck - optional probe so Compose and other services know when a container is ready:

healthcheck:
  test: ['CMD', 'redis-cli', 'ping']
  interval: 5s
  timeout: 3s
  retries: 5

Commands

Command	Purpose
`docker compose up`	Start services (foreground, logs in terminal)
`docker compose up -d`	Start in detached mode
`docker compose up --build`	Rebuild images before starting
`docker compose down`	Stop and remove containers
`docker compose down -v`	Also remove named volumes
`docker compose ps`	List running services
`docker compose logs -f api`	Follow logs for one service
`docker compose exec api sh`	Open a shell in a running container
`docker compose pull`	Pull latest images

When to use what

Tool	Best for
`docker run`	One-off containers, quick image tests
Docker Compose	Local multi-service stacks, dev databases and queues
Kubernetes	Production orchestration, scaling, rolling deploys

Service-specific setups

Postgres and Redis containers with Docker Compose - databases with Pgweb and Redis Commander
RabbitMQ container with Docker Compose - message broker with management UI
MongoDB containers with Docker Compose - MongoDB with Mongo Express
Kafka containers with Docker Compose - KRaft-mode Kafka with Kafka UI
DynamoDB and SQS containers with Docker Compose - DynamoDB Local and ElasticMQ

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation

Git SSH keys setup

Željko Šević — Thu, 18 Jun 2026 12:48:03 +0000

SSH keys let you authenticate with Git hosts without entering a password on every push or pull. This post covers generating keys for multiple providers, loading them into the SSH agent, and cloning repositories over SSH.

For general Git commands, see the Git cheatsheet.

Generate SSH keys

Generate a separate key for each provider (for example, GitHub and Bitbucket). Run ssh-keygen for each key, set a distinct filename, and optionally add a passphrase.

ssh-keygen -f ~/.ssh/id_rsa_github
ssh-keygen -f ~/.ssh/id_rsa_bitbucket

Add public keys to providers

Copy each public key (the .pub file) and add it to the provider:

cat ~/.ssh/id_rsa_github.pub
cat ~/.ssh/id_rsa_bitbucket.pub

Activate SSH keys

Start the SSH agent and add the keys you need for the current session.

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa_github
ssh-add ~/.ssh/id_rsa_bitbucket

Verify the connection to a provider:

ssh -T git@github.com
ssh -T git@bitbucket.org

Shell aliases per provider

Add aliases to ~/.bashrc or ~/.zshrc to run the agent setup and load the correct key in one command.

alias ssh-github='eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_rsa_github'
alias ssh-bitbucket='eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_rsa_bitbucket'

Reload the shell configuration, then run the alias before working with that provider:

source ~/.zshrc
ssh-github

Clone repositories

Use the SSH remote URL when cloning. The host (github.com or bitbucket.org) determines which key the provider expects.

# git clone <REPOSITORY_URL>
git clone git@github.com:workspace/repo-name.git
git clone git@bitbucket.org:workspace/repo-name.git

If authentication fails, run the matching alias (for example, ssh-github) and try again.

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation

Conversation memory for LangChain agents

Željko Šević — Wed, 17 Jun 2026 22:12:55 +0000

This post extends the support triage agent from Building AI agents with LangChain into a multi-turn flow: turn 1 looks up the customer and invoice; turn 2 creates the ticket without the user repeating IDs. It is post #5 in the LangChain series, following the overview, loaders/chunking, RAG, and agents posts.

Prerequisites

OpenAI account
Generated API key
Enabled billing
Node.js version 26
Packages from the agents post, plus the checkpoint package:

npm i langchain @langchain/openai @langchain/core @langchain/langgraph-checkpoint zod

OPENAI_API_KEY set in the environment

Mental model

Three related concepts:

Checkpointer - short-term session memory. Saves messages and graph state after each step so the next invoke on the same thread can resume.
thread_id - conversation key passed in configurable. Same ID = same history; different ID = isolated session.
Store - long-term memory across threads (user preferences, facts learned over time). LangGraph stores are separate from checkpointers; this post focuses on checkpointers only.

Typical support flow with memory:

Turn 1 - rep asks to look up cus_1042 and inv_8891; agent calls lookup tools and summarizes findings.
Turn 2 - rep says "create the ticket we discussed"; agent recalls prior tool results and calls create_support_ticket.

MemorySaver

For demos and tests, use MemorySaver - an in-memory checkpointer that persists state for the lifetime of the process:

import { MemorySaver } from '@langchain/langgraph-checkpoint';

const checkpointer = new MemorySaver();

State is lost when the Node process exits. That is fine for local scripts; production apps need a durable backend (see below).

Attach a checkpointer to createAgent

Pass the checkpointer when creating the agent. Reuse the same triage tools and instructions from the agents post:

import { createAgent } from 'langchain';
import { MemorySaver } from '@langchain/langgraph-checkpoint';

const agent = createAgent({
  model: 'gpt-5.5',
  tools: supportTools,
  systemPrompt: TRIAGE_INSTRUCTIONS,
  checkpointer: new MemorySaver(),
});

The agent loop is unchanged - the checkpointer hooks into LangGraph beneath createAgent.

First turn - lookup

Pass a stable thread_id in the invoke config:

const threadConfig = { configurable: { thread_id: 'support-cus-1042' } };

const turn1 = await agent.invoke(
  {
    messages: [
      {
        role: 'user',
        content:
          'Look up customer cus_1042 and invoice inv_8891 for a possible duplicate charge. Summarize what you find. Do not create a ticket yet.',
      },
    ],
  },
  threadConfig,
);

console.log(turn1.messages.at(-1)?.content);

The agent calls get_customer, get_invoice, and search_knowledge_base. LangGraph saves the full message history (including tool results) to the checkpointer.

Second turn - follow-up without IDs

Send only the new user message on the same thread_id. Prior context is restored automatically:

const turn2 = await agent.invoke(
  {
    messages: [
      {
        role: 'user',
        content: 'Create the support ticket we discussed.',
      },
    ],
  },
  threadConfig,
);

console.log(turn2.messages.at(-1)?.content);

The agent should call create_support_ticket using customer and invoice details from turn 1 - the user does not repeat cus_1042 or inv_8891.

Read the final answer from result.messages as in the agents post:

const lastAi = [...turn2.messages]
  .reverse()
  .find((message) => message.type === 'ai');

console.log(lastAi?.content);

Thread isolation

Different thread_id values do not share history. Two support reps working different cases should use separate thread IDs:

await agent.invoke(
  { messages: [{ role: 'user', content: 'Look up cus_1042.' }] },
  { configurable: { thread_id: 'rep-alice-case-1' } },
);

await agent.invoke(
  { messages: [{ role: 'user', content: 'Create the ticket we discussed.' }] },
  { configurable: { thread_id: 'rep-bob-case-2' } },
);

The second invoke on rep-bob-case-2 has no knowledge of Alice's lookup - Bob's thread starts empty.

Production checkpointers

MemorySaver is process-local and not suitable for production. LangGraph supports durable checkpointers backed by Postgres, SQLite, and other stores via @langchain/langgraph-checkpoint integrations. Swap the checkpointer implementation; the thread_id API stays the same.

Pick a backend that matches your deployment: Postgres for multi-instance apps, SQLite for single-node services.

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation

Building AI agents with LangChain

Željko Šević — Tue, 16 Jun 2026 20:31:35 +0000

LangChain agents are built on LangGraph: the model calls tools in a loop until it returns a final answer. The high-level entry point is createAgent - pass a model, tools defined with tool(), and an optional systemPrompt.

This post builds the same support triage agent as the Vercel AI SDK agents and OpenAI Agents SDK posts so you can compare SDKs on one scenario. It follows the LangChain overview for Node.js and fits as post #4 in the LangChain series (after loaders/chunking and the RAG with pgvector pipeline).

Prerequisites

OpenAI account
Generated API key
Enabled billing
Node.js version 26
langchain, @langchain/openai, @langchain/core, and zod installed:

npm i langchain @langchain/openai @langchain/core zod

OPENAI_API_KEY set in the environment

Mental model - turns and the agent loop

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

returns final text (the run ends), or
returns tool calls (LangChain executes them and starts another turn with the results)

Typical flow for the support triage agent: user question → model calls lookup tools (get_customer, get_invoice, search_knowledge_base) → model creates a ticket or escalates → final answer.

A single turn can include multiple parallel tool calls. Set recursionLimit on invoke or stream to cap how many graph steps run (each model generation and tool batch counts toward the limit).

Defining tools

Use tool() from langchain with a Zod schema, plus name and description so the model knows when to call each tool:

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

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

LangChain uses schema (not Vercel's inputSchema or OpenAI Agents' parameters). The handler receives validated input as the first argument.

createAgent

Wire the model, tools, and triage instructions:

import { createAgent } from 'langchain';

const agent = createAgent({
  model: 'gpt-5.5',
  tools: [getInvoice],
  systemPrompt: `You are a billing support triage agent.
Look up records before recommending refunds or creating tickets.`,
});

model can be a provider string ('gpt-5.5', 'openai:gpt-5.5') or a chat model instance from @langchain/openai.

Invoke

Pass a messages array and read the final answer from result.messages:

const result = await agent.invoke({
  messages: [
    {
      role: 'user',
      content: 'What is the status of invoice inv_8891? Reply in one sentence.',
    },
  ],
});

const lastAi = [...result.messages]
  .reverse()
  .find((message) => message.type === 'ai');

console.log(lastAi?.content);

The last AI message is the agent's final reply after any tool calls complete.

Support triage scenario

Example prompt:

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

A realistic chain:

get_customer - plan tier, open ticket count
get_invoice - amount, status, payment IDs
search_knowledge_base - duplicate-charge and refund policy
create_support_ticket or escalate_to_human - write action or escalation

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

Multi-tool agent

import { createAgent } from 'langchain';
import {
  getCustomer,
  getInvoice,
  searchKnowledgeBase,
  createSupportTicket,
  escalateToHuman,
  TRIAGE_INSTRUCTIONS,
} from './tools/index.js';

const agent = createAgent({
  model: 'gpt-5.5',
  tools: [
    getCustomer,
    getInvoice,
    searchKnowledgeBase,
    createSupportTicket,
    escalateToHuman,
  ],
  systemPrompt: TRIAGE_INSTRUCTIONS,
});

const result = await agent.invoke({
  messages: [
    {
      role: 'user',
      content:
        'Customer cus_1042 says they were charged twice for invoice inv_8891. What should we do?',
    },
  ],
  recursionLimit: 15,
});

const answer = [...result.messages]
  .reverse()
  .find((message) => message.type === 'ai');

console.log(answer?.content);

Inspect result.messages for the full trace: human input, AI tool-call messages, tool results, and the final AI reply.

Streaming

agent.stream() yields state updates as the graph runs. Use streamMode: 'values' to receive the full message list after each step:

const stream = await agent.stream(
  {
    messages: [
      {
        role: 'user',
        content:
          'Customer cus_1042 says they were charged twice for invoice inv_8891. What should we do?',
      },
    ],
  },
  { streamMode: 'values', recursionLimit: 15 },
);

let finalMessages = [];

for await (const state of stream) {
  if (state.messages) {
    finalMessages = state.messages;
  }
}

const answer = [...finalMessages]
  .reverse()
  .find((message) => message.type === 'ai');

console.log(answer?.content);

For token-level streaming, use streamMode: 'messages' or streamEvents (see LangGraph streaming).

When to pick LangChain

	LangChain `createAgent`	Vercel AI SDK	OpenAI Agents SDK
Best for	RAG + LCEL + agents in one stack	TypeScript apps already on AI SDK	OpenAI-first agent primitives
Tool definition	`tool()` + Zod `schema`	`tool()` + `inputSchema`	`tool()` + Zod `parameters`
Run API	`agent.invoke` / `agent.stream`	`generateText` + `stopWhen`	`run()` + `maxTurns`
Handoffs / guardrails	Middleware (advanced)	Limited	Built-in
Memory	LangGraph checkpointers	Bring your own	Session helpers

Pick LangChain when document loaders, retrievers, and agents should share one ecosystem. Pick Vercel AI SDK or OpenAI Agents SDK when you want a focused agent layer without the broader LangChain surface.

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation

DEV Community: Željko Šević

Git hooks with Husky

Prerequisites

Setup

Mental model

Pre-commit with lint-staged

Other useful hooks

Skipping hooks

Pitfalls

When to use what

Need help with your project?

Cron jobs and schedulers with BullMQ

Prerequisites

Mental model

Queue and worker

Cron schedulers

Register schedulers on startup

NestJS with @nestjs/bullmq

Pitfalls

When to use what

Need help with your project?

Integration with Lever public jobs API

Prerequisites

Find the site slug

API overview

Basic integration

Filter at the source

Normalize to a stable shape

Need help with your project?

Integration with Workable public jobs API

Prerequisites

Find the account slug

API overview

Basic integration

Locations and remote detection

Normalize to a stable shape

Need help with your project?

Integration with Greenhouse public jobs API

Prerequisites

Find the board token

API overview

Basic integration

Location and metadata

Normalize to a stable shape

Need help with your project?

Integration with Ashby public jobs API

Prerequisites

Find the job board name

API overview

Basic integration

Normalize to a stable shape

Need help with your project?

Request context in Node.js with AsyncLocalStorage

What AsyncLocalStorage is

Prerequisites

Core API

Express middleware pattern

NestJS interceptor and decorator

Why it works

Common pitfalls

Related use cases

Need help with your project?

Nginx local setup

Prerequisites

Mental model

Install

Config layout

Proxy one service

Path-based routes

Static files

Commands

Local networking on Windows + WSL

Troubleshooting

Need help with your project?

Docker Compose overview

Prerequisites

Mental model

Minimal compose file

Core concepts

Commands

NestJS with `@nestjs/bullmq`