DEV Community: Aon infotech

Image Caching and CDN Strategies in Next.js — Getting Fast Image Delivery Right

Aon infotech — Mon, 29 Jun 2026 13:58:49 +0000

Image performance is usually the largest opportunity in a Next.js application. Images are often the heaviest assets on the page, the most likely LCP element, and the area where caching strategy has the most impact on user experience.

Here's what actually works for image caching and CDN delivery in Next.js App Router — including the patterns I've found necessary building an application where image delivery is literally the core product at pixova.io/blog/ai-generated-images-no-copyright.

How Next.js Image Optimization Works

Next.js built-in image optimization (next/image) handles several things automatically:

Format conversion — serves WebP or AVIF to browsers that support them, falling back to the original format
Size optimization — generates appropriately sized images based on the sizes attribute
Lazy loading — defers loading of off-screen images by default
Blur placeholder — shows a blurred version while the full image loads What it doesn't do: manage CDN caching headers in most deployment configurations, or give you control over the cache-control headers on generated images.

Cache-Control Headers — What Next.js Sets by Default

When Next.js serves an optimized image, it sets a cache-control header based on the minimumCacheTTL configuration:

// next.config.js
module.exports = {
  images: {
    minimumCacheTTL: 60, // 60 seconds (default)
  },
};

The default is 60 seconds — which means optimized images are only cached for 1 minute. For static images that don't change, this is extremely conservative and causes unnecessary re-requests.

Increase this for production:

module.exports = {
  images: {
    minimumCacheTTL: 31536000, // 1 year in seconds
    formats: ['image/avif', 'image/webp'],
  },
};

A year-long TTL is appropriate for images with content-addressed URLs (where the filename changes when the content changes). For images with stable filenames that might change, use a shorter TTL and rely on cache invalidation.

Remote Images and CDN Configuration

For images served from an external CDN or storage service, you need to explicitly allow the domain in next.config.js:

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'your-cdn.example.com',
        port: '',
        pathname: '/images/**',
      },
      {
        protocol: 'https',
        hostname: 'storage.example.com',
      },
    ],
  },
};

