DEV Community: Michal

Sending Images in Web APIs: Stop Making the Wrong Choice

Michal — Fri, 29 Aug 2025 21:58:46 +0000

You're building an API endpoint that accepts images. You have three main approaches, and most devs pick the wrong one. Let's fix that.

1. Base64 Encoding (The Lazy Way)

Base64 converts binary data to text. Yes, it was useful for email attachments in 1995 when SMTP servers choked on binary data. Today? It's mostly a bad idea.

The reality: Base64 inflates your payload by ~33%. That 3MB image becomes 4MB. Your API parsing that JSON? It's now handling massive strings. Your database storing these strings? Enjoy the bloat.

When it's actually okay: Tiny icons or SVGs under 10KB embedded in CSS/HTML. That's it. If you're sending actual images this way, you're doing it wrong.

2. Multipart/Form-Data (The Standard Way)

This is how HTML forms have sent files since forever. The catch? Everything that isn't a file becomes a string.

// What you send
formData.append('file', imageFile);
formData.append('metadata', JSON.stringify({ title: 'My Image', tags: ['nature'] }));

The problem: Your nice DTOs and validation decorators in NestJS? Useless. You're parsing strings and validating manually. That metadata field? You're JSON.parse()-ing it and praying it's valid.

When to use it: Simple uploads with minimal metadata. Profile picture update? Sure. Complex nested objects with files? Pain.

3. Separate Endpoints (The Clean Way)

Upload files to one endpoint, get back IDs, then send those IDs with your JSON payload to another endpoint.

// Step 1: Upload image
POST /api/uploads
Response: { id: "abc123", url: "https://..." }

// Step 2: Create resource with image reference
POST /api/posts
Body: { title: "My Post", imageId: "abc123", ... }

The tradeoff: Yes, orphaned files. Write a cleanup job that runs every hour and deletes uploads older than 24 hours without associations. It's 20 lines of code, not rocket science.

Why this wins:

Clean separation of concerns
DTOs work normally
Better caching strategies
Resumable uploads become possible
Can optimize file handling separately (CDN, processing queues)

The Production Reality

Stop overthinking this. For 90% of apps, use separate endpoints. For simple forms with a single file, use multipart. Never use base64 for actual files unless you enjoy angry users and slow APIs.

And please, implement proper file validation. Check MIME types, file sizes, and actually validate the file content. Users will upload anything.

Questions?

Got a different approach? Think I'm wrong about base64? Running into edge cases I didn't cover? Drop a comment. And if you're still sending 10MB PNGs as base64 strings in 2025, we need to talk.

Building Real-time Chat with Socket.io and React Query

Michal — Mon, 25 Aug 2025 15:35:26 +0000

I built a Discord-style chat system with Socket.io, React Query, and infinite scroll. It took me weeks to figure out how to make these technologies play nicely together. Here's what every tutorial skips.

The Problem Nobody Talks About

Socket.io tutorials show you how to send messages. React Query tutorials show you how to cache data. But nobody explains how to combine them without creating a mess of duplicate data, stale caches, and memory leaks.

Here's what we're building:

Real-time message updates
Infinite scroll that doesn't break with new messages
Typing indicators that actually work
Proper socket connection management (no memory leaks)

What we're NOT building (to keep this focused):

Online/offline status - adds complexity, minimal value for an MVP
Read receipts - requires database schema changes
Session persistence - using regular auth tokens instead of session cookies to avoid the extra session management logic

Prerequisites

Before diving into code, understand how WebSockets actually work. These resources are worth your time:

Socket.io Fundamentals - Best conceptual overview
NestJS WebSockets - If you're using NestJS backend

The Architecture

Every chat needs three core features:

Message history - REST API + React Query for caching
Real-time updates - Socket.io for new messages
Infinite scroll - IntersectionObserver + React Query's infinite queries

The trick is making them work together without fighting each other.

Socket Events You Actually Need

If you're coming from REST APIs, Socket.io's event system feels backwards. Here's the minimum viable setup:

Events to listen for (.on):

