DEV Community: Sathish

Next.js: I stop AI refactors with a guardrail

Sathish — Thu, 07 May 2026 15:01:00 +0000

I don’t let Cursor/Claude “refactor freely” anymore.
I add cheap guardrails: type-level checks + runtime assertions.
I catch the dumb bugs: undefined envs, wrong shapes, silent 200s.
You can copy my 4-file setup in 10 minutes.

Context

I build small SaaS apps. Usually solo. Usually fast.

AI-assisted coding makes me faster. Also makes me sloppy.

My recurring failure mode: I ask for a “cleanup refactor”. Cursor applies a wide diff. Claude rewrites helpers. Tests don’t exist yet. Then I ship. Then prod logs say something like TypeError: Cannot read properties of undefined (reading 'split').

Brutal part? The code looks cleaner. The bug hides in the seams.

So I stopped arguing with my own workflow. I added guardrails that are boring, loud, and hard to accidentally remove.

1) I start by making config impossible to “kind of work”

My favorite bug.

Missing env var. Code still boots. Then it fails 12 minutes later.

I used to do this:

// ❌ Don't do this
const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000";

That default is a trap. It makes staging point at localhost. I’ve done it.

Now I parse env once. At startup. And I crash early.

// src/env.ts
import { z } from "zod";

const EnvSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  NEXT_PUBLIC_BASE_URL: z.string().url(),
  DATABASE_URL: z.string().min(1),
  SUPABASE_SERVICE_ROLE_KEY: z.string().min(1),
});

export const env = EnvSchema.parse({
  NODE_ENV: process.env.NODE_ENV,
  NEXT_PUBLIC_BASE_URL: process.env.NEXT_PUBLIC_BASE_URL,
  DATABASE_URL: process.env.DATABASE_URL,
  SUPABASE_SERVICE_ROLE_KEY: process.env.SUPABASE_SERVICE_ROLE_KEY,
});

Two wins.

One: if Claude “helpfully” renames an env var, I’ll know immediately.

Two: when I paste snippets, I import env and stop touching process.env directly. Less surface area for mistakes.

And yeah, this has saved me on deploy. More than once.

2) I force every API response through a single type

Next.js route handlers are easy to mess up during refactors.

AI loves changing shapes.

Yesterday it’s { data: ... }. Today it’s { result: ... }. My client keeps compiling because it’s any somewhere. Then runtime explodes.

So I made one response envelope. Everywhere.

// src/lib/api-response.ts
export type ApiOk = { ok: true; data: T };
export type ApiErr = {
  ok: false;
  error: { code: string; message: string; details?: unknown };
};

export type ApiResponse = ApiOk | ApiErr;

export function ok(data: T): ApiOk {
  return { ok: true, data };
}

export function err(code: string, message: string, details?: unknown): ApiErr {
  return { ok: false, error: { code, message, details } };
}

Then I use it in a route handler.

// src/app/api/user/route.ts
import { NextResponse } from "next/server";
import { ok, err, type ApiResponse } from "@/lib/api-response";

type UserDto = { id: string; email: string };

export async function GET() {
  try {
    // Pretend this comes from DB.
    const user: UserDto = { id: "u_123", email: "a@b.com" };

    const body: ApiResponse = ok(user);
    return NextResponse.json(body, { status: 200 });
  } catch (e) {
    const body: ApiResponse = err("INTERNAL", "Something broke", e);
    return NextResponse.json(body, { status: 500 });
  }
}

Now when AI tries to return { user } or { success: true }, TypeScript complains.

Not always. But often enough.

And when it doesn’t complain, the next guardrail does.

3) I validate request + response at runtime (not just types)

Types lie.

Especially when the boundary is JSON.

So I validate input. And I validate output.

I don’t do it for every endpoint. Only the ones I touch a lot.

// src/lib/schemas.ts
import { z } from "zod";

export const CreateThingSchema = z.object({
  name: z.string().min(1).max(80),
  enabled: z.boolean().default(true),
});

export const ThingSchema = z.object({
  id: z.string().min(1),
  name: z.string().min(1),
  enabled: z.boolean(),
  createdAt: z.string().datetime(),
});

export type CreateThingInput = z.infer;
export type Thing = z.infer;

And in the route:

// src/app/api/things/route.ts
import { NextResponse } from "next/server";
import { z } from "zod";
import { ok, err, type ApiResponse } from "@/lib/api-response";
import { CreateThingSchema, ThingSchema, type Thing } from "@/lib/schemas";

export async function POST(req: Request) {
  try {
    const json = await req.json();
    const input = CreateThingSchema.parse(json);

    // Fake DB write.
    const thing: Thing = {
      id: crypto.randomUUID(),
      name: input.name,
      enabled: input.enabled,
      createdAt: new Date().toISOString(),
    };

    // Output validation catches “helpful” refactors.
    const safeThing = ThingSchema.parse(thing);

    const body: ApiResponse = ok(safeThing);
    return NextResponse.json(body, { status: 201 });
  } catch (e) {
    const message = e instanceof z.ZodError ? "Invalid payload" : "Internal error";
    const body: ApiResponse = err("BAD_REQUEST", message, e);
    return NextResponse.json(body, { status: 400 });
  }
}

That last ThingSchema.parse(thing) feels redundant.

It isn’t.

I had Claude refactor a DTO once and “simplify” createdAt into a Date. Everything compiled. JSON serialization changed. Client parsing broke. Took me 2 hours.

Now it dies in the handler.

Fast.

4) I make Cursor show me a checklist before I accept a diff

This part isn’t code. But it’s still a guardrail.

I keep a tiny REFRACTOR_CHECKLIST.md in the repo root. Cursor sees it. Claude sees it. And I paste it into chat when I’m about to do a big change.

It’s not motivational. It’s annoying on purpose.

Example of what I keep in mine:

# Refactor checklist (non-negotiable)

- No new `process.env` usage. Import from `src/env.ts`.
- API responses must match `ApiResponse`.
- Any JSON boundary: Zod parse input.
- If you changed response shape: update schema + client.
- No silent fallbacks ("" || default) for URLs/keys.
- Run: `pnpm lint` and `pnpm typecheck`.

Yeah, it’s simple.

But it changes the vibe. Cursor stops being “do whatever.” It becomes “do it, but inside the rails.”

And when I ignore it, I can’t pretend I didn’t know.

Results

I used this setup on 3 refactors over the last 9 days.

Before: I’d usually ship 1 dumb runtime bug per refactor. Missing env var. Wrong response key. A Date sneaking into JSON. Stuff like that.

After: I caught 8 failures locally.

3 were missing env vars during next dev.
2 were response shape mismatches.
2 were invalid request payloads I didn’t handle.
1 was a createdAt type mismatch.

No prod incidents from those refactors. Small win. I’ll take it.

Key takeaways

Parse env once. Crash early. Don’t default URLs.
Use one API envelope. Force it with types.
Validate JSON boundaries at runtime with Zod.
Validate outputs too, not just inputs.
Keep a repo checklist file so AI sees the rules.

Closing

Cursor + Claude make big diffs feel safe. They aren’t.

I stopped trying to “prompt better” and started adding rails the codebase can enforce.

What guardrail do you rely on most: env parsing, response envelopes, runtime schemas, or something else entirely?

React Native offline: SQLite migrations without pain

Sathish — Wed, 06 May 2026 15:01:02 +0000

I ship schema changes in an offline-first Expo app.
I run migrations inside a single SQLite transaction.
I use PRAGMA user_version as my only “migration table”.
I added a tiny verifier to catch broken migrations fast.

Context

I’m building a React Native fitness app. Expo. SQLite. Offline-first.

Workouts must log without internet. Always.

Then the real problem hits. Schema changes.

I started with “I’ll just add a column”. Brutal.
One bad ALTER in production and you’ve got users stuck on an old schema, with data you can’t read, and no easy way to recover.

I tried keeping migrations in my head. That lasted 2 days.
Then I spent 4 hours debugging “no such column: sets.rpe”. Most of it was wrong.

What finally worked: PRAGMA user_version + transactional migrations + a startup verifier.
No ORM. No magic.

1) I treat migrations like app code. Versioned.

I don’t keep a migrations table.
I keep one number.

SQLite already has it: PRAGMA user_version.

So my app has a single source of truth:

current schema version in code
current schema version in the database
a deterministic path forward

Here’s the core helper I run at app startup.

// db/migrate.ts
import * as SQLite from 'expo-sqlite';

export const SCHEMA_VERSION = 4;

export async function getUserVersion(db: SQLite.SQLiteDatabase) {
  const row = await db.getFirstAsync&lt;{ user_version: number }&gt;(
    'PRAGMA user_version;'
  );
  return row?.user_version ?? 0;
}

export async function setUserVersion(db: SQLite.SQLiteDatabase, v: number) {
  // PRAGMA doesn't support bindings here.
  await db.execAsync(`PRAGMA user_version = ${v};`);
}

export async function migrateIfNeeded(db: SQLite.SQLiteDatabase) {
  const from = await getUserVersion(db);
  if (from === SCHEMA_VERSION) return;
  if (from &gt; SCHEMA_VERSION) throw new Error(`DB version ${from} &gt; app ${SCHEMA_VERSION}`);

  await db.execAsync('BEGIN;');
  try {
    for (let v = from + 1; v &lt;= SCHEMA_VERSION; v++) {
      await runMigration(db, v);
      await setUserVersion(db, v);
    }
    await db.execAsync('COMMIT;');
  } catch (e) {
    await db.execAsync('ROLLBACK;');
    throw e;
  }
}

async function runMigration(db: SQLite.SQLiteDatabase, toVersion: number) {
  switch (toVersion) {
    case 1:
      await db.execAsync(`
        CREATE TABLE IF NOT EXISTS workouts (
          id TEXT PRIMARY KEY NOT NULL,
          started_at INTEGER NOT NULL,
          ended_at INTEGER
        );
      `);
      return;
    case 2:
      await db.execAsync(`
        CREATE TABLE IF NOT EXISTS sets (
          id TEXT PRIMARY KEY NOT NULL,
          workout_id TEXT NOT NULL,
          exercise_id TEXT NOT NULL,
          reps INTEGER NOT NULL,
          weight_kg REAL NOT NULL,
          created_at INTEGER NOT NULL
        );
      `);
      await db.execAsync('CREATE INDEX IF NOT EXISTS idx_sets_workout ON sets(workout_id);');
      return;
    case 3:
      // Add RPE. Nullable first. Backfill later.
      await db.execAsync('ALTER TABLE sets ADD COLUMN rpe INTEGER;');
      return;
    case 4:
      // New index for my “last set per exercise” screen.
      await db.execAsync('CREATE INDEX IF NOT EXISTS idx_sets_exercise_created ON sets(exercise_id, created_at);');
      return;
    default:
      throw new Error(`Missing migration for version ${toVersion}`);
  }
}

One thing that bit me — ALTER TABLE ... ADD COLUMN is forgiving, but not free.
If you later want NOT NULL or a default, you’re in table-rebuild territory.
So I add columns nullable first. Then I backfill. Then I enforce later (if I still care).

2) I don’t trust my migrations. I verify them.

SQLite will happily let you ship a schema that “kinda works”.
Until one query hits a missing index or column.

So I verify after migrating.
Not with a test suite. On-device.
A tiny check. Runs in dev and prod.

This caught a real bug: I renamed weight to weight_kg in code, but never migrated old installs.
My UI was fine on fresh installs. Broken on my phone.

// db/verify.ts
import * as SQLite from 'expo-sqlite';
import { SCHEMA_VERSION, getUserVersion } from './migrate';

type Col = { name: string };

export async function verifySchema(db: SQLite.SQLiteDatabase) {
  const v = await getUserVersion(db);
  if (v !== SCHEMA_VERSION) throw new Error(`verifySchema: expected v${SCHEMA_VERSION}, got v${v}`);

  const cols = await db.getAllAsync('PRAGMA table_info(sets);');
  const names = new Set(cols.map(c =&gt; c.name));

  // Guard the query paths my app uses every session.
  for (const required of ['id', 'workout_id', 'exercise_id', 'reps', 'weight_kg', 'created_at', 'rpe']) {
    if (!names.has(required)) {
      throw new Error(`verifySchema: missing sets.${required}`);
    }
  }

  // Also verify my hot index exists.
  const idx = await db.getAllAsync&lt;{ name: string }&gt;("PRAGMA index_list('sets');");
  const idxNames = new Set(idx.map(i =&gt; i.name));
  if (!idxNames.has('idx_sets_exercise_created')) {
    throw new Error('verifySchema: missing idx_sets_exercise_created');
  }
}