The pathname pattern limits which paths are allowed — good security practice to not permit /** on every domain.

Bypass Next.js Image Optimization for CDN-Served Images

If your images are already optimized and served from a CDN, Next.js's built-in optimization layer adds unnecessary processing overhead. You can bypass it with a custom loader:

// next.config.js
module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './lib/imageLoader.js',
  },
};

// lib/imageLoader.js
export default function cdnImageLoader({ src, width, quality }) {
  const url = new URL(src);
  url.searchParams.set('w', width.toString());
  url.searchParams.set('q', (quality || 75).toString());
  return url.toString();
}

This tells Next.js to use your custom loader function instead of its built-in optimization. The loader receives the source URL, requested width, and quality, and returns the URL to actually fetch.

Your CDN handles the transformation rather than Next.js — which is appropriate when your CDN's image transformation is faster or already caching transformed variants.

Static Image Optimization — The `public` Directory

Images in /public are served directly without Next.js processing. They have no built-in optimization, but they're also served with simpler, more predictable caching behavior.

For static assets that don't change, public is often the right choice. Cache these aggressively at the CDN/server level:

// next.config.js
async headers() {
  return [
    {
      source: '/images/:path*',
      headers: [
        {
          key: 'Cache-Control',
          value: 'public, max-age=31536000, immutable',
        },
      ],
    },
    {
      source: '/fonts/:path*',
      headers: [
        {
          key: 'Cache-Control',
          value: 'public, max-age=31536000, immutable',
        },
      ],
    },
  ];
},

The immutable directive tells browsers not to even send a validation request for the lifetime of the cache — the image will never change, so there's no point checking.

Vercel-Specific Considerations

On Vercel, Next.js image optimization runs on Vercel's infrastructure. The optimized images are cached at Vercel's edge CDN.

Key things to know:

Image optimization counts toward your Vercel usage. Each unique image+width combination that gets optimized counts toward your image optimization quota. Using sizes correctly reduces this by ensuring you're not generating more size variants than necessary.

Cache is per-region by default. A user in Singapore and a user in New York might both trigger optimization of the same image in different regions. The minimumCacheTTL helps here — longer TTL means the cached version in each region persists longer.

Vercel's Image Optimization API can be called directly if you need programmatic control:

// Construct a Vercel-optimized image URL directly
function getVercelOptimizedUrl(src, width) {
  return `/_next/image?url=${encodeURIComponent(src)}&w=${width}&q=75`;
}

Preloading Critical Images

For images that will definitely be in the viewport on load (LCP candidates), preload them in the <head>:

// app/layout.js
export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <link
          rel="preload"
          as="image"
          href="/hero-image.webp"
          type="image/webp"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Or use <Image> with priority:

<Image
  src="/hero-image.webp"
  alt="Hero"
  width={1200}
  height={630}
  priority // Adds preload link automatically
/>

The priority prop adds a preload link automatically — use it on the LCP image and nothing else.

Measuring Cache Performance

A few things worth monitoring:

Cache hit rate — what percentage of image requests are served from cache versus hitting origin. High miss rate suggests either TTL is too short or you have too many unique image variants.

Image size distribution — are you serving appropriately sized images for mobile vs desktop? The sizes attribute on <Image> should reflect actual rendered sizes.

LCP timing by device — mobile LCP is almost always worse than desktop for image-heavy pages. If mobile LCP is poor, the image is either not preloaded, too large, or the CDN isn't close enough to mobile users.

Check these in Chrome DevTools (Network tab, filter by Img, check response headers for Cache-Control and X-Cache headers) and in Search Console's Core Web Vitals report for field data.

The Configuration That Actually Works

After a lot of iteration, here's the Next.js image configuration that performs well in production:

// next.config.js
module.exports = {
  images: {
    minimumCacheTTL: 2592000, // 30 days
    formats: ['image/avif', 'image/webp'],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920],
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
    remotePatterns: [
      // Add your CDN domains here
    ],
  },
  async headers() {
    return [
      {
        source: '/_next/static/:path*',
        headers: [
          { key: 'Cache-Control', value: 'public, max-age=31536000, immutable' },
        ],
      },
    ];
  },
};

30-day cache TTL for dynamically optimized images, year-long for static assets, AVIF and WebP format negotiation, explicit device size breakpoints that match your actual layout breakpoints.

Stale-While-Revalidate for Dynamic Images

For images that update occasionally but should load fast, the stale-while-revalidate cache directive is useful:

async headers() {
  return [
    {
      source: '/api/generated/:path*',
      headers: [
        {
          key: 'Cache-Control',
          // Serve stale for up to 24h while revalidating in background
          value: 'public, max-age=3600, stale-while-revalidate=86400',
        },
      ],
    },
  ];
},

This tells clients: "This image is fresh for 1 hour. After that, serve the stale version immediately while fetching a fresh one in the background." The user gets a fast response, the cache stays reasonably fresh.

Content-Addressed URLs — The Clean Solution

The cleanest approach to image caching is content-addressed URLs: the filename includes a hash of the content, so the URL changes whenever the content changes.

// lib/imageUrl.ts
import crypto from 'crypto';

export function getContentAddressedUrl(content: Buffer): string {
  const hash = crypto
    .createHash('md5')
    .update(content)
    .digest('hex')
    .slice(0, 8);
  return `/images/${hash}.webp`;
}

With content-addressed URLs, you can set very long cache TTLs (1 year or longer) because the URL literally changes when the content changes. Old URLs automatically become stale when content updates because nothing links to them anymore.

This is the pattern static site generators and bundlers use for JavaScript and CSS. Applying it to images gives you the same reliable caching behavior without worrying about stale content.

Building a Type-Safe API Layer in Next.js App Router With Zod and Server Actions

Aon infotech — Sun, 28 Jun 2026 07:10:56 +0000

Server Actions in Next.js App Router look deceptively simple — write an async function, mark it with 'use server', call it from a Client Component. The surface area is small.

The problems surface when you start thinking about validation, error handling, and type safety across the client-server boundary. Without a deliberate approach, you end up with untyped form data on the server, error handling that varies across actions, and client code that can't trust the shape of what comes back.

Here's the pattern I landed on for type-safe Server Actions with Zod validation and consistent error handling, from building the generation pipeline powering the free AI wallpaper maker at pixova.io.

The Problem With Naive Server Actions

The simplest Server Action works fine for prototypes:

'use server';

export async function submitForm(formData: FormData) {
  const prompt = formData.get('prompt') as string;
  // No validation, no type safety, any error handling is ad hoc
  const result = await generateImage(prompt);
  return result;
}

The issues:

formData.get('prompt') returns string | null | File — the as string cast hides a bug waiting to happen
No validation means invalid input reaches your business logic
Error handling is whatever you add ad hoc to each action

- The return type isn't defined, so the client has no type information

The Foundation — A Result Type

Start with a discriminated union for action results:

// lib/types/action.ts
export type ActionSuccess<T> = {
  success: true;
  data: T;
};

export type ActionError = {
  success: false;
  error: string;
  fieldErrors?: Record<string, string[]>;
};

export type ActionResult<T> = ActionSuccess<T> | ActionError;

Every Server Action returns Promise<ActionResult<T>>. The client always knows whether the action succeeded and what shape the data has.

Adding Zod Validation

// lib/schemas/generate.ts
import { z } from 'zod';

export const GenerateSchema = z.object({
  prompt: z
    .string()
    .min(3, 'Prompt must be at least 3 characters')
    .max(500, 'Prompt must be under 500 characters')
    .trim(),
  aspectRatio: z.enum(['1:1', '16:9', '9:16', '4:5']).default('1:1'),
  style: z.string().optional(),
});

export type GenerateInput = z.infer<typeof GenerateSchema>;

The Server Action With Full Type Safety

// app/actions/generate.ts
'use server';

import { z } from 'zod';
import { GenerateSchema, GenerateInput } from '@/lib/schemas/generate';
import { ActionResult } from '@/lib/types/action';

type GenerateResult = {
  jobId: string;
  estimatedSeconds: number;
};

export async function generateImageAction(
  input: GenerateInput
): Promise<ActionResult<GenerateResult>> {
  // Validate — even though TypeScript already knows the type,
  // runtime validation catches anything that slips through
  const parsed = GenerateSchema.safeParse(input);

  if (!parsed.success) {
    return {
      success: false,
      error: 'Invalid input',
      fieldErrors: parsed.error.flatten().fieldErrors as Record<string, string[]>,
    };
  }

  try {
    const { prompt, aspectRatio, style } = parsed.data;

    // Your business logic here
    const job = await submitGenerationJob({ prompt, aspectRatio, style });

    return {
      success: true,
      data: {
        jobId: job.id,
        estimatedSeconds: job.estimatedDuration,
      },
    };
  } catch (error) {
    // Log server-side for debugging
    console.error('Generation failed:', error);

    // Return user-friendly error to client
    return {
      success: false,
      error: 'Generation failed. Please try again.',
    };
  }
}

The Client-Side Hook

// hooks/useGenerate.ts
'use client';

import { useState, useTransition } from 'react';
import { generateImageAction } from '@/app/actions/generate';
import { GenerateInput } from '@/lib/schemas/generate';

export function useGenerate() {
  const [isPending, startTransition] = useTransition();
  const [result, setResult] = useState<{ jobId: string } | null>(null);
  const [error, setError] = useState<string | null>(null);

  const generate = (input: GenerateInput) => {
    setError(null);
    setResult(null);

    startTransition(async () => {
      const response = await generateImageAction(input);

      if (response.success) {
        setResult({ jobId: response.data.jobId });
      } else {
        setError(response.error);
      }
    });
  };

  return { generate, isPending, result, error };
}

The Form Component

// components/GenerateForm.tsx
'use client';

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { GenerateSchema, GenerateInput } from '@/lib/schemas/generate';
import { useGenerate } from '@/hooks/useGenerate';

export function GenerateForm() {
  const { generate, isPending, error } = useGenerate();

  const { register, handleSubmit, formState: { errors } } = useForm<GenerateInput>({
    resolver: zodResolver(GenerateSchema),
    defaultValues: {
      aspectRatio: '1:1',
    },
  });

  return (
    <form onSubmit={handleSubmit(generate)} className="flex flex-col gap-4">
      <div>
        <textarea
          {...register('prompt')}
          placeholder="Describe what you want to generate..."
          className="w-full p-3 rounded-xl border border-border bg-card 
            text-foreground resize-none h-24 focus:outline-none 
            focus:ring-2 focus:ring-orange-500"
        />
        {errors.prompt && (
          <p className="text-sm text-red-500 mt-1">{errors.prompt.message}</p>
        )}
      </div>

      <select
        {...register('aspectRatio')}
        className="p-2 rounded-lg border border-border bg-card text-foreground"
      >
        <option value="1:1">Square (1:1)</option>
        <option value="16:9">Landscape (16:9)</option>
        <option value="9:16">Portrait (9:16)</option>
        <option value="4:5">Instagram (4:5)</option>
      </select>

      {error && (
        <p className="text-sm text-red-500">{error}</p>
      )}

      <button
        type="submit"
        disabled={isPending}
        className="px-6 py-3 bg-orange-500 text-white rounded-full 
          font-medium hover:bg-orange-600 transition-colors
          disabled:opacity-50 disabled:cursor-not-allowed"
      >
        {isPending ? 'Generating...' : 'Generate'}
      </button>
    </form>
  );
}

A Reusable Action Wrapper

For larger applications with many actions, a wrapper reduces boilerplate:

// lib/action-wrapper.ts
import { z } from 'zod';
import { ActionResult } from './types/action';

export function createAction<TInput, TOutput>(
  schema: z.ZodSchema<TInput>,
  handler: (input: TInput) => Promise<TOutput>
) {
  return async (input: unknown): Promise<ActionResult<TOutput>> => {
    const parsed = schema.safeParse(input);

    if (!parsed.success) {
      return {
        success: false,
        error: 'Validation failed',
        fieldErrors: parsed.error.flatten().fieldErrors as Record<string, string[]>,
      };
    }

    try {
      const data = await handler(parsed.data);
      return { success: true, data };
    } catch (error) {
      console.error('Action error:', error);
      return { 
        success: false, 
        error: error instanceof Error ? error.message : 'Something went wrong' 
      };
    }
  };
}

// Usage
export const generateImageAction = createAction(
  GenerateSchema,
  async (input) => {
    const job = await submitGenerationJob(input);
    return { jobId: job.id };
  }
);

The Payoff

With this pattern in place:

Every action has a consistent interface — ActionResult<T>
Validation errors surface to the client with field-level detail
TypeScript knows the exact shape of success and error responses
Error handling is centralized rather than ad hoc per action
Adding a new action means writing the schema and handler — the boilerplate is handled The upfront investment in the wrapper and types pays off quickly across a codebase with more than a handful of Server Actions.

Testing Server Actions

Server Actions are async functions — they're straightforward to unit test:

// __tests__/actions/generate.test.ts
import { generateImageAction } from '@/app/actions/generate';

// Mock the generation service
jest.mock('@/lib/generation', () => ({
  submitGenerationJob: jest.fn(),
}));

import { submitGenerationJob } from '@/lib/generation';
const mockSubmit = submitGenerationJob as jest.Mock;

describe('generateImageAction', () => {
  it('returns success with valid input', async () => {
    mockSubmit.mockResolvedValue({ id: 'job-123', estimatedDuration: 8 });

    const result = await generateImageAction({
      prompt: 'A sunset over mountains',
      aspectRatio: '16:9',
    });

    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.jobId).toBe('job-123');
    }
  });

  it('returns validation error for short prompt', async () => {
    const result = await generateImageAction({
      prompt: 'hi', // Too short
      aspectRatio: '1:1',
    });

    expect(result.success).toBe(false);
    if (!result.success) {
      expect(result.fieldErrors?.prompt).toBeDefined();
    }
  });

  it('returns error when service throws', async () => {
    mockSubmit.mockRejectedValue(new Error('Service unavailable'));

    const result = await generateImageAction({
      prompt: 'A valid prompt that is long enough',
      aspectRatio: '1:1',
    });

    expect(result.success).toBe(false);
  });
});

Testing with the ActionResult type makes assertions clean — the discriminated union means TypeScript narrows the type inside the if (result.success) block, so you get full type checking on both success and error paths.

Common Pitfalls

Forgetting that Server Actions run on the server. They don't have access to window, document, or browser APIs. If you're calling a Server Action from a component that also uses browser APIs, make sure the action itself doesn't try to use them.

Not handling revalidatePath or revalidateTag after mutations. If an action mutates data and the page should reflect that, you need to explicitly invalidate the cache:

import { revalidatePath } from 'next/cache';

export async function deleteItem(id: string): Promise<ActionResult<void>> {
  try {
    await db.items.delete(id);
    revalidatePath('/items'); // Update the cache
    return { success: true, data: undefined };
  } catch {
    return { success: false, error: 'Failed to delete item' };
  }
}

Passing complex objects when primitives work. Server Actions serialize arguments across the network. Simple types (strings, numbers, plain objects) serialize cleanly. Class instances, functions, and non-serializable objects don't. Keep action inputs to JSON-serializable types.

Skeleton Loading Screens in Next.js App Router — The Right Way to Handle Async UI

Aon infotech — Sat, 27 Jun 2026 05:47:23 +0000

Skeleton screens are one of those things that seem simple until you actually implement them well. The basic idea is straightforward: show a placeholder shaped like the content while it loads. The execution has a lot of ways to go wrong.

Here's what actually works in Next.js App Router, from the patterns I've landed on after a lot of iteration building free AI image generator high quality where loading states are visible on almost every interaction.

Why Skeletons Beat Spinners for Most Cases

A spinner communicates "something is happening." A skeleton communicates "here's roughly what you're about to see." That distinction matters more than it sounds.

Users who see a skeleton can start mentally orienting to the layout before content arrives. They're not staring at an empty space trying to remember what was supposed to appear there. The cognitive load is lower, and the perceived wait time is shorter — not because the content actually loads faster, but because the user's brain is doing useful work during the wait.

The exception: if content will arrive in under 200ms, show nothing. A skeleton that flashes briefly is more disorienting than just waiting for the content.

The Suspense Boundary Pattern

App Router's native approach uses React Suspense with a loading.js file or inline Suspense boundaries:

// app/dashboard/loading.js — automatic Suspense wrapper
export default function DashboardLoading() {
  return <DashboardSkeleton />;
}

// Inline Suspense for granular control
import { Suspense } from 'react';

export default function Page() {
  return (
    <div>
      <h1>Dashboard</h1>
      <Suspense fallback={<StatsSkeleton />}>
        <Stats />
      </Suspense>
      <Suspense fallback={<FeedSkeleton />}>
        <ActivityFeed />
      </Suspense>
    </div>
  );
}

The inline approach lets different sections load independently — the stats can show while the activity feed is still loading. This is often better UX than waiting for everything.

Building the Skeleton Components

The skeleton needs to match the real component's dimensions exactly. This is where most implementations go wrong — a skeleton that's 40px shorter than the content it replaces causes layout shift when content loads.

// The real component
function UserCard({ user }) {
  return (
    <div className="flex items-center gap-3 p-4 rounded-xl border border-border">
      <img 
        src={user.avatar} 
        alt={user.name}
        className="w-10 h-10 rounded-full"
      />
      <div className="flex flex-col">
        <span className="text-sm font-medium text-foreground">{user.name}</span>
        <span className="text-xs text-muted">{user.email}</span>
      </div>
    </div>
  );
}

// The skeleton — identical structure, shimmer instead of content
function UserCardSkeleton() {
  return (
    <div className="flex items-center gap-3 p-4 rounded-xl border border-border">
      <div className="w-10 h-10 rounded-full bg-neutral-200 dark:bg-neutral-700 animate-pulse" />
      <div className="flex flex-col gap-1.5">
        <div className="h-4 w-32 rounded bg-neutral-200 dark:bg-neutral-700 animate-pulse" />
        <div className="h-3 w-24 rounded bg-neutral-200 dark:bg-neutral-700 animate-pulse" />
      </div>
    </div>
  );
}

Key things to match exactly:

Padding and margins (the p-4 and gap-3)
Element dimensions (w-10 h-10 for the avatar, specific widths for text lines)
Border and border-radius

- The flex/grid layout structure

The Shimmer Animation

animate-pulse from Tailwind is the quickest approach — it fades the element opacity up and down. For a more polished shimmer effect:

/* globals.css */
@keyframes shimmer {
  0% { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}

.skeleton-shimmer {
  background: linear-gradient(
    90deg,
    rgb(var(--skeleton-base)) 25%,
    rgb(var(--skeleton-highlight)) 50%,
    rgb(var(--skeleton-base)) 75%
  );
  background-size: 200% 100%;
  animation: shimmer 1.5s infinite;
}

/* In your theme */
:root {
  --skeleton-base: 229 231 235;      /* neutral-200 */
  --skeleton-highlight: 243 244 246; /* neutral-100 */
}

.dark {
  --skeleton-base: 38 38 38;         /* neutral-800 */
  --skeleton-highlight: 55 55 55;    /* neutral-700 */
}

The directional shimmer feels more intentional than the pulse — it suggests something is actively loading rather than just waiting.

Lists of Unknown Length

When you don't know how many items will load, skeletons need a sensible count. I use three as the default:

function ListSkeleton({ count = 3 }) {
  return (
    <div className="flex flex-col gap-3">
      {Array.from({ length: count }).map((_, i) => (
        <ItemSkeleton key={i} />
      ))}
    </div>
  );
}

Pick a number that represents a typical result set for your content. If users usually see 8-10 items, show 8 skeleton items. Showing 3 when 10 arrive causes a larger layout shift than showing a count closer to the actual result.

Avoiding the Double Flash

One subtle issue: if data loads very fast (under 200ms), the user sees the skeleton flash briefly before content appears. This can actually feel worse than no skeleton.

'use client';
import { useState, useEffect } from 'react';

function useDeferredLoading(isLoading, delay = 200) {
  const [showSkeleton, setShowSkeleton] = useState(false);

  useEffect(() => {
    if (!isLoading) {
      setShowSkeleton(false);
      return;
    }

    const timer = setTimeout(() => {
      setShowSkeleton(true);
    }, delay);

    return () => clearTimeout(timer);
  }, [isLoading, delay]);

  return showSkeleton;
}

// Usage
function Component() {
  const { data, isLoading } = useSomeData();
  const showSkeleton = useDeferredLoading(isLoading);

  if (showSkeleton) return <ComponentSkeleton />;
  if (!data) return null;
  return <ComponentContent data={data} />;
}

This only shows the skeleton if loading takes longer than 200ms. Fast loads show nothing, and the content just appears. Slower loads get the skeleton treatment.

The Skeleton Component Library Pattern

For larger applications, a shared skeleton primitive keeps things consistent:

// components/ui/Skeleton.jsx
function Skeleton({ className, ...props }) {
  return (
    <div
      className={cn(
        "animate-pulse rounded-md bg-neutral-200 dark:bg-neutral-700",
        className
      )}
      {...props}
    />
  );
}

// Usage in feature skeletons
function ProductCardSkeleton() {
  return (
    <div className="space-y-3 p-4">
      <Skeleton className="h-48 w-full rounded-xl" />
      <Skeleton className="h-4 w-3/4" />
      <Skeleton className="h-3 w-1/2" />
      <div className="flex gap-2">
        <Skeleton className="h-8 w-20" />
        <Skeleton className="h-8 w-16" />
      </div>
    </div>
  );
}

The cn utility (clsx + tailwind-merge) handles the class merging. This pattern makes it easy to compose skeletons from a consistent primitive.

What I Built This On

The skeleton patterns above are running in production handling the generation loading state at pixova.io — the placeholder appears at the exact dimensions of the output image (aspect ratio selected before generation), so there's zero layout shift when the image arrives. The deferred loading hook prevents a flash when generation completes faster than expected.

Questions on specific skeleton scenarios? Comments open.

Common Mistakes I've Made With Skeletons

Matching width but not height. Text lines in skeletons are often set to h-4 (16px) but the actual rendered text at that font size is more like 20px with line height. Measure the real component, don't estimate.

Forgetting dark mode. bg-neutral-200 looks fine in light mode and nearly invisible against a dark background. Always add the dark mode variant: bg-neutral-200 dark:bg-neutral-700.

Using skeletons for errors. A skeleton that never resolves because there's an error underneath is confusing — users sit watching a shimmer that will never become content. Always have a clear error state that replaces the skeleton when something fails.

Too many simultaneous animations. A page with 20 elements all pulsing at slightly different rates creates visual noise. Either sync the animation timing or use a single shimmer direction across all skeletons so they feel coordinated.

Skeletons that don't match responsive behavior. Your card might be full-width on mobile and 50% on desktop. Your skeleton should match both. Use the same responsive classes on the skeleton wrapper that you use on the real component.

A Testing Approach That Actually Helps

Throttle your network in DevTools (Network tab → No throttling dropdown → Slow 3G) and reload pages with your skeleton implementation. Things to check:

Does the skeleton appear before content? (It should)
Does content replace the skeleton without any layout shift? (Measure with Chrome's CLS recording)
Does the skeleton look obviously different from the real content's shape? (It shouldn't — adjust dimensions)
Does it look okay in dark mode? (Switch and check)

Slow 3G throttling surfaces layout shift issues that you'd miss at normal speeds. Worth doing before shipping any new skeleton implementation.

Optimizing Next.js App Router for Core Web Vitals — A Practical Guide

Aon infotech — Tue, 23 Jun 2026 05:33:27 +0000

Core Web Vitals have been a ranking factor for a while, but App Router introduced new patterns that affect how you optimize for them. Some old approaches don't apply. Some new ones are surprisingly easy to miss.

Here's what actually moves the needle for LCP, CLS, and INP in a Next.js App Router application — from lessons building a production app — the same patterns power the free AI image generator high quality output at pixova.io.

The Three Metrics — What Changed in App Router

LCP (Largest Contentful Paint): The largest visible element loading fast. In App Router, Server Components help here because content can start streaming before JavaScript loads. But images are still the most common LCP element and need explicit attention.

CLS (Cumulative Layout Shift): Visual stability — elements not jumping around as the page loads. App Router's streaming model can actually make CLS worse if you're not careful about skeleton sizing.

INP (Interaction to Next Paint): Replaced FID as a metric in 2024. Measures responsiveness to user interactions. React's concurrent rendering in App Router helps here, but heavy Client Components can still block the main thread.

LCP — The Image Problem

The most common LCP failure in Next.js applications: images that load too slowly, or that aren't identified as the LCP element.

Step 1 — Identify your LCP element

Open Chrome DevTools → Performance → record a page load → look for the LCP marker. In most content-heavy pages, it's an image. In App Router applications, it might be a server-rendered text block.

Step 2 — Add priority to your LCP image

// Without priority — image loads lazily (wrong for LCP)
<Image src={heroImage} alt="Hero" width={1200} height={630} />

// With priority — image preloaded immediately (correct for LCP)
<Image 
  src={heroImage} 
  alt="Hero" 
  width={1200} 
  height={630}
  priority  // Only use on above-the-fold LCP images
/>

priority tells Next.js to preload this image and skip lazy loading. Only use it on the single LCP element — adding it to multiple images defeats the purpose.

Step 3 — Preconnect to external image domains

// app/layout.js
export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <link rel="preconnect" href="https://your-cdn.com" />
        <link rel="dns-prefetch" href="https://your-cdn.com" />
      </head>
      <body>{children}</body>
    </html>
  );
}

