Forem: Sandeep Bansod

Stop using `any` — here's how to type your messy API responses correctly

Sandeep Bansod — Mon, 06 Apr 2026 04:36:38 +0000

You cast the API response to any to stop TypeScript complaining. It worked. Now a field changed shape three months later and the bug is in production. Here's how to type messy API responses properly — with real validation, not just type assertions.

You've done it. Everyone has. The API returns something, TypeScript starts complaining, and the fastest fix is as any. The error goes away. You move on. Six weeks later, that field is null instead of a string, the bug is in production, and TypeScript said nothing — because you told it not to.

The problem is not that API responses are messy. They are, and always will be. The problem is that any doesn't model that mess — it erases it. You lose the one thing TypeScript is there to give you: a guarantee that your code matches your data.

This article covers the real techniques — from unknown to type guards to Zod to a fully typed fetch wrapper — that let you handle unpredictable API shapes without lying to the compiler.

The Real Problem with any

When you write const data = response.json() as any, TypeScript stops checking entirely. Every property access, every method call, every nested field — unchecked. You could write data.user.address.city.toUpperCase() and TypeScript would nod along even if address is undefined.

// This compiles. It will blow up at runtime.
const res  = await fetch('/api/user/1');
const data = (await res.json()) as any;

console.log(data.profile.avatar.url.trim());
//                       ^^^^^^ could be null
//                              ^^^ could be undefined
//                                  ^^^ TypeScript: fine by me

The worse version is as unknown as YourType — the double cast. It is exactly as dangerous as any, just more words. You're not adding safety, you're just suppressing a different error with extra ceremony.

// Still no actual validation — just a louder lie
const user = (await res.json()) as unknown as User;
console.log(user.email.toLowerCase()); // runtime error if email is null

The real issue is that fetch returns Promise<any>. The TypeScript standard library types Response.json() as returning any because it genuinely cannot know the shape. That's the compiler being honest. When you cast that any to your type, you're being dishonest on its behalf.

Your First Tool: unknown Instead of any

unknown is the honest version of any. It tells TypeScript: "I have a value and I don't know its shape yet." The critical difference is that TypeScript forces you to prove the shape before you use it. You cannot access properties on unknown without narrowing it first.

const res  = await fetch('/api/user/1');
const data: unknown = await res.json();

// TypeScript blocks this immediately
console.log(data.email);
// Error: Object is of type 'unknown'

// You must narrow it first
if (
  typeof data === 'object' &&
  data !== null &&
  'email' in data &&
  typeof (data as any).email === 'string'
) {
  console.log(data.email); // TypeScript: now it's safe
}

This is the right instinct but the wrong implementation for anything larger than a toy example. Writing inline narrowing for a 20-field API response is unreadable and unmaintainable. That's what type guards and schema validators are for.

Type Guards — Validate at the Boundary

A type guard is a function that takes an unknown value, validates its shape at runtime, and tells TypeScript what it is. The return type value is YourType is the key — it's called a type predicate, and it narrows the type inside any if block that uses it.

// types/user.ts
export interface User {
  id:        number;
  email:     string;
  name:      string;
  role:      'admin' | 'editor' | 'viewer';
  createdAt: string;
}

// guards/isUser.ts
export function isUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    typeof (value as Record<string, unknown>).id        === 'number' &&
    typeof (value as Record<string, unknown>).email     === 'string' &&
    typeof (value as Record<string, unknown>).name      === 'string' &&
    ['admin', 'editor', 'viewer'].includes(
      (value as Record<string, unknown>).role as string
    )
  );
}

Now use it at the API boundary — the one place in your codebase where external data enters:

import { isUser } from '../guards/isUser';

export async function fetchUser(id: number): Promise<User> {
  const res  = await fetch(`/api/users/${id}`);
  const data: unknown = await res.json();

  if (!isUser(data)) {
    throw new Error(`Unexpected response shape from /api/users/${id}`);
  }

  // TypeScript knows `data` is User from here on
  return data;
}

Everything downstream of fetchUser works with a real User type — fully typed, autocompleted, checked on every property access. The mess is contained to the guard function.

The downside: writing guards by hand is verbose and easy to get wrong. If you add a field to the User interface, you have to remember to update the guard. If you don't, the guard silently misses the new field. For large or frequently changing APIs, use Zod.

Zod — Runtime Validation That Generates Types

Zod is a schema declaration library that solves the gap between your TypeScript type and your runtime validation. Instead of maintaining both a type and a guard separately, you define one schema and Zod generates the type from it automatically.

npm install zod

import { z } from 'zod';