Yes, it’s a little paranoid.
But “no such column” in production is worse.

If verification throws, I show a blocking screen with a support code.
Because letting the app limp forward corrupts data.

3) I learned table rebuilds the hard way

At some point you’ll want:

NOT NULL
real defaults
dropping columns
changing types

SQLite doesn’t support most of that directly.
So you rebuild the table.

I messed this up once and duplicated rows.
I forgot to copy the primary key constraint.
Spent an evening staring at “UNIQUE constraint failed: sets.id”.

This is the rebuild pattern I use now.
It’s boring. That’s the point.

// db/migrations/rebuildSets.ts
import * as SQLite from 'expo-sqlite';

export async function rebuildSetsWithDefaults(db: SQLite.SQLiteDatabase) {
  // 1) New table with the final shape.
  await db.execAsync(`
    CREATE TABLE sets_new (
      id TEXT PRIMARY KEY NOT NULL,
      workout_id TEXT NOT NULL,
      exercise_id TEXT NOT NULL,
      reps INTEGER NOT NULL,
      weight_kg REAL NOT NULL,
      rpe INTEGER NOT NULL DEFAULT 0,
      created_at INTEGER NOT NULL
    );
  `);

  // 2) Copy data over. COALESCE handles old NULL rpe.
  await db.execAsync(`
    INSERT INTO sets_new (id, workout_id, exercise_id, reps, weight_kg, rpe, created_at)
    SELECT id, workout_id, exercise_id, reps, weight_kg, COALESCE(rpe, 0), created_at
    FROM sets;
  `);

  // 3) Swap.
  await db.execAsync('DROP TABLE sets;');
  await db.execAsync('ALTER TABLE sets_new RENAME TO sets;');

  // 4) Recreate indexes.
  await db.execAsync('CREATE INDEX IF NOT EXISTS idx_sets_workout ON sets(workout_id);');
  await db.execAsync('CREATE INDEX IF NOT EXISTS idx_sets_exercise_created ON sets(exercise_id, created_at);');
}

I only do this inside the migration transaction.
If anything fails, rollback leaves the old table untouched.

And yeah — on huge tables this can be slow.
For my app it’s fine.
My largest real device had 3,482 set rows when I tested it.

4) I wire it into Expo startup. No race conditions.

My first attempt ran migrations after the UI mounted.
Bad move.

The app rendered screens that queried the DB while migrations were running.
I got:

SQLiteException: no such table: sets
and once, a silent empty list because my query failed and I swallowed the error

Now I block rendering until:

DB opens
migrations run
verification passes

// App.tsx
import React from 'react';
import * as SQLite from 'expo-sqlite';
import { migrateIfNeeded } from './db/migrate';
import { verifySchema } from './db/verify';

export default function App() {
  const [ready, setReady] = React.useState(false);
  const [err, setErr] = React.useState(null);

  React.useEffect(() =&gt; {
    let cancelled = false;
    (async () =&gt; {
      try {
        const db = await SQLite.openDatabaseAsync('gym.db');
        await migrateIfNeeded(db);
        await verifySchema(db);
        if (!cancelled) setReady(true);
      } catch (e: any) {
        if (!cancelled) setErr(e?.message ?? String(e));
      }
    })();
    return () =&gt; {
      cancelled = true;
    };
  }, []);

  if (err) return DB init failed: {err};
  if (!ready) return Opening database…;

  return ;
}

function Text(props: any) {
  return &lt;&gt;{/* replace with RN Text in real app */}{props.children};
}

function MainApp() {
  return App ready;
}

In my real project I pass db via context.
But the point stands.
No UI until the DB is safe.

Results

I shipped 4 schema versions across 3 physical devices (Pixel 7, iPhone 13, a cheap Android 11 burner).

Before this setup, upgrading from my old build failed on 2 of those 3 devices with no such column: sets.rpe.
After switching to user_version + transactional migrations + verification, I did 27 cold starts in a row without a single migration-related crash.

The biggest win wasn’t performance.
It was confidence.
I can add a column at midnight and not fear the next morning.

Key takeaways

Use PRAGMA user_version for schema state. One number. No drama.
Wrap every migration in BEGIN/COMMIT. Always rollback on error.
Add columns nullable first. Rebuild later if you need constraints.
Verify the schema after migrating with PRAGMA table_info and PRAGMA index_list.
Block UI until migrations + verification finish, or you’ll chase race-condition ghosts.

Closing

I’m still deciding how aggressive to be on verification failures.
Right now I hard-block the app and show an error.
No “continue anyway” button.

If you ship offline-first SQLite apps, do you ever auto-reset the local DB on schema mismatch, or do you always force a manual recovery path?

Next.js job board: stop Google indexing filters

Sathish — Tue, 05 May 2026 15:00:52 +0000

I blocked /jobs?* pages from getting indexed.
I kept filters usable for users (and shareable).
I generated canonicals + noindex consistently in App Router.
I wrote a tiny script to catch regressions before deploy.

Context

I’m building a job board for Psychiatric Mental Health Nurse Practitioners. Next.js 14. App Router. Supabase Postgres.

The data’s big enough to hurt. 8,000+ active listings. 2,000+ companies. I scrape 200+ jobs daily. The UI needs filters. Location, remote, salary, posted date.

And Google loved my filters. Too much.

I ended up with thousands of crawlable URLs like /jobs?remote=true&state=CA&salaryMin=160000. Same content. Slightly different. Crawl budget drain. Index bloat. Brutal.

I didn’t want to kill filters. Users need them. I just needed Google to index the right pages.

1) I decide what’s indexable. Everything else is `noindex`.

I keep it simple.

/jobs (no filters): indexable.
/jobs?remote=true (one “primary” filter): indexable.
Anything else: noindex,follow.

That last part matters. I still want Google to crawl job detail pages linked from filtered results.

I centralize the rule. One function. No guessing across components.

// lib/seo/indexing.ts

export type JobsSearchParams = Record;

const INDEXABLE_KEYS = new Set(["remote", "state", "q"]);

export function shouldIndexJobsListing(searchParams: JobsSearchParams): boolean {
  // No params =&gt; indexable
  const keys = Object.keys(searchParams).filter((k) =&gt; {
    const v = searchParams[k];
    if (v === undefined) return false;
    if (Array.isArray(v)) return v.length &gt; 0;
    return String(v).length &gt; 0;
  });

  if (keys.length === 0) return true;

  // Only one allowed key =&gt; indexable
  if (keys.length === 1 &amp;&amp; INDEXABLE_KEYS.has(keys[0])) return true;

  return false;
}

I spent 2 hours trying to make “smart rules.”

Like “index salary filters but only if salaryMin >= 140000.”

Don’t.
You’ll ship a bug. And you’ll forget it exists.

2) I generate canonical URLs that ignore junk params

The canonical is the other half.

Even with noindex, canonicals keep things tidy. And they prevent weird duplication when Google ignores your noindex for a while.

I canonicalize /jobs pages to a clean version:

Keep only the one indexable key.
Drop everything else.
Sort params so the URL is stable.

// lib/seo/canonical.ts

import type { JobsSearchParams } from "./indexing";

const CANONICAL_ALLOWLIST = new Set(["remote", "state", "q"]);

export function canonicalJobsUrl(baseUrl: string, searchParams: JobsSearchParams): string {
  const url = new URL("/jobs", baseUrl);

  const entries: Array&lt;[string, string]&gt; = [];

  for (const [k, v] of Object.entries(searchParams)) {
    if (!CANONICAL_ALLOWLIST.has(k)) continue;
    if (v === undefined) continue;

    // Next.js can give string | string[]
    const value = Array.isArray(v) ? v[0] : v;
    if (!value) continue;

    entries.push([k, value]);
  }

  // Only keep the first canonical param.
  // This matches my indexing rule: 0 or 1 param.
  entries.sort(([a], [b]) =&gt; a.localeCompare(b));
  const first = entries[0];
  if (first) url.searchParams.set(first[0], first[1]);

  return url.toString();
}

One thing that bit me — q (search query) can explode into infinite combinations.

I still allow it as indexable for one term. Because PMHNP queries are usually specific.

If your site gets spammed with q=asdf123, don’t index q. Period.

3) I wire it into Next.js metadata. No custom `` hacks.

App Router makes this clean.

I compute robots and alternates.canonical in generateMetadata.

And I do it per request. Using searchParams.

`ts
// app/jobs/page.tsx

import type { Metadata } from "next";
import { shouldIndexJobsListing } from "@/lib/seo/indexing";
import { canonicalJobsUrl } from "@/lib/seo/canonical";

export async function generateMetadata(
props: { searchParams: Promise> }
): Promise {
const searchParams = await props.searchParams;
const baseUrl = process.env.NEXT_PUBLIC_SITE_URL!;

const indexable = shouldIndexJobsListing(searchParams);
const canonical = canonicalJobsUrl(baseUrl, searchParams);

return {
title: "PMHNP Jobs",
alternates: { canonical },
robots: indexable
? { index: true, follow: true }
: { index: false, follow: true },
};
}

export default async function JobsPage() {
// ...normal page code
return null;
}
`

Yes, I’m using NEXT_PUBLIC_SITE_URL.

I tried to infer the host from headers.
That got messy behind Vercel previews.

So I set it explicitly per environment.

Preview: https://..vercel.app
Prod: my real domain

No surprises.

4) I add a `robots.txt` rule. Because crawlers are stubborn.

Metadata helps.

But crawlers still hammer filtered URLs. Especially if they find them in internal links.

So I also disallow query-string crawling for the listing route.

This doesn’t replace noindex. It reduces noise.

`ts
// app/robots.ts

import type { MetadataRoute } from "next";

export default function robots(): MetadataRoute.Robots {
const siteUrl = process.env.NEXT_PUBLIC_SITE_URL!;

return {
rules: [
{
userAgent: "",
allow: ["/"],
disallow: [
"/jobs?", // stop crawling filter combos
"/api/", // obvious
],
},
],
sitemap: ${siteUrl}/sitemap.xml,
};
}
`

I know. robots.txt is advisory.

But it still cuts crawling.
And it’s cheap.