This starts the connection to your image CDN before the image request fires, saving DNS lookup and TLS handshake time.

Step 4 — Use proper sizes attribute

// Wrong — browser downloads full-size image for mobile
<Image src={image} alt="" width={1200} height={630} />

// Right — browser downloads appropriate size for viewport
<Image 
  src={image} 
  alt=""
  fill
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
/>

The sizes attribute tells the browser what size the image will be rendered at, letting it download the appropriately sized version instead of always downloading the full-size image.

CLS — The Streaming Problem

App Router's streaming with Suspense is excellent for performance, but introduces a CLS risk: if Suspense boundaries don't have sized fallbacks, content below them shifts when they resolve.

// CLS problem — unsized fallback causes layout shift
<Suspense fallback={<div>Loading...</div>}>
  <UserProfile />
</Suspense>

// CLS fixed — fallback matches expected content size
<Suspense fallback={<UserProfileSkeleton />}>
  <UserProfile />
</Suspense>

// UserProfileSkeleton — must match UserProfile dimensions exactly
function UserProfileSkeleton() {
  return (
    <div className="flex items-center gap-3 p-4">
      <div className="w-10 h-10 rounded-full bg-neutral-200 animate-pulse" />
      <div className="flex flex-col gap-2">
        <div className="h-4 w-32 bg-neutral-200 rounded animate-pulse" />
        <div className="h-3 w-24 bg-neutral-200 rounded animate-pulse" />
      </div>
    </div>
  );
}

The rule: Every Suspense boundary fallback must be dimensionally identical to what it's replacing. Any size difference between fallback and resolved content = CLS.

CLS — Font Loading

Custom fonts are another common CLS source. Text renders in the fallback font, then shifts when the custom font loads.

// app/layout.js
import { Inter } from 'next/font/google';

const inter = Inter({ 
  subsets: ['latin'],
  display: 'swap',     // Show fallback font immediately
  preload: true,       // Preload font files
  // Optional: reduce FOUT with size-adjust
  adjustFontFallback: true,
});

export default function RootLayout({ children }) {
  return (
    <html className={inter.className}>
      <body>{children}</body>
    </html>
  );
}

next/font handles font optimization automatically — it self-hosts Google Fonts, eliminates the network request to Google's servers, and generates size-adjust CSS to reduce the visual shift when the font loads.

INP — Client Component Optimization

INP measures how quickly the page responds to user input. Long tasks on the main thread cause high INP. In App Router, the main culprits:

Heavy Client Components loading too early:

// Loads everything upfront — heavy JS bundle blocks INP
import { HeavyEditor } from '@/components/HeavyEditor';

// Better — loads only when needed
import dynamic from 'next/dynamic';
const HeavyEditor = dynamic(() => import('@/components/HeavyEditor'), {
  loading: () => <EditorSkeleton />,
  ssr: false, // Client-only component
});

Event handlers doing too much synchronously:

// INP problem — blocks main thread for 200ms
function handleClick() {
  const result = heavyComputation(); // Blocks
  setResult(result);
}

// Better — yield between chunks (keeps thread free for input)
async function handleClick() {
  // Immediate UI feedback
  setIsLoading(true);

  // Option 1: chunked work with yielding
  for (const chunk of dataChunks) {
    processChunk(chunk);
    await scheduler.yield(); // browser can handle input between chunks
  }

  // Option 2: genuinely heavy computation → Web Worker
  // const worker = new Worker('computation.js');
  // worker.postMessage(data);
  // worker.onmessage = (e) => { setResult(e.data); setIsLoading(false); };

  setIsLoading(false);
}

Measuring Progress

Don't rely on Lighthouse scores alone — they're simulated and don't reflect real user experience. Use these alongside:

PageSpeed Insights — runs Lighthouse but also shows field data from Chrome UX Report (real users, not simulation).

Google Search Console → Core Web Vitals — actual performance data from your real visitors, segmented by mobile/desktop.

Web Vitals library for in-app measurement:

import { onLCP, onCLS, onINP } from 'web-vitals';

onLCP(metric => sendToAnalytics(metric));
onCLS(metric => sendToAnalytics(metric));
onINP(metric => sendToAnalytics(metric));

Simulate → measure in field → fix → repeat. Lab scores that don't match field data usually mean the simulation is missing something about your real environment.

The Checklist

[ ] LCP image has priority prop
[ ] LCP image has correct sizes attribute
[ ] CDN domain has preconnect link
[ ] All Suspense fallbacks match resolved content dimensions
[ ] Fonts use next/font (not <link> to Google Fonts)
[ ] Heavy Client Components are dynamically imported
[ ] Event handlers don't block the main thread
[ ] Measuring with field data, not just Lighthouse Most Core Web Vitals improvements come from fixing one or two specific issues, not broad optimization. Identify the actual problem in field data first, then fix that.

Common Mistakes I Made (And Fixed)

Mistake 1: priority on every above-fold image

I added priority to four images thinking "more is better." It broke the preload order — the browser couldn't prioritize when everything claimed priority. Fixed: priority on one LCP image only.

Mistake 2: Suspense fallbacks that were too short

A Suspense boundary with a one-line "Loading..." fallback replaced a card that was 200px tall. The 190px shift when content resolved was catastrophic for CLS. Fixed: skeleton components that exactly match resolved component dimensions.

Mistake 3: Measuring only with Lighthouse

Lighthouse showed a 90 performance score. Real users on mobile 4G were seeing 4+ second LCP. The simulation doesn't model real network conditions accurately. Fixed: monitoring with Search Console field data as the source of truth.

Mistake 4: Importing all icons at component level

// Wrong — imports entire icon library
import * as Icons from 'react-icons/all';

// Right — imports only what's needed
import { FiDownload, FiShare } from 'react-icons/fi';

Tree-shaking requires named imports. Default imports of entire libraries bypass tree-shaking and bloat the bundle significantly.

Real Numbers

After working through this checklist on a production application:

LCP improved from 4.2s to 1.8s (mobile, 75th percentile field data)
CLS dropped from 0.18 to 0.02 (CLS threshold is 0.1)
INP improved from 340ms to 95ms The LCP improvement came entirely from priority + preconnect. The CLS fix was entirely skeleton sizing. The INP improvement was dynamic importing of a heavy client component.

Three fixes, significant results. Core Web Vitals optimization is usually like this — find the specific bottleneck, fix it precisely, measure the improvement.

Update: Thanks to @nazar_boyko for
catching this — setTimeout defers work but the main thread still
blocks during computation. scheduler.yield() or a Web Worker are
the correct approaches for genuine INP improvement.

Error Boundaries in Next.js App Router — Handling Failures Gracefully

Aon infotech — Mon, 22 Jun 2026 08:53:21 +0000

Most Next.js applications handle the happy path well. A request comes in, data loads, components render, user sees the page. Error handling is where applications often reveal their real quality — and where App Router introduces some nuances worth understanding.

