Introduction

Recently, while debugging a performance issue for a client, I encountered something puzzling. They reported that an image wasn't loading properly, but when I opened the browser's developer tools to check the network requests, the image was nowhere to be found. No HTTP request, no 404 error, nothing. The image was displaying correctly on the page, but it seemed to have vanished from the network tab entirely.

This led me down a rabbit hole that taught me something valuable about Vite's asset optimization features, specifically asset inlining.

What happened

What I discovered was that the image file was under 4KB, so Vite had automatically converted it to a base64 data URL and embedded it directly into the JavaScript bundle. Instead of this:

<img src="/assets/logo-abc123.png" />

The browser was rendering this:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." />

Since data URLs don't require network requests, there was nothing to show in the network tab. The image data was already bundled with the JavaScript.

How Vite handles asset inlining

Vite automatically inlines assets smaller than 4KB by default. This behavior is controlled by the build.assetsInlineLimit configuration option:

// vite.config.js
export default {
  build: {
    assetsInlineLimit: 4096, // 4KB threshold (default)
  },
};

Files smaller than this threshold get converted to base64 data URLs and embedded directly into your bundles. Larger files remain as separate assets with hashed filenames.

You can customize this behavior in several ways:

// Disable inlining completely
export default {
  build: {
    assetsInlineLimit: 0,
  },
};

// Increase the threshold to 8KB
export default {
  build: {
    assetsInlineLimit: 8192,
  },
};

// Use a function for custom logic
export default {
  build: {
    assetsInlineLimit: (filePath, content) => {
      // Never inline SVGs
      if (filePath.endsWith('.svg')) return false;
      // Default behavior for other files
      return content.length < 4096;
    },
  },
};

Why this matters

Asset inlining reduces HTTP requests, which can improve page load times, especially for small assets like icons. It also eliminates potential flash of unstyled content while waiting for assets to load.

However, there are trade-offs. Base64 encoding increases file size by roughly 33%, and all inlined assets are loaded into memory immediately. Changes to any inlined asset also invalidate the entire bundle cache.

Debugging inlined assets

When you suspect an asset might be inlined, you can check the rendered HTML in developer tools to look for base64 data URLs. You can also search through your built JavaScript files for base64 strings, or use bundle analysis tools to visualize what's included in your bundles.

The key insight is that missing network requests often indicate inlined assets rather than broken functionality.

Final thoughts

Asset inlining is one of those optimizations that works quietly in the background. While it initially caused confusion during my debugging session, understanding how it works has made me appreciate the thoughtful optimizations that modern build tools provide.

The 4KB default threshold works well for most use cases, but it's worth knowing how to customize it when needed. Sometimes the best optimizations are the ones you don't even notice working until you need to debug them.