// Define once — Zod generates the type AND validates at runtime
const UserSchema = z.object({
  id:        z.number(),
  email:     z.string().email(),
  name:      z.string().min(1),
  role:      z.enum(['admin', 'editor', 'viewer']),
  createdAt: z.string().datetime(),
});

// Type is inferred automatically — no separate interface needed
export type User = z.infer<typeof UserSchema>;

Now the fetch function becomes clean and fully safe:

export async function fetchUser(id: number): Promise<User> {
  const res  = await fetch(`/api/users/${id}`);
  const data: unknown = await res.json();

  // .parse() throws a ZodError with a detailed message if validation fails
  // .safeParse() returns { success, data, error } — use this in production
  const result = UserSchema.safeParse(data);

  if (!result.success) {
    console.error('Validation failed:', result.error.flatten());
    throw new Error(`Invalid response from /api/users/${id}`);
  }

  return result.data; // Fully typed User
}

result.error.flatten() gives you a structured breakdown of exactly which fields failed and why — far more useful than a generic "invalid response" message when you're debugging at 2AM.

The key difference from a type guard: if you add phoneNumber: z.string().optional() to UserSchema, the User type updates automatically. Schema and type are always in sync because they're the same thing.

Typing Partial and Nullable API Fields

Real APIs are messy. Fields are sometimes null, sometimes missing entirely, sometimes a string and sometimes a number depending on context. Zod handles all of these explicitly.

const OrderSchema = z.object({
  id:          z.number(),
  status:      z.enum(['pending', 'shipped', 'delivered', 'cancelled']),

  // nullable — the API returns null when not yet assigned
  assignedTo:  z.string().nullable(),

  // optional — the field may not be present at all
  couponCode:  z.string().optional(),

  // nullable AND optional — null or missing are both valid
  notes:       z.string().nullable().optional(),

  // coerce a string date to a Date object automatically
  shippedAt:   z.coerce.date().nullable(),

  // API returns strings for monetary values — validate and keep as string
  total:       z.string().regex(/^\d+\.\d{2}$/),

  // nested object
  address: z.object({
    line1:    z.string(),
    line2:    z.string().optional(),
    city:     z.string(),
    postcode: z.string(),
    country:  z.string().length(2), // ISO 3166-1 alpha-2
  }),

  // array of nested objects
  items: z.array(z.object({
    sku:      z.string(),
    quantity: z.number().int().positive(),
    price:    z.string(),
  })),
});

export type Order = z.infer<typeof OrderSchema>;

The generated Order type reflects all of this precisely — assignedTo: string | null, couponCode?: string, notes?: string | null | undefined. TypeScript will force you to handle the null and undefined cases. Not because you asked it to — because the schema told it to.

Handling API Errors Correctly

Most typed fetch examples only type the happy path. Real APIs return structured error objects too, and those have shapes worth validating.

// The error shape your API returns on 4xx / 5xx
const ApiErrorSchema = z.object({
  code:    z.string(),            // e.g. 'USER_NOT_FOUND'
  message: z.string(),
  details: z.record(z.string()).optional(), // field-level errors
});

export type ApiError = z.infer<typeof ApiErrorSchema>;

// A typed result type — no throwing unless truly unexpected
export type ApiResult<T> =
  | { ok: true;  data:  T        }
  | { ok: false; error: ApiError };

export async function fetchUser(id: number): Promise<ApiResult<User>> {
  const res  = await fetch(`/api/users/${id}`);
  const body: unknown = await res.json();

  if (!res.ok) {
    const errResult = ApiErrorSchema.safeParse(body);
    return {
      ok:    false,
      error: errResult.success
        ? errResult.data
        : { code: 'UNKNOWN', message: 'Unexpected error shape' },
    };
  }

  const result = UserSchema.safeParse(body);
  if (!result.success) {
    return { ok: false, error: { code: 'INVALID_SHAPE', message: 'Response schema mismatch' } };
  }

  return { ok: true, data: result.data };
}

Now at the call site, TypeScript forces you to handle both cases. No unchecked exceptions, no silent failures:

const result = await fetchUser(42);

if (!result.ok) {
  // result.error is typed as ApiError
  showToast(result.error.message);
  return;
}

// result.data is typed as User — fully safe from here
updateProfile(result.data);

Generic Fetch Wrapper with Full Type Safety

Once you have schemas, you can write one typed fetch utility and use it everywhere instead of duplicating the validation logic in every service function.

import { z, ZodSchema } from 'zod';

export type FetchResult<T> =
  | { ok: true;  data:  T      }
  | { ok: false; error: string; status: number };