Here's how error boundaries work in App Router, what the error.js file actually does, and the patterns that make failure handling feel intentional rather than afterthought. This is the approach I use in production for a free AI image generator for beginners where graceful degradation matters more than on sites with simpler data flows.

What Changes in App Router

Pages Router had _error.js and getInitialProps for error handling. App Router introduces a different model built on React's Error Boundary concept, with error.js files that can be nested at any level of the route hierarchy.

The key mental model shift: errors are contained at the nearest error.js boundary, not propagated to a global handler. This means you can have different error UIs for different sections of your app.

The `error.js` File

Place an error.js file in any route segment to catch errors in that segment and its children:

app/
├── layout.js          # Root layout
├── error.js           # Catches errors in root segment
├── page.js
├── dashboard/
│   ├── error.js       # Catches errors in dashboard only
│   ├── layout.js
│   └── page.js
└── blog/
    ├── error.js       # Catches errors in blog only
    └── [slug]/
        └── page.js

// app/error.js
'use client'; // Error components must be Client Components

import { useEffect } from 'react';

export default function Error({ error, reset }) {
  useEffect(() => {
    // Log to error reporting service
    console.error(error);
  }, [error]);

  return (
    <div className="flex flex-col items-center justify-center 
      min-h-[400px] gap-4 p-6 text-center">
      <h2 className="text-xl font-semibold text-foreground">
        Something went wrong
      </h2>
      <p className="text-sm text-muted max-w-sm">
        {error.message || 'An unexpected error occurred.'}
      </p>
      <button
        onClick={reset}
        className="px-4 py-2 bg-orange-500 text-white 
          rounded-full text-sm font-medium 
          hover:bg-orange-600 transition-colors"
      >
        Try again
      </button>
    </div>
  );
}

Important: error.js must be a Client Component ('use client'). React Error Boundaries are a client-side concept — server errors get converted to client-side error events before reaching the boundary.

The reset function retries the failed render. Use it for transient errors (network issues, temporary service failures) rather than permanent ones.

The `reset` Function — When to Show It

The reset button only makes sense for errors that might succeed on retry:

export default function Error({ error, reset }) {
  // Check if error is retryable
  const isRetryable = error.digest !== 'NEXT_NOT_FOUND';

  return (
    <div className="error-container">
      <h2>Something went wrong</h2>
      <p>{getErrorMessage(error)}</p>

      {isRetryable && (
        <button onClick={reset}>Try again</button>
      )}

      {!isRetryable && (
        <a href="/">Return home</a>
      )}
    </div>
  );
}

function getErrorMessage(error) {
  if (error.message?.includes('fetch')) {
    return 'Failed to load data. Check your connection.';
  }
  if (error.message?.includes('timeout')) {
    return 'Request timed out. Please try again.';
  }
  return 'An unexpected error occurred.';
}

Global Error Handling — `global-error.js`

The root error.js doesn't catch errors in the root layout.js. For that, you need global-error.js:

// app/global-error.js
'use client';

export default function GlobalError({ error, reset }) {
  return (
    <html>
      <body>
        <div className="global-error">
          <h1>Application Error</h1>
          <p>Something went wrong at the application level.</p>
          <button onClick={reset}>Reload</button>
        </div>
      </body>
    </html>
  );
}

global-error.js replaces the root layout when it renders, so it needs to include <html> and <body> tags. This is the last-resort catch for errors that escape all other boundaries.

Server Component Error Handling

Server components can throw errors directly, but handling them well requires a pattern slightly different from what you might expect:

// app/blog/[slug]/page.js
async function getBlogPost(slug) {
  const response = await fetch(`/api/posts/${slug}`);

  if (response.status === 404) {
    notFound(); // Triggers not-found.js, not error.js
  }

  if (!response.ok) {
    throw new Error(`Failed to fetch post: ${response.status}`);
    // This triggers error.js
  }

  return response.json();
}

export default async function BlogPost({ params }) {
  const post = await getBlogPost(params.slug);
  return <PostContent post={post} />;
}

notFound() vs throw Error(): Use notFound() for expected missing resources — it renders not-found.js and returns a 404 status. Use throw for unexpected failures — it renders error.js.

The `not-found.js` File

For 404-style errors, not-found.js provides a cleaner separation than error.js:

// app/not-found.js
import Link from 'next/link';

export default function NotFound() {
  return (
    <div className="flex flex-col items-center justify-center 
      min-h-[400px] gap-4 text-center p-6">
      <h2 className="text-2xl font-semibold">Page not found</h2>
      <p className="text-muted text-sm">
        The page you're looking for doesn't exist or has been moved.
      </p>
      <Link 
        href="/"
        className="px-4 py-2 bg-foreground text-background 
          rounded-full text-sm font-medium"
      >
        Return home
      </Link>
    </div>
  );
}

Error Boundaries for Async Operations in Client Components

Client components that fetch data need their own error handling since they're outside the server component error flow:

'use client';
import { useState, useEffect } from 'react';

export function DataFetcher({ url }) {
  const [data, setData] = useState(null);
  const [error, setError] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchData() {
      try {
        setLoading(true);
        setError(null);
        const response = await fetch(url);
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        const json = await response.json();
        setData(json);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    fetchData();
  }, [url]);

  if (loading) return <Skeleton />;

  if (error) return (
    <div className="error-inline">
      <p className="text-sm text-red-500">{error}</p>
      <button 
        onClick={() => fetchData()}
        className="text-xs text-muted hover:text-foreground"
      >
        Retry
      </button>
    </div>
  );

  return <DataDisplay data={data} />;
}

Error Reporting Integration

error.js is the right place to integrate with error monitoring:

'use client';
import { useEffect } from 'react';

export default function Error({ error, reset }) {
  useEffect(() => {
    // Send to your error monitoring service
    reportError({
      message: error.message,
      digest: error.digest, // Next.js server error ID
      stack: error.stack,
      timestamp: new Date().toISOString(),
      path: window.location.pathname,
    });
  }, [error]);

  return (
    // Error UI
  );
}

async function reportError(errorData) {
  try {
    await fetch('/api/errors', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(errorData),
    });
  } catch {
    // Don't let error reporting itself cause more errors
    console.error('Failed to report error:', errorData);
  }
}

The error.digest is particularly useful — it's a hash that Next.js uses to identify server-side errors in logs without exposing sensitive stack traces to the client.

The Error Boundary Hierarchy in Practice

For a real application, the error boundary structure might look like:

global-error.js        ← Last resort, includes <html>
├── error.js           ← Root-level errors
│   ├── (auth)/
│   │   └── error.js   ← Auth-specific errors  
│   ├── dashboard/
│   │   └── error.js   ← Dashboard-specific errors
│   └── api/
│       └── route.js   ← API routes handle their own errors

This lets you show relevant error messages — "Your session expired, please log in again" for auth errors, "Failed to load dashboard data" for dashboard errors — rather than a generic "something went wrong" for everything.

What I Built This On

This error handling pattern runs in production on pixova.io. The generation pipeline has several async steps where things can go wrong — API timeouts, inference failures, upload errors — and the error boundary setup means failures at each step show appropriate messages rather than breaking the whole page.

The reset button is particularly important for generation tools where users are mid-workflow when something fails — it retries without losing the prompt they just wrote.

Questions on specific error scenarios? Drop them in the comments.

Building a Dark Mode System in Next.js App Router — Without Layout Flash

Aon infotech — Sun, 21 Jun 2026 08:05:41 +0000

Dark mode sounds simple until you implement it. Then you discover the flash.

On first load, before JavaScript runs, your page renders with the default theme. Then the theme switcher kicks in. For a fraction of a second — sometimes longer on slow connections — users see the wrong theme before it corrects itself.

This is the flash of unstyled content (FOUC) applied to theming, and it's one of the more annoying UX problems to solve correctly in Next.js App Router.

Here's the approach that works, which I used building the theming system for a free AI image generation tool.

Why the Flash Happens

Next.js App Router renders on the server by default. The server doesn't know the user's theme preference — that's stored in localStorage or a cookie on the client. So the server renders with the default theme, sends that HTML to the browser, and then JavaScript runs and corrects the theme.

The gap between HTML arriving and JavaScript running = the flash.

The Solution — Inline Script Before React Hydration

The key insight: to prevent the flash, you need to apply the theme before React hydrates. This means a synchronous inline script in the <head> that reads the preference and applies it immediately.

// app/layout.js
export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <script
          dangerouslySetInnerHTML={{
            __html: `
              (function() {
                try {
                  var theme = localStorage.getItem('theme');
                  var prefersDark = window.matchMedia(
                    '(prefers-color-scheme: dark)'
                  ).matches;

                  if (theme === 'dark' || (!theme && prefersDark)) {
                    document.documentElement.classList.add('dark');
                  }
                } catch (e) {}
              })();
            `,
          }}
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Why suppressHydrationWarning? React will complain that the server-rendered HTML doesn't match the client (because we've added a dark class that the server didn't know about). This prop tells React to ignore that mismatch on the html element specifically.

Why try/catch? localStorage can throw in certain browser environments (private mode, security policies). Wrapping prevents a JavaScript error from breaking the page.

The Theme Context

// contexts/ThemeContext.js
'use client';
import { createContext, useContext, useEffect, useState } from 'react';

const ThemeContext = createContext({
  theme: 'system',
  setTheme: () => {},
  resolvedTheme: 'light',
});