Also, don’t disallow your job detail pages.
I almost did /jobs/* out of frustration.
That would’ve been a full self-own.

5) I test it with a script. Not with “I’ll remember.”

This is where I usually mess up.

I change filter UI. Add a param. Forget to update canonical rules.
Two weeks later, GSC is screaming.

So I wrote a tiny Node script.
It fetches a handful of URLs and asserts:

Filter combos => noindex
Canonical is clean

`js
// scripts/check-jobs-indexing.mjs

const SITE = process.env.SITE_URL || "http://localhost:3000";

const cases = [
"/jobs",
"/jobs?remote=true",
"/jobs?remote=true&state=CA",
"/jobs?state=CA&salaryMin=160000",
"/jobs?q=pmhnp",
];

function assert(cond, msg) {
if (!cond) throw new Error(msg);
}

for (const path of cases) {
const url = ${SITE}${path};
const res = await fetch(url, { redirect: "manual" });
const html = await res.text();

const robots = html.match(/

Cursor + Claude: stop shipping broken env vars

Sathish — Thu, 30 Apr 2026 15:00:50 +0000

I stopped guessing why builds break. I lint env vars.
I generate .env.example from code. Not docs.
I validate at runtime with Zod. One error message.
I run a tiny Node script in CI. Fails fast.

Context

I ship small SaaS apps. Usually solo. Usually fast.

And I kept losing time to env vars.

The worst kind of bug. Works on my machine. Fails in CI. Or only fails after deploy. Or fails only in preview.

Real examples from the last month:

NEXT_PUBLIC_APP_URL was missing in Vercel preview. OAuth callback broke.
DATABASE_URL existed, but pointed to the wrong DB. Brutal.
STRIPE_WEBHOOK_SECRET had a trailing space. Took me 40 minutes.

Cursor + Claude helped. But not by “prompting harder”.
I needed a system.

So I built an env pipeline:
1) single schema
2) runtime validation
3) .env.example generated from that schema
4) CI script that fails before Next.js even starts

1) I wrote one env schema. Everything else follows.

I used to scatter process.env.X across files.

That’s how you get silent undefined.
Then you “fix” it with || ''.
Then prod does something weird.

Now I centralize env parsing.
One file. One export.

I use Zod because the error messages are readable.
And because it lets me do coercion without hacks.

// src/env.ts
import { z } from "zod";

const EnvSchema = z.object({
  // Server-only
  DATABASE_URL: z.string().url(),
  AUTH_SECRET: z.string().min(32),

  // Public (Next.js exposes these)
  NEXT_PUBLIC_APP_URL: z.string().url(),
  NEXT_PUBLIC_POSTHOG_KEY: z.string().min(1).optional(),

  // Example of coercion
  RATE_LIMIT_PER_MINUTE: z.coerce.number().int().positive().default(60),
});

// Parse once. Throw once.
export const env = EnvSchema.parse({
  DATABASE_URL: process.env.DATABASE_URL,
  AUTH_SECRET: process.env.AUTH_SECRET,
  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
  NEXT_PUBLIC_POSTHOG_KEY: process.env.NEXT_PUBLIC_POSTHOG_KEY,
  RATE_LIMIT_PER_MINUTE: process.env.RATE_LIMIT_PER_MINUTE,
});

export type Env = z.infer;

Cursor made this fast.
I highlighted my old process.env usage and asked it to “extract to env.ts with Zod”.
It got 80% right.

The other 20% was me catching mistakes.
Like it tried to mark DATABASE_URL as NEXT_PUBLIC_... once. Nope.

One thing that bit me — Next.js runs code in weird places.
If you import env in a client component, you’ll bundle secrets.
So I keep env imports server-only.

2) I made Next.js scream early (before any page renders)

Runtime validation is good.
But I wanted it earlier than “user hits route”.

So I validate inside an instrumentation hook.
This runs when the server starts.
If env is wrong, it dies immediately.

// src/instrumentation.ts
// Next.js will run this on server startup.
// It won't run in the browser.

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    // Import only on server to avoid bundling.
    await import("./env");
  }
}

This saved me from the dumbest deploy.
Preview environment missing AUTH_SECRET.
Instead of “random auth errors”, the build just failed with a Zod stack trace.

And yeah, the first time I wired this up I got:
Error: Cannot find module './env'

My fault.
Wrong path.
Spent 25 minutes.
Most of it was me staring at a working file.

3) I generate `.env.example` from the schema

Docs lie.
Old README snippets lie even harder.

I want .env.example to be derived from the schema.
So when I add a var, the example updates.
No manual steps.

I keep a tiny script.
It writes keys only. No secrets.

// scripts/generate-env-example.ts
import { writeFileSync } from "node:fs";
import { z } from "zod";

// Keep this list in sync with src/env.ts.
// I don't try to auto-parse TS. Too fragile.
const EnvSchema = z.object({
  DATABASE_URL: z.string().url(),
  AUTH_SECRET: z.string().min(32),
  NEXT_PUBLIC_APP_URL: z.string().url(),
  NEXT_PUBLIC_POSTHOG_KEY: z.string().min(1).optional(),
  RATE_LIMIT_PER_MINUTE: z.coerce.number().int().positive().default(60),
});

const shape = (EnvSchema as z.ZodObject).shape;
const lines = Object.keys(shape)
  .sort()
  .map((key) =&gt; `${key}=`);

const header = [
  "# Auto-generated. Don't edit by hand.",
  "# Run: pnpm gen:env",
  "",
].join("\n");

writeFileSync(".env.example", header + lines.join("\n") + "\n", "utf8");
console.log(`Wrote .env.example with ${lines.length} keys`);

This isn’t perfect.
I’m duplicating the schema.
I tried to get Claude to “read the TS AST and extract keys”.
Spent 4 hours.
Most of it was wrong.

It kept breaking on:

re-exports
renamed imports
schema composition (merge, extend)

So I stopped.
Duplication is fine if the script is dumb and stable.

I run it whenever I touch env.
Cursor makes it muscle memory because it keeps scripts/ open in the sidebar.

4) I added a CI check that fails fast

Local validation is nice.
CI validation is mandatory.

I want CI to fail with a single readable error.
Not “Next build failed somewhere”.

So I wrote a Node script that:

loads .env locally (only when present)
imports env to trigger Zod parsing
exits non-zero on failure

// scripts/check-env.ts
import "dotenv/config";

async function main() {
  try {
    // Import triggers parsing + validation.
    await import("../src/env");
    console.log("env: OK");
  } catch (err: any) {
    console.error("env: INVALID\n");

    // Zod errors are readable, but nested.
    // Print the message and the cause if present.
    console.error(err?.message ?? err);
    if (err?.cause) console.error("\nCause:\n", err.cause);

    process.exit(1);
  }
}

main();

Then I wire it into package.json.

{
  "scripts": {
    "gen:env": "ts-node scripts/generate-env-example.ts",
    "check:env": "ts-node scripts/check-env.ts",
    "build": "pnpm check:env &amp;&amp; next build"
  }
}

Yes, ts-node in CI can be slow.
Mine adds ~2 seconds.
Worth it.

If you hate ts-node, compile scripts with tsx or plain JS.
I kept it simple.

One more thing that got me.
I once had CI passing but deploy failing.
Because CI had secrets configured, but preview didn’t.

So I now run check:env in preview too.
If the platform supports it, make it part of the build command.

Results

Before this, env bugs were constant.
In April, I hit 9 separate env-related failures across 3 codebases.
I tracked them in a text file because I was annoyed.

After switching to the schema + startup validation + CI check, I hit 1 env failure in the last 14 days.
And that one was legit: I rotated AUTH_SECRET and forgot to update a preview environment.

Time-wise, I stopped losing 30–60 minutes per deploy.
Now it’s a 10-second failure with a clear message.

Key takeaways

Put every env var in one schema file. No scattered process.env.
Validate on server startup, not when a route gets hit.
Generate .env.example from something deterministic. Humans won’t keep it updated.
Make CI run check:env before next build. Fast failure beats log archaeology.
Don’t try to get fancy with AST parsing unless you enjoy pain.

Closing

I’m curious about one specific thing.

Do you prefer strict env validation that fails the build, or do you allow missing optional vars in preview and only enforce them in production?

React Native offline-first: fast set logging UI

Sathish — Wed, 29 Apr 2026 15:00:42 +0000

I stopped blocking the UI on SQLite writes.
I log sets in-memory first, then flush.
I use a tiny write queue + one transaction.
I ship a “pending” state that never lies.

Context

My fitness app has one job during a workout.
Log a set in under 5 seconds.

I started with “just write to SQLite on button tap”.
Brutal.
Every tap waited on IO. Then React re-rendered. Then the list jumped.

Also offline-first means I can’t punt to the server.
SQLite is the source of truth.
But the UI can’t feel like a database client.

So I split it.
UI writes to memory instantly.
SQLite catches up in the background.
If SQLite fails, I show it.
No silent drops.

1) I treat SQLite like a sink, not my UI state

My first version did this:
Tap “+”. Await insert. Then query. Then render.
It “worked”.
It also felt like a 2012 Android app.

Now I keep a local in-memory log.
It’s the thing the list renders.
SQLite is the durable sink.

I model it with a clientId.
Always.
That ID exists before SQLite.
That’s the trick.

// types.ts
export type SetRow = {
  id?: number;              // SQLite row id (after flush)
  clientId: string;         // stable id generated in UI
  workoutId: string;
  exerciseId: string;
  reps: number;
  weight: number;
  createdAt: number;        // ms epoch
  pending: 0 | 1;           // UI + sync status
  error?: string;           // only in memory
};

export const makeClientId = () =&gt; {
  // No deps. Works in Expo.
  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
};

One thing that bit me — I tried to use SQLite autoincrement id as the list key.
That forces you to wait for SQLite.
So you lose.

clientId becomes my React key.
Stable. Instant.

2) I enqueue writes. I don’t `await` them on tap

I keep a queue in memory.
Each tap pushes a “write intent”.
Then a flusher drains the queue.

I spent 4 hours building a generic job queue.
Most of it was wrong.
I don’t need retries with backoff and fancy priorities.
I need “don’t block the UI” and “don’t lose data”.

So it’s small.
A single in-flight promise.

// writeQueue.ts
import * as SQLite from "expo-sqlite";
import type { SetRow } from "./types";

const db = SQLite.openDatabaseSync("gym.db");

type WriteJob = { type: "insertSet"; set: SetRow };

let queue: WriteJob[] = [];
let flushing = false;

export function enqueue(job: WriteJob) {
  queue.push(job);
  void flushSoon();
}

async function flushSoon() {
  if (flushing) return;
  flushing = true;
  try {
    // Drain everything currently queued in one transaction.
    const batch = queue;
    queue = [];

    db.withTransactionSync(() =&gt; {
      for (const job of batch) {
        if (job.type === "insertSet") {
          const s = job.set;
          db.runSync(
            `INSERT INTO sets (client_id, workout_id, exercise_id, reps, weight, created_at, pending)
             VALUES (?, ?, ?, ?, ?, ?, 1)`,
            [s.clientId, s.workoutId, s.exerciseId, s.reps, s.weight, s.createdAt]
          );
        }
      }
    });
  } finally {
    flushing = false;

    // If new jobs arrived during the transaction, flush again.
    if (queue.length) void flushSoon();
  }
}

Yeah, I’m using openDatabaseSync + runSync.
On purpose.

In Expo’s SQLite, the async API still posts work to the native module.
If you await it in the press handler, you’re back to “button feels sticky”.
The win here is: enqueue is instant, flush is decoupled.

Also: one transaction.
That’s the difference between “fine” and “why does it stutter on older phones?”.

3) I render “pending” rows so the UI never lies

Offline-first apps love lying.
They show the new row.
But it never hit disk.
Then you reopen the app. It’s gone.

I make pending visible.
Not with a spinner everywhere.
Just a subtle state.

On tap:

add row to memory with pending: 1
enqueue insert
later, refresh from SQLite and clear pending

This hook is the glue.
It keeps memory fast.
And it reconciles with SQLite.

// useSets.ts
import { useCallback, useMemo, useState } from "react";
import * as SQLite from "expo-sqlite";
import type { SetRow } from "./types";
import { enqueue } from "./writeQueue";
import { makeClientId } from "./types";

const db = SQLite.openDatabaseSync("gym.db");

export function useSets(workoutId: string) {
  const [sets, setSets] = useState([]);

  const reloadFromDb = useCallback(() =&gt; {
    const rows = db.getAllSync&lt;{
      id: number;
      client_id: string;
      workout_id: string;
      exercise_id: string;
      reps: number;
      weight: number;
      created_at: number;
      pending: 0 | 1;
    }&gt;(
      `SELECT id, client_id, workout_id, exercise_id, reps, weight, created_at, pending
       FROM sets
       WHERE workout_id = ?
       ORDER BY created_at ASC`,
      [workoutId]
    );

    setSets(
      rows.map((r) =&gt; ({
        id: r.id,
        clientId: r.client_id,
        workoutId: r.workout_id,
        exerciseId: r.exercise_id,
        reps: r.reps,
        weight: r.weight,
        createdAt: r.created_at,
        pending: r.pending,
      }))
    );
  }, [workoutId]);

  const addSet = useCallback(
    (exerciseId: string, reps: number, weight: number) =&gt; {
      const newSet: SetRow = {
        clientId: makeClientId(),
        workoutId,
        exerciseId,
        reps,
        weight,
        createdAt: Date.now(),
        pending: 1,
      };

      // UI first. Always.
      setSets((prev) =&gt; [...prev, newSet]);

      // SQLite later.
      enqueue({ type: "insertSet", set: newSet });

      // Keep it simple: reload after the flush tick.
      // This avoids needing "returning id" support.
      setTimeout(reloadFromDb, 0);
    },
    [reloadFromDb, workoutId]
  );

  return useMemo(() =&gt; ({ sets, addSet, reloadFromDb }), [sets, addSet, reloadFromDb]);
}

That setTimeout(reloadFromDb, 0) looks dumb.
It is.
It also works.

I originally tried to grab the inserted row id immediately.
Then I hit SQLiteError: cannot commit - no transaction is active while mixing async calls.
I stopped being clever.
Reloading is cheap for one workout.

If you have 2,000 rows in the same screen, you’ll need a smarter reconcile.
But for a workout detail page?
This stays fast.

4) I measure tap-to-render time. Not “feels faster”

My brain lies.
Especially after midnight.

So I put timing directly in the handler.
I log “tap -> next frame”.
If that number spikes, I know I regressed.

// perf.ts
import { InteractionManager } from "react-native";

export function measureTapToFrame(label: string) {
  const t0 = global.performance?.now?.() ?? Date.now();

  // After interactions + next frame.
  InteractionManager.runAfterInteractions(() =&gt; {
    requestAnimationFrame(() =&gt; {
      const t1 = global.performance?.now?.() ?? Date.now();
      const ms = Math.round(t1 - t0);
      console.log(`[perf] ${label}: ${ms}ms`);
    });
  });
}

Then in my button:

call measureTapToFrame("addSet")
call addSet(...)

If I see 180ms, I go hunting.
If I see 22ms, I leave it alone.

The biggest regression I caused?
I added an await in the press handler to “ensure durability”.
Tap-to-frame jumped from 28ms to 146ms on my Pixel 6a.
I reverted it.
Durability moved to the background flush.

Results

The set logging screen stopped stuttering.
That’s the real result.

Before: I logged 10 sets and the UI froze 2–3 times per workout.
My console showed tap-to-frame spikes between 120ms and 210ms.

After: the same flow stays between 18ms and 45ms for tap-to-frame on my Pixel 6a.
I also stopped losing sets when I toggled airplane mode mid-workout, because the UI always marks rows as pending: 1 until SQLite confirms them.

No magic.
Just not blocking the tap.

Key takeaways

Generate a clientId in the UI. Use it as the list key.
Don’t await SQLite in press handlers. Enqueue instead.
Flush in one transaction. Batches beat chatty writes.
Render pending state. Offline-first apps can’t pretend.
Measure tap-to-frame with a real timer. Your gut’s unreliable.

Closing

I’m still not fully happy with the setTimeout(reloadFromDb, 0) reconcile.
It’s simple. It’s also a little sloppy.

If you’re shipping offline-first React Native screens: do you reconcile UI-to-SQLite by requerying, or do you propagate inserted row ids back into memory without a full reload?

Next.js job board: reliable scrapes with leases

Sathish — Tue, 28 Apr 2026 15:00:54 +0000

I stopped double-scraping jobs with a Postgres lease table.
I made cron runs idempotent with a single SQL function.
I got rid of “why is this job missing?” by logging per-source runs.
Works on Next.js 14 + Supabase + Vercel cron.

Context

I’m building a job board for Psychiatric Mental Health Nurse Practitioners.

It scrapes 200+ jobs daily. Multiple sources. Different HTML. Different APIs. The usual pain.

At ~8,000 active listings and ~2,000 companies, one bad cron day hurts. Duplicates show up. Or worse — jobs silently don’t.

My first version was “just run scraping in a cron route.” Brutal.

Vercel cron can overlap. Deploys can overlap. And if a source gets slow, the next run starts anyway. I spent 4 hours “fixing dedupe” and most of it was wrong because the real issue was concurrency.

So I moved coordination into Postgres. Not Redis. Not queues. Just SQL.

1) I stopped trusting cron timing. I added a lease.

Two cron invocations can run at the same minute.

And if you redeploy while a scrape is running? You can get a second run. Same source. Same time window.

I needed a lock. But I also needed it to expire, because scrapers crash.

So: a lease table in Postgres.

-- supabase/migrations/202604280001_scrape_leases.sql

create table if not exists public.scrape_leases (
  source text primary key,
  lease_owner uuid not null,
  lease_until timestamptz not null,
  updated_at timestamptz not null default now()
);

-- Helps cleanup queries and debugging
create index if not exists scrape_leases_until_idx
  on public.scrape_leases (lease_until);

A lease is just “I own scraping source until lease_until”.

No background workers. No magic.

And yeah, I tried pg_advisory_lock first. It works. Then you hit serverless edges and connection pooling weirdness. I wanted something I can inspect with a normal select *.

2) I made the lock acquisition a single SQL function

Doing “select then insert/update” from Node is where race conditions breed.

So I pushed it into a Postgres function.

One round-trip. Atomic.

-- supabase/migrations/202604280002_try_acquire_lease.sql

create or replace function public.try_acquire_scrape_lease(
  p_source text,
  p_owner uuid,
  p_ttl_seconds int
)
returns boolean
language plpgsql
as $$
declare
  v_now timestamptz := now();
  v_until timestamptz := v_now + make_interval(secs =&gt; p_ttl_seconds);
begin
  -- Insert if missing
  insert into public.scrape_leases (source, lease_owner, lease_until, updated_at)
  values (p_source, p_owner, v_until, v_now)
  on conflict (source) do update
    set lease_owner = excluded.lease_owner,
        lease_until = excluded.lease_until,
        updated_at = excluded.updated_at
  where public.scrape_leases.lease_until &lt; v_now
     or public.scrape_leases.lease_owner = p_owner;

  -- If we own it now, we acquired it.
  return exists (
    select 1
    from public.scrape_leases l
    where l.source = p_source
      and l.lease_owner = p_owner
      and l.lease_until &gt;= v_now
  );
end;
$$;

That where lease_until < now() or lease_owner = p_owner line matters.

It lets the same run renew its own lease. But it blocks other runs.

I learned the hard way that “lock once at the start” isn’t enough. A slow source can run longer than your TTL. Then the next cron steals the lease and now two runs are writing.

So I renew.

3) I wired it into a Next.js 14 cron route

This is App Router.

I use a single cron route, and loop sources.

Each source gets a lease owner UUID for that invocation.

// app/api/cron/scrape/route.ts
import { NextResponse } from "next/server";
import { createClient } from "@supabase/supabase-js";
import { randomUUID } from "crypto";

export const runtime = "nodejs";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!,
  { auth: { persistSession: false } }
);

const SOURCES = ["indeed", "ziprecruiter", "hospital_site"] as const;

async function acquire(source: string, owner: string, ttlSeconds: number) {
  const { data, error } = await supabase.rpc("try_acquire_scrape_lease", {
    p_source: source,
    p_owner: owner,
    p_ttl_seconds: ttlSeconds,
  });
  if (error) throw error;
  return Boolean(data);
}

export async function GET(req: Request) {
  const auth = req.headers.get("authorization");
  if (auth !== `Bearer ${process.env.CRON_SECRET}`) {
    return NextResponse.json({ ok: false }, { status: 401 });
  }

  const owner = randomUUID();
  const results: Record = {};

  for (const source of SOURCES) {
    const gotLease = await acquire(source, owner, 8 * 60); // 8 minutes
    if (!gotLease) {
      results[source] = "skipped (lease held)";
      continue;
    }

    // Do the real work.
    // Important: renew inside the scraper for long runs.
    await scrapeSource(source, owner);
    results[source] = "ok";
  }

  return NextResponse.json({ ok: true, owner, results });
}

async function scrapeSource(source: string, owner: string) {
  // placeholder for your per-source scraper.
  // I keep these in /lib/scrapers/*
  await new Promise((r) =&gt; setTimeout(r, 50));

  // Example renewal for long jobs. In real code I do this every ~60s.
  await acquire(source, owner, 8 * 60);
}

This isn’t fancy.

But it stopped the overlap bugs immediately.

Also: don’t forget runtime = "nodejs" if you use crypto.randomUUID().

I hit ReferenceError: crypto is not defined once when I forgot and it ran on edge. Wasted 30 minutes.

4) I logged every run. Because “skipped” isn’t enough.

After I added leases, I still had the “where did the jobs go?” problem.

A source might be skipped for 6 hours because another run grabbed the lease and then crashed before logging anything useful.

So I added a run log table.

One row per source run. Status + counts + error.

-- supabase/migrations/202604280003_scrape_runs.sql

create table if not exists public.scrape_runs (
  id bigserial primary key,
  source text not null,
  owner uuid not null,
  started_at timestamptz not null default now(),
  finished_at timestamptz,
  status text not null default 'running', -- running|ok|error|skipped
  fetched_count int not null default 0,
  upserted_count int not null default 0,
  error text
);

create index if not exists scrape_runs_source_started_idx
  on public.scrape_runs (source, started_at desc);

And in the route, I insert/update around the scrape.

// lib/scrapeRunLog.ts
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!,
  { auth: { persistSession: false } }
);

export async function startRun(source: string, owner: string) {
  const { data, error } = await supabase
    .from("scrape_runs")
    .insert({ source, owner, status: "running" })
    .select("id")
    .single();
  if (error) throw error;
  return data.id as number;
}

export async function finishRun(params: {
  id: number;
  status: "ok" | "error" | "skipped";
  fetchedCount?: number;
  upsertedCount?: number;
  errorText?: string;
}) {
  const { error } = await supabase
    .from("scrape_runs")
    .update({
      status: params.status,
      fetched_count: params.fetchedCount ?? 0,
      upserted_count: params.upsertedCount ?? 0,
      error: params.errorText ?? null,
      finished_at: new Date().toISOString(),
    })
    .eq("id", params.id);
  if (error) throw error;
}

Now when I wake up and something’s off, I query:

last run per source
last error text
“skipped” streaks

It’s boring. It’s also the difference between guessing and knowing.

Results

Before leases, I saw overlapping runs a few times a week. Real duplicates. Not just “same job from two sources” duplicates — literal same source, same job, inserted twice because two scrapers ran concurrently.

After shipping the lease + run log, the cron route ran 96 times over 48 hours (every 30 minutes). 0 overlaps per source. 0 double inserts from concurrency.

I also got faster debugging. When a source started failing, I had the last 10 error strings in scrape_runs instead of scanning Vercel logs for “Error: socket hang up”.

The board stayed steady at 8,000+ active listings without surprise spikes.

Key takeaways

Don’t coordinate scrapes in Node. Coordinate in Postgres.
Use a lease with TTL. Scrapers crash.
Make lease acquisition one SQL function. One round-trip. Atomic.
Renew leases during long scrapes, not just at the start.
Log every source run with counts + error text, or you’ll debug from vibes.

Closing

If you’re scraping multiple sources, concurrency bugs show up late — right when you’ve got enough data that cleaning it is miserable.

Do you prefer Postgres leases like this, or do you use advisory locks (pg_advisory_lock) for cron coordination in serverless environments?

Cursor + Claude: stop shipping flaky API clients

Sathish — Thu, 23 Apr 2026 15:00:52 +0000

I generate a typed API client from an OpenAPI file.
I run contract tests locally with zero servers.
I make Cursor fix only what the tests prove.
I ship fewer “it works on my laptop” bugs.

Context

I build small SaaS projects. Usually solo. Usually fast.

My most common failure mode isn’t UI. It’s the boring glue code between frontend and backend.

I’d tweak an endpoint. Rename a field. Change a status code. Then ship.

Next day: runtime errors. Cannot read properties of undefined. Or worse. Silent wrong data.

Manual testing didn’t catch it. Postman collections drifted. And “just write types” didn’t help when my types were lying.

So I pushed my API boundary into something I can diff and test: OpenAPI + generated client + contract tests. Cursor + Claude help a lot here, but only when I force them to work against failing tests.

1) I start with a real contract. Not vibes.

I keep a single openapi.json in my repo.

Not perfect. Still worth it.

The point: my client types come from the contract, not from whatever I remembered last night.

Here’s a minimal OpenAPI snippet that already saves me from dumb mistakes (wrong path params, wrong response shapes).

{
  "openapi": "3.0.3",
  "info": { "title": "Example API", "version": "1.0.0" },
  "paths": {
    "/v1/jobs/{id}": {
      "get": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["id", "title"],
                  "properties": {
                    "id": { "type": "string" },
                    "title": { "type": "string" },
                    "salary": { "type": "integer", "nullable": true }
                  }
                }
              }
            }
          },
          "404": { "description": "Not found" }
        }
      }
    }
  }
}

I learned the hard way that “nullable” matters.

Without it, I’d treat salary: null as a bug and add weird defaulting logic. Then I’d hide real missing data.

2) I generate the client. Then I stop hand-writing fetch.

I used to write wrappers like getJob(id) with fetch() everywhere.

Brutal to keep consistent.

Now I generate.

I use openapi-typescript for types. And openapi-fetch for a tiny client. Both are boring. That’s why I like them.

# install
npm i -D openapi-typescript
npm i openapi-fetch

# generate types
npx openapi-typescript ./openapi.json -o ./src/api/schema.d.ts

Then I create a single client file.

// src/api/client.ts
import createClient from "openapi-fetch";
import type { paths } from "./schema";

// One client. One baseUrl.
// In Next.js I set NEXT_PUBLIC_API_BASE_URL.
const baseUrl = process.env.NEXT_PUBLIC_API_BASE_URL ?? "http://localhost:3000";

export const api = createClient({
  baseUrl,
  headers: {
    "content-type": "application/json"
  }
});

And I call it like this:

// src/api/jobs.ts
import { api } from "./client";

export async function getJob(id: string) {
  const { data, error, response } = await api.GET("/v1/jobs/{id}", {
    params: { path: { id } }
  });

  if (response.status === 404) return null;
  if (error) throw new Error(JSON.stringify(error));

  // data is typed from OpenAPI
  return data;
}

This kills a whole category of bugs.

No more fetch('/v1/jobs/' + id) missing a slash. No more “was it jobId or id?” arguments.

Cursor helps here. A lot.

But I don’t let it “design” my API calls. I paste the OpenAPI path and tell it: “Use the generated client. No raw fetch.” It’ll still try to sneak in raw fetch sometimes. I delete it. Every time.

3) I write contract tests with a fake server. Zero Docker.

I want a test that fails if:

the client assumes the wrong status code
the response body shape changes
the client forgets to handle 404

I don’t want to spin up my whole backend.

So I mock at the HTTP layer using msw (Mock Service Worker) in Node mode.

This is where Claude is useful. It writes the handlers fast. And I can focus on the assertions.

// test/msw.ts
import { setupServer } from "msw/node";
import { http, HttpResponse } from "msw";

export const server = setupServer(
  http.get("http://localhost:3000/v1/jobs/:id", ({ params }) => {
    const id = String(params.id);

    if (id === "missing") {
      return new HttpResponse(null, { status: 404 });
    }

    return HttpResponse.json({
      id,
      title: "Data Engineer",
      salary: null
    });
  })
);

And the test itself.

// test/jobs.test.ts
import { beforeAll, afterAll, afterEach, test, expect } from "vitest";
import { server } from "./msw";
import { getJob } from "../src/api/jobs";

beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

test("getJob returns typed data", async () => {
  process.env.NEXT_PUBLIC_API_BASE_URL = "http://localhost:3000";

  const job = await getJob("123");

  expect(job?.id).toBe("123");
  expect(job?.title).toBe("Data Engineer");
  expect(job?.salary).toBe(null);
});

test("getJob returns null on 404", async () => {
  process.env.NEXT_PUBLIC_API_BASE_URL = "http://localhost:3000";

  const job = await getJob("missing");
  expect(job).toBe(null);
});

Yes, I set env vars inside tests. It’s not pretty.

But it’s deterministic. And it keeps my client code clean.

Also: onUnhandledRequest: "error" is everything.

Without it, MSW will quietly let real network calls through. Then your test “passes” while hitting your actual dev server. Ask me how I know. Spent 4 hours on that. Most of it was wrong.

4) I only let Cursor touch code when a test fails

This is the workflow change.

Not a tool change.

I do this loop:

Change OpenAPI spec.
Regenerate types.
Run tests.
If tests fail, I paste the failing output into Cursor chat.
I ask for the smallest diff that makes tests pass.

Example failure I hit a lot:

I change a field from salary to salaryUsd in the spec.
Generated types update.
UI code still reads job.salary.

TypeScript catches some of it. But not all.

So I add one more test. A tiny runtime assertion that matches what the UI expects.

// src/api/assert.ts
export function assertHasTitle(x: unknown): asserts x is { title: string } {
  if (!x || typeof x !== "object") throw new Error("Expected object");

  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const anyX = x as any;

  if (typeof anyX.title !== "string") {
    throw new Error("Expected title:string");
  }
}

Then in a component or loader:

// src/app/job/[id]/loader.ts
import { getJob } from "@/api/jobs";
import { assertHasTitle } from "@/api/assert";

export async function loadJob(id: string) {
  const job = await getJob(id);
  if (!job) return null;

  // Runtime guard for UI assumptions
  assertHasTitle(job);
  return job;
}

Now when the contract changes, something screams early.

And Cursor becomes a mechanic, not a novelist.

I’ll literally write: “Fix loadJob and getJob to satisfy assertHasTitle and tests. Don’t change the tests.”

It works.

Results

I used to ship API mismatches weekly. Like clockwork.

In the last 14 days, I hit 11 contract breaks while refactoring endpoints (wrong field name, wrong nullable handling, missing 404 branch). All 11 got caught by local tests before I pushed.

Before this setup, those 11 would’ve made it to runtime. At least 7 would’ve hit a real user flow. And 3 would’ve been silent wrong-data bugs.

The best part: I can change APIs faster now, because I’m not scared of the blast radius.

Key takeaways

Put your API contract in a file and diff it like code.
Generate the client. Don’t hand-roll fetch wrappers.
Use msw with onUnhandledRequest: "error" or you’ll lie to yourself.
Add one or two runtime assertions for UI assumptions. Types don’t cover everything.
With Cursor + Claude, always drive from failing tests. No exceptions.

Closing

If you already generate clients, you’re ahead.

But I’m curious about the testing part.

Do you run contract tests against a mocked HTTP layer (MSW), or do you spin up the real API in CI and hit it for real?

React Native offline-first: 5s logging with SQLite

Sathish — Wed, 22 Apr 2026 15:00:54 +0000

Keep “5-second set logging” fast, offline.
Use SQLite transactions + a tiny write queue.
Optimistic UI with a rollback path.
One schema trick that cut my writes in half.

Context

I’m building a fitness app. React Native + Expo. SQLite for local storage. Offline-first because gyms have garbage reception.

The core interaction is set logging. Tap weight, tap reps, hit save. Done. If that takes more than a couple seconds, people stop using it.

My first attempt was “just write to SQLite on every tap”. Brutal. UI jank. And I hit a fun Expo SQLite error mid-set: database is locked.

So I rebuilt the flow around one rule.

UI updates instantly. Writes happen in order. In a single transaction. Always.

1) I split “what the user sees” from “what I persist”

I keep a local in-memory row for the current set. That’s what the UI binds to.

Then I persist only on “Save set”. Not on every tap.

This sounds obvious. I still got it wrong at first.

I was persisting weight and reps separately. Two writes per set. Sometimes three. When you’re logging 18 sets, that’s a lot of churn.

So I made a single set_events row. One insert. Append-only.

-- schema.sql
-- One row per completed set. Append-only.
-- I don't update rows during a workout.

PRAGMA foreign_keys = ON;

CREATE TABLE IF NOT EXISTS workouts (
  id TEXT PRIMARY KEY,
  started_at INTEGER NOT NULL,
  ended_at INTEGER
);

CREATE TABLE IF NOT EXISTS set_events (
  id TEXT PRIMARY KEY,
  workout_id TEXT NOT NULL,
  exercise_id TEXT NOT NULL,
  set_index INTEGER NOT NULL,
  weight_kg REAL NOT NULL,
  reps INTEGER NOT NULL,
  created_at INTEGER NOT NULL,
  dirty INTEGER NOT NULL DEFAULT 1,
  FOREIGN KEY (workout_id) REFERENCES workouts(id) ON DELETE CASCADE
);

CREATE INDEX IF NOT EXISTS idx_set_events_workout
ON set_events(workout_id, created_at);

Append-only means fewer locks. Fewer “oops I updated the wrong row”. And sync later is simpler because every set is an event.

One thing that bit me — REAL for weight is fine, but don’t store 0.1 plates and expect perfect math. I store what the user typed. I don’t sum floats for anything critical.

2) I serialize writes. Because SQLite will.

Expo SQLite is fast. But it’s still SQLite. One writer at a time.

My bug was multiple async writes from different components.

Set screen saving.
Workout timer updating.
Background sync marking rows clean.

Sometimes they overlap. Then SQLite throws database is locked.

So I added a tiny write queue. Single concurrency. No fancy library.

// db/writeQueue.ts
import * as SQLite from 'expo-sqlite';

const db = SQLite.openDatabaseSync('gym.db');

let chain = Promise.resolve();

// Ensures all writes run sequentially.
export function enqueueWrite(fn: (db: SQLite.SQLiteDatabase) => Promise): Promise {
  const run = chain.then(() => fn(db));
  // Keep the chain alive even if a write fails.
  chain = run.then(() => undefined, () => undefined);
  return run;
}

export async function withTx(fn: (tx: SQLite.SQLiteDatabase) => Promise) {
  return enqueueWrite(async (db) => {
    await db.execAsync('BEGIN IMMEDIATE');
    try {
      const res = await fn(db);
      await db.execAsync('COMMIT');
      return res;
    } catch (e) {
      await db.execAsync('ROLLBACK');
      throw e;
    }
  });
}

BEGIN IMMEDIATE is intentional.

It grabs the write lock early. If it can’t, I’d rather fail fast than stall the UI for 900ms mid-set.

And yeah, I spent 4 hours “fixing” this by sprinkling await everywhere. Most of it was wrong.

3) I do optimistic UI. But I keep a rollback key.

If the UI waits for SQLite, it feels broken.

So when the user hits “Save set”, I immediately append a set to the UI list.

Then I persist in the background. If it fails, I remove that optimistic item and show an error.

I don’t love rollback UX. But it happens rarely, and it beats lag.

// features/sets/saveSet.ts
import { randomUUID } from 'expo-crypto';
import { withTx } from '../../db/writeQueue';

export type SetEvent = {
  id: string;
  workoutId: string;
  exerciseId: string;
  setIndex: number;
  weightKg: number;
  reps: number;
  createdAt: number;
  optimistic?: boolean;
};

export async function saveSetEvent(input: Omit) {
  const id = randomUUID();
  const createdAt = Date.now();

  await withTx(async (db) => {
    await db.runAsync(
      `INSERT INTO set_events
       (id, workout_id, exercise_id, set_index, weight_kg, reps, created_at, dirty)
       VALUES (?, ?, ?, ?, ?, ?, ?, 1)`,
      [id, input.workoutId, input.exerciseId, input.setIndex, input.weightKg, input.reps, createdAt]
    );
  });

  return { id, createdAt };
}

In the component, I keep two operations:

addOptimisticSet(set)
replaceOptimisticId(tempId, realId) or removeOptimistic(tempId)

I’m not pasting my whole Zustand store here. The pattern matters more than my state shape.

Also: don’t generate ids with Math.random().

I did. Sync conflicts were hilarious. Not in a good way.

4) I batch “workout screen” queries so the UI stays snappy

Another mistake.

I was querying the DB after every save to rebuild the whole list.

That’s safe. It’s also slow.

Now I do this:

UI list updates from memory.
DB query runs on screen focus, and on app resume.

And the query is one select. Not N selects.

// features/workouts/getWorkoutSets.ts
import * as SQLite from 'expo-sqlite';

const db = SQLite.openDatabaseSync('gym.db');

export type DbSetRow = {
  id: string;
  exercise_id: string;
  set_index: number;
  weight_kg: number;
  reps: number;
  created_at: number;
};

export async function getWorkoutSets(workoutId: string) {
  // One query. Ordered for rendering.
  const rows = await db.getAllAsync(
    `SELECT id, exercise_id, set_index, weight_kg, reps, created_at
     FROM set_events
     WHERE workout_id = ?
     ORDER BY created_at ASC`,
    [workoutId]
  );

  return rows;
}

This keeps “Save set” lightweight.

The screen still stays correct because I refresh on focus/resume. And because the app is offline-first, I assume the DB is the source of truth eventually — just not for every single tap.

One more thing that saved me.

I stopped doing setState([...sets, newSet]) in a loop. I use functional updates. Otherwise React drops frames when the list is long.

Results

On my Android test device (Pixel 6a), I timed set logging with performance.now() around the Save press.

Before: median 620ms from tap to UI update, with random spikes around 1,900ms when the app was also syncing.

After the write queue + optimistic UI: median 38ms to UI update, and I couldn’t reproduce the spikes. The SQLite write still takes time (usually 12–40ms), but it’s off the critical path.

The database is locked error went from “every gym session” to 0 times in 9 sessions.

Key takeaways

Don’t persist every tap. Persist completed actions.
SQLite wants one writer. Give it one.
Append-only tables make offline sync calmer.
Optimistic UI is fine if you can rollback.
Refresh from DB on focus/resume, not constantly.

Closing

If you’re doing offline-first in React Native: do you serialize SQLite writes with a queue like this, or do you rely on a library to manage write concurrency for you?

Next.js job board: zero-downtime schema changes

Sathish — Tue, 21 Apr 2026 15:01:09 +0000

I stopped breaking my job board during migrations.
I run Postgres changes as additive-only, then backfill.
I version my Next.js + Supabase queries to survive both schemas.
I ship a migration checklist that catches the dumb stuff.

Context

I’m building a job board for Psychiatric Mental Health Nurse Practitioners.

It’s Next.js 14 (App Router) on Vercel. Supabase + Postgres behind it.

The data’s not small. 8,000+ active listings. 2,000+ companies. I scrape 200+ jobs daily.

And I kept doing the same dumb thing.

I’d change a column. Deploy. Then pages 500 because one query still expected the old schema. Brutal.

So I switched to a boring rule: schema changes must be zero-downtime. Additive first. Backfill second. Cutover last.

This is the exact pattern I’m using now.

1) I treat migrations like deploys. Because they are.

I don’t run manual SQL in the dashboard anymore.

I did that for weeks. It worked. Until it didn’t.

Now every change is a migration file. Even “tiny” ones.

I keep them in supabase/migrations/ and run them locally with the Supabase CLI. Same SQL in CI. Same SQL in prod.

Here’s a real example: adding a salary_min / salary_max pair to my jobs table without breaking old code.

-- supabase/migrations/202604210901_add_salary_range.sql
-- Additive-only. No renames. No drops.

alter table public.jobs
  add column if not exists salary_min integer,
  add column if not exists salary_max integer;

-- Keep reads fast. I filter on salary_min a lot.
create index if not exists jobs_salary_min_idx
  on public.jobs (salary_min);

-- Safety: prevent negative values.
alter table public.jobs
  add constraint jobs_salary_min_nonneg check (salary_min is null or salary_min >= 0);

alter table public.jobs
  add constraint jobs_salary_max_nonneg check (salary_max is null or salary_max >= 0);

That migration never breaks old code.

Old queries don’t select those columns. Old inserts don’t send them. Postgres fills nulls.

What used to break me was doing the opposite.

Renaming columns mid-flight. Dropping columns “because I’m done with them.” Then Next.js server components explode at runtime.

2) I backfill in small chunks. Not one giant UPDATE.

Backfills are where I used to time out.

I’d run a single update jobs set ... across thousands of rows.

It worked locally. Then in prod, it locked rows long enough to make my API feel flaky.

Now I backfill in chunks. With a loop. With sleep.

I run this as a one-off Node script (locally, pointed at prod), or as a manual GitHub Actions job.

// scripts/backfill-salary-range.ts
// Run: node scripts/backfill-salary-range.ts

import 'dotenv/config'
import { createClient } from '@supabase/supabase-js'

const url = process.env.SUPABASE_URL!
const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY!

const supabase = createClient(url, serviceKey, {
  auth: { persistSession: false },
})

const BATCH = 250

async function main() {
  let offset = 0

  while (true) {
    // Pull a stable slice. Order by id so offset is predictable.
    const { data: rows, error } = await supabase
      .from('jobs')
      .select('id, salary_text') // salary_text = scraped string like "$140k-$180k" or "Up to $160,000"
      .order('id', { ascending: true })
      .range(offset, offset + BATCH - 1)

    if (error) throw error
    if (!rows?.length) break

    const updates = rows
      .map((r) => {
        const { min, max } = parseSalary(r.salary_text ?? '')
        if (min === null && max === null) return null
        return { id: r.id, salary_min: min, salary_max: max }
      })
      .filter(Boolean) as Array<{ id: string; salary_min: number | null; salary_max: number | null }>

    if (updates.length) {
      // Upsert by primary key. Only touches rows in this batch.
      const { error: upsertError } = await supabase
        .from('jobs')
        .upsert(updates, { onConflict: 'id' })

      if (upsertError) throw upsertError
    }

    offset += BATCH
    await sleep(200) // small pause. Keeps load sane.
  }
}

function parseSalary(input: string): { min: number | null; max: number | null } {
  // Cheap parser. Works for my scraped sources.
  // Examples: "$140k-$180k", "Up to $160,000", "$120,000 - $150,000/year"
  const s = input.toLowerCase().replace(/,/g, '')

  const upTo = s.match(/up to\s*\$?(\d+(?:\.\d+)?)\s*(k)?/)
  if (upTo) {
    const n = toNumber(upTo[1], upTo[2] === 'k')
    return { min: null, max: n }
  }

  const range = s.match(/\$?(\d+(?:\.\d+)?)\s*(k)?\s*[-–]\s*\$?(\d+(?:\.\d+)?)\s*(k)?/)
  if (range) {
    const min = toNumber(range[1], range[2] === 'k')
    const max = toNumber(range[3], range[4] === 'k')
    return { min, max }
  }

  return { min: null, max: null }
}

function toNumber(n: string, isK: boolean): number {
  const v = Math.round(Number(n) * (isK ? 1000 : 1))
  return Number.isFinite(v) ? v : 0
}

function sleep(ms: number) {
  return new Promise((r) => setTimeout(r, ms))
}

main().catch((e) => {
  console.error(e)
  process.exit(1)
})

This isn’t fancy.

But it avoids long locks, keeps the site responsive, and gives me a place to log weird rows.

One thing that bit me — range(offset, ...) gets slower as offset grows.

If you have millions of rows, switch to keyset pagination (where id > lastId). I’m not there yet.

3) I ship code that can read both schemas

This is the part I skipped before.

I’d add columns. Then immediately refactor the UI to assume they exist.

That’s how you get the classic production error:

column jobs.salary_min does not exist

It happens when:

Vercel deploy hits before migration ran
or you have multiple environments and one lags

So I write the query to tolerate missing fields.

In practice: I select the new columns, but I don’t require them.

// app/jobs/[slug]/page.tsx
// Server Component. Reads from Supabase.

import { createClient } from '@supabase/supabase-js'
import { notFound } from 'next/navigation'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!,
)

type JobRow = {
  id: string
  title: string
  company_name: string
  salary_text: string | null
  // New columns. Nullable. Might not exist in older envs.
  salary_min?: number | null
  salary_max?: number | null
}

export default async function JobPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params

  // Keep select list explicit. Avoid "select('*')" drift.
  const { data, error } = await supabase
    .from('jobs')
    .select('id,title,company_name,salary_text,salary_min,salary_max')
    .eq('slug', slug)
    .maybeSingle()

  // If the new columns aren't deployed yet, Supabase will error.
  // I fall back to an old select list.
  if (error && /salary_(min|max)/.test(error.message)) {
    const fallback = await supabase
      .from('jobs')
      .select('id,title,company_name,salary_text')
      .eq('slug', slug)
      .maybeSingle()

    if (fallback.error || !fallback.data) notFound()
    return 
  }

  if (error || !data) notFound()
  return 
}

function JobView({ job }: { job: JobRow }) {
  const salary =
    job.salary_min || job.salary_max
      ? `${job.salary_min ?? '—'} to ${job.salary_max ?? '—'}`
      : job.salary_text ?? '—'

  return (

      # {job.title}

      {job.company_name}

      Salary: {salary}


  )
}

Yeah, it’s extra code.

But it lets me deploy UI first or DB first. Either order. No downtime.

Once the migration is everywhere, I delete the fallback.

I actually track that cleanup as a task. Otherwise the fallback lives forever.

4) I don’t drop columns until I’ve proven nothing reads them

Dropping columns is where you discover all your hidden dependencies.

Old scripts. Admin pages. A random cron route you forgot.

So I do a “soft deprecation” first.

Step 1: stop writing the old column.

Step 2: keep reading it for a week.

Step 3: add a DB trigger that screams if something still writes it.

Here’s the trigger pattern. It saved me twice.

-- Run after you've switched your app to stop writing old_salary_text
-- This throws if any insert/update still touches it.

create or replace function public.block_old_salary_writes()
returns trigger
language plpgsql
as $$
begin
  if new.old_salary_text is distinct from old.old_salary_text then
    raise exception 'old_salary_text is deprecated; stop writing it';
  end if;
  return new;
end;
$$;

drop trigger if exists trg_block_old_salary_writes on public.jobs;

create trigger trg_block_old_salary_writes
before update on public.jobs
for each row
execute function public.block_old_salary_writes();

The first time I ran this, it immediately threw.

The culprit was a scrape normalization step I forgot existed.

Spent 4 hours chasing “why are job inserts failing?”

Most of it was wrong.

But after I fixed it, I finally trusted that I could remove the column.

Results

I used this approach while expanding my jobs schema (salary range + a couple metadata fields) on a dataset with 8,000+ active listings and 2,000+ companies.

Before, a schema change usually caused at least 1 broken deploy per week. That meant real 500s on job detail pages until I reverted.

After switching to additive migrations + chunked backfills + dual-schema reads, I did 6 migrations in 9 days with 0 production rollbacks. The scraper kept ingesting 200+ jobs daily the whole time.

No heroics. Just fewer self-inflicted outages.

Key takeaways

Add columns first. Always. Renames are downtime in disguise.
Backfill in chunks with pauses. Your DB will thank you.
Never select('*') on a job board schema. You’ll regret it.
Ship UI that survives both schemas, then delete the fallback.
Before dropping anything, block writes with a trigger and see what breaks.

Closing

Schema changes used to scare me more than scraping.

Now it’s a checklist and a couple scripts.

If you’re running Next.js + Supabase in production, you’re one “rename column” away from a bad night.

Do you handle schema cutovers by deploying DB-first, app-first, or do you build dual-schema reads like I do?

Cursor + Claude: a repeatable refactor workflow

Sathish — Thu, 16 Apr 2026 15:01:23 +0000

I refactor with Cursor + Claude using a strict, diff-first loop.
I add a “tripwire” test first, so AI can’t lie.
I use one script to block dead imports + circular deps.
I ship smaller PRs by slicing refactors into phases.

Context

I build small SaaS apps. Usually solo. Usually fast.

Refactors are where I lose time. Not feature work. Refactors.

The failure mode is always the same. I ask an AI to “clean up” a folder. It touches 23 files. Tests still pass. Then I hit runtime and get TypeError: Cannot read properties of undefined. Brutal.

So I stopped doing vibe refactors.

Now I do repeatable refactors. Boring ones. With tripwires. With diffs I can actually review. Cursor + Claude still helps a lot. But only inside a tight workflow.

1) I write a tripwire test first. Always.

If I can’t prove behavior, I can’t refactor.

I don’t mean “increase coverage.” I mean a single test that fails loudly if I break the contract.

Most of my refactors are around data-shape drift. Objects coming from APIs. DB rows. JSON blobs. The tripwire is usually “given input X, output must be Y.”

Here’s a tiny example. A toUserDTO() function. I’ve broken this exact thing by renaming fields during a refactor.

// user.mapper.ts
export type UserRow = {
  id: string;
  email: string;
  created_at: string; // ISO
};

export type UserDTO = {
  id: string;
  email: string;
  createdAt: string;
};

export function toUserDTO(row: UserRow): UserDTO {
  // Keep mapping explicit. Avoid spreading unknown fields.
  return {
    id: row.id,
    email: row.email,
    createdAt: row.created_at,
  };
}

// user.mapper.test.ts
import { describe, expect, it } from "vitest";
import { toUserDTO } from "./user.mapper";

describe("toUserDTO", () => {
  it("maps snake_case to camelCase without changing values", () => {
    const dto = toUserDTO({
      id: "u_123",
      email: "a@b.com",
      created_at: "2026-04-16T10:11:12.000Z",
    });

    expect(dto).toEqual({
      id: "u_123",
      email: "a@b.com",
      createdAt: "2026-04-16T10:11:12.000Z",
    });
  });
});

Now the AI can refactor structure. Rename files. Extract helpers.

But it can’t “accidentally” change behavior without me noticing. The test becomes a landmine.

One thing that bit me — I used to ask Claude to “improve the test” too. Don’t. The test is the contract. Lock it.

2) I force Cursor to work in small, named phases

Big refactors fail because the AI loses the plot.

Cursor will happily apply a sweeping edit across a repo. Then you’re stuck reviewing 600 lines of diff with your brain half off.

My fix is dumb. I name phases and I don’t let the AI cross them.

Phase examples:

Phase A: move files, keep exports identical
Phase B: replace barrel exports
Phase C: delete dead code

I also keep a “refactor plan” file in the repo while I’m working. Not forever. Just during the refactor. Cursor’s context gets better, and I stop re-explaining myself.

<!-- REFACTOR_PLAN.md -->
# Refactor: src/lib -> src/core

## Phase A (no behavior changes)
- Move files under src/core
- Keep public exports identical
- Add temp re-exports to avoid breaking imports

## Phase B
- Update internal imports to new paths
- Remove temp re-exports

## Phase C
- Delete dead files
- Run typecheck + tests

## Non-goals
- No renaming DTO fields
- No changing runtime behavior

Then I prompt like this (inside Cursor):

“Do Phase A only. Don’t touch behavior. Keep exports identical. Update REFACTOR_PLAN.md checkbox when done.”

It sounds silly.

It works because I can review Phase A diffs quickly. Mostly file moves and export shims. If it breaks, it breaks in a small surface area.

And yeah — I’ve spent 4 hours on a refactor where I skipped this. Most of it was wrong.

3) I block dead imports and circular deps with one script

The most common refactor breakage I ship is import rot.

Stuff like:

a file moved but an old path still compiles somewhere
a circular dependency introduced by a new index.ts
a barrel export that re-exports server-only code into the client bundle

TypeScript won’t always save you. Especially with path aliases, dynamic imports, or unused exports.

So I run a dependency check script locally before I even open a PR.

This uses dependency-cruiser. It’s not perfect. But it catches the dumb stuff.

# install
npm i -D dependency-cruiser

// scripts/depcheck.mjs
import { cruise } from "dependency-cruiser";

const result = await cruise(["src"], {
  // Keep it strict. Refactors are when this matters.
  ruleSet: {
    forbidden: [
      {
        name: "no-circular",
        severity: "error",
        from: {},
        to: { circular: true },
      },
      {
        name: "no-orphans",
        severity: "warn",
        from: { orphan: true },
        to: {},
      },
      {
        name: "no-deprecated-core",
        severity: "error",
        from: { path: "^src/" },
        to: { path: "^src/legacy/" },
      },
    ],
  },

  // Make output readable in CI logs.
  outputType: "err",
  validate: true,
});

if (result.output?.trim()) {
  console.error(result.output);
  process.exit(1);
}

console.log("depcheck: ok");

// package.json
{
  "scripts": {
    "depcheck": "node scripts/depcheck.mjs"
  }
}

This catches cycles like:

src/core/index.ts -> src/core/http.ts -> src/core/index.ts

And orphans like:

src/utils/oldThing.ts that nobody imports anymore

Cursor + Claude helps here too. When depcheck fails, I paste the exact error output and ask for the smallest fix.

Smallest. Fix.

Not “refactor the architecture.”

4) I do diff reviews like a paranoid person

AI makes code changes fast. Reviewing is the bottleneck.

So I changed how I review.

Rules I follow:

I don’t review by file tree. I review by diff chunks.
I search the diff for export * from and index.ts. Every time.
I grep for any and as unknown as. If those appear during a refactor, something’s off.

This is my local helper script. It’s basic. It saves me from myself.

# scripts/refactor-review.sh
set -euo pipefail

# 1) Show summary first.
git status --porcelain

echo "\n--- DIFF STATS ---"
git diff --stat

echo "\n--- BARRELS / RE-EXPORTS ---"
# Find new/changed barrel exports in the diff
# (works even if ripgrep isn't installed)
git diff | grep -E "^\+.*export \* from|^\+.*from \"\.\/index\"" || true

echo "\n--- TYPE ESCAPES ---"
# Catch common 'make TS shut up' edits
# These are sometimes legit. Often they're hiding a broken import.
git diff | grep -E "^\+.*\bany\b|^\+.*as unknown as" || true

echo "\n--- DONE ---"

Run it:

bash scripts/refactor-review.sh

When that script prints anything under “TYPE ESCAPES”, I stop. I go fix the root cause.

Because the root cause is usually: I moved a file, broke an import, and the AI patched it with a cast.

That’s not a fix. That’s debt.

Results

My refactors got smaller.

Before this workflow, a “cleanup” often turned into 20 to 40 files changed in one sitting, with at least 1 runtime-only bug that I’d catch after deploying to preview.

This week, I did 3 refactor batches. Each stayed under 12 files changed. I hit npm run depcheck 9 times total and it caught 2 circular dependencies and 6 orphan files before they hit git history.

The bigger win: review time. I went from staring at diffs for ~45 minutes per refactor to ~15 minutes, because the changes were phased and the tripwire test stayed stable.

Key takeaways

Write one tripwire test before touching structure.
Refactor in named phases. Cursor needs boundaries.
Add a dependency check script. Run it a lot.
Treat any and double-casts as refactor smoke.
Keep exports boring until the very end.

Closing

Cursor + Claude can refactor fast. That’s the easy part.

The hard part is keeping refactors reviewable and reversible, especially when you’re solo and nobody’s catching your mistakes.

What’s your current “tripwire” for refactors — a specific test, a script like depcheck, or something else you run every single time?

React Native offline-first: SQLite schema for speed

Sathish — Wed, 15 Apr 2026 15:00:47 +0000

I model workouts as “events”, not nested JSON.
I use SQLite indexes that match my screens.
I store local-only IDs + sync state cleanly.
I hit sub-100ms reads on a mid phone.

Context

My fitness app has one job.
Log a set in ~5 seconds.

Offline-first forced my hand.
I can’t rely on network.
I can’t rely on a giant in-memory object either.
I tried the “store the whole workout as JSON” approach first.
Brutal.
It made edits painful, queries slow, and sync a mess.

So I went boring.
SQLite.
Not as a cache.
As the source of truth.

This post is just one angle.
Schema.
Tables, indexes, and the queries that map to screens.

1) I store sets as append-only events

I stopped thinking in “workout objects”.
I started thinking in “things that happened”.

A set logged is an event.
Editing a set is another event.
Deleting is another event.
Later, I can compact.
But day-to-day? Append-only wins.

It fixed two annoying problems.
Undo becomes easy.
Sync conflicts get smaller.

Here’s the schema I’m using in Expo SQLite.
It’s not fancy.
But it’s stable.

-- 001_init.sql
PRAGMA foreign_keys = ON;

CREATE TABLE IF NOT EXISTS workouts (
  id TEXT PRIMARY KEY,              -- UUID (client-generated)
  started_at INTEGER NOT NULL,       -- epoch ms
  ended_at INTEGER,                 -- epoch ms
  title TEXT,
  note TEXT,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL
);

CREATE TABLE IF NOT EXISTS set_events (
  id TEXT PRIMARY KEY,              -- UUID
  workout_id TEXT NOT NULL,
  exercise_id TEXT NOT NULL,
  set_index INTEGER NOT NULL,        -- position within exercise in that workout
  kind TEXT NOT NULL,               -- 'LOG' | 'EDIT' | 'DELETE'
  reps INTEGER,
  weight_kg REAL,
  rir INTEGER,                       -- reps in reserve
  happened_at INTEGER NOT NULL,      -- epoch ms
  device_seq INTEGER NOT NULL,       -- monotonic per device
  dirty INTEGER NOT NULL DEFAULT 1,  -- 1 = needs sync
  server_rev INTEGER NOT NULL DEFAULT 0,
  FOREIGN KEY (workout_id) REFERENCES workouts(id) ON DELETE CASCADE
);

-- The screen query: "latest state per set" needs this.
CREATE INDEX IF NOT EXISTS idx_set_events_workout_exercise
  ON set_events(workout_id, exercise_id, set_index, happened_at DESC);

-- Sync query: "give me dirty events in order" needs this.
CREATE INDEX IF NOT EXISTS idx_set_events_dirty_seq
  ON set_events(dirty, device_seq);

I learned the hard way that device_seq matters.
I originally sorted by happened_at.
Two events in the same millisecond.
Same phone.
Same JS tick.
Order flipped once.
I stared at a “ghost delete” for 4 hours.
Most of it was wrong.

Now I do device_seq.
Just an integer I increment locally.

2) I index for the UI I actually have

SQLite is fast.
But “fast” disappears when you make it guess.

My app has three hot paths:
1) Today’s workout screen (list exercises + latest sets)
2) Exercise history screen (last 20 sets)
3) Sync (dirty events)

So I index for those.
Not for “normal forms”.
For screens.

This is the query behind “show me the latest sets for this exercise in this workout”.
It uses a window function.
Expo’s SQLite ships new enough SQLite for this.
If you’re on something ancient, you’ll need a different approach.

// db/queries.ts
import * as SQLite from "expo-sqlite";

export type LatestSetRow = {
  set_index: number;
  reps: number | null;
  weight_kg: number | null;
  rir: number | null;
  kind: "LOG" | "EDIT" | "DELETE";
  happened_at: number;
};

export async function getLatestSetsForExercise(
  db: SQLite.SQLiteDatabase,
  workoutId: string,
  exerciseId: string
): Promise {
  const sql = `
    WITH ranked AS (
      SELECT
        set_index, reps, weight_kg, rir, kind, happened_at,
        ROW_NUMBER() OVER (
          PARTITION BY set_index
          ORDER BY happened_at DESC
        ) AS rn
      FROM set_events
      WHERE workout_id = ? AND exercise_id = ?
    )
    SELECT set_index, reps, weight_kg, rir, kind, happened_at
    FROM ranked
    WHERE rn = 1 AND kind != 'DELETE'
    ORDER BY set_index ASC;
  `;

  const rows = await db.getAllAsync(sql, [workoutId, exerciseId]);
  return rows;
}

That idx_set_events_workout_exercise index is doing real work here.
Without it, my mid-tier Android (Pixel 6a) was spiking.
Not always.
Just enough to feel gross.

One thing that bit me — using TEXT IDs everywhere means indexes get bigger.
Still fine.
But don’t add random extra indexes “just in case”.
Each one costs writes.
And I’m writing a lot.

3) I keep sync state out of my domain fields

I don’t want “server stuff” leaking everywhere.
But offline-first means I need it.
So I isolate it.

My rule:

Domain fields: reps, weight, exercise_id
Sync fields: dirty, server_rev, device_seq

Then sync is just: “give me dirty events, ordered”.
No scanning.
No weird filters.

Here’s the exact query + a tiny “mark as synced” function.
This is intentionally boring.

// db/sync.ts
import * as SQLite from "expo-sqlite";

type DirtyEvent = {
  id: string;
  workout_id: string;
  exercise_id: string;
  set_index: number;
  kind: string;
  reps: number | null;
  weight_kg: number | null;
  rir: number | null;
  happened_at: number;
  device_seq: number;
  server_rev: number;
};

export async function getDirtyEvents(
  db: SQLite.SQLiteDatabase,
  limit = 200
): Promise {
  const sql = `
    SELECT id, workout_id, exercise_id, set_index, kind,
           reps, weight_kg, rir, happened_at, device_seq, server_rev
    FROM set_events
    WHERE dirty = 1
    ORDER BY device_seq ASC
    LIMIT ?;
  `;
  return db.getAllAsync(sql, [limit]);
}

export async function markEventsSynced(
  db: SQLite.SQLiteDatabase,
  eventIds: string[],
  newServerRev: number
) {
  if (eventIds.length === 0) return;

  const placeholders = eventIds.map(() => "?").join(",");
  const sql = `
    UPDATE set_events
    SET dirty = 0,
        server_rev = ?
    WHERE id IN (${placeholders});
  `;

  await db.runAsync(sql, [newServerRev, ...eventIds]);
}

I used to store “lastSyncedAt” on the workout.
Bad move.
One event fails.
Now the whole workout looks synced.
Congrats, you just lost data.

Event-level sync state is annoying.
But it’s correct.

4) I generate IDs and sequences locally. Every time.

Offline means no server IDs at write time.
So I generate UUIDs on device.
And I keep a monotonic sequence.

I’m on Expo.
So I use expo-crypto for UUID.
And I store the sequence in SQLite too.
No AsyncStorage.
One storage system.
Less weirdness.

// db/writeSet.ts
import * as Crypto from "expo-crypto";
import * as SQLite from "expo-sqlite";

async function nextDeviceSeq(db: SQLite.SQLiteDatabase): Promise {
  await db.execAsync(`
    CREATE TABLE IF NOT EXISTS kv (
      key TEXT PRIMARY KEY,
      value TEXT NOT NULL
    );
  `);

  await db.runAsync(
    `INSERT OR IGNORE INTO kv(key, value) VALUES('device_seq', '0');`
  );

  // Atomic increment in SQLite.
  await db.runAsync(
    `UPDATE kv SET value = CAST(value AS INTEGER) + 1 WHERE key = 'device_seq';`
  );

  const row = await db.getFirstAsync<{ value: string }>(
    `SELECT value FROM kv WHERE key = 'device_seq';`
  );

  return Number(row?.value ?? 0);
}

export async function logSetEvent(
  db: SQLite.SQLiteDatabase,
  input: {
    workoutId: string;
    exerciseId: string;
    setIndex: number;
    reps: number;
    weightKg: number;
    rir?: number | null;
  }
) {
  const id = Crypto.randomUUID();
  const deviceSeq = await nextDeviceSeq(db);
  const now = Date.now();

  await db.runAsync(
    `INSERT INTO set_events(
      id, workout_id, exercise_id, set_index,
      kind, reps, weight_kg, rir,
      happened_at, device_seq, dirty
    ) VALUES(?, ?, ?, ?, 'LOG', ?, ?, ?, ?, ?, 1);`,
    [
      id,
      input.workoutId,
      input.exerciseId,
      input.setIndex,
      input.reps,
      input.weightKg,
      input.rir ?? null,
      now,
      deviceSeq,
    ]
  );

  return { id, deviceSeq };
}

This fixed a nasty bug.
I had device_seq in memory.
Killed the app.
Restart.
Sequence reset.
Sync order broke.

Storing it in SQLite is dull.
Also bulletproof.

Results

After moving from “nested JSON per workout” to the event schema above, my heaviest screen stopped stuttering.
On my Pixel 6a, the “open workout” query went from ~280–450ms down to ~45–85ms for a workout with 9 exercises and 31 logged sets.
Set logging writes are ~6–12ms per event locally.
Sync became simpler too: I send 1–200 small rows instead of merging a big JSON blob.
The best part is debugging.
I can read the event table and know what happened.
No guessing.

Key takeaways

Model offline writes as events. Editing becomes another event.
Add indexes that match your screens. Not your ER diagram.
Keep sync fields (dirty, server_rev, device_seq) separate from domain fields.
Don’t sort by timestamps alone. A monotonic sequence saves you.
Store your sequence in SQLite, not memory. App restarts are real.

Closing

I’m still tuning this.
Next up is compaction: turning 40 events into 1 “current set” row without losing history.

If you’ve shipped offline-first on React Native: do you compact event logs on-device, or only on the server?

Next.js job board: stop indexing expired jobs

Sathish — Tue, 14 Apr 2026 15:00:50 +0000

I stopped Google indexing expired job pages. Without deleting them.
I used Next.js 14 + Supabase to return 410/404 correctly.
I added a tiny robots guardrail to prevent “helpful” bugs.
I shipped a sitemap that only includes active listings.

Context

I’m building a job board for Psychiatric Mental Health Nurse Practitioners.

It has 8,000+ active listings and ~2,000 companies. New jobs arrive daily (200+ scraped/day). Old jobs expire daily too.

My first version treated “expired” as a UI state. The route still returned 200 OK. Google loved that. Brutal.

I ended up with thousands of low-value pages indexed. Many were “Apply closed” pages. Some were thin because the source removed details.

The fix wasn’t “better SEO.” It was HTTP correctness. And a sitemap that doesn’t lie.

1) I model job lifecycle in Postgres. Not in UI

I needed a single truth: is this job indexable?

So I made it explicit in the table. Status. Timestamps. And an immutable first_seen_at so my scraper doesn’t rewrite history.

Here’s the migration I used (Supabase Postgres).

-- 001_jobs_lifecycle.sql

-- Jobs can be active, expired, or removed.
-- removed = source page is gone, or legal takedown, etc.
-- expired = time-based expiration or “closed” detected

create type job_status as enum ('active', 'expired', 'removed');

alter table public.jobs
  add column if not exists status job_status not null default 'active',
  add column if not exists first_seen_at timestamptz not null default now(),
  add column if not exists last_seen_at timestamptz not null default now(),
  add column if not exists expires_at timestamptz,
  add column if not exists removed_at timestamptz;

-- Helps query “what’s indexable” fast.
create index if not exists jobs_status_expires_at_idx
  on public.jobs (status, expires_at);

create index if not exists jobs_last_seen_at_idx
  on public.jobs (last_seen_at desc);

One thing that bit me — I originally used a boolean is_active.

Then I needed “removed” vs “expired” behavior. Different HTTP codes. Different sitemap behavior.

Enums saved me from the boolean mess.

2) I return 410 for expired. 404 for removed

This is the whole point.

If a job is expired, I want it to disappear from the index fast. 410 Gone is explicit.

If the job was removed (source vanished, or I removed it), I return 404.

Next.js notFound() always returns 404. That’s not enough.

So I return a NextResponse with the right status.

// app/jobs/[slug]/page.tsx
import { createClient } from "@supabase/supabase-js";
import { notFound } from "next/navigation";
import { NextResponse } from "next/server";

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY! // server only
);

type JobRow = {
  id: string;
  slug: string;
  title: string;
  status: "active" | "expired" | "removed";
  expires_at: string | null;
};

export default async function JobPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;

  const { data: job, error } = await supabase
    .from("jobs")
    .select("id, slug, title, status, expires_at")
    .eq("slug", slug)
    .maybeSingle();

  if (error) throw error;
  if (!job) return notFound();

  // Removed: behave like a missing resource.
  if (job.status === "removed") return notFound();

  // Expired: return 410. Still render a human page.
  if (job.status === "expired") {
    return new NextResponse(
      `${escapeHtml(
        job.title
      )} (Closed)# Job closed
`,
      {
        status: 410,
        headers: {
          "content-type": "text/html; charset=utf-8",
          "cache-control": "public, max-age=300",
        },
      }
    );
  }

  // Active: normal render.
  return (

      # {job.title}

      {/* rest of the job page */}

  );
}