export async function typedFetch<T>(
  url:     string,
  schema:  ZodSchema<T>,
  options?: RequestInit,
): Promise<FetchResult<T>> {
  let res: Response;

  try {
    res = await fetch(url, options);
  } catch (err) {
    return { ok: false, error: 'Network error', status: 0 };
  }

  const body: unknown = await res.json().catch(() => null);

  if (!res.ok) {
    const message = typeof body === 'object' && body !== null && 'message' in body
      ? String((body as Record<string, unknown>).message)
      : `HTTP ${res.status}`;
    return { ok: false, error: message, status: res.status };
  }

  const parsed = schema.safeParse(body);
  if (!parsed.success) {
    console.error('[typedFetch] schema mismatch:', parsed.error.flatten());
    return { ok: false, error: 'Invalid response shape', status: res.status };
  }

  return { ok: true, data: parsed.data };
}

Using it across your app:

// Any endpoint — just pass the schema
const userResult = await typedFetch(`/api/users/${id}`, UserSchema);
const orderResult = await typedFetch(`/api/orders/${id}`, OrderSchema);

// POST with body
const createResult = await typedFetch(
  '/api/users',
  UserSchema,
  {
    method:  'POST',
    headers: { 'Content-Type': 'application/json' },
    body:    JSON.stringify({ email: 'user@example.com', name: 'Riya' }),
  },
);

if (createResult.ok) {
  // createResult.data is User — fully typed
  console.log('Created:', createResult.data.email);
}

The schema is the only thing that changes between endpoints. All error handling, network error recovery, and logging lives in one place.

When the API Shape Changes Without Warning

Third-party APIs change. Internal APIs change. The backend team renames a field and forgets to tell you. With any, this breaks silently at runtime. With Zod, the safeParse fails immediately with a clear error message pointing to the exact field.

Two Zod tools are useful here:

z.object().passthrough() — validates the fields you defined but allows extra unknown fields through. Useful when the API adds fields you don't need yet, without breaking validation:

// Extra fields from the API are allowed through — your type stays clean
const UserSchema = z.object({
  id:    z.number(),
  email: z.string(),
  name:  z.string(),
}).passthrough();

z.object().strip() (the default) — strips unknown fields. Safer for security-sensitive contexts where you don't want unexpected data flowing through your app.

For APIs that evolve, use .catch() to provide fallback values for non-critical fields instead of failing the whole parse:

const UserSchema = z.object({
  id:     z.number(),
  email:  z.string(),
  name:   z.string(),

  // If the API stops sending `avatarUrl`, fall back to null
  // instead of throwing a validation error
  avatarUrl: z.string().nullable().catch(null),

  // If `theme` is an unexpected value, default to 'light'
  theme: z.enum(['light', 'dark']).catch('light'),
});

This gives you a resilient schema — strict on the fields that matter, graceful on the fields that might drift.

Common Mistakes

Using as YourType instead of actually validating — a type assertion tells TypeScript what you believe the shape is, not what it actually is. If you're wrong, TypeScript cannot help you
Validating in components instead of at the fetch boundary — validation belongs in your service or API layer, not scattered across UI components. Components should receive already-validated, fully-typed data
Marking everything optional to avoid validation failures — z.string().optional() on a required field means you'll get undefined where you don't expect it. Be strict on required fields; only use optional where the API contract genuinely allows absence
Using .parse() instead of .safeParse() in production code — .parse() throws a ZodError on failure, which means unhandled promise rejections unless you wrap every call in try/catch. Use .safeParse() and handle the error branch explicitly
Writing a separate interface and a separate guard — this is the pre-Zod pattern that created the sync problem in the first place. With Zod, z.infer is your type. One source of truth

The Takeaway

any doesn't solve the problem of messy API responses — it hides it until runtime. unknown forces you to be explicit. Type guards add reusable validation. Zod makes schema and type the same thing so they can never go out of sync. A generic typedFetch wrapper brings it all together so validation happens once, consistently, at the boundary where external data enters your app. After that, the rest of your codebase works with real types — and TypeScript can actually protect you.

If you found this useful, I write about TypeScript, Node.js, Security and DevOps at stackdevlife.com — drop a follow if you'd like more!

Originally published at stackdevlife.com

Environment Variables You're Leaking to the Frontend Without Knowing It

Sandeep Bansod — Sun, 05 Apr 2026 09:09:00 +0000

You added NEXT_PUBLIC_ to your API key "just to test something quickly". That was six months ago. It's still there.

Most developers know the rule: secret keys go in .env, never in client code. But the actual leaks aren't that obvious. They don't happen because someone is careless — they happen because the tooling is confusing, the error messages are silent, and the mistakes look completely fine until someone opens DevTools or pulls your bundle.

Mistake 1 — The NEXT_PUBLIC_ prefix on secrets