export function ThemeProvider({ children }) {
  const [theme, setThemeState] = useState('system');
  const [resolvedTheme, setResolvedTheme] = useState('light');

  useEffect(() => {
    // Read stored preference on mount
    const stored = localStorage.getItem('theme') ?? 'system';
    setThemeState(stored);
  }, []);

  useEffect(() => {
    const root = document.documentElement;

    if (theme === 'dark') {
      root.classList.add('dark');
      setResolvedTheme('dark');
      localStorage.setItem('theme', 'dark');
    } else if (theme === 'light') {
      root.classList.remove('dark');
      setResolvedTheme('light');
      localStorage.setItem('theme', 'light');
    } else {
      // System preference
      localStorage.removeItem('theme');
      const prefersDark = window.matchMedia(
        '(prefers-color-scheme: dark)'
      ).matches;

      if (prefersDark) {
        root.classList.add('dark');
        setResolvedTheme('dark');
      } else {
        root.classList.remove('dark');
        setResolvedTheme('light');
      }
    }
  }, [theme]);

  // Listen for system preference changes
  useEffect(() => {
    if (theme !== 'system') return;

    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
    const handler = (e) => {
      setResolvedTheme(e.matches ? 'dark' : 'light');
      document.documentElement.classList.toggle('dark', e.matches);
    };

    mediaQuery.addEventListener('change', handler);
    return () => mediaQuery.removeEventListener('change', handler);
  }, [theme]);

  const setTheme = (newTheme) => setThemeState(newTheme);

  return (
    <ThemeContext.Provider value={{ theme, setTheme, resolvedTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

export const useTheme = () => useContext(ThemeContext);

The Toggle Component

// components/ThemeToggle.jsx
'use client';
import { useTheme } from '@/contexts/ThemeContext';

export function ThemeToggle() {
  const { theme, setTheme, resolvedTheme } = useTheme();

  return (
    <div className="flex items-center gap-2">
      <button
        onClick={() => setTheme('light')}
        className={`p-2 rounded-lg transition-colors ${
          theme === 'light'
            ? 'bg-neutral-200 dark:bg-neutral-700'
            : 'hover:bg-neutral-100 dark:hover:bg-neutral-800'
        }`}
        aria-label="Light mode"
      >
        ☀️
      </button>

      <button
        onClick={() => setTheme('system')}
        className={`p-2 rounded-lg transition-colors ${
          theme === 'system'
            ? 'bg-neutral-200 dark:bg-neutral-700'
            : 'hover:bg-neutral-100 dark:hover:bg-neutral-800'
        }`}
        aria-label="System preference"
      >
        💻
      </button>

      <button
        onClick={() => setTheme('dark')}
        className={`p-2 rounded-lg transition-colors ${
          theme === 'dark'
            ? 'bg-neutral-200 dark:bg-neutral-700'
            : 'hover:bg-neutral-100 dark:hover:bg-neutral-800'
        }`}
        aria-label="Dark mode"
      >
        🌙
      </button>
    </div>
  );
}

CSS Variables for Theming

Using CSS variables with Tailwind's dark mode makes theme-aware colors straightforward:

/* globals.css */
:root {
  --background: 255 255 255;
  --foreground: 15 15 15;
  --card: 248 248 248;
  --border: 226 226 226;
  --muted: 115 115 115;
}

.dark {
  --background: 10 10 10;
  --foreground: 245 245 245;
  --card: 24 24 24;
  --border: 38 38 38;
  --muted: 163 163 163;
}

// tailwind.config.js
module.exports = {
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        background: 'rgb(var(--background) / <alpha-value>)',
        foreground: 'rgb(var(--foreground) / <alpha-value>)',
        card: 'rgb(var(--card) / <alpha-value>)',
        border: 'rgb(var(--border) / <alpha-value>)',
        muted: 'rgb(var(--muted) / <alpha-value>)',
      },
    },
  },
};

Now you can use bg-background, text-foreground, border-border anywhere in your components and they switch automatically.

Common Pitfalls

Forgetting suppressHydrationWarning: React will throw hydration warnings in development. Add it to the <html> element specifically — not globally.

Using useEffect to read localStorage on mount: This still causes a flash, just a shorter one. The inline script approach is necessary to eliminate the flash entirely.

Not handling the system preference case: If the user has "system" preference and changes their OS theme while on your site, nothing updates unless you listen for prefers-color-scheme changes.

Images that don't adapt: Dark and light mode images need separate handling. Either use CSS filters (filter: invert(1) on dark backgrounds) or conditionally render different image sources using resolvedTheme.

Testing

// Verify no flash on load
// 1. Set theme to dark in localStorage
// 2. Hard refresh — should load dark immediately
// 3. Clear localStorage — should follow system preference
// 4. Toggle OS dark mode — should update without refresh (system mode)

The inline script approach eliminates the flash across all browsers I've tested. The trade-off is a small inline script in every page's <head> — negligible performance impact for the user experience improvement it provides.

What I Built This On

This theming system is running in production on pixova.io — the dark/light toggle in the navigation uses exactly this approach. No flash, system preference respected, instant switching.

Questions about specific edge cases? Comments open.

Handling Server Components With Theme

One tricky area in App Router: server components don't have access to the client's theme preference. This affects things like server-rendered images or content that should vary by theme.

Option 1 — CSS-only solution (preferred):
Use CSS to show/hide variants based on the .dark class:

/* Show light version by default, dark version when .dark is active */
.logo-light { display: block; }
.logo-dark { display: none; }

.dark .logo-light { display: none; }
.dark .logo-dark { display: block; }

This requires no JavaScript and works instantly since the .dark class is already applied by the inline script.

Option 2 — Client component wrapper:
Wrap theme-sensitive server components in a client component that reads resolvedTheme:

'use client';
import { useTheme } from '@/contexts/ThemeContext';

export function ThemedImage({ lightSrc, darkSrc, alt }) {
  const { resolvedTheme } = useTheme();

  return (
    <img
      src={resolvedTheme === 'dark' ? darkSrc : lightSrc}
      alt={alt}
    />
  );
}

The downside: this introduces a client boundary just for the image. The CSS approach is cleaner for most cases.

Cookie-Based Alternative (For SSR Accuracy)

If you need the server to know the theme (for server-rendered charts, personalized content, or avoiding any flash at all), store the preference in a cookie rather than localStorage.

// middleware.js — read theme cookie, add to response
import { NextResponse } from 'next/server';

export function middleware(request) {
  const theme = request.cookies.get('theme')?.value ?? 'system';
  const response = NextResponse.next();

  // Pass theme as a header the layout can read
  response.headers.set('x-theme', theme);
  return response;
}

// app/layout.js — read theme from headers for SSR
import { headers } from 'next/headers';

export default function RootLayout({ children }) {
  const headersList = headers();
  const theme = headersList.get('x-theme') ?? 'system';
  const isDark = theme === 'dark';

  return (
    <html 
      lang="en" 
      className={isDark ? 'dark' : ''}
      suppressHydrationWarning
    >
      ...
    </html>
  );
}

This eliminates the flash entirely — even before JavaScript runs — because the server knows the theme. The trade-off: requires a middleware layer and adds a cookie to every request.

For most use cases, the inline script approach is sufficient and simpler. The cookie approach is worth implementing if you have server-rendered content that needs to match the theme exactly on first load.

Summary

The flash-free dark mode stack in Next.js App Router:

Inline script in <head> reads preference and applies class before hydration
suppressHydrationWarning on <html> to suppress React's mismatch warning
Theme context manages state and localStorage persistence
CSS variables handle color switching
System preference listener updates in real-time for "system" mode The inline script is the non-obvious piece that most implementations miss. Without it, no amount of context optimization eliminates the flash.

Rate Limiting Without User Accounts — Strategies for Anonymous APIs

Aon infotech — Sat, 20 Jun 2026 07:18:22 +0000

Rate limiting an authenticated API is straightforward — you have a user ID, you track requests per user, you throttle when they exceed limits.

Rate limiting an anonymous API is a different problem entirely. No user ID means you're working with proxies for identity: IP address, device fingerprint, behavioral signals. Each has weaknesses. Here's how to layer them effectively, which is exactly the challenge we solved building free AI image generator no sign up.

Why Anonymous Rate Limiting Is Harder

With authenticated users:

// Simple — user ID is a stable, reliable identifier
const key = `rate_limit:${userId}`;
const requests = await redis.incr(key);
if (requests > LIMIT) throw new RateLimitError();

With anonymous users, you have no stable identifier. Everything you use as a proxy is either spoofable, unreliable, or both.

Layer 1 — IP Address (Baseline)

IP is the obvious first layer. It's available on every request and requires no client cooperation.

// middleware.js
export function middleware(request) {
  const ip = 
    request.headers.get('x-forwarded-for')?.split(',')[0].trim() 
    ?? request.headers.get('x-real-ip')
    ?? 'unknown';

  return ip;
}

The problems with IP-only rate limiting:

Shared IPs are common. Corporate offices, universities, ISPs using carrier-grade NAT — dozens or hundreds of users sharing one IP address. Blocking an IP blocks all of them.

VPNs and proxies trivially bypass IP limits. A determined user can rotate through IPs faster than you can block them.

Dynamic IPs mean genuine users get rate limited because a previous user of that IP address hit the limit.

Still use it — IP rate limiting stops the majority of automated abuse. Just don't rely on it exclusively.

Layer 2 — Token Bucket Per IP With Generous Limits

Rather than hard cutoffs, token bucket algorithms allow burst usage while preventing sustained abuse:

// lib/rateLimiter.js
class TokenBucket {
  constructor({ capacity, refillRate, refillInterval }) {
    this.capacity = capacity;           // Max tokens
    this.refillRate = refillRate;       // Tokens added per interval
    this.refillInterval = refillInterval; // Milliseconds
    this.buckets = new Map();
  }

  async consume(key, tokens = 1) {
    const now = Date.now();
    let bucket = this.buckets.get(key) ?? {
      tokens: this.capacity,
      lastRefill: now,
    };

    // Refill based on elapsed time
    const elapsed = now - bucket.lastRefill;
    const intervals = Math.floor(elapsed / this.refillInterval);
    if (intervals > 0) {
      bucket.tokens = Math.min(
        this.capacity,
        bucket.tokens + intervals * this.refillRate
      );
      bucket.lastRefill = now;
    }

    if (bucket.tokens < tokens) {
      this.buckets.set(key, bucket);
      return { allowed: false, remaining: 0 };
    }

    bucket.tokens -= tokens;
    this.buckets.set(key, bucket);
    return { allowed: true, remaining: bucket.tokens };
  }
}

// Configuration for a generation endpoint
export const generationLimiter = new TokenBucket({
  capacity: 12,          // 12 burst generations
  refillRate: 1,         // 1 token per interval
  refillInterval: 60_000, // Per minute
});

Key advantage: A user can generate 12 images quickly for rapid iteration, but can't sustain 100+ requests per hour.

Layer 3 — Browser Fingerprinting (Client-Side Signal)

A lightweight fingerprint — screen resolution, timezone, language, platform — creates a more persistent identifier than IP alone without storing anything personally identifying.

// lib/fingerprint.js (client-side)
export async function getFingerprint() {
  const components = [
    navigator.language,
    navigator.platform,
    screen.width + 'x' + screen.height,
    screen.colorDepth,
    Intl.DateTimeFormat().resolvedOptions().timeZone,
    navigator.hardwareConcurrency,
  ];

  // Hash the components
  const str = components.join('|');
  const buffer = await crypto.subtle.digest(
    'SHA-256',
    new TextEncoder().encode(str)
  );

  return Array.from(new Uint8Array(buffer))
    .map(b => b.toString(16).padStart(2, '0'))
    .join('').slice(0, 16); // 16 char fingerprint
}

Send this alongside each request and rate limit on fingerprint + IP combined:

// More stable identifier: combine IP + fingerprint
const rateLimitKey = `${ip}:${fingerprint}`;

Weaknesses: Fingerprint can be spoofed with developer tools. Changes when users switch browsers. But it meaningfully raises the effort required to bypass limits.

Layer 4 — Behavioral Signals

Automated abuse has distinctive patterns. Tracking these adds another detection layer:

// lib/behaviorAnalyzer.js
export function analyzeBehavior(requestHistory) {
  const timestamps = requestHistory.map(r => r.timestamp);

  // Bots often have unnaturally consistent intervals
  const intervals = timestamps
    .slice(1)
    .map((t, i) => t - timestamps[i]);

  const avgInterval = intervals.reduce((a, b) => a + b, 0) / intervals.length;
  const variance = intervals.reduce((sum, interval) => {
    return sum + Math.pow(interval - avgInterval, 2);
  }, 0) / intervals.length;

  // Low variance = suspiciously regular = likely bot
  const isSuspiciouslyRegular = variance < 500; // ms²

  // Too fast between requests = likely automated
  const minimumInterval = Math.min(...intervals);
  const isTooFast = minimumInterval < 800; // 800ms minimum

  return {
    suspicious: isSuspiciouslyRegular || isTooFast,
    variance,
    minimumInterval,
  };
}

Layer 5 — Graceful Degradation Over Hard Blocks

Hard IP blocks create false positives (blocking legitimate shared-IP users) and create adversarial relationships with users who hit limits accidentally.

A better approach: degrade gracefully before blocking.

// Instead of blocking, slow down first
async function handleRequest(ip, fingerprint) {
  const key = `${ip}:${fingerprint}`;
  const { allowed, remaining } = await generationLimiter.consume(key);

  if (!allowed) {
    // How many seconds until next token?
    const waitTime = calculateWaitTime(key);

    return new Response(
      JSON.stringify({
        error: 'Rate limit reached',
        retryAfter: waitTime,
        message: `Please wait ${waitTime} seconds before generating again.`
      }),
      { 
        status: 429,
        headers: { 
          'Retry-After': String(waitTime),
          'X-RateLimit-Remaining': '0',
        }
      }
    );
  }

  // Add rate limit headers to successful responses too
  return NextResponse.next({
    headers: {
      'X-RateLimit-Remaining': String(remaining),
    }
  });
}

Production Edge Cases

Handling Vercel/CDN header forwarding:

// Different headers depending on deployment environment
function getClientIp(request) {
  return (
    request.headers.get('cf-connecting-ip') ||     // Cloudflare
    request.headers.get('x-vercel-forwarded-for') || // Vercel
    request.headers.get('x-forwarded-for')?.split(',')[0].trim() ||
    request.headers.get('x-real-ip') ||
    'unknown'
  );
}

Memory leak prevention in in-process stores:

// Clean up old buckets periodically
setInterval(() => {
  const cutoff = Date.now() - 3_600_000; // 1 hour
  for (const [key, bucket] of generationLimiter.buckets) {
    if (bucket.lastRefill < cutoff) {
      generationLimiter.buckets.delete(key);
    }
  }
}, 600_000); // Every 10 minutes

Multi-instance deployments: In-memory rate limiting doesn't share state across serverless function instances. For production scale, move the rate limit state to Redis or a similar distributed store.

What This Looks Like in Practice

The layered approach — IP + fingerprint + behavioral signals — reduces automated abuse significantly without meaningfully impacting legitimate users.

The key design choice: treat false positives as more costly than missed abuse. A legitimate user who gets incorrectly blocked is a worse outcome than an abuser who gets through occasionally. Generous limits + graceful degradation + multiple signals = the right balance for most anonymous APIs.

For monitoring, track your 429 rate as a percentage of total requests. Sustained spikes indicate either abuse or limits set too aggressively — both worth investigating.

Testing Your Rate Limiting

A few practical tests before shipping:

Test 1 — Verify limits trigger correctly:

// test/rateLimiting.test.js
async function testRateLimit() {
  const results = [];

  // Fire requests rapidly
  for (let i = 0; i < 20; i++) {
    const response = await fetch('/api/generate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ prompt: 'test' }),
    });
    results.push(response.status);
  }

  // Should see 200s followed by 429s
  const allowed = results.filter(s => s === 200).length;
  const blocked = results.filter(s => s === 429).length;

  console.log(`Allowed: ${allowed}, Blocked: ${blocked}`);
  // Expected: Allowed ~12 (bucket capacity), Blocked ~8
}