connect - Socket connected
disconnect - Connection lost
app_error - Application-level errors (not error - that's for socket errors)
new-message - Incoming messages
user-started-typing - Typing indicators
user-stopped-typing - Clear typing indicators

Events to emit:

join-chat - Subscribe to a chat room
leave-chat - Unsubscribe from a chat room
start-typing - Notify others you're typing
stop-typing - Clear your typing indicator

The Implementation

1. Socket Connection Management

The biggest mistake everyone makes: creating multiple socket connections. Here's a context that manages a single connection properly:

import {
    createContext,
    useCallback,
    useContext,
    useEffect,
    useRef,
    useState,
} from "react";
import { socket } from "../../../socket";
import { Chat } from "../types/chat";

type TypingData = {
    userId: string;
    chatId: string;
    userName: string;
};

interface ChatContextType {
    selectedChat: Chat | null;
    selectChat: (chat: Chat) => void;
    startTyping: () => void;
    stopTyping: () => void;
    typingUsers: Omit<TypingData, "chatId">[];
}

export const ChatContext = createContext<ChatContextType | undefined>(
    undefined
);

export const ChatProvider: React.FC<{ children: React.ReactNode }> = ({
    children,
}) => {
    const [selectedChat, setSelectedChat] = useState<Chat | null>(null);
    const [typingUsers, setTypingUsers] = useState<
        { userId: string; userName: string }[]
    >([]);
    const isInitialized = useRef(false);

    // Initialize socket connection ONCE
    useEffect(() => {
        if (isInitialized.current) return;

        const handleError = (error: any) => {
            console.error("Socket error:", error);
        };

        // Connect only if not already connected
        if (!socket.connected) {
            console.log("Connecting socket...");
            socket.connect();
        }

        socket.on("connect", () => {
            console.log("Socket connected:", socket.id);
        });

        socket.on("disconnect", (reason) => {
            console.log("Socket disconnected:", reason);
        });

        socket.on("app_error", handleError);

        isInitialized.current = true;

        // Cleanup only on app unmount
        return () => {
            if (socket.connected) {
                socket.off("connect");
                socket.off("disconnect");
                socket.off("app_error", handleError);
                socket.disconnect();
                isInitialized.current = false;
            }
        };
    }, []);

    // Handle typing indicators for selected chat
    useEffect(() => {
        if (!selectedChat) return;

        const handleUserStartedTyping = (data: TypingData) => {
            // Only show typing for current chat
            if (data.chatId !== selectedChat._id) return;

            setTypingUsers((prev) => {
                // Prevent duplicates
                if (!prev.some((user) => user.userId === data.userId)) {
                    return [...prev, { userId: data.userId, userName: data.userName }];
                }
                return prev;
            });
        };

        const handleUserStoppedTyping = (data: Omit<TypingData, "userName">) => {
            if (data.chatId !== selectedChat._id) return;

            setTypingUsers((prev) =>
                prev.filter((user) => user.userId !== data.userId)
            );
        };

        socket.on("user-started-typing", handleUserStartedTyping);
        socket.on("user-stopped-typing", handleUserStoppedTyping);

        return () => {
            socket.off("user-started-typing", handleUserStartedTyping);
            socket.off("user-stopped-typing", handleUserStoppedTyping);
            setTypingUsers([]); // Clear typing indicators on chat change
        };
    }, [selectedChat?._id]);

    const selectChat = useCallback(
        (chat: Chat) => {
            if (!socket.connected) {
                console.warn("Socket not connected. Cannot select chat.");
                return;
            }

            // Leave previous chat room
            if (selectedChat?._id) {
                socket.emit("leave-chat", { chatId: selectedChat._id });
            }

            // Join new chat room
            setSelectedChat(chat);
            socket.emit("join-chat", { chatId: chat._id });
        },
        [selectedChat]
    );

    const startTyping = useCallback(() => {
        if (!selectedChat) return;
        socket.emit("start-typing", { chatId: selectedChat._id });
    }, [selectedChat]);

    const stopTyping = useCallback(() => {
        if (!selectedChat) return;
        socket.emit("stop-typing", { chatId: selectedChat._id });
    }, [selectedChat]);

    return (
        <ChatContext.Provider
            value={{ selectedChat, selectChat, startTyping, stopTyping, typingUsers }}
        >
            {children}
        </ChatContext.Provider>
    );
};

export const useChat = () => {
    const context = useContext(ChatContext);
    if (!context) {
        throw new Error("useChat must be used within ChatProvider");
    }
    return context;
};

2. Infinite Scroll with React Query

The key insight: use React Query for data fetching, but invalidate on socket events.

import { useInfiniteQuery, useQuery } from "@tanstack/react-query";
import apiClient from "../../auth/services/auth";
import { Chat } from "../types/chat";
import { Message } from "../types/message";

interface MessageResponse {
    data: {
        messages: Message[];
        currentPage: number;
        hasNextPage: boolean;
        totalPages: number;
        totalCount: number;
    };
}

export const useInfiniteMessages = (chatId: string, limit: number = 20) => {
    return useInfiniteQuery<MessageResponse>({
        queryKey: ["messages", chatId, "infinite"],
        queryFn: ({ pageParam = 1 }) =>
            apiClient.get(`/message/chat/${chatId}`, {
                params: {
                    page: pageParam,
                    limit,
                },
            }),
        getNextPageParam: (lastPage, allPages) => {
            // Only fetch next page if current page has messages
            const nextPage = lastPage.data.messages.length
                ? allPages.length + 1
                : undefined;
            return nextPage;
        },
        initialPageParam: 1,
        enabled: !!chatId, // Don't fetch until chat is selected
    });
};

3. Smart Typing Indicators

Most typing indicators suck. They either never clear or clear too quickly. Here's a hook that handles both:

import { useCallback, useEffect, useRef } from "react";
import { useChat } from "../context/ChatContext";

export const useTypingIndicator = (typingTimeout = 3000) => {
    const { startTyping, stopTyping } = useChat();
    const typingTimeoutRef = useRef<NodeJS.Timeout | null>(null);
    const isTypingRef = useRef(false);

    const clearTypingTimeout = useCallback(() => {
        if (typingTimeoutRef.current) {
            clearTimeout(typingTimeoutRef.current);
            typingTimeoutRef.current = null;
        }
    }, []);

    const handleTyping = useCallback(
        (value: string) => {
            // Start typing indicator on first character
            if (value.length > 0 && !isTypingRef.current) {
                startTyping();
                isTypingRef.current = true;
            }

            // Reset timeout on each keystroke
            clearTypingTimeout();

            if (value.length > 0) {
                // Stop typing after 3 seconds of inactivity
                typingTimeoutRef.current = setTimeout(() => {
                    stopTyping();
                    isTypingRef.current = false;
                }, typingTimeout);
            } else {
                // Stop immediately if input is cleared
                stopTyping();
                isTypingRef.current = false;
            }
        },
        [startTyping, stopTyping, clearTypingTimeout, typingTimeout]
    );

    const handleStopTyping = useCallback(() => {
        clearTypingTimeout();
        if (isTypingRef.current) {
            stopTyping();
            isTypingRef.current = false;
        }
    }, [stopTyping, clearTypingTimeout]);

    // Cleanup on unmount
    useEffect(() => {
        return () => {
            clearTypingTimeout();
            if (isTypingRef.current) {
                stopTyping();
            }
        };
    }, [clearTypingTimeout, stopTyping]);

    return { handleTyping, handleStopTyping };
};

4. Connecting Socket Events to React Query

This is where everything comes together. When a new message arrives via socket, invalidate the React Query cache:

useEffect(() => {
    if (!socket || !selectedChat?._id) return;

    const handleNewMessage = (data: { message: any; type: string }) => {
        // Invalidate cache to trigger refetch
        queryClient.invalidateQueries({
            queryKey: ["messages", selectedChat._id],
        });
    };

    socket.on("new-message", handleNewMessage);

    return () => {
        socket.off("new-message", handleNewMessage);
        handleStopTyping(); // Clean up typing indicator
    };
}, [socket, selectedChat?._id, queryClient, handleStopTyping]);

5. Infinite Scroll That Doesn't Break

The hardest part: maintaining scroll position when loading older messages. Here's an IntersectionObserver implementation that actually works:

useEffect(() => {
    const trigger = loadMoreTriggerRef.current;
    if (!trigger) return;

    const observer = new IntersectionObserver(
        (entries) => {
            const [entry] = entries;
            if (
                entry.isIntersecting &&
                hasNextPage &&
                !isFetchingNextPage &&
                !isSmoothScrolling // Prevent loading during auto-scroll
            ) {
                // Store current scroll position
                const container = messagesContainerRef.current;
                if (container) {
                    const scrollHeight = container.scrollHeight;
                    const scrollTop = container.scrollTop;

                    fetchNextPage().then(() => {
                        // Maintain scroll position after content loads
                        requestAnimationFrame(() => {
                            if (container) {
                                const newScrollHeight = container.scrollHeight;
                                const heightDifference = newScrollHeight - scrollHeight;
                                // Adjust scroll to keep current messages in view
                                container.scrollTop = scrollTop + heightDifference;
                            }
                        });
                    });
                }
            }
        },
        {
            root: messagesContainerRef.current,
            rootMargin: "50px", // Trigger before reaching the top
            threshold: 0,
        }
    );

    observer.observe(trigger);

    return () => {
        observer.disconnect();
    };
}, [hasNextPage, isFetchingNextPage, isSmoothScrolling, fetchNextPage]);

Common Pitfalls and Solutions

1. Multiple socket connections

Store socket instance in a separate file, import everywhere
Use React context for connection management

2. Stale closures in socket handlers

Always clean up listeners in useEffect returns
Be careful with dependencies

3. Infinite scroll jumping

Store scroll position before fetch
Restore after content loads using requestAnimationFrame

4. Typing indicators not clearing

Use timeouts with refs
Clear on component unmount
Clear when switching chats

Performance Optimizations

Debounce typing events - Don't emit on every keystroke
Virtualize long message lists - Use react-window for 1000+ messages
Lazy load images - Use IntersectionObserver for image previews
Batch socket events - Group rapid updates to reduce re-renders

Resources

IntersectionObserver Deep Dive - For infinite scroll mastery
Socket.io Client Options - Connection optimization

Next Steps

This setup handles the basics. To production-ready it:

Add reconnection logic with exponential backoff
Implement message queue for offline support
Add encryption for sensitive messages
Build message search with Elasticsearch
Add file upload with progress tracking

The hardest part isn't the individual features - it's making them work together without creating a mess. This architecture scales to thousands of concurrent users without major changes.

Questions or improvements? Drop them in the comments.

Stripe Subscriptions: The Gotchas That Cost Me 3 Weeks

Michal — Sun, 24 Aug 2025 23:07:47 +0000

I spent three weeks fighting Stripe's subscription API while building a multi-tenant SaaS. The documentation is comprehensive, but it buries critical details that you only discover when everything breaks. Here's what I wish someone had told me on day one.

Stripe's Confusing Terminology

These terms meant nothing to me at first. If you're confused too, you're not alone.

payment intent, invoice, subscription item, subscription, customer

Here's how they actually connect:

Customer → has Subscriptions → contain Subscription Items → generate Invoices → create Payment Intents

Quick definitions that would have saved me days:

customer - The Stripe object representing your user's payment profile
subscription - NOT your product's subscription tier, but a specific customer's active subscription instance
subscription item - Individual line items within a subscription (crucial for updates - more on this later)
invoice - Automatically generated via webhooks, controls payment completion status
payment intent - Handles one-time payments and the actual charge process

Stripe's 4 Integration Approaches

No-code customer portal - Great for MVPs, zero flexibility
Pre-built checkout - Stripe-hosted, limited customization
Advanced integration - Full control, maximum pain
Direct payment links - Works like the portal, good for invoicing

I went with option 3 because I needed custom checkout flows for a multi-tenant SaaS. Here's what the docs don't make clear.

Essential Resources Before You Start

Watch this first (seriously, it'll save you hours):

Stripe Payment Element Video

Then read:

Design an Integration Documentation

The diagram will confuse you initially. Quick tip: "Two-step confirmation" is just Amazon-style checkout (contact info → payment). I used "Collect payment details before creating an Intent" for single-page checkout.

The tutorial is straightforward for basic payments, but completely glosses over subscription handling and multi-tenant scenarios where you need both one-time purchases and subscriptions. Here's what's missing.

Critical Gotchas Nobody Mentions

1. Never Allow Guest Subscription Purchases

Sounds obvious? It's not. If you allow guests to buy subscriptions, you can't upgrade/downgrade them later without a massive headache. Force account creation first.

2. Stripe Prices are Immutable

You can't edit a price object in Stripe. Ever. You must:

Create new price objects for changes
Track active/inactive status in YOUR database
Archive old prices properly

I learned this after trying to update prices for 50 products.

3. Store Both Subscription ID and Subscription Item ID

This is the killer. Everyone stores the subscription ID. Nobody mentions you NEED the subscription item ID for updates.

// THIS WILL FAIL without the subscription item ID
await this.stripeClient.subscriptions.update(
  sub.stripeSubscriptionId,
  {
    items: [
      {
        id: sub.stripeSubscriptionItemId, // THIS is what everyone misses
        price: newStripePrice.id,
      },
    ],
    proration_behavior: 'none',
  },
);

Alternative: Use subscriptionSchedule for future-dated changes.

4. Idempotency Keys and Database Transactions are Mandatory

Not optional. Not "best practice." Mandatory. Without them, you'll have:

Duplicate subscriptions
Orphaned database records
Angry customers with multiple charges

Working Implementation

Database Schema

Here's my working schema (adjust for your needs):
Database Diagram

Key point: Prices are mirrored from Stripe with additional fields for your business logic.

Subscription Checkout Flow

The docs cover one-time payments here. Subscriptions are different. Here's what actually works:

async startSubscriptionCheckout(
  customer: UserEntity | OrganizationEntity,
  idempotencyKey: string,
  subscriptionRequest: CreateCheckoutDto,
) {
  // Validate your products/prices against Stripe
  const preparedItems =
    await this.subscriptionValidator.validateAndPrepareItems(
      subscriptionRequest,
    );

  // Create order in YOUR database first (as draft)
  const draftOrder = await this.orderManager.createDraftOrder(
    preparedItems,
    customer,
  );

  try {
    // Create Stripe subscription
    const subscriptionSession =
      await this.paymentGateway.createSubscriptionSession(
        customer,
        idempotencyKey,
        preparedItems,
      );

    // Link Stripe session to your order
    await this.orderManager.attachPayment(
      draftOrder.id.toString(),
      subscriptionSession.id,
      'subscription',
    );

    return {
      clientSecret: subscriptionSession.clientSecret,
    };
  } catch (error) {
    // Clean up on failure
    await this.orderManager.markAsFailed(draftOrder.id.toString());

    throw new BadRequestException(
      `Could not create subscription checkout: ${error}`,
    );
  }
}

The magic happens in creating the subscription with the right parameters:

private async createPaymentSubscription(
  customerId: string,
  preparedItems: SubscriptionItem[],
  idempotencyKey: string,
  customer: UserEntity | OrganizationEntity,
) {
  const subscription = await this.paymentProvider.subscriptions.create(
    {
      customer: customerId,
      items: preparedItems.map((item) => ({
        price: item.priceId,
        quantity: item.quantity,
      })),
      payment_behavior: 'default_incomplete', // Critical for checkout flow
      payment_settings: {
        save_default_payment_method: 'on_subscription', // Saves card for renewals
      },
      metadata: {
        type: 'subscription',
        customerId: customer.id.toString(), // Link to YOUR database
      },
      expand: ['latest_invoice.confirmation_secret'], // Need this for client-side confirmation
    },
    {
      idempotencyKey: `${customer.id.toString()}_${idempotencyKey}`,
    },
  );

  // Extract the client secret for payment element
  const invoice = subscription.latest_invoice as Invoice & {
    confirmation_secret?: {
      client_secret: string;
    };
  };

  if (!invoice || typeof invoice === 'string' || !invoice.confirmation_secret) {
    throw new BadGatewayException('Payment processing temporarily unavailable');
  }

  return {
    clientSecret: invoice.confirmation_secret.client_secret,
    id: subscription.id,
  };
}

Webhook Hell: What Actually Matters

You'll find 30+ webhook events. You need 4:

async handleWebhookEvent(signature: string, req: RawBodyRequest<Request>) {
  const event = this.constructEvent(signature, req);

  switch (event.type) {
    case 'payment_intent.succeeded':
      await this.handlePaymentIntentSucceeded(event.data.object);
      break;
    case 'payment_intent.payment_failed':
      await this.handlePaymentIntentFailed(event.data.object);
      break;
    case 'invoice.paid':
      await this.handleInvoicePaid(event.data.object);
      break;
    case 'invoice.payment_failed':
      await this.handleInvoiceFailed(event.data.object);
      break;
    default:
      console.warn(`Unhandled event type: ${event.type}`);
  }
  return { received: true };
}

Critical distinction:

payment_intent.* = One-time payments
invoice.* = Subscription payments

Filter them properly:

// In payment intent handlers
if (paymentIntent.invoice) {
  return; // Skip - this is subscription-related
}

// In invoice handlers
if (!invoice.subscription) {
  return; // Skip - this is a one-time invoice
}

NestJS Webhook Middleware

If you're using NestJS, raw body parsing is tricky. Here's what works:

import { json, Request, RequestHandler, Response } from 'express';

interface RequestWithRawBody extends Request {
  rawBody: Buffer;
}

function rawBodyMiddleware(): RequestHandler {
  return json({
    verify: (
      request: RequestWithRawBody,
      response: Response,
      buffer: Buffer,
    ) => {
      if (request.url === '/stripe-webhook' && Buffer.isBuffer(buffer)) {
        request.rawBody = Buffer.from(buffer);
      }
      return true;
    },
  });
}

export default rawBodyMiddleware;

Add to main.ts:

app.use(rawBodyMiddleware());

Resources That Actually Help

Complete webhook event types - Bookmark this
Subscription lifecycle - Read twice
Testing subscriptions - Use test clocks, not trial and error

Final Thoughts

Stripe's subscription API is powerful but assumes you already know the gotchas. You don't need to learn them the hard way like I did. Store subscription item IDs, handle webhooks correctly, use idempotency keys, and force authentication for subscriptions.

Questions? Hit me up in the comments. I've probably hit the same wall you're facing.