function escapeHtml(input: string) {
  return input
    .replaceAll("&", "&")
    .replaceAll("<", "<")
    .replaceAll(">", ">")
    .replaceAll('"', """)
    .replaceAll("'", "'");
}

Yeah. It’s weird returning raw HTML in a page.

I tried to do it “the React way” for 410. Spent 4 hours. Most of it was wrong.

In App Router, you don’t get an easy “render UI but with status 410” primitive. So I went direct.

And I keep it intentionally minimal. No indexing. No internal links. Just a polite dead-end.

3) I enforce “noindex” for anything not active

Status codes are good.

But bugs happen. Scrapers misclassify. Admin toggles go wrong. Somebody changes code and accidentally returns 200 for expired.

So I added a second guardrail: robots meta.

If a job isn’t active, it gets noindex, nofollow.

// app/jobs/[slug]/metadata.ts
import type { Metadata } from "next";
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

type JobMetaRow = {
  title: string;
  status: "active" | "expired" | "removed";
};

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}): Promise {
  const { slug } = await params;

  const { data: job } = await supabase
    .from("jobs")
    .select("title, status")
    .eq("slug", slug)
    .maybeSingle();

  if (!job) return { title: "Not found" };

  const isIndexable = job.status === "active";

  return {
    title: job.title,
    robots: isIndexable
      ? { index: true, follow: true }
      : { index: false, follow: false },
  };
}

Two layers now.

Active: 200 + index,follow
Expired: 410 + noindex,nofollow
Removed: 404

I sleep better.

4) I generate a sitemap from the DB. Only active jobs

My original sitemap was route-based.

/jobs/[slug] exists, so it got listed. That’s how I fed crawlers a buffet of expired pages.

Now I generate the sitemap from Postgres.

Only active jobs. And I cap it. Because 8,000 URLs is fine, but it keeps growing.

// app/sitemap.ts
import type { MetadataRoute } from "next";
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

export default async function sitemap(): Promise {
  const siteUrl = process.env.NEXT_PUBLIC_SITE_URL!; // e.g. https://pmhnp.example

  // Only active jobs get into the sitemap.
  // I keep it under 45,000 to stay safe with size.
  const { data: jobs, error } = await supabase
    .from("jobs")
    .select("slug, last_seen_at")
    .eq("status", "active")
    .order("last_seen_at", { ascending: false })
    .limit(45000);

  if (error) throw error;

  const urls: MetadataRoute.Sitemap = jobs.map((j) => ({
    url: `${siteUrl}/jobs/${j.slug}`,
    lastModified: new Date(j.last_seen_at),
    changeFrequency: "daily",
    priority: 0.6,
  }));

  // Add a couple of stable pages.
  urls.push(
    {
      url: `${siteUrl}/`,
      lastModified: new Date(),
      changeFrequency: "daily",
      priority: 1,
    },
    {
      url: `${siteUrl}/jobs`,
      lastModified: new Date(),
      changeFrequency: "hourly",
      priority: 0.8,
    }
  );

  return urls;
}

This also forced me to keep status accurate.

If my scraper forgets to expire something, it stays in the sitemap. That’s a loud failure. Good.

5) I expire jobs automatically with one SQL update

I didn’t want a complicated workflow.

My scraper sets last_seen_at = now() whenever it still sees the job. If a job hasn’t been seen in 30 days, it’s probably closed.

So once per day, I run one SQL statement.

This is intentionally boring.

-- 002_expire_jobs.sql

-- Expire jobs not seen in 30 days.
-- Keeps “active” set clean for sitemap + indexing.

update public.jobs
set
  status = 'expired',
  expires_at = coalesce(expires_at, now())
where
  status = 'active'
  and last_seen_at < now() - interval '30 days';

In Supabase, I run this via a scheduled job (pg_cron if you have it, or a Vercel Cron hitting an API route that executes the SQL).

I used Vercel Cron.

Because I already have it. And I didn’t want to fight extension permissions.

Results

After this change, my sitemap dropped from 12,418 URLs to 8,091 URLs. That’s just “active” jobs now.

I also stopped serving 200 for closed listings. Expired jobs now return 410 consistently. Removed jobs return 404.

In Google Search Console, “Indexed, not submitted in sitemap” for job URLs went down from 3,204 to 611 over 10 days. Not zero yet, but it’s finally moving the right direction.

And my crawl stats stopped wasting time on dead pages.

Key takeaways

Don’t encode lifecycle in UI state. Put it in Postgres.
Use 410 Gone for expired content. It clears faster than a soft 404.
Add noindex as a second guardrail. Bugs happen.
Generate sitemaps from your database, not your route tree.
One daily SQL update beats a “smart” expiration pipeline.

Closing

If you’re running a job board (or any scraped directory), how are you deciding between 404 and 410?

Do you return 410 immediately on “closed”, or do you keep a grace period so the page can still help users for a week?

DEV Community: Sathish

Next.js: I stop AI refactors with a guardrail

Context

1) I start by making config impossible to “kind of work”

2) I force every API response through a single type

3) I validate request + response at runtime (not just types)

4) I make Cursor show me a checklist before I accept a diff

Results

Key takeaways

Closing

React Native offline: SQLite migrations without pain

Context

1) I treat migrations like app code. Versioned.

2) I don’t trust my migrations. I verify them.

3) I learned table rebuilds the hard way

4) I wire it into Expo startup. No race conditions.

Results

Key takeaways

Closing

Next.js job board: stop Google indexing filters

Context

1) I decide what’s indexable. Everything else is noindex.

2) I generate canonical URLs that ignore junk params

3) I wire it into Next.js metadata. No custom `` hacks.

4) I add a robots.txt rule. Because crawlers are stubborn.

5) I test it with a script. Not with “I’ll remember.”

Cursor + Claude: stop shipping broken env vars

Context

1) I wrote one env schema. Everything else follows.

2) I made Next.js scream early (before any page renders)

3) I generate .env.example from the schema

4) I added a CI check that fails fast

Results

Key takeaways

Closing

React Native offline-first: fast set logging UI

Context

1) I treat SQLite like a sink, not my UI state

2) I enqueue writes. I don’t await them on tap

3) I render “pending” rows so the UI never lies

4) I measure tap-to-render time. Not “feels faster”

Results

Key takeaways

Closing

Next.js job board: reliable scrapes with leases

Context

1) I stopped trusting cron timing. I added a lease.

2) I made the lock acquisition a single SQL function

3) I wired it into a Next.js 14 cron route

4) I logged every run. Because “skipped” isn’t enough.

Results

Key takeaways

Closing

Cursor + Claude: stop shipping flaky API clients

Context

1) I start with a real contract. Not vibes.

2) I generate the client. Then I stop hand-writing fetch.

3) I write contract tests with a fake server. Zero Docker.

4) I only let Cursor touch code when a test fails

Results

Key takeaways

Closing

React Native offline-first: 5s logging with SQLite

Context

1) I split “what the user sees” from “what I persist”

2) I serialize writes. Because SQLite will.

3) I do optimistic UI. But I keep a rollback key.

4) I batch “workout screen” queries so the UI stays snappy

Results

Key takeaways

Closing

Next.js job board: zero-downtime schema changes

Context

1) I treat migrations like deploys. Because they are.

2) I backfill in small chunks. Not one giant UPDATE.

3) I ship code that can read both schemas

4) I don’t drop columns until I’ve proven nothing reads them

Results

Key takeaways

Closing

1) I decide what’s indexable. Everything else is `noindex`.

4) I add a `robots.txt` rule. Because crawlers are stubborn.

3) I generate `.env.example` from the schema

2) I enqueue writes. I don’t `await` them on tap