Test 2 — Verify headers are present:

const response = await fetch('/api/generate', { method: 'POST', ... });
console.log(response.headers.get('x-ratelimit-remaining'));
console.log(response.headers.get('retry-after')); // Present on 429s

Test 3 — Verify bucket refill:

// Hit the limit, wait for refill, verify access restored
await hitRateLimit();
await sleep(61_000); // Wait for 1 minute refill
const response = await fetch('/api/generate', { method: 'POST', ... });
console.log(response.status); // Should be 200 again

Summary

Anonymous rate limiting requires layers because no single signal is reliable:

IP — baseline filter, easy to bypass but catches most automated abuse
Token bucket — allows bursts, prevents sustained hammering
Fingerprint — raises bypass effort without user friction
Behavioral signals — catches bot-like patterns IP can't detect
Graceful degradation — 429 with retry-after is better than hard blocks The goal isn't to make abuse impossible — it's to make abuse more expensive than it's worth, while keeping the experience smooth for legitimate users.

Async Job Queues in Next.js — Handling Long-Running Tasks Without Timeouts

Aon infotech — Fri, 19 Jun 2026 06:54:07 +0000

Most Next.js tutorials cover the happy path — a request comes in, the server responds quickly, done. But what happens when the task takes 15 seconds? Server functions time out. Users get errors. The experience breaks.

Here's the pattern that solves it, used in production for any long-running server-side task.

Why Standard API Routes Break on Long Tasks

Next.js API routes (and serverless functions generally) have execution time limits. On Vercel's free tier, that's 10 seconds. Even on paid plans, holding a connection open for 30+ seconds is unreliable — networks drop, browsers time out, proxies intervene.

The naive approach:

// ❌ This breaks on long tasks
export async function POST(request) {
  const result = await doSomethingThatTakes20Seconds();
  return Response.json({ result }); // Often never reaches here
}

The fix is to decouple job submission from job completion.

The Async Queue Pattern

Client submits job → API returns job ID immediately →
Client polls status endpoint → 
Worker processes job in background →
Status endpoint returns result when ready

Three pieces: submit endpoint, status endpoint, and background worker.

Step 1 — Submit Endpoint (Returns Immediately)

// app/api/jobs/submit/route.js
import { createJob } from '@/lib/queue';

export async function POST(request) {
  const { payload } = await request.json();

  if (!payload) {
    return Response.json(
      { error: 'Payload required' },
      { status: 400 }
    );
  }

  // Create job — returns immediately with an ID
  const jobId = await createJob({ payload });

  return Response.json({
    jobId,
    status: 'queued',
  });
}

The client gets a jobId back in milliseconds. The actual work hasn't started yet.

Step 2 — Status Endpoint (Polling Target)

// app/api/jobs/[jobId]/route.js
import { getJobStatus } from '@/lib/queue';

export async function GET(request, { params }) {
  const { jobId } = params;
  const job = await getJobStatus(jobId);

  if (!job) {
    return Response.json(
      { error: 'Job not found' },
      { status: 404 }
    );
  }

  return Response.json({
    jobId,
    status: job.status, // 'queued' | 'processing' | 'completed' | 'failed'
    result: job.result,
    error: job.error,
    createdAt: job.createdAt,
    completedAt: job.completedAt,
  });
}

Step 3 — Simple In-Memory Queue (Development)

// lib/queue.js
const jobs = new Map();

export async function createJob({ payload }) {
  const jobId = crypto.randomUUID();

  jobs.set(jobId, {
    id: jobId,
    payload,
    status: 'queued',
    result: null,
    error: null,
    createdAt: new Date().toISOString(),
    completedAt: null,
  });

  // Process asynchronously — don't await
  processJob(jobId).catch(console.error);

  return jobId;
}

export async function getJobStatus(jobId) {
  return jobs.get(jobId) ?? null;
}

async function processJob(jobId) {
  const job = jobs.get(jobId);
  if (!job) return;

  jobs.set(jobId, { ...job, status: 'processing' });

  try {
    const result = await runTask(job.payload);
    jobs.set(jobId, {
      ...job,
      status: 'completed',
      result,
      completedAt: new Date().toISOString(),
    });
  } catch (error) {
    jobs.set(jobId, {
      ...job,
      status: 'failed',
      error: error.message,
      completedAt: new Date().toISOString(),
    });
  }
}

Important: In-memory storage resets on server restart and doesn't work across multiple instances. For production, replace Map with Redis or a database.

Step 4 — Frontend Polling

'use client';
import { useState, useCallback, useEffect, useRef } from 'react';

export function useJobPoller() {
  const [status, setStatus] = useState('idle');
  const [result, setResult] = useState(null);
  const [error, setError] = useState(null);
  const pollerRef = useRef(null);

  const stopPolling = useCallback(() => {
    if (pollerRef.current) {
      clearInterval(pollerRef.current);
      pollerRef.current = null;
    }
  }, []);

  const startJob = useCallback(async (payload) => {
    setStatus('submitting');
    setResult(null);
    setError(null);

    try {
      const submitRes = await fetch('/api/jobs/submit', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ payload }),
      });

      const { jobId } = await submitRes.json();
      setStatus('queued');

      pollerRef.current = setInterval(async () => {
        const statusRes = await fetch(`/api/jobs/${jobId}`);
        const data = await statusRes.json();
        setStatus(data.status);

        if (data.status === 'completed') {
          setResult(data.result);
          stopPolling();
        }
        if (data.status === 'failed') {
          setError(data.error);
          stopPolling();
        }
      }, 2000);

    } catch (err) {
      setStatus('failed');
      setError(err.message);
    }
  }, [stopPolling]);

  useEffect(() => () => stopPolling(), [stopPolling]);

  return { startJob, status, result, error };
}

Production Considerations

Concern	Solution
Job persistence	Replace Map with Redis or database
Multiple instances	External queue (BullMQ, SQS, etc.)
Job expiry	TTL on stored jobs
Polling overhead	WebSockets for high-frequency updates
Stuck jobs	Timeout detection + auto-fail

When to Use This Pattern

Use async queues when:

Task duration exceeds 5-10 seconds reliably
You need progress feedback during processing
Task failure should be recoverable without losing the request Skip it when:
Task completes in under 3 seconds consistently

- Simplicity matters more than edge case handling

What I Built With This

I implemented this exact pattern in pixova.io — a free AI image generator. Every generation request goes through this async queue: the UI gets a job ID instantly, polls every 2 seconds, and renders the image when the GPU inference completes. The queue handles cold starts, retries, and timeout detection cleanly.

If you want to see the end-user experience this powers — open pixova.io, type a prompt, and watch the polling happen in real time in your network tab.

Questions about specific parts of the implementation? Comments open.

Building a Loading State That Doesn't Feel Slow — Lessons From an AI Generation Tool

Aon infotech — Thu, 18 Jun 2026 06:00:06 +0000

Generation tools have a UX problem most apps don't: a genuine 8-15 second wait between action and result. Get the loading state wrong and users perceive the tool as slow even when the actual processing time is reasonable.

Here's what I learned building the loading experience for generate AI images for free.

The Problem With a Plain Spinner

The default instinct is a spinning loader. It works, technically. But it communicates almost nothing — no sense of progress, no indication anything specific is happening, just "wait."

Users staring at a generic spinner for 10 seconds report the wait as longer than users watching something that suggests progress, even when the actual duration is identical. This is a well-documented perception effect, and it matters disproportionately for generation tools where the wait is unavoidable.

Three Things That Changed Perceived Speed

1. Immediate state change on click

The button needs to respond the instant it's clicked — not after a network request confirms anything.

const [status, setStatus] = useState('idle');

const handleGenerate = async () => {
  setStatus('starting'); // Instant — before any API call

  try {
    const result = await submitGeneration(prompt);
    setStatus('processing');
    await pollUntilComplete(result.jobId);
    setStatus('complete');
  } catch {
    setStatus('error');
  }
};

The gap between click and first visual feedback should be milliseconds, regardless of how long the actual generation takes afterward.

2. A skeleton that matches final dimensions

Instead of a spinner floating in empty space, show a placeholder shaped exactly like the output will be.

function LoadingSkeleton({ aspectRatio }) {
  const ratioClass = {
    '1:1': 'aspect-square',
    '16:9': 'aspect-video',
    '9:16': 'aspect-[9/16]',
  }[aspectRatio];

  return (
    <div className={`w-full ${ratioClass} rounded-2xl 
      bg-gradient-to-br from-neutral-100 to-neutral-200 
      dark:from-neutral-800 dark:to-neutral-900
      animate-pulse relative overflow-hidden`}>
      <div className="absolute inset-0 flex items-center 
        justify-center">
        <span className="text-sm text-neutral-400">
          Generating...
        </span>
      </div>
    </div>
  );
}

This does two things: it eliminates layout shift when the real image arrives, and it gives users something more substantial to look at than an empty spinner.

3. Subtle progressive messaging

Static text ("Loading...") for 10 seconds feels stagnant. Rotating through a few status messages — even generic ones — creates a sense of progress.