Next.js exposes any variable prefixed with NEXT_PUBLIC_ to the browser. That's by design. The problem is developers reach for it the moment they hit a "variable is undefined" error on the client side — without asking why it's undefined.

# .env.local

# Fine — this is meant to be public
NEXT_PUBLIC_API_URL=https://api.example.com

# DANGER — now exposed in every JS bundle
NEXT_PUBLIC_STRIPE_SECRET_KEY=sk_live_xxxxxxxxx
NEXT_PUBLIC_DATABASE_URL=postgres://user:password@host/db

Anyone can open your deployed site, go to Network → JS files, search for sk_live_ and find it.

Stripe secret keys have a very recognizable prefix. So do AWS access keys (AKIA), Supabase service role keys, and SendGrid API keys.

The fix: if your key is only used in API routes or server components, it should never have NEXT_PUBLIC_. Call a backend route instead.

// Wrong — secret key exposed to client
const stripe = new Stripe(process.env.NEXT_PUBLIC_STRIPE_SECRET_KEY!);

// Right — only used in /api/checkout/route.ts (server-side)
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

Mistake 2 — Vite's import.meta.env and the VITE_ prefix

Vite works exactly the same way. Any variable prefixed with VITE_ gets statically inlined into your bundle at build time. It's not fetched at runtime — it's literally copied into your JavaScript.

VITE_API_URL=https://api.example.com        # fine
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1Ni   # fine
VITE_SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1Ni...  # never prefix this

Run npm run build then open dist/assets/index-xxxx.js and search for your key. You'll find it in plain text, wrapped in production whatever.

Mistake 3 — process.env in bundled client code

With Create React App or older webpack setups, REACT_APP_ variables get inlined. But even without that pattern, developers sometimes write shared utility files that get pulled into the client bundle without realizing it.

// utils/config.ts — imported by both client and server code
export const config = {
  apiUrl: process.env.API_URL,
  stripeKey: process.env.STRIPE_SECRET_KEY,
};

The safe pattern: never import server config into code that's shared with the client.

// lib/server-config.ts — only imported in server files
export const serverConfig = {
  apiUrl: process.env.API_URL,
  stripeKey: process.env.STRIPE_SECRET_KEY,
};

// lib/client-config.ts — safe to import anywhere
export const clientConfig = {
  apiUrl: process.env.NEXT_PUBLIC_API_URL,
};

Mistake 4 — Exposing .env through source maps

You've been careful with your variables. But did you ship source maps to production? Source maps reconstruct your original source code in the browser. If your server-side code ends up in a source map in your production build, the DevTools Sources tab will show the original file — including any hardcoded fallbacks.

// A common but dangerous pattern
const key = process.env.STRIPE_SECRET_KEY || "sk_live_fallback_for_dev";

In Next.js, make sure source maps stay off in production:

// next.config.js
module.exports = {
  productionBrowserSourceMaps: false, // default is false — make sure it stays that way
};

For Vite:

// vite.config.ts
export default defineConfig({
  build: {
    sourcemap: false, // or "hidden" if you need them for error tracking only
  },
});

Mistake 5 — The API debug route you forgot to remove

This one is embarrassing but common. During local debugging, you add a quick route to dump env state. You commit it. It goes to production.

https://yourapp.com/api/debug

Now returns every single environment variable on your server.

// pages/api/debug.ts
export default function handler(req, res) {
  res.json({ env: process.env }); // must never go to production
}

How to audit what you're actually shipping

Build your app and grep the bundle for known secret patterns:

# Next.js
npm run build
grep -r "sk_live\|AKIA\|password\|secret" .next/static/chunks/

# Vite
npm run build
grep -r "sk_live\|AKIA\|password\|secret" dist/assets/

Common mistakes

Prefixing secrets "temporarily" to fix a client-side undefined error — the root cause is architectural, not a missing prefix
Sharing a single config file between server and client code — split them and enforce it with ESLint import rules
Using fallbacks with real keys — process.env.KEY || "real-key-here" defeats the entire point
Forgetting that third-party SDKs initialized client-side log their config (Sentry, Supabase, Firebase initialized with wrong keys expose them in network requests)

The takeaway

The leaks that hurt you aren't the obvious ones — they're the subtle ones. Every time you see NEXT_PUBLIC_, you added in a rush, the shared config file that got bundled, the debug route that made it to production. Build a habit: before any deploy, grep your bundle for known secret patterns, keep a hard separation between server and client config, and treat every environment variable as guilty until proven safe to expose.

If you found this useful, I write about TypeScript, Node.js, Security and DevOps at stackdevlife.com — drop a follow if you'd like more!

Originally published at stackdevlife.com