const loadingMessages = [
  'Processing your prompt...',
  'Generating image...',
  'Almost there...',
];

function useRotatingMessage(isLoading) {
  const [index, setIndex] = useState(0);

  useEffect(() => {
    if (!isLoading) {
      setIndex(0);
      return;
    }

    const interval = setInterval(() => {
      setIndex(prev => 
        Math.min(prev + 1, loadingMessages.length - 1)
      );
    }, 3000);

    return () => clearInterval(interval);
  }, [isLoading]);

  return loadingMessages[index];
}

Important caveat: don't fake specificity you don't have. If you don't actually know what stage the process is in, rotating generic-but-plausible messages is honest. Claiming false precision ("Optimizing pixel array...") when nothing like that is happening erodes trust once users notice the pattern repeats identically every time.

Handling the Variable Wait Time Honestly

Generation time isn't always consistent — cold starts, server load, and prompt complexity all affect duration. A loading state that assumes a fixed duration breaks when reality doesn't match.

// Avoid: assumes a fixed timeline
useEffect(() => {
  setTimeout(() => setMessage('Almost done!'), 8000);
}, []);

// Better: respond to actual elapsed time without
// promising a specific completion point
function useElapsedFeedback(isLoading) {
  const [elapsed, setElapsed] = useState(0);

  useEffect(() => {
    if (!isLoading) {
      setElapsed(0);
      return;
    }
    const interval = setInterval(() => {
      setElapsed(prev => prev + 1);
    }, 1000);
    return () => clearInterval(interval);
  }, [isLoading]);

  if (elapsed < 5) return 'Generating your image...';
  if (elapsed < 15) return 'Still working on it...';
  return 'This is taking longer than usual...';
}

The thresholds adjust messaging based on what's actually happening rather than assuming every generation takes the same time.

Error States Deserve the Same Care

A failed generation after a 10-second wait is frustrating. How you communicate the failure affects whether users try again or leave.

function ErrorState({ onRetry }) {
  return (
    <div className="flex flex-col items-center gap-3 p-6 
      text-center">
      <p className="text-sm text-neutral-500">
        Something went wrong with that generation.
      </p>
      <button
        onClick={onRetry}
        className="text-sm font-medium text-orange-500 
          hover:text-orange-600"
      >
        Try again
      </button>
    </div>
  );
}

Specific, actionable, no blame language, immediate retry option. Avoid technical error codes in user-facing messaging — "Error 500" means nothing to most users and feels worse than a plain-language explanation.

Measuring Whether It Actually Helped

Perceived speed improvements are hard to measure directly, but a few proxy metrics worked as indicators:

Metric	Before	After
Users abandoning during generation	Higher	Lower
Repeat generations per session	Lower	Higher
Support messages about "slow"	Present	Rare

None of these prove causation precisely, but the direction was consistent with the perception research this approach is based on.

TL;DR

Change button state instantly on click, before any network confirmation
Use a skeleton matching final output dimensions, not a generic spinner
Rotate honest, generic progress messages rather than static text or false specificity
Base messaging thresholds on elapsed time, not assumed fixed durations
Error states need the same UX care as success states — clear, actionable, blame-free The complete prompt and generation flow this powers is at pixova.io if you want to see it in practice.

What's your approach to loading states for genuinely slow operations? Curious how others have solved this.

Image Optimization for AI-Generated Content — WebP, LCP, and Layout Shift

Aon infotech — Wed, 17 Jun 2026 05:47:57 +0000

AI-generated images create a specific performance problem most optimization guides don't cover: you don't know the image dimensions, format, or content until generation completes — but you still need to avoid layout shift and slow loading.

Here's how I approached it building free AI image generator no sign up unlimited.

The Core Problem

Standard image optimization assumes you know the image ahead of time — you can pre-calculate dimensions, generate responsive srcsets, and optimize at build time.

Generated images break this assumption. The image doesn't exist until the user requests it. You can't pre-optimize what doesn't exist yet.

Format Selection — Why WebP Wins

Raw inference output is typically PNG. For delivery, that's the wrong choice.

PNG: lossless, larger files, ~800KB-1.2MB typical
WebP: ~25-35% smaller than PNG at equivalent quality
AVIF: smaller still, but inconsistent browser support

The conversion step matters:

// Conceptual flow — actual implementation varies by stack
async function optimizeForDelivery(rawImageBuffer) {
  const optimized = await convertToWebP(rawImageBuffer, {
    quality: 85, // Sweet spot for generated content
  });

  return optimized;
}

Why quality 85, not 100: AI-generated images already have inherent texture noise from the generation process. Higher compression quality settings show diminishing returns — the difference between 85 and 100 is rarely visible but adds significant file size.

The Aspect Ratio Pre-Sizing Problem

Users select aspect ratios (1:1, 16:9, 9:16, 4:3) before generating. This is actually an optimization advantage — you know the shape before the image exists.

// Pre-size the container based on selected ratio
const aspectRatioClasses = {
  '1:1': 'aspect-square',
  '16:9': 'aspect-video', 
  '9:16': 'aspect-[9/16]',
  '4:3': 'aspect-[4/3]',
};

function ImageContainer({ ratio, children }) {
  return (
    <div className={`w-full ${aspectRatioClasses[ratio]} 
      rounded-2xl overflow-hidden bg-neutral-100`}>
      {children}
    </div>
  );
}

This single decision eliminates cumulative layout shift (CLS) — the container exists at the correct dimensions before the image arrives.

LCP — The Generated Image IS the LCP Element

For a generation tool, Largest Contentful Paint is almost always the output image. This makes LCP optimization unusually important compared to typical content sites.

Three changes that mattered most:

1. Priority loading hint

<Image
  src={generatedImageUrl}
  alt={altText}
  width={1024}
  height={1024}
  priority // Tells the framework this is critical
/>

2. Preconnect to image delivery domain

<link rel="preconnect" href="https://your-cdn-domain.com" />

This shaves connection setup time off the critical path — DNS lookup, TLS handshake happen before the image request fires.

3. Skeleton matching final dimensions

{isGenerating && (
  <div className="w-full aspect-square bg-neutral-100 
    dark:bg-neutral-800 animate-pulse rounded-2xl" />
)}

The skeleton occupies the exact space the final image will fill — zero shift when it arrives.

Caching Strategy for Generated Content

Generated images present an interesting caching question: many users generate similar or identical prompts. Should you cache?

Arguments for caching:

Identical prompts (rare but happens) return instantly
Reduces redundant inference costs Arguments against:
Generation should feel "live" — caching undermines the perception of fresh creation
Storage costs accumulate
Privacy consideration — should identical prompts from different users return the same cached image? The approach I landed on: Cache at the CDN layer for delivery speed (repeated requests for the same generated image load fast), but don't cache at the inference layer (every generation request produces a fresh image, even for identical prompts).

// CDN-level caching headers
{
  'Cache-Control': 'public, max-age=31536000, immutable',
  // Each generated image gets a unique URL,
  // so caching is safe — it's never going to change
}

Since each generated image gets a unique identifier, aggressive CDN caching is safe — the URL only exists once a specific image has been generated.

Lazy Loading Considerations

Standard lazy loading wisdom (loading="lazy") doesn't apply to the primary generated image — it's above the fold and needs immediate loading.

It does apply to secondary content — example galleries, previous generations in a session history, related content sections.

{/* Primary generated image — eager load */}
<Image src={currentImage} priority />

{/* Gallery of examples below the fold — lazy load */}
{exampleImages.map(img => (
  <Image key={img.id} src={img.url} loading="lazy" />
))}

Results

Metric	Before optimization	After
Average delivered size	~900KB	~200KB
LCP (median)	4.1s	1.9s
CLS	Present	Eliminated

The CLS elimination came almost entirely from pre-sizing containers based on selected aspect ratio — a decision that's available specifically because users choose dimensions before generation starts.

TL;DR

Convert to WebP at ~85 quality for generated content — diminishing returns above that
Pre-size containers using the aspect ratio selected before generation
Mark the generated image as priority — it's almost always your LCP element
CDN-cache aggressively since each generated image has a unique, immutable URL
Reserve lazy loading for below-the-fold secondary content only For the architecture decisions behind the generation pipeline itself, I covered that in a separate post here.

What's your approach to optimizing dynamically generated content? Comments open.

Building a Text-to-Image Pipeline with Next.js — Architecture Decisions

Aon infotech — Tue, 16 Jun 2026 06:50:42 +0000

When I built the backend for free AI image generator no credit card, the core challenge was connecting a Next.js frontend to a GPU inference endpoint efficiently. Here's the architecture thinking — not the specific implementation, but the decisions that shaped it.

The Core Architecture Problem

Text-to-image generation has an unusual request profile:

Each request is computationally expensive (GPU inference)
Requests are unpredictable — traffic spikes randomly
Each generation takes 5-20 seconds
Users expect real-time feedback during the wait This rules out the standard REST API pattern where you send a request and wait for a response. A 15-second HTTP connection held open per user doesn't scale.

The solution: async job queue pattern.

User submits prompt → 
Job created in queue → 
Job ID returned immediately → 
Frontend polls for status → 
Result delivered when ready

The Three Architecture Options

Option A — Synchronous (Simple, Doesn't Scale)

// app/api/generate/route.js
export async function POST(request) {
  const { prompt } = await request.json();

  // BAD: holds connection open for 15+ seconds
  const image = await runInference(prompt);
  return NextResponse.json({ image });
}

Problem: HTTP connections time out. Vercel serverless functions have execution limits. One slow generation blocks the connection.

Option B — Async with Polling (What Works)

// app/api/generate/route.js — Submit job
export async function POST(request) {
  const { prompt } = await request.json();

  // Submit to inference queue, get job ID immediately
  const jobId = await submitToQueue({ prompt });

  // Return immediately — don't wait for completion
  return NextResponse.json({ jobId, status: 'processing' });
}

// app/api/status/[jobId]/route.js — Check status
export async function GET(request, { params }) {
  const { jobId } = params;
  const result = await checkJobStatus(jobId);

  return NextResponse.json({
    status: result.status, // 'processing' | 'completed' | 'failed'
    image: result.image ?? null,
  });
}

Frontend polls /api/status/[jobId] every 2 seconds until complete.

Option C — WebSockets (Best UX, More Complex)

// Real-time updates via WebSocket
// Backend notifies frontend when job completes
// No polling overhead
// More infrastructure to maintain

For an early-stage product, Option B (polling) is the right tradeoff — simpler to implement and debug, good enough UX.

The Frontend — State Management

'use client';
import { useState, useCallback } from 'react';
import Image from 'next/image';

export default function ImageGenerator() {
  const [prompt, setPrompt] = useState('');
  const [status, setStatus] = useState('idle');
  // idle | submitting | processing | complete | error
  const [imageUrl, setImageUrl] = useState(null);

  const generate = useCallback(async () => {
    if (!prompt.trim() || status === 'processing') return;

    setStatus('submitting');

    try {
      // Submit job
      const submitRes = await fetch('/api/generate', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ prompt }),
      });

      const { jobId } = await submitRes.json();
      setStatus('processing');

      // Poll for result
      await pollForResult(jobId);

    } catch {
      setStatus('error');
    }
  }, [prompt, status]);

  const pollForResult = async (jobId) => {
    const maxAttempts = 60; // 2 min timeout

    for (let i = 0; i < maxAttempts; i++) {
      await new Promise(r => setTimeout(r, 2000));

      const statusRes = await fetch(`/api/status/${jobId}`);
      const data = await statusRes.json();

      if (data.status === 'completed') {
        setImageUrl(data.image);
        setStatus('complete');
        return;
      }

      if (data.status === 'failed') {
        setStatus('error');
        return;
      }
    }

    setStatus('error'); // Timeout
  };

  return (
    <div className="flex flex-col gap-4 max-w-2xl mx-auto p-6">
      <textarea
        value={prompt}
        onChange={(e) => setPrompt(e.target.value)}
        placeholder="Describe the image you want..."
        className="w-full p-3 border border-border rounded-xl 
          resize-none h-24 bg-background text-foreground"
        disabled={status === 'processing'}
      />

      <button
        onClick={generate}
        disabled={status === 'processing' || !prompt.trim()}
        className="bg-orange-500 text-white px-6 py-3 
          rounded-full font-semibold transition-colors
          hover:bg-orange-600 disabled:opacity-50"
      >
        {status === 'processing' ? 'Generating...' : 'Generate'}
      </button>

      {/* Loading skeleton — matches output dimensions */}
      {status === 'processing' && (
        <div className="w-full aspect-square rounded-2xl 
          bg-neutral-100 dark:bg-neutral-800 animate-pulse" />
      )}

      {/* Generated result */}
      {status === 'complete' && imageUrl && (
        <div className="relative w-full aspect-square 
          rounded-2xl overflow-hidden">
          <Image
            src={imageUrl}
            alt={prompt}
            fill
            className="object-cover"
            priority
          />
          <a
            href={imageUrl}
            download="generated.png"
            className="absolute bottom-4 right-4 
              bg-white/90 backdrop-blur text-black 
              px-4 py-2 rounded-full text-sm font-semibold
              hover:bg-white transition-colors"
          >
            Download
          </a>
        </div>
      )}

      {status === 'error' && (
        <p className="text-red-500 text-sm text-center">
          Something went wrong. Try again.
        </p>
      )}
    </div>
  );
}

Key UX Decisions

Skeleton loading over spinner

The skeleton placeholder has the exact dimensions of the output image. When the result arrives, no layout shift — the image drops into the same space.

{/* Dimensions match expected output */}
{status === 'processing' && (
  <div className="w-full aspect-square rounded-2xl 
    bg-neutral-100 animate-pulse" />
)}

Disable input during generation

Users shouldn't be able to submit a second job while one is processing. Disable both the input and the button.

Immediate button state change

The button should reflect 'submitting' state before the API call returns — not after. Users notice the lag.

Rate Limiting Without Accounts

Without user accounts, rate limiting falls on IP address:

// middleware.js
const requestCounts = new Map();

export function middleware(request) {
  const ip = request.headers.get('x-forwarded-for') 
    ?? 'unknown';
  const now = Date.now();
  const window = 60_000; // 1 minute
  const limit = 8; // requests per window

  const history = (requestCounts.get(ip) ?? [])
    .filter(t => now - t < window);

  if (history.length >= limit) {
    return new Response('Rate limit exceeded', { 
      status: 429 
    });
  }

  requestCounts.set(ip, [...history, now]);
  return NextResponse.next();
}

export const config = {
  matcher: '/api/generate',
};

Important: In-memory rate limiting resets on server restart and doesn't work across multiple instances. For production, use a distributed cache for rate limit state.

Performance Considerations

Problem	Solution
Cold starts on inference	Keep minimum workers warm
Large image payloads	Use CDN URL instead of base64
Layout shift on load	Pre-sized skeleton placeholder
Polling overhead	Stop polling after completion
Timeout handling	Max attempts with user feedback

What I'd Do Differently

Webhooks over polling. The inference backend notifying the frontend when complete is cleaner than the frontend repeatedly asking. Polling works, but it's chatty.

Better error categorization. A single 'error' state isn't enough. Timeout is different from inference failure is different from invalid prompt. Each deserves different user messaging.

For a full breakdown of how the no-account architecture affects product decisions, I wrote a detailed post here.

Questions about the architecture? Comments open.

How I Optimized Next.js Image Delivery for an AI Generation Tool

Aon infotech — Mon, 15 Jun 2026 07:48:52 +0000

When I launched unlimited AI image generator free to the public, the first performance problem wasn't the AI inference — it was image delivery.

Generated images were arriving fine. Getting them to the user's browser efficiently was the bottleneck. Here's what I found and how I fixed it.

The Problem

Users generate an image. The model produces it. Then what?

The naive approach: return the image as a base64 string directly in the API response.

// Naive approach — works but not optimal
const imageBuffer = await runInference(prompt);
const base64 = imageBuffer.toString('base64');
return res.json({ image: `data:image/png;base64,${base64}` });

Problems with this:

Large payload size (PNG base64 adds ~33% overhead)
No caching
No CDN delivery
Browser has to decode base64 before rendering For a tool where image quality perception matters, this showed.

The Next.js Image Component Constraint

Next.js <Image> component handles optimization automatically — but only for images with known dimensions at build time or from approved domains.

For dynamically generated images from external sources, you need to configure remotePatterns:

// next.config.js
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'res.cloudinary.com',
        pathname: '/your-cloud-name/**',
      },
    ],
  },
};

Without this, <Image> throws errors on dynamically sourced URLs.

The Cloudinary Layer

I added Cloudinary as an intermediary between inference output and browser delivery.

The flow:

Inference API → Raw image → Upload to Cloudinary → 
Cloudinary URL returned → Next.js <Image> renders → 
Cloudinary CDN delivers WebP to browser

Key Cloudinary transformations applied automatically:

// Cloudinary URL with transformations
const optimizedUrl = cloudinary.url(publicId, {
  format: 'webp',        // WebP conversion
  quality: 'auto',       // Automatic quality optimization  
  fetch_format: 'auto',  // Format based on browser support
  width: 1024,
  crop: 'limit',
});

Results:

PNG → WebP: ~40-60% file size reduction
CDN delivery: edge nodes worldwide

- Caching: repeated requests served instantly

Handling Temporary vs Persistent Storage

Not all generated images need permanent storage. For a tool where prompts aren't saved:

// Temporary upload — auto-deletes after 1 hour
const uploadResult = await cloudinary.uploader.upload(imageBuffer, {
  folder: 'generated',
  resource_type: 'image',
  invalidate: true,
  // Auto-delete after delivery window
  tags: ['temp', 'generated'],
});

This keeps storage costs minimal — images exist long enough to be downloaded, then removed.

LCP Impact

Largest Contentful Paint is the metric that matters most for perceived performance on a generation tool. The generated image IS the LCP element for most users.

Changes that improved LCP:

1. Preconnect to Cloudinary

<link rel="preconnect" href="https://res.cloudinary.com" />

2. Priority on the generated image

<Image
  src={generatedImageUrl}
  alt={altText}
  width={1024}
  height={1024}
  priority  // Tells Next.js to preload this image
  sizes="(max-width: 768px) 100vw, 50vw"
/>

3. Skeleton loading state
Show a loading placeholder with the exact dimensions of the output image. Prevents layout shift when the image loads.

{isGenerating ? (
  <div className="w-full aspect-square bg-neutral-100 
    dark:bg-neutral-800 rounded-2xl animate-pulse" />
) : (
  <Image src={imageUrl} ... />
)}

The Aspect Ratio Problem

Users select different aspect ratios — 1:1, 16:9, 9:16, 4:3. The image container needs to match the selected ratio before the image loads, otherwise there's a layout shift when it arrives.

const aspectClasses = {
  '1:1': 'aspect-square',
  '16:9': 'aspect-video',
  '9:16': 'aspect-[9/16]',
  '4:3': 'aspect-[4/3]',
};

<div className={`w-full ${aspectClasses[selectedRatio]}`}>
  {isGenerating ? <Skeleton /> : <Image ... />}
</div>

Tailwind's arbitrary aspect ratio syntax handles the non-standard ratios cleanly.

Results Summary

Metric	Before	After
Average file size	~800KB PNG	~180KB WebP
LCP (median)	4.2s	1.8s
CDN cache hit rate	0%	~60%
Layout shift	Present	Eliminated

The CDN cache hit rate at 60% surprised me — many users generate similar prompts, and Cloudinary serves cached versions of identical outputs instantly.

TL;DR

Use Cloudinary as intermediary for dynamic image optimization
Configure remotePatterns in next.config.js for approved domains
Set priority on the LCP image element
Pre-size containers with aspect ratio classes to prevent layout shift
Temporary storage for generated images — delete after delivery window For the full technical breakdown of the stack, I wrote a detailed architecture post here.

What's your approach to dynamic image delivery in Next.js? Comments open.

DEV Community: Aon infotech

Image Caching and CDN Strategies in Next.js — Getting Fast Image Delivery Right

How Next.js Image Optimization Works

Cache-Control Headers — What Next.js Sets by Default

Remote Images and CDN Configuration

Bypass Next.js Image Optimization for CDN-Served Images

Static Image Optimization — The public Directory

Vercel-Specific Considerations

Preloading Critical Images

Measuring Cache Performance

The Configuration That Actually Works

Stale-While-Revalidate for Dynamic Images

Content-Addressed URLs — The Clean Solution

Building a Type-Safe API Layer in Next.js App Router With Zod and Server Actions

The Problem With Naive Server Actions

- The return type isn't defined, so the client has no type information

The Foundation — A Result Type

Adding Zod Validation

The Server Action With Full Type Safety

The Client-Side Hook

The Form Component

A Reusable Action Wrapper

The Payoff

Testing Server Actions

Common Pitfalls

Skeleton Loading Screens in Next.js App Router — The Right Way to Handle Async UI

Why Skeletons Beat Spinners for Most Cases

The Suspense Boundary Pattern

Building the Skeleton Components

- The flex/grid layout structure

The Shimmer Animation

Lists of Unknown Length

Avoiding the Double Flash

The Skeleton Component Library Pattern

What I Built This On

Common Mistakes I've Made With Skeletons

A Testing Approach That Actually Helps

Optimizing Next.js App Router for Core Web Vitals — A Practical Guide

The Three Metrics — What Changed in App Router

LCP — The Image Problem

CLS — The Streaming Problem

CLS — Font Loading

INP — Client Component Optimization

Measuring Progress

The Checklist

Common Mistakes I Made (And Fixed)

Real Numbers

Error Boundaries in Next.js App Router — Handling Failures Gracefully

What Changes in App Router

The error.js File

The reset Function — When to Show It

Global Error Handling — global-error.js

Server Component Error Handling

The not-found.js File

Error Boundaries for Async Operations in Client Components

Error Reporting Integration

The Error Boundary Hierarchy in Practice

What I Built This On

Building a Dark Mode System in Next.js App Router — Without Layout Flash

Why the Flash Happens

The Solution — Inline Script Before React Hydration

The Theme Context

The Toggle Component

CSS Variables for Theming

Common Pitfalls

Testing

What I Built This On

Handling Server Components With Theme

Cookie-Based Alternative (For SSR Accuracy)

Summary

Rate Limiting Without User Accounts — Strategies for Anonymous APIs

Why Anonymous Rate Limiting Is Harder

Layer 1 — IP Address (Baseline)

Layer 2 — Token Bucket Per IP With Generous Limits

Layer 3 — Browser Fingerprinting (Client-Side Signal)

Layer 4 — Behavioral Signals

Layer 5 — Graceful Degradation Over Hard Blocks

Production Edge Cases

What This Looks Like in Practice

Testing Your Rate Limiting

Static Image Optimization — The `public` Directory

The `error.js` File

The `reset` Function — When to Show It

Global Error Handling — `global-error.js`

The `not-found